repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit external command inventory

e5ad5bb43a6de382a2734c6f7048fa3e1c4ae23f

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`, `audit.sh`, `smoke.sh`.
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 19 - QML imports are limited to Qt, Quickshell, and local `import "."`.
19 20 - every QML component has an early decision comment.
20 21 - local resource references are audited; currently only bundled `nugu.json` is allowed via `Qt.resolvedUrl`.
49 50 documented_components=29
50 51 ipc_methods=58
51 52 documented_ipc=58
52 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,audit.sh,smoke.sh
53 +documented_external_commands=25
54 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
53 55 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
54 56 WARN transitional external bridge still present: cliphist
55 57 WARN transitional external bridge still present: makoctl
59 61 documented_components=29
60 62 ipc_methods=58
61 63 documented_ipc=58
62 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,audit.sh,smoke.sh
64 +documented_external_commands=25
65 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
63 66 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
64 67 WARN transitional external bridge still present: cliphist
65 68 WARN transitional external bridge still present: makoctl

quickshell/nugu/EXTERNALS.md

Added
new file mode 100644
1 +# Nugu Quickshell external command inventory
3 +Quickshell owns the companion UI, but some system/session actions still cross an
4 +external command boundary. This file documents every approved executable name
5 +that may appear in QML process-launch code or shell snippets.
7 +The audit fails unknown direct launch commands and prints detected commands. A
8 +`transitional` status means the command is a temporary bridge and must disappear
9 +before the replaced app/service is retired.
11 +| Command | Status | Why it is allowed now |
12 +| --- | --- | --- |
13 +| `awk` | approved | Parser inside existing shell snippets. |
14 +| `brightnessctl` | approved | Current brightness control/status backend. |
15 +| `cliphist` | transitional | Clipboard storage bridge until native/replacement storage is in scope. |
16 +| `cut` | approved | Parser inside existing shell snippets. |
17 +| `grep` | approved | Parser inside existing shell snippets. |
18 +| `head` | approved | Parser inside existing shell snippets. |
19 +| `hyprctl` | approved | Hyprland control path until final bind/config simplification. |
20 +| `hyprlock` | approved | Current session lock backend. |
21 +| `hyprpicker` | approved | Current color picker backend. |
22 +| `hyprshot` | approved | Current screenshot backend. |
23 +| `iwctl` | approved | Current iwd WiFi status backend. |
24 +| `loginctl` | approved | Current session lock helper in suspend flow. |
25 +| `makoctl` | transitional | Notification bridge while native notification parity is blocked. |
26 +| `nu` | approved | Terminal TUI shell for existing helper panes. |
27 +| `playerctl` | approved | MPRIS media action helper until live MPRIS parity is proven. |
28 +| `satty` | approved | Current screenshot annotation backend. |
29 +| `sed` | approved | Parser inside existing shell snippets. |
30 +| `sh` | approved | Shell boundary for inherited command pipelines. |
31 +| `systemctl` | approved | Gated power/session backend; destructive actions remain dry-run until approval. |
32 +| `upower` | approved | Existing battery details TUI backend. |
33 +| `uptime` | approved | Power popup status backend. |
34 +| `uwsm` | approved | Session-aware app launcher for graphical helpers. |
35 +| `wezterm` | approved | Terminal launcher for existing helper panes. |
36 +| `wl-copy` | approved | Clipboard output backend. |
37 +| `wpctl` | approved | Current PipeWire control/status backend. |

quickshell/nugu/README.md

Modified
29 29 `COMPONENTS.md` inventories every QML file with why it exists and current rollout
30 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
31 +`EXTERNALS.md` inventories every approved executable boundary. The audit checks
32 +that required named-config files are present, every QML component and IPC method
33 +are documented, QML imports stay local/Qt/Quickshell, every component has an
34 +early decision comment, local resources are audited, the bundled palette matches
35 +`hypr/generated/nugu.json`, external commands are documented, and retired
36 +companion launchers are not executable dependencies. It intentionally warns while
36 37 transitional `cliphist` and `makoctl` bridges remain; those warnings must
37 38 disappear before final retirement.

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", "IPC.md", "audit.sh", "smoke.sh")
21 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "audit.sh", "smoke.sh")
23 23 for name in required_files:
24 24 if not (config_dir / name).exists():
112 112 # phases remove or validate them. Unknown commands fail so new dependencies do
113 113 # not sneak into the self-contained config.
114 114 all_code = "\n".join(code_by_file.values())
115 -external_commands = {
116 - "awk": "approved parser in shell snippet",
117 - "brightnessctl": "approved brightness backend",
118 - "cliphist": "transitional clipboard storage bridge",
119 - "cut": "approved parser in shell snippet",
120 - "grep": "approved parser in shell snippet",
121 - "head": "approved parser in shell snippet",
122 - "hyprctl": "approved Hyprland control until bind migration",
123 - "hyprlock": "approved session lock backend",
124 - "hyprpicker": "approved color picker backend",
125 - "hyprshot": "approved screenshot backend",
126 - "iwctl": "approved iwd status backend",
127 - "loginctl": "approved session lock helper",
128 - "makoctl": "transitional notification bridge",
129 - "nu": "approved terminal TUI shell",
130 - "playerctl": "approved MPRIS action helper",
131 - "satty": "approved screenshot annotation backend",
132 - "sed": "approved parser in shell snippet",
133 - "sh": "approved shell boundary for existing command pipelines",
134 - "systemctl": "approved gated power/session backend",
135 - "upower": "approved battery TUI backend",
136 - "uptime": "approved status backend",
137 - "uwsm": "approved session app launcher",
138 - "wezterm": "approved terminal launcher",
139 - "wl-copy": "approved clipboard output backend",
140 - "wpctl": "approved PipeWire action helper",
115 +externals_doc = config_dir / "EXTERNALS.md"
116 +external_commands = {}
117 +external_status = {}
118 +if externals_doc.exists():
119 + for match in re.finditer(r"^\| `([^`]+)` \| ([^|]+) \| ([^|]+) \|$", externals_doc.read_text(), re.M):
120 + command = match.group(1)
121 + status = match.group(2).strip()
122 + reason = match.group(3).strip()
123 + external_commands[command] = reason
124 + external_status[command] = status
125 + if not external_commands:
126 + errors.append("EXTERNALS.md has no command rows")
127 +else:
128 + external_commands = {}
129 + external_status = {}
143 131 detected = []
144 132 for command, reason in sorted(external_commands.items()):
145 133 if re.search(rf"(?<![A-Za-z0-9_-]){re.escape(command)}(?![A-Za-z0-9_-])", all_code):
146 134 detected.append((command, reason))
147 - if reason.startswith("transitional"):
135 + if external_status.get(command) == "transitional":
148 136 warnings.append(f"transitional external bridge still present: {command}")
150 138 # This catches direct process-launch array heads that are not in the approved
175 163 print(f"documented_components={len(documented)}")
176 164 print(f"ipc_methods={len(ipc_methods)}")
177 165 print(f"documented_ipc={len(documented_ipc)}")
166 +print(f"documented_external_commands={len(external_commands)}")
178 167 print("required_files=" + ",".join(required_files))
179 168 if detected:
180 169 print("external_commands=" + ",".join(command for command, _reason in detected))