repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit ipc inventory

79bae901c159f92a04706ec25e5e7b9fb567bfef

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`, `audit.sh`, `smoke.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `audit.sh`, `smoke.sh`.
16 16 - every QML component is listed in `COMPONENTS.md` with purpose and rollout status.
17 +- every `nugu` IPC method from `shell.qml` is listed in `IPC.md` with purpose and rollout status.
17 18 - QML imports are limited to Qt, Quickshell, and local `import "."`.
18 19 - every QML component has an early decision comment.
19 20 - local resource references are audited; currently only bundled `nugu.json` is allowed via `Qt.resolvedUrl`.
46 47 PASS nugu quickshell audit
47 48 qml_files=29
48 49 documented_components=29
49 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,audit.sh,smoke.sh
50 +ipc_methods=58
51 +documented_ipc=58
52 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,audit.sh,smoke.sh
50 53 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
51 54 WARN transitional external bridge still present: cliphist
52 55 WARN transitional external bridge still present: makoctl
54 57 PASS nugu quickshell audit
55 58 qml_files=29
56 59 documented_components=29
57 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,audit.sh,smoke.sh
60 +ipc_methods=58
61 +documented_ipc=58
62 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,audit.sh,smoke.sh
58 63 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
59 64 WARN transitional external bridge still present: cliphist
60 65 WARN transitional external bridge still present: makoctl

quickshell/nugu/IPC.md

Added
new file mode 100644
1 +# Nugu Quickshell IPC inventory
3 +All calls use the named config target:
5 +```sh
6 +qs ipc -c nugu call nugu <method> [args...]
7 +```
9 +This inventory is audited against `shell.qml`. It exists so later Hypr config
10 +simplification can replace old companion commands with stable Quickshell IPC
11 +instead of rediscovering ad-hoc function names.
13 +## Method inventory
15 +| Method | Purpose | Rollout status |
16 +| --- | --- | --- |
17 +| `showDiagnostics` | Show the safe diagnostics surface for visual/theme probing. | Scaffold verified. |
18 +| `hideDiagnostics` | Hide the diagnostics surface. | Scaffold verified. |
19 +| `toggleDiagnostics` | Toggle diagnostics during manual visual checks. | Scaffold verified. |
20 +| `showBar` | Show the Quickshell bar beside Ironbar during rollout. | Scaffold verified; not live default. |
21 +| `hideBar` | Hide the Quickshell bar. | Scaffold verified. |
22 +| `toggleBar` | Toggle the Quickshell bar for screenshots/manual checks. | Scaffold verified. |
23 +| `reloadTheme` | Reload bundled Nugu palette and mode cache. | Smoke verified. |
24 +| `setThemeMode` | Select `light`, `dark`, or `auto` without writing global state. | Smoke verified. |
25 +| `themeMode` | Return current effective theme mode. | Smoke verified. |
26 +| `themeSource` | Return `preview` or `auto`. | Smoke verified. |
27 +| `themeState` | Return mode/source plus key loaded Nugu tokens. | Token smoke verified. |
28 +| `scaffoldState` | Return one compact JSON snapshot for smoke tests. | Smoke verified. |
29 +| `hideAll` | Close Quickshell surfaces and disable gated native notifications. | Smoke verified. |
30 +| `enableNativeNotifications` | Opt in to native notification daemon while Mako is stopped. | Implemented; DBus parity blocked. |
31 +| `disableNativeNotifications` | Disable native notification daemon for rollback. | Implemented; rollback path pending live DBus. |
32 +| `nativeNotificationCount` | Report tracked native notification count. | Implemented; DBus parity blocked. |
33 +| `dismissNativeNotifications` | Dismiss all native notification toasts. | Implemented; DBus parity blocked. |
34 +| `restoreNativeNotification` | Restore last native notification. | Implemented; DBus parity blocked. |
35 +| `showOsd` | Show arbitrary OSD text with a semantic tone. | Scaffold verified. |
36 +| `hideOsd` | Hide the OSD. | Scaffold verified. |
37 +| `showVolumeOsd` | Show volume text without changing audio. | Scaffold verified. |
38 +| `showBrightnessOsd` | Show brightness text without changing backlight. | Scaffold verified. |
39 +| `osdVolumeUp` | Raise volume and show OSD. | Implemented; live bind validation pending. |
40 +| `osdVolumeDown` | Lower volume and show OSD. | Implemented; live bind validation pending. |
41 +| `osdMuteAudio` | Toggle output mute and show OSD. | Implemented; live bind validation pending. |
42 +| `osdMuteMic` | Toggle microphone mute and show OSD. | Implemented; live bind validation pending. |
43 +| `osdBrightnessUp` | Raise brightness and show OSD. | Implemented; live bind validation pending. |
44 +| `osdBrightnessDown` | Lower brightness and show OSD. | Implemented; live bind validation pending. |
45 +| `osdMediaNext` | Advance media player and show OSD. | Implemented; DBus/MPRIS/live player validation pending. |
46 +| `osdMediaToggle` | Toggle media playback and show OSD. | Implemented; DBus/MPRIS/live player validation pending. |
47 +| `osdMediaPrev` | Previous media item and show OSD. | Implemented; DBus/MPRIS/live player validation pending. |
48 +| `osdReloadHypr` | Reload Hyprland and show OSD. | Implemented; bind migration pending. |
49 +| `osdSessionLock` | Lock session and show OSD. | Implemented; lock live validation pending. |
50 +| `osdSessionSuspendDryRun` | Dry-run suspend path and show OSD. | Dry-run verified. |
51 +| `osdCaptureRegion` | Capture a selected region and show OSD. | Implemented; interactive validation pending. |
52 +| `osdCaptureWindow` | Capture a selected window and show OSD. | Implemented; interactive validation pending. |
53 +| `osdCaptureOutput` | Capture an output and show OSD. | Implemented; interactive validation pending. |
54 +| `osdCaptureAnnotate` | Capture region and open annotation flow. | Implemented; interactive validation pending. |
55 +| `osdPickColor` | Pick a color and show OSD. | Implemented; interactive validation pending. |
56 +| `lastOsdAction` | Report last OSD command result for tests. | Smoke/dry-run helper. |
57 +| `openLauncher` | Open native desktop-entry launcher with optional query. | Keyboard/app-launch verified; bind migration pending. |
58 +| `closeLauncher` | Close launcher. | Verified. |
59 +| `launcherVisible` | Report launcher visibility. | Verified. |
60 +| `launcherMatchCount` | Report launcher result count. | Verified. |
61 +| `launcherFirstMatchName` | Report first launcher match name. | Verified. |
62 +| `openClipboardPicker` | Open clipboard picker with optional query. | Verified frontend; cliphist bridge remains. |
63 +| `closeClipboardPicker` | Close clipboard picker. | Verified. |
64 +| `clipboardPickerVisible` | Report clipboard picker visibility. | Verified. |
65 +| `clipboardPickerMatchCount` | Report clipboard picker result count. | Verified. |
66 +| `clipboardPickerFirstPreview` | Report first clipboard preview text. | Verified. |
67 +| `chooseClipboardIndex` | Copy selected clipboard result by index. | Verified frontend; cliphist bridge remains. |
68 +| `openPowerMenu` | Open confirmed power menu. | Dry-run matrix verified. |
69 +| `closePowerMenu` | Close power menu and clear pending action. | Dry-run matrix verified. |
70 +| `powerMenuVisible` | Report power menu visibility. | Dry-run matrix verified. |
71 +| `requestPowerAction` | Stage lock/sleep/logout/reboot/poweroff action. | Dry-run matrix verified. |
72 +| `pendingPowerAction` | Report currently staged power action. | Dry-run matrix verified. |
73 +| `confirmPowerAction` | Confirm staged action; non-lock remains dry-run. | Dry-run matrix verified. |
74 +| `lastPowerAction` | Report last power command result. | Dry-run matrix verified. |

quickshell/nugu/README.md

Modified
29 29 `COMPONENTS.md` inventories every QML file with why it exists and current rollout
30 -status. The audit checks that required named-config files are present, every QML
31 -component is documented there, QML imports stay local/Qt/Quickshell, every
32 -component has an early decision comment, local resources are audited, the bundled
33 -palette matches `hypr/generated/nugu.json`, and retired companion launchers are
34 -not executable dependencies. It intentionally warns while transitional `cliphist`
35 -and `makoctl` bridges remain; those warnings must disappear before final
36 -retirement.
30 +status. `IPC.md` inventories every `nugu` IPC method Hypr binds can later target.
31 +The audit checks that required named-config files are present, every QML
32 +component and IPC method are documented, QML imports stay local/Qt/Quickshell,
33 +every component has an early decision comment, local resources are audited, the
34 +bundled palette matches `hypr/generated/nugu.json`, and retired companion
35 +launchers are not executable dependencies. It intentionally warns while
36 +transitional `cliphist` and `makoctl` bridges remain; those warnings must
37 +disappear before final retirement.
38 39 The smoke runner creates a temporary `HOME` and `XDG_CONFIG_HOME`, symlinks only
39 40 this config as `quickshell/nugu`, runs the audit, starts `qs -c nugu`, checks

quickshell/nugu/audit.sh

Modified
18 18 warnings = []
19 19 qml_files = sorted(config_dir.glob("*.qml"))
20 20 code_by_file = {}
21 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "audit.sh", "smoke.sh")
21 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "audit.sh", "smoke.sh")
23 23 for name in required_files:
24 24 if not (config_dir / name).exists():
40 40 else:
41 41 documented = set()
43 +shell_text = (config_dir / "shell.qml").read_text() if (config_dir / "shell.qml").exists() else ""
44 +ipc_block = shell_text.split("IpcHandler {", 1)[1].split("\n Connections {", 1)[0] if "IpcHandler {" in shell_text else ""
45 +ipc_methods = set(re.findall(r"\bfunction\s+([A-Za-z0-9_]+)\s*\(", ipc_block))
46 +ipc_doc = config_dir / "IPC.md"
47 +if ipc_doc.exists():
48 + documented_ipc = set(re.findall(r"^\| `([A-Za-z0-9_]+)` \|", ipc_doc.read_text(), re.M))
49 + missing_ipc = sorted(ipc_methods - documented_ipc)
50 + stale_ipc = sorted(documented_ipc - ipc_methods)
51 + for name in missing_ipc:
52 + errors.append(f"IPC.md missing method {name}")
53 + for name in stale_ipc:
54 + errors.append(f"IPC.md references missing method {name}")
55 +else:
56 + documented_ipc = set()
43 58 allowed_imports = ("QtQuick", "Quickshell")
44 59 for path in qml_files:
45 60 text = path.read_text()
158 173 print("PASS nugu quickshell audit")
159 174 print(f"qml_files={len(qml_files)}")
160 175 print(f"documented_components={len(documented)}")
176 +print(f"ipc_methods={len(ipc_methods)}")
177 +print(f"documented_ipc={len(documented_ipc)}")
161 178 print("required_files=" + ",".join(required_files))
162 179 if detected:
163 180 print("external_commands=" + ",".join(command for command, _reason in detected))