repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit self-contained manifest

9f5c8ef83b76089ac0edbb1e794e28ed56fbc289

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`, `HYPR_MIGRATION.md`, `ROLLOUT.md`, `PERF.md`, `STYLE.md`, `SCRIPTS.md`, `audit.sh`, `smoke.sh`, `live-check.sh`, `gate.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `MANIFEST.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `TRANSITIONS.md`, `SERVICE.md`, `PARITY.md`, `HYPR_MIGRATION.md`, `ROLLOUT.md`, `PERF.md`, `STYLE.md`, `SCRIPTS.md`, `audit.sh`, `smoke.sh`, `live-check.sh`, `gate.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 +- `MANIFEST.md` must list every direct file in `quickshell/nugu`; orphaned or stale manifest rows fail the audit.
17 18 - `SCRIPTS.md` must inventory every `*.sh` file; each script must be executable and start with `#!/bin/sh` plus `set -eu`.
18 19 - `live-check.sh` is executable and audited read-only: it must not link, start, stop, enable, disable, restart, or launch `qs -c nugu`.
19 20 - `smoke.sh` is executable and audited for self-contained temp `HOME`/`XDG_CONFIG_HOME`, named config launch, launcher/clipboard/power/native-notification/OSD IPC probes, cleanup trap, and no live link/service mutation.
72 73 documented_external_commands=25
73 74 detected_external_commands=25
74 75 docs_index=ok
76 +manifest_files=47
77 +manifest=ok
75 78 script_files=4
76 79 script_rows=4
77 80 script_contract=ok
97 100 rollout_boundary=ok
98 101 contrast_pairs=12
99 102 contrast_min=5.50
100 -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,ROLLOUT.md,PERF.md,STYLE.md,SCRIPTS.md,audit.sh,smoke.sh,live-check.sh,gate.sh
103 +required_files=shell.qml,Theme.qml,nugu.json,README.md,MANIFEST.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,ROLLOUT.md,PERF.md,STYLE.md,SCRIPTS.md,audit.sh,smoke.sh,live-check.sh,gate.sh
101 104 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
102 105 WARN transitional external bridge still present: cliphist
103 106 WARN transitional external bridge still present: makoctl
111 114 documented_external_commands=25
112 115 detected_external_commands=25
113 116 docs_index=ok
117 +manifest_files=47
118 +manifest=ok
114 119 script_files=4
115 120 script_rows=4
116 121 script_contract=ok
136 141 rollout_boundary=ok
137 142 contrast_pairs=12
138 143 contrast_min=5.50
139 -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,ROLLOUT.md,PERF.md,STYLE.md,SCRIPTS.md,audit.sh,smoke.sh,live-check.sh,gate.sh
144 +required_files=shell.qml,Theme.qml,nugu.json,README.md,MANIFEST.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,HYPR_MIGRATION.md,ROLLOUT.md,PERF.md,STYLE.md,SCRIPTS.md,audit.sh,smoke.sh,live-check.sh,gate.sh
140 145 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
141 146 WARN transitional external bridge still present: cliphist
142 147 WARN transitional external bridge still present: makoctl

quickshell/nugu/MANIFEST.md

Added
new file mode 100644
1 +# Nugu Quickshell self-contained manifest
3 +This manifest is the outer inventory for the named config. Every file directly
4 +inside `quickshell/nugu` must be listed here so the config cannot accumulate
5 +undocumented helpers, stale notes, or hidden rollout state.
7 +| File | Kind | Role |
8 +| --- | --- | --- |
9 +| `Bar.qml` | QML component | Multi-monitor top bar shell that hosts the Quickshell replacement widgets while Ironbar stays authoritative. |
10 +| `BarButton.qml` | QML component | Shared compact bar button primitive for consistent Nugu hover, active, and muted states. |
11 +| `BatteryWidget.qml` | QML component | UPower-backed battery status widget for Ironbar battery parity. |
12 +| `BindModeWidget.qml` | QML component | Hidden future bind-mode indicator for Hypr submap parity after bind migration. |
13 +| `BluetoothWidget.qml` | QML component | Quickshell Bluetooth status widget replacing the current bar status surface. |
14 +| `BrightnessWidget.qml` | QML component | Brightness status and wheel action widget using the current brightnessctl backend. |
15 +| `COMPONENTS.md` | documentation | Audited inventory of every QML component and why it exists. |
16 +| `CalendarPopup.qml` | QML component | Nugu-styled clock calendar popup replacing external calendar affordances. |
17 +| `ClipboardPicker.qml` | QML component | Full clipboard picker frontend replacing the old launcher dmenu flow while retaining cliphist storage. |
18 +| `ClipboardWidget.qml` | QML component | Bar clipboard preview and entry point for current Ironbar clipboard parity. |
19 +| `ClockWidget.qml` | QML component | Clock widget and calendar popup anchor for Ironbar clock parity. |
20 +| `Commands.qml` | QML component | Central process boundary for inherited command actions and future Hypr IPC simplification. |
21 +| `CpuWidget.qml` | QML component | Lightweight CPU percentage widget for status bar parity. |
22 +| `Diagnostics.qml` | QML component | Safe visual diagnostics surface for theme and rollout checks before live replacement. |
23 +| `EXTERNALS.md` | documentation | Audited inventory of every approved external command boundary. |
24 +| `HYPR_MIGRATION.md` | documentation | Audited future map from current Hypr helper refs to Quickshell IPC targets. |
25 +| `IPC.md` | documentation | Audited inventory of every `nugu` IPC method exposed by `shell.qml`. |
26 +| `InhibitWidget.qml` | QML component | Manual keep-awake widget preserving current idle-inhibit bar behavior. |
27 +| `Launcher.qml` | QML component | Native desktop-entry launcher replacing hyprlauncher after live bind validation. |
28 +| `MANIFEST.md` | documentation | Outer file inventory that prevents undocumented files in the self-contained config. |
29 +| `MediaWidget.qml` | QML component | MPRIS media status widget for Ironbar media parity once user DBus is healthy. |
30 +| `NotificationBridgeWidget.qml` | QML component | Transitional Mako count and action bridge while native notification parity is blocked. |
31 +| `NotificationDaemon.qml` | QML component | Gated native notification server candidate for eventual Mako retirement. |
32 +| `NotificationToast.qml` | QML component | Nugu-styled notification toast renderer used by the gated native daemon. |
33 +| `Osd.qml` | QML component | Nugu OSD surface replacing transient `hyprctl notify` wrappers after bind migration. |
34 +| `PARITY.md` | documentation | Audited companion parity matrix and old-service retirement gates. |
35 +| `PERF.md` | documentation | Audited performance budget for polling, action processes, and future live perf evidence. |
36 +| `PowerMenu.qml` | QML component | Confirmed power menu replacing hyprshutdown while destructive actions remain gated. |
37 +| `PowerWidget.qml` | QML component | Bar power affordance and popup preserving current power surface parity. |
38 +| `README.md` | documentation | Main operator guide for the named config, gates, IPC, and rollout boundaries. |
39 +| `ROLLOUT.md` | documentation | Approval-only live cutover and rollback runbook. |
40 +| `SCRIPTS.md` | documentation | Audited inventory of verification scripts and their mutation boundaries. |
41 +| `SERVICE.md` | documentation | Future user-service contract for running the named config through systemd. |
42 +| `STYLE.md` | documentation | Audited Nugu semantic style, font, and token-use contract. |
43 +| `StatusItem.qml` | QML component | Shared status row/button primitive for popups and critical/warning states. |
44 +| `TRANSITIONS.md` | documentation | Audited transition bridge inventory for temporary cliphist and makoctl dependencies. |
45 +| `Theme.qml` | QML component | Bundled Nugu palette loader with dark, light, and auto mode support. |
46 +| `TrayWidget.qml` | QML component | System tray display and menu forwarding surface for Ironbar tray parity. |
47 +| `VolumeWidget.qml` | QML component | PipeWire volume status and wheel/click controls for Ironbar volume parity. |
48 +| `WifiWidget.qml` | QML component | iwd WiFi status widget using the current network backend. |
49 +| `WorkspaceWidget.qml` | QML component | Hyprland workspace display and interaction widget replacing Ironbar workspaces. |
50 +| `audit.sh` | script | Static repository gate for self-containment, inventories, contracts, and transitional warnings. |
51 +| `gate.sh` | script | Non-mutating verification chain for audit, unit verification, smoke, and live readiness. |
52 +| `live-check.sh` | script | Read-only live readiness reporter for links, services, DBus, Hypr errors, and old helper refs. |
53 +| `nugu.json` | data | Bundled Nugu palette data required for named-config self-containment. |
54 +| `shell.qml` | QML entrypoint | Main Quickshell scope that wires state, IPC, surfaces, and shared services. |
55 +| `smoke.sh` | script | Temporary-home named-config smoke runner for surfaces, IPC, themes, and cleanup behavior. |

quickshell/nugu/README.md

Modified
28 28 NUGU_QS_SMOKE_SCREENSHOT_DIR=/tmp/nugu-qs-theme-smoke quickshell/nugu/smoke.sh
31 -`COMPONENTS.md` inventories every QML file with why it exists and current rollout
31 +`MANIFEST.md` inventories every file in this directory so the named config stays
32 +self-contained and has no undocumented helpers. `COMPONENTS.md` inventories every QML file with why it exists and current rollout
32 33 status. `IPC.md` inventories every `nugu` IPC method Hypr binds can later target.
33 34 `EXTERNALS.md` inventories every approved executable boundary. `TRANSITIONS.md`
34 35 inventories temporary bridge commands and removal gates. `SERVICE.md`
39 40 `SCRIPTS.md` inventories each verification script and its mutation boundary.
40 41 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
41 42 and retirement gates. `HYPR_MIGRATION.md` maps current Hypr binds/helpers to
42 -future Quickshell IPC targets. `live-check.sh` reports final rollout blockers, including old Hypr companion refs, without mutating live services or links. `gate.sh` runs the current read-only/self-contained verification chain. The audit checks that required named-config files are present, every verification script is inventoried and executable, the rollout runbook keeps approval/rollback boundaries visible, the performance budget documents every polling/action boundary, the style contract keeps IBM Plex/Nugu-token usage enforced, every QML component and IPC method
43 +future Quickshell IPC targets. `live-check.sh` reports final rollout blockers, including old Hypr companion refs, without mutating live services or links. `gate.sh` runs the current read-only/self-contained verification chain. The audit checks that required named-config files are present, every direct config file is listed in the manifest, every verification script is inventoried and executable, the rollout runbook keeps approval/rollback boundaries visible, the performance budget documents every polling/action boundary, the style contract keeps IBM Plex/Nugu-token usage enforced, every QML component and IPC method
43 44 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
44 45 early decision/why comment, QML has no unresolved TODO/stub comments, local resources
45 46 are audited, the bundled palette matches

quickshell/nugu/audit.sh

Modified
24 24 style_font_refs = 0
25 25 style_hex_refs = 0
26 26 script_rows = {}
27 -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", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh")
27 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "MANIFEST.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh")
29 29 for name in required_files:
30 30 if not (config_dir / name).exists():
111 111 readme_path = config_dir / "README.md"
112 112 if readme_path.exists():
113 113 readme_text = readme_path.read_text()
114 - for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh", "qs -c nugu", "qs ipc -c nugu"):
114 + for marker in ("MANIFEST.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh", "qs -c nugu", "qs ipc -c nugu"):
115 115 if marker not in readme_text:
116 116 errors.append(f"README.md missing self-contained entry marker {marker!r}")
120 120 if not qml_files:
121 121 errors.append("no QML files found")
123 +manifest_doc = config_dir / "MANIFEST.md"
124 +manifest_rows = {}
125 +if manifest_doc.exists():
126 + manifest_source = manifest_doc.read_text()
127 + for number, line in enumerate(manifest_source.splitlines(), 1):
128 + if not line.startswith("| `"):
129 + continue
130 + cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
131 + if len(cells) != 3:
132 + errors.append(f"MANIFEST.md:{number}: manifest row needs file, kind, and role columns")
133 + continue
134 + match = re.fullmatch(r"`([^`]+)`", cells[0])
135 + if not match:
136 + continue
137 + name = match.group(1)
138 + if "/" in name or name.startswith("."):
139 + errors.append(f"MANIFEST.md:{number}: manifest only accepts direct visible files, got {name!r}")
140 + if name in manifest_rows:
141 + errors.append(f"MANIFEST.md:{number}: duplicate manifest row {name!r}")
142 + kind = cells[1]
143 + role = cells[2]
144 + if kind not in ("QML component", "QML entrypoint", "documentation", "script", "data"):
145 + errors.append(f"MANIFEST.md:{number}: unexpected kind {kind!r} for {name!r}")
146 + if len(role) < 32:
147 + errors.append(f"MANIFEST.md:{number}: thin manifest role for {name!r}: {role!r}")
148 + if re.search(r"\b(TODO|FIXME|XXX|HACK|stub|placeholder)\b", role, re.I):
149 + errors.append(f"MANIFEST.md:{number}: unresolved placeholder wording")
150 + manifest_rows[name] = cells[1:]
151 + actual_files = {path.name for path in config_dir.iterdir() if path.is_file() and not path.name.startswith(".")}
152 + documented_files = set(manifest_rows)
153 + for name in sorted(actual_files - documented_files):
154 + errors.append(f"MANIFEST.md missing config file {name}")
155 + for name in sorted(documented_files - actual_files):
156 + errors.append(f"MANIFEST.md references missing config file {name}")
157 + required_manifest_markers = (
158 + "every file directly",
159 + "undocumented helpers",
160 + "stale notes",
161 + "hidden rollout state",
163 + manifest_lower = manifest_source.lower()
164 + for marker in required_manifest_markers:
165 + if marker not in manifest_lower:
166 + errors.append(f"MANIFEST.md missing manifest contract marker {marker!r}")
167 +else:
168 + errors.append("missing MANIFEST.md")
123 170 script_doc = config_dir / "SCRIPTS.md"
124 171 script_files = sorted(path.name for path in config_dir.glob("*.sh"))
125 172 if script_doc.exists():
707 754 print(f"documented_external_commands={len(external_commands)}")
708 755 print(f"detected_external_commands={len(detected)}")
709 756 print("docs_index=ok")
757 +print(f"manifest_files={len(manifest_rows)}")
758 +print("manifest=ok")
710 759 print(f"script_files={len(script_files)}")
711 760 print(f"script_rows={len(script_rows)}")
712 761 print("script_contract=ok")