repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit verification scripts

c884149d8fa65738d0d1d8e711bcdd0a0ca494c0

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`, `audit.sh`, `smoke.sh`, `live-check.sh`, `gate.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`, `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 +- `SCRIPTS.md` must inventory every `*.sh` file; each script must be executable and start with `#!/bin/sh` plus `set -eu`.
17 18 - `live-check.sh` is executable and audited read-only: it must not link, start, stop, enable, disable, restart, or launch `qs -c nugu`.
18 19 - `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.
19 20 - `gate.sh` is executable and audited as the read-only/self-contained verification chain: audit, unit verify, smoke, live-check, optional strict live-check.
71 72 documented_external_commands=25
72 73 detected_external_commands=25
73 74 docs_index=ok
75 +script_files=4
76 +script_rows=4
77 +script_contract=ok
74 78 live_check=ok
75 79 live_check_readonly=ok
76 80 smoke_contract=ok
93 97 rollout_boundary=ok
94 98 contrast_pairs=12
95 99 contrast_min=5.50
96 -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,audit.sh,smoke.sh,live-check.sh,gate.sh
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
97 101 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
98 102 WARN transitional external bridge still present: cliphist
99 103 WARN transitional external bridge still present: makoctl
107 111 documented_external_commands=25
108 112 detected_external_commands=25
109 113 docs_index=ok
114 +script_files=4
115 +script_rows=4
116 +script_contract=ok
110 117 live_check=ok
111 118 live_check_readonly=ok
112 119 smoke_contract=ok
129 136 rollout_boundary=ok
130 137 contrast_pairs=12
131 138 contrast_min=5.50
132 -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,audit.sh,smoke.sh,live-check.sh,gate.sh
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
133 140 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
134 141 WARN transitional external bridge still present: cliphist
135 142 WARN transitional external bridge still present: makoctl

quickshell/nugu/README.md

Modified
36 36 `ROLLOUT.md` documents the approval-only cutover and rollback sequence.
37 37 `PERF.md` inventories polling/action process budgets and the future live perf gate.
38 38 `STYLE.md` records the audited Nugu style/font/color contract.
39 +`SCRIPTS.md` inventories each verification script and its mutation boundary.
39 40 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
40 41 and retirement gates. `HYPR_MIGRATION.md` maps current Hypr binds/helpers to
41 -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, 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
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
42 43 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
43 44 early decision/why comment, QML has no unresolved TODO/stub comments, local resources
44 45 are audited, the bundled palette matches

quickshell/nugu/SCRIPTS.md

Added
new file mode 100644
1 +# Nugu Quickshell script inventory
3 +These scripts are part of the self-contained named config. They are allowed to
4 +verify repository and temporary-home behavior, but they must not link live config,
5 +start/stop companion services, restart DBus, simplify Hypr, or retire old apps.
7 +| Script | Purpose | Mutation boundary |
8 +| --- | --- | --- |
9 +| `audit.sh` | Static repository guard for inventories, QML self-containment, Nugu style, rollout contracts, and stale dependency rows. | Read-only; checks files and exits without touching live HOME, services, DBus, or Hypr state. |
10 +| `smoke.sh` | Named-config scaffold runner using temporary `HOME` and `XDG_CONFIG_HOME` to prove Quickshell surfaces and IPC load without live links. | May create and remove only its own temp directory and its own temporary `qs` process. |
11 +| `live-check.sh` | Read-only live readiness reporter for links, services, DBus health, Hypr config errors, and old helper refs. | Reports blockers only; never starts, stops, enables, disables, links, reloads, or launches `qs -c nugu`. |
12 +| `gate.sh` | One-command verification chain for audit, user unit verification, smoke, live readiness, and optional strict live readiness. | Delegates only to audited non-mutating/self-contained gates; never performs rollout actions itself. |
14 +## Contract
16 +Every `*.sh` file in this directory must be listed here, executable, and use
17 +`#!/bin/sh` plus `set -eu`. Any new script must document why it exists and what
18 +it is allowed to mutate before the audit accepts it.

quickshell/nugu/audit.sh

Modified
23 23 decision_comment_files = set()
24 24 style_font_refs = 0
25 25 style_hex_refs = 0
26 -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", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh")
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")
28 29 for name in required_files:
29 30 if not (config_dir / name).exists():
110 111 readme_path = config_dir / "README.md"
111 112 if readme_path.exists():
112 113 readme_text = readme_path.read_text()
113 - for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh", "qs -c nugu", "qs ipc -c nugu"):
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 115 if marker not in readme_text:
115 116 errors.append(f"README.md missing self-contained entry marker {marker!r}")
119 120 if not qml_files:
120 121 errors.append("no QML files found")
123 +script_doc = config_dir / "SCRIPTS.md"
124 +script_files = sorted(path.name for path in config_dir.glob("*.sh"))
125 +if script_doc.exists():
126 + script_source = script_doc.read_text()
127 + for number, line in enumerate(script_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"SCRIPTS.md:{number}: script row needs script, purpose, and mutation boundary columns")
133 + continue
134 + match = re.fullmatch(r"`([^`]+\.sh)`", cells[0])
135 + if not match:
136 + continue
137 + name = match.group(1)
138 + if name in script_rows:
139 + errors.append(f"SCRIPTS.md:{number}: duplicate script row {name!r}")
140 + for cell in cells[1:]:
141 + if len(cell) < 24:
142 + errors.append(f"SCRIPTS.md:{number}: thin script inventory text for {name!r}: {cell!r}")
143 + if re.search(r"\b(TODO|FIXME|XXX|HACK|stub|placeholder)\b", cell, re.I):
144 + errors.append(f"SCRIPTS.md:{number}: unresolved placeholder wording")
145 + script_rows[name] = cells[1:]
146 + documented_scripts = set(script_rows)
147 + actual_scripts = set(script_files)
148 + for name in sorted(actual_scripts - documented_scripts):
149 + errors.append(f"SCRIPTS.md missing shell script {name}")
150 + for name in sorted(documented_scripts - actual_scripts):
151 + errors.append(f"SCRIPTS.md references missing shell script {name}")
152 + required_script_markers = (
153 + "must not link live config",
154 + "start/stop companion services",
155 + "restart dbus",
156 + "simplify hypr",
157 + "retire old apps",
158 + "#!/bin/sh",
159 + "set -eu",
161 + script_lower = script_source.lower()
162 + for marker in required_script_markers:
163 + if marker not in script_lower:
164 + errors.append(f"SCRIPTS.md missing script contract marker {marker!r}")
165 +else:
166 + errors.append("missing SCRIPTS.md")
168 +for script_name in script_files:
169 + script_path = config_dir / script_name
170 + script_text = script_path.read_text()
171 + if not script_text.startswith("#!/bin/sh\nset -eu\n"):
172 + errors.append(f"{script_name} must start with #!/bin/sh followed by set -eu")
173 + if not os.access(script_path, os.X_OK):
174 + errors.append(f"{script_name} must be executable")
122 176 def inventory_rows(path, label, expected_pattern):
123 177 rows = {}
124 178 if not path.exists():
653 707 print(f"documented_external_commands={len(external_commands)}")
654 708 print(f"detected_external_commands={len(detected)}")
655 709 print("docs_index=ok")
710 +print(f"script_files={len(script_files)}")
711 +print(f"script_rows={len(script_rows)}")
712 +print("script_contract=ok")
656 713 print("live_check=ok")
657 714 print("live_check_readonly=ok")
658 715 print("smoke_contract=ok")