repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit service rollout contract

cb65ec34bb3b1000aa3c60496fc0e10e010b2019

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`, `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`, `SERVICE.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 18 - every approved executable boundary is listed in `EXTERNALS.md` with status and reason, and stale unused rows fail.
19 +- future service rollout is documented in `SERVICE.md`; `hypr/systemd/quickshell.service` must start `qs -c nugu`, and `x230.symlinks` must link both config and service.
19 20 - QML imports are limited to Qt, Quickshell, and local `import "."`.
20 21 - every QML component has an early decision comment.
21 22 - QML comments do not contain unresolved TODO/stub/placeholder markers; rollout status belongs in inventories.
39 40 ```sh
40 41 cd /home/oli/Workspace/dotfiles
41 42 quickshell/nugu/audit.sh
43 +systemd-analyze --user verify hypr/systemd/quickshell.service
42 44 sh -n quickshell/nugu/smoke.sh
43 45 quickshell/nugu/smoke.sh
44 46 pgrep -a qs || true
54 56 documented_ipc=58
55 57 documented_external_commands=25
56 58 detected_external_commands=25
59 +service_contract=ok
57 60 contrast_pairs=12
58 61 contrast_min=5.50
59 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
62 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,audit.sh,smoke.sh
60 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
61 64 WARN transitional external bridge still present: cliphist
62 65 WARN transitional external bridge still present: makoctl
68 71 documented_ipc=58
69 72 documented_external_commands=25
70 73 detected_external_commands=25
74 +service_contract=ok
71 75 contrast_pairs=12
72 76 contrast_min=5.50
73 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,audit.sh,smoke.sh
77 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,audit.sh,smoke.sh
74 78 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
75 79 WARN transitional external bridge still present: cliphist
76 80 WARN transitional external bridge still present: makoctl

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 -`EXTERNALS.md` inventories every approved executable boundary. The audit checks
32 -that required named-config files are present, every QML component and IPC method
31 +`EXTERNALS.md` inventories every approved executable boundary. `SERVICE.md`
32 +documents the future user-service rollout contract without activating it. The
33 +audit checks that required named-config files are present, every QML component and IPC method
33 34 are documented, QML imports stay local/Qt/Quickshell, every component has an
34 35 early decision comment, QML has no unresolved TODO/stub comments, local resources
35 36 are audited, the bundled palette matches
36 37 `hypr/generated/nugu.json`, critical Nugu foreground/background pairs keep at
37 -least 4.5 contrast, external commands are documented without stale rows, and
38 -retired companion launchers are not executable dependencies. It intentionally
38 +least 4.5 contrast, external commands are documented without stale rows, the
39 +future user service starts the named config, the x230 dorkfiles manifest links
40 +that service/config pair, and retired companion launchers are not executable dependencies. It intentionally
39 41 warns while
40 42 transitional `cliphist` and `makoctl` bridges remain; those warnings must
41 43 disappear before final retirement.

quickshell/nugu/SERVICE.md

Added
new file mode 100644
1 +# Nugu Quickshell service rollout contract
3 +This file documents the future live activation boundary. It is intentionally a
4 +contract, not an activation instruction: Ironbar and Mako stay live until parity
5 +is proven and approved.
7 +## Tracked install targets
9 +The x230 dorkfiles manifest must link:
11 +| Repo path | Live target | Why |
12 +| --- | --- | --- |
13 +| `quickshell/nugu` | `~/.config/quickshell/nugu` | Keeps the Quickshell named config self-contained. |
14 +| `hypr/systemd/quickshell.service` | `~/.config/systemd/user/quickshell.service` | Starts the named config only after rollout approval. |
16 +## Required unit shape
18 +`hypr/systemd/quickshell.service` must keep these properties:
20 +| Property | Required value | Why |
21 +| --- | --- | --- |
22 +| `ExecStart` | `/usr/bin/qs -c nugu` | Uses the named self-contained config, not a live/repo path. |
23 +| `Environment` | `QS_NO_RELOAD_POPUP=1` | Avoids hot-reload popups in the session service. |
24 +| `Restart` | `on-failure` | Makes recoverability testable without respawning clean exits. |
25 +| `RestartSec` | `2` | Fast enough for desktop recovery, slow enough to avoid a tight loop. |
26 +| `Slice` | `session-graphical.slice` | Accounts companion UI with interactive session surfaces. |
27 +| `WantedBy` | `graphical-session.target` | Starts with the graphical user session when enabled later. |
29 +## Rollout boundary
31 +Do not run `just link`, enable, start, stop, or restart this service without
32 +explicit approval. Static checks may verify this contract; live activation waits
33 +until Quickshell parity, rollback, and visual approval are complete.

quickshell/nugu/audit.sh

Modified
19 19 warnings = []
20 20 qml_files = sorted(config_dir.glob("*.qml"))
21 21 code_by_file = {}
22 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "audit.sh", "smoke.sh")
22 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "audit.sh", "smoke.sh")
24 24 for name in required_files:
25 25 if not (config_dir / name).exists():
155 155 except (KeyError, ValueError, json.JSONDecodeError) as error:
156 156 errors.append(f"invalid Nugu palette for contrast audit: {error}")
158 +service_path = repo_dir / "hypr" / "systemd" / "quickshell.service"
159 +manifest_path = repo_dir / "x230.symlinks"
160 +if service_path.exists():
161 + service_text = service_path.read_text()
162 + required_unit_lines = {
163 + "Environment=QS_NO_RELOAD_POPUP=1": "disable reload popups in the service",
164 + "ExecStart=/usr/bin/qs -c nugu": "start the named self-contained config",
165 + "Restart=on-failure": "recover failed companion process",
166 + "RestartSec=2": "avoid tight restart loops",
167 + "Slice=session-graphical.slice": "account UI with graphical session",
168 + "WantedBy=graphical-session.target": "enable into graphical user session",
170 + for line, reason in required_unit_lines.items():
171 + if line not in service_text:
172 + errors.append(f"quickshell.service missing {line!r} ({reason})")
173 +else:
174 + errors.append("missing hypr/systemd/quickshell.service")
176 +if manifest_path.exists():
177 + manifest_text = manifest_path.read_text()
178 + required_manifest_pairs = {
179 + "quickshell/nugu\n~/.config/quickshell/nugu": "link named Quickshell config",
180 + "hypr/systemd/quickshell.service\n~/.config/systemd/user/quickshell.service": "link future user service",
182 + for pair, reason in required_manifest_pairs.items():
183 + if pair not in manifest_text:
184 + errors.append(f"x230.symlinks missing {reason}")
185 +else:
186 + errors.append("missing x230.symlinks")
158 188 # Keep executable dependencies explicit. Quickshell can replace companion UI,
159 189 # but system/session CLIs still exist at command boundaries until later parity
160 190 # phases remove or validate them. Unknown commands fail so new dependencies do
217 247 print(f"documented_ipc={len(documented_ipc)}")
218 248 print(f"documented_external_commands={len(external_commands)}")
219 249 print(f"detected_external_commands={len(detected)}")
250 +print("service_contract=ok")
220 251 print(f"contrast_pairs={len(contrast_pairs)}")
221 252 if contrast_pairs:
222 253 print(f"contrast_min={min(ratio for _mode, _label, ratio in contrast_pairs):.2f}")