repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit hypr bind migration map

69076bf1887b8d133b8942eb8219ef6f7326e96c

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

docs/super/inventory/2026-06-17-quickshell-self-contained-audit.md

Modified
13 13 `quickshell/nugu/audit.sh` checks repository state only:
15 -- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `TRANSITIONS.md`, `SERVICE.md`, `PARITY.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `TRANSITIONS.md`, `SERVICE.md`, `PARITY.md`, `HYPR_MIGRATION.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
16 16 - `README.md` links the required inventories, service/parity contracts, smoke/audit/live-check gates, named config command, and IPC command form.
17 17 - `live-check.sh` is executable and audited read-only: it must not link, start, stop, enable, disable, restart, or launch `qs -c nugu`.
18 18 - `smoke.sh` is executable and audited for self-contained temp `HOME`/`XDG_CONFIG_HOME`, named config launch, cleanup trap, and no live link/service mutation.
23 23 - every `transitional` external command is listed in `TRANSITIONS.md` with current role and removal gate; stale transition rows fail.
24 24 - future service rollout is documented in `SERVICE.md`; `hypr/systemd/quickshell.service` must start `qs -c nugu`, and `x230.symlinks` must link both config and service.
25 25 - replacement scope is documented in `PARITY.md`, including old companion retirement targets, non-thin row statuses/gates, valid QML replacement references, human approval, and the explicit “not complete / old tools remain authoritative” boundary.
26 +- Hypr simplification is documented in `HYPR_MIGRATION.md`; rows must cover old helper markers and point only at existing `nugu` IPC methods.
26 27 - QML imports are limited to Qt, Quickshell, and local `import "."`.
27 28 - every QML component has an early decision/why comment, not just a generic file description.
28 29 - QML comments do not contain unresolved TODO/stub/placeholder markers; rollout status belongs in inventories.
74 75 service_contract=ok
75 76 parity_matrix=ok
76 77 parity_rows=12
78 +hypr_migration_rows=21
79 +hypr_migration=ok
77 80 rollout_boundary=ok
78 81 contrast_pairs=12
79 82 contrast_min=5.50
80 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
83 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,audit.sh,smoke.sh,live-check.sh
81 84 external_commands=awk,brightnessctl,cliphist,cut,grep,head,hyprctl,hyprlock,hyprpicker,hyprshot,iwctl,loginctl,makoctl,nu,playerctl,satty,sed,sh,systemctl,upower,uptime,uwsm,wezterm,wl-copy,wpctl
82 85 WARN transitional external bridge still present: cliphist
83 86 WARN transitional external bridge still present: makoctl
100 103 service_contract=ok
101 104 parity_matrix=ok
102 105 parity_rows=12
106 +hypr_migration_rows=21
107 +hypr_migration=ok
103 108 rollout_boundary=ok
104 109 contrast_pairs=12
105 110 contrast_min=5.50
106 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
111 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,audit.sh,smoke.sh,live-check.sh
107 112 external_commands=awk,brightnessctl,cliphist,cut,grep,head,hyprctl,hyprlock,hyprpicker,hyprshot,iwctl,loginctl,makoctl,nu,playerctl,satty,sed,sh,systemctl,upower,uptime,uwsm,wezterm,wl-copy,wpctl
108 113 WARN transitional external bridge still present: cliphist
109 114 WARN transitional external bridge still present: makoctl

quickshell/nugu/HYPR_MIGRATION.md

Added
new file mode 100644
1 +# Nugu Quickshell Hypr bind migration matrix
3 +This file is the future simplification map for `hypr/modules/binds.lua`,
4 +`hypr/modules/apps.lua`, and `hypr/modules/hypr_osd.lua`. It is not applied yet:
5 +old Hypr binds stay authoritative until Quickshell is live, recoverable, and the
6 +parity gates pass.
8 +| Current bind/tool | Current path | Future Quickshell target | Migration gate |
9 +| --- | --- | --- | --- |
10 +| `SUPER + Space` / `hyprlauncher` | `apps.launcher` | `qs ipc -c nugu call nugu openLauncher` | Launcher live bind, keyboard, mouse, app-launch, and screenshot parity verified. |
11 +| `SUPER + V` / `cliphist plus hyprlauncher --dmenu` | `apps.clipboard` | `qs ipc -c nugu call nugu openClipboardPicker` | Clipboard picker live bind, selection, copy, keyboard, mouse, and storage decision verified. |
12 +| `CTRL + ALT + Delete` / `hyprshutdown` | `apps.logout` | `qs ipc -c nugu call nugu openPowerMenu` | Confirmed power UI accepted; lock/sleep/logout/reboot/poweroff gates approved. |
13 +| `SUPER + SHIFT + R` / `hyprctl notify` reload wrapper | `osd.session.reload` | `qs ipc -c nugu call nugu osdReloadHypr` | Reload action produces Quickshell OSD and Hypr config still has no errors. |
14 +| `SUPER + Escape` / `makoctl dismiss --all` | `osd.notifications.clear_all` | `qs ipc -c nugu call nugu dismissNativeNotifications` | Native notification dismiss/history parity proven after Mako stop/rollback tests. |
15 +| `XF86AudioRaiseVolume` | `osd.controls.volume_up` | `qs ipc -c nugu call nugu osdVolumeUp` | Hardware key repeat changes volume and renders OSD without `hyprctl notify`. |
16 +| `XF86AudioLowerVolume` | `osd.controls.volume_down` | `qs ipc -c nugu call nugu osdVolumeDown` | Hardware key repeat changes volume and renders OSD without `hyprctl notify`. |
17 +| `XF86AudioMute` | `osd.controls.mute` | `qs ipc -c nugu call nugu osdMuteAudio` | Hardware key toggles sink mute and renders OSD without `hyprctl notify`. |
18 +| `XF86AudioMicMute` | `osd.controls.mic_mute` | `qs ipc -c nugu call nugu osdMuteMic` | Hardware key toggles mic mute and renders OSD without `hyprctl notify`. |
19 +| `XF86MonBrightnessUp` | `osd.controls.brightness_up` | `qs ipc -c nugu call nugu osdBrightnessUp` | Hardware key repeat changes brightness and renders OSD without `hyprctl notify`. |
20 +| `XF86MonBrightnessDown` | `osd.controls.brightness_down` | `qs ipc -c nugu call nugu osdBrightnessDown` | Hardware key repeat changes brightness and renders OSD without `hyprctl notify`. |
21 +| `XF86AudioNext` | `osd.controls.media_next` | `qs ipc -c nugu call nugu osdMediaNext` | MPRIS/DBus healthy; live player advances and OSD renders. |
22 +| `XF86AudioPause` / `XF86AudioPlay` | `osd.controls.media_toggle` | `qs ipc -c nugu call nugu osdMediaToggle` | MPRIS/DBus healthy; live player toggles and OSD renders. |
23 +| `XF86AudioPrev` | `osd.controls.media_prev` | `qs ipc -c nugu call nugu osdMediaPrev` | MPRIS/DBus healthy; live player goes previous and OSD renders. |
24 +| `SUPER + ALT + L` | `osd.session.lock` | `qs ipc -c nugu call nugu osdSessionLock` | Lock action validated live with rollback/relogin confidence. |
25 +| `SUPER + ALT + S` | `osd.session.suspend` | `qs ipc -c nugu call nugu osdSessionSuspendDryRun` | Suspend remains dry-run until explicit destructive/session approval. |
26 +| `Print` | `osd.capture.region` | `qs ipc -c nugu call nugu osdCaptureRegion` | Interactive region capture works and OSD reports success/failure. |
27 +| `SHIFT + Print` | `osd.capture.window` | `qs ipc -c nugu call nugu osdCaptureWindow` | Interactive window capture works and OSD reports success/failure. |
28 +| `CTRL + Print` | `osd.capture.output` | `qs ipc -c nugu call nugu osdCaptureOutput` | Output capture works and OSD reports success/failure. |
29 +| `SUPER + Print` | `osd.capture.annotate` | `qs ipc -c nugu call nugu osdCaptureAnnotate` | Region capture plus annotation flow works and OSD reports success/failure. |
30 +| `SUPER + SHIFT + Print` / `hyprpicker` | `osd.capture.color` | `qs ipc -c nugu call nugu osdPickColor` | Color picker copies color and OSD reports success/failure. |
32 +## Boundary
34 +Do not edit `hypr/modules/binds.lua`, `hypr/modules/apps.lua`, or
35 +`hypr/modules/hypr_osd.lua` from this matrix until `live-check.sh --strict`
36 +passes or the remaining blockers are explicitly approved as retained
37 +infrastructure. This matrix exists to make the later Hypr simplification small,
38 +reviewable, and reversible.

quickshell/nugu/README.md

Modified
33 33 inventories temporary bridge commands and removal gates. `SERVICE.md`
34 34 documents the future user-service rollout contract without activating it.
35 35 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
36 -and retirement gates. `live-check.sh` reports final rollout blockers without mutating live services or links. The audit checks that required named-config files are present, every QML component and IPC method
36 +and retirement gates. `HYPR_MIGRATION.md` maps current Hypr binds/helpers to
37 +future Quickshell IPC targets. `live-check.sh` reports final rollout blockers without mutating live services or links. The audit checks that required named-config files are present, every QML component and IPC method
37 38 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
38 39 early decision/why comment, QML has no unresolved TODO/stub comments, local resources
39 40 are audited, the bundled palette matches
42 43 transitional bridge commands have removal gates, the future user service starts
43 44 the named config, the x230 dorkfiles manifest links
44 45 that service/config pair, the parity matrix still names old companion retirement
45 -targets, and retired companion launchers are not executable dependencies. It intentionally
46 +targets, the Hypr migration matrix points only at existing `nugu` IPC methods,
47 +and retired companion launchers are not executable dependencies. It intentionally
46 48 warns while
47 49 transitional `cliphist` and `makoctl` bridges remain; those warnings must
48 50 disappear before final retirement.

quickshell/nugu/audit.sh

Modified
21 21 qml_files = sorted(config_dir.glob("*.qml"))
22 22 code_by_file = {}
23 23 decision_comment_files = set()
24 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh")
24 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "audit.sh", "smoke.sh", "live-check.sh")
26 26 for name in required_files:
27 27 if not (config_dir / name).exists():
75 75 readme_path = config_dir / "README.md"
76 76 if readme_path.exists():
77 77 readme_text = readme_path.read_text()
78 - for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
78 + for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
79 79 if marker not in readme_text:
80 80 errors.append(f"README.md missing self-contained entry marker {marker!r}")
81 81 else:
334 334 errors.append("missing PARITY.md")
336 +hypr_migration_doc = config_dir / "HYPR_MIGRATION.md"
337 +hypr_migration_rows = []
338 +if hypr_migration_doc.exists():
339 + migration_source = hypr_migration_doc.read_text()
340 + migration_text = migration_source.lower()
341 + required_migration_markers = (
342 + "hypr/modules/binds.lua",
343 + "hypr/modules/apps.lua",
344 + "hypr/modules/hypr_osd.lua",
345 + "hyprlauncher",
346 + "hyprlauncher --dmenu",
347 + "hyprshutdown",
348 + "hyprctl notify",
349 + "makoctl",
350 + "cliphist",
351 + "hyprpicker",
352 + "qs ipc -c nugu call nugu openlauncher",
353 + "qs ipc -c nugu call nugu openclipboardpicker",
354 + "qs ipc -c nugu call nugu openpowermenu",
355 + "qs ipc -c nugu call nugu osdvolumeup",
356 + "qs ipc -c nugu call nugu osdcaptureregion",
357 + "live-check.sh --strict",
359 + for marker in required_migration_markers:
360 + if marker not in migration_text:
361 + errors.append(f"HYPR_MIGRATION.md missing bind migration marker {marker!r}")
363 + seen_binds = set()
364 + for number, line in enumerate(migration_source.splitlines(), 1):
365 + if not line.startswith("|") or "---" in line:
366 + continue
367 + cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
368 + if not cells or cells[0] == "Current bind/tool":
369 + continue
370 + if len(cells) != 4:
371 + errors.append(f"HYPR_MIGRATION.md:{number}: migration row needs current bind, current path, future target, and gate columns")
372 + continue
373 + current, path_name, target, gate = cells
374 + key = "".join(ch for ch in current if ch != chr(96)).lower()
375 + if key in seen_binds:
376 + errors.append(f"HYPR_MIGRATION.md:{number}: duplicate bind/tool row {current!r}")
377 + seen_binds.add(key)
378 + if not target.startswith("`qs ipc -c nugu call nugu "):
379 + errors.append(f"HYPR_MIGRATION.md:{number}: future target must be a nugu IPC call")
380 + method = target.removeprefix("`qs ipc -c nugu call nugu ").removesuffix("`").split()[0]
381 + if method not in ipc_methods:
382 + errors.append(f"HYPR_MIGRATION.md:{number}: future target references missing IPC method {method!r}")
383 + if len(path_name) < 10:
384 + errors.append(f"HYPR_MIGRATION.md:{number}: thin current path for {current!r}")
385 + if len(gate) < 32:
386 + errors.append(f"HYPR_MIGRATION.md:{number}: thin migration gate for {current!r}")
387 + if re.search(r"\b(TODO|FIXME|XXX|HACK|stub|placeholder)\b", " ".join(cells), re.I):
388 + errors.append(f"HYPR_MIGRATION.md:{number}: unresolved placeholder wording")
389 + hypr_migration_rows.append(cells)
390 + if len(hypr_migration_rows) < 20:
391 + errors.append(f"HYPR_MIGRATION.md has only {len(hypr_migration_rows)} migration rows; expected old bind coverage")
392 +else:
393 + errors.append("missing HYPR_MIGRATION.md")
336 395 # Keep executable dependencies explicit. Quickshell can replace companion UI,
337 396 # but system/session CLIs still exist at command boundaries until later parity
338 397 # phases remove or validate them. Unknown commands fail so new dependencies do
422 481 print("service_contract=ok")
423 482 print("parity_matrix=ok")
424 483 print(f"parity_rows={len(parity_rows)}")
484 +print(f"hypr_migration_rows={len(hypr_migration_rows)}")
485 +print("hypr_migration=ok")
425 486 print("rollout_boundary=ok")
426 487 print(f"contrast_pairs={len(contrast_pairs)}")
427 488 if contrast_pairs: