repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

test(quickshell): reject stale external inventory

a01ba63f50773ecb2a1a7c3224d8598702ce56dc

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
15 15 - required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `audit.sh`, `smoke.sh`.
16 16 - every QML component is listed in `COMPONENTS.md` with purpose and rollout status.
17 17 - every `nugu` IPC method from `shell.qml` is listed in `IPC.md` with purpose and rollout status.
18 -- every approved executable boundary is listed in `EXTERNALS.md` with status and reason.
18 +- every approved executable boundary is listed in `EXTERNALS.md` with status and reason, and stale unused rows fail.
19 19 - QML imports are limited to Qt, Quickshell, and local `import "."`.
20 20 - every QML component has an early decision comment.
21 21 - local resource references are audited; currently only bundled `nugu.json` is allowed via `Qt.resolvedUrl`.
52 52 ipc_methods=58
53 53 documented_ipc=58
54 54 documented_external_commands=25
55 +detected_external_commands=25
55 56 contrast_pairs=12
56 57 contrast_min=5.50
57 58 required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
65 66 ipc_methods=58
66 67 documented_ipc=58
67 68 documented_external_commands=25
69 +detected_external_commands=25
68 70 contrast_pairs=12
69 71 contrast_min=5.50
70 72 required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh

quickshell/nugu/EXTERNALS.md

Modified
4 4 # Nugu Quickshell external command inventory
6 6 Quickshell owns the companion UI, but some system/session actions still cross an
7 7 external command boundary. This file documents every approved executable name
8 8 that may appear in QML process-launch code or shell snippets.
10 -The audit fails unknown direct launch commands and prints detected commands. A
11 -`transitional` status means the command is a temporary bridge and must disappear
12 -before the replaced app/service is retired.
10 +The audit fails unknown direct launch commands and stale documented commands,
11 +then prints detected commands. A `transitional` status means the command is a
12 +temporary bridge and must disappear before the replaced app/service is retired.
14 14 | Command | Status | Why it is allowed now |
15 15 | --- | --- | --- |

quickshell/nugu/README.md

Modified
33 33 are documented, QML imports stay local/Qt/Quickshell, every component has an
34 34 early decision comment, local resources are audited, the bundled palette matches
35 35 `hypr/generated/nugu.json`, critical Nugu foreground/background pairs keep at
36 -least 4.5 contrast, external commands are documented, and retired companion
37 -launchers are not executable dependencies. It intentionally warns while
36 +least 4.5 contrast, external commands are documented without stale rows, and
37 +retired companion launchers are not executable dependencies. It intentionally
38 +warns while
38 39 transitional `cliphist` and `makoctl` bridges remain; those warnings must
39 40 disappear before final retirement.

quickshell/nugu/audit.sh

Modified
178 178 if external_status.get(command) == "transitional":
179 179 warnings.append(f"transitional external bridge still present: {command}")
181 +detected_commands = {command for command, _reason in detected}
182 +for command in sorted(set(external_commands) - detected_commands):
183 + errors.append(f"EXTERNALS.md documents unused command {command!r}; remove stale row or use it intentionally")
181 185 # This catches direct process-launch array heads that are not in the approved
182 186 # inventory. Shell snippets launched through `sh -c` are inventoried by known
183 187 # command names above; they remain explicit but are too free-form for a safe
207 211 print(f"ipc_methods={len(ipc_methods)}")
208 212 print(f"documented_ipc={len(documented_ipc)}")
209 213 print(f"documented_external_commands={len(external_commands)}")
214 +print(f"detected_external_commands={len(detected)}")
210 215 print(f"contrast_pairs={len(contrast_pairs)}")
211 216 if contrast_pairs:
212 217 print(f"contrast_min={min(ratio for _mode, _label, ratio in contrast_pairs):.2f}")