repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

test(quickshell): audit self-contained config

9904fafdc834dd1696a4f62ccc9cbf14aaeaeead

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (8)

docs/super/inventory/2026-06-17-quickshell-self-contained-audit.md

Added
new file mode 100644
1 +# Quickshell self-contained audit verification
3 +Date: 2026-06-17
5 +## Scope
7 +Add and verify a static guard for the self-contained documented Nugu Quickshell config.
9 +No live links, user services, Ironbar, Mako, Hyprland binds, or `~/.config/quickshell` were changed.
11 +## What the audit checks
13 +`quickshell/nugu/audit.sh` checks repository state only:
15 +- QML imports are limited to Qt, Quickshell, and local `import "."`.
16 +- Every QML component has an early decision comment.
17 +- `quickshell/nugu/nugu.json` exists and matches `hypr/generated/nugu.json`.
18 +- executable code does not call retired companion app markers:
19 + - `hyprlauncher`
20 + - `hyprshutdown`
21 + - `hyprctl notify`
22 +- transitional bridges are explicitly reported as warnings, not hidden:
23 + - `cliphist`
24 + - `makoctl`
26 +These warnings are expected during rollout and must disappear before final companion retirement.
28 +## Commands
30 +```sh
31 +cd /home/oli/Workspace/dotfiles
32 +quickshell/nugu/audit.sh
33 +sh -n quickshell/nugu/smoke.sh
34 +quickshell/nugu/smoke.sh
35 +pgrep -a qs || true
36 +```
38 +Observed:
40 +```text
41 +PASS nugu quickshell audit
42 +qml_files=29
43 +WARN transitional external bridge still present: cliphist
44 +WARN transitional external bridge still present: makoctl
45 +PASS nugu quickshell scaffold smoke
46 +PASS nugu quickshell audit
47 +qml_files=29
48 +WARN transitional external bridge still present: cliphist
49 +WARN transitional external bridge still present: makoctl
50 +smoke_exit=0
51 +--- lingering qs ---
52 +```
54 +The smoke runner now executes the audit before launching `qs -c nugu` with temporary `HOME` and `XDG_CONFIG_HOME`.
56 +## Boundary
58 +This improves the self-contained documented config gate only. Overall companion parity remains incomplete:
60 +- `quickshell.service` is still not live.
61 +- Ironbar and Mako remain active.
62 +- `cliphist` and `makoctl` are still known transitional bridges.
63 +- Hypr binds are not simplified until replacement IPC is proven live and approved.

quickshell/nugu/CalendarPopup.qml

Modified
5 5 PopupWindow {
6 6 id: root
8 + // Calendar stays a lightweight popup owned by the bar instead of launching an
9 + // external applet. It proves Quickshell can cover Ironbar's clock surface in
10 + // the same Nugu style without adding another service.
8 11 required property QtObject theme
9 12 required property var barWindow
10 13 required property var anchorItem

quickshell/nugu/ClipboardWidget.qml

Modified
7 7 Item {
8 8 id: root
10 + // Bar clipboard preview is intentionally small: it gives Ironbar parity on
11 + // the status bar while the full picker owns search/keyboard selection. The
12 + // storage backend remains cliphist until replacement storage is in scope.
10 13 required property QtObject theme
11 14 required property QtObject commands
12 15 required property var barWindow

quickshell/nugu/InhibitWidget.qml

Modified
4 4 import QtQuick
5 5 import "."
7 7 StatusItem {
8 8 id: root
10 + // The inhibit widget keeps the current bar's manual keep-awake control in
11 + // Quickshell state. It emits a plain signal so the bar can decide the actual
12 + // Wayland idle-inhibit mechanism without coupling this button to a window.
10 13 property bool inhibiting: false
11 14 property int durationIndex: 3
12 15 readonly property var durations: [

quickshell/nugu/PowerWidget.qml

Modified
7 7 Item {
8 8 id: root
10 + // Bar power popup keeps the legacy quick actions visible while the confirmed
11 + // PowerMenu becomes the real replacement. Destructive actions stay dry-run
12 + // here so rollout cannot accidentally reboot or power off the session.
10 13 required property QtObject theme
11 14 required property QtObject commands
12 15 required property var barWindow

quickshell/nugu/README.md

Modified
18 18 qs -c nugu
21 -Run the self-contained scaffold smoke without touching live links/services:
21 +Run static self-contained checks and scaffold smoke without touching live links/services:
23 23 ```sh
24 +quickshell/nugu/audit.sh
24 25 quickshell/nugu/smoke.sh
25 26 NUGU_QS_SMOKE_SCREENSHOT_DIR=/tmp/nugu-qs-theme-smoke quickshell/nugu/smoke.sh
29 +The audit checks that QML imports stay local/Qt/Quickshell, every component has
30 +an early decision comment, the bundled palette matches `hypr/generated/nugu.json`,
31 +and retired companion launchers are not executable dependencies. It intentionally
32 +warns while transitional `cliphist` and `makoctl` bridges remain; those warnings
33 +must disappear before final retirement.
28 35 The smoke runner creates a temporary `HOME` and `XDG_CONFIG_HOME`, symlinks only
29 -this config as `quickshell/nugu`, verifies the copied palette still matches
30 -`hypr/generated/nugu.json`, starts `qs -c nugu`, checks
36 +this config as `quickshell/nugu`, runs the audit, starts `qs -c nugu`, checks
31 37 Diagnostics/bar/theme/hideAll IPC, and cleans up its own `qs` process. When
32 38 `NUGU_QS_SMOKE_SCREENSHOT_DIR` is set it saves cropped dark/light scaffold
33 39 screenshots from the focused monitor; the crop is limited to the top-left rollout

quickshell/nugu/audit.sh

Added
new file mode 100755
1 +#!/bin/sh
2 +set -eu
4 +# Static guard for the named Nugu Quickshell config. It checks repository
5 +# structure, not live user state, so it is safe to run before smoke tests and in
6 +# review without touching ~/.config or user services.
7 +config_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
8 +repo_dir=$(CDPATH= cd -- "$config_dir/../.." && pwd -P)
10 +python - "$config_dir" "$repo_dir" <<'PY'
11 +from pathlib import Path
12 +import re
13 +import sys
15 +config_dir = Path(sys.argv[1])
16 +repo_dir = Path(sys.argv[2])
17 +errors = []
18 +warnings = []
19 +qml_files = sorted(config_dir.glob("*.qml"))
21 +if not qml_files:
22 + errors.append("no QML files found")
24 +allowed_imports = ("QtQuick", "Quickshell")
25 +for path in qml_files:
26 + text = path.read_text()
27 + rel = path.relative_to(config_dir)
28 + lines = text.splitlines()
30 + for number, line in enumerate(lines, 1):
31 + stripped = line.strip()
32 + if not stripped.startswith("import "):
33 + continue
34 + target = stripped.split(maxsplit=1)[1]
35 + if target == '"."':
36 + continue
37 + if target.startswith(allowed_imports):
38 + continue
39 + errors.append(f"{rel}:{number}: non-self-contained import {target}")
41 + early = lines[:40]
42 + if not any(line.strip().startswith("//") for line in early):
43 + errors.append(f"{rel}: missing early decision comment")
45 + code_lines = []
46 + for line in lines:
47 + code_lines.append(line.split("//", 1)[0])
48 + code = "\n".join(code_lines)
49 + for forbidden in ("hyprlauncher", "hyprshutdown", "hyprctl notify"):
50 + if forbidden in code:
51 + errors.append(f"{rel}: executable dependency on retired companion marker {forbidden!r}")
53 +palette = config_dir / "nugu.json"
54 +generated = repo_dir / "hypr" / "generated" / "nugu.json"
55 +if not palette.exists():
56 + errors.append("missing bundled nugu.json")
57 +elif generated.exists() and palette.read_text() != generated.read_text():
58 + errors.append("quickshell/nugu/nugu.json differs from hypr/generated/nugu.json")
60 +# These are known transitional bridges, not hidden dependencies. Keep them
61 +# visible so they cannot be mistaken for final parity.
62 +all_code = "\n".join(p.read_text() for p in qml_files)
63 +for command in ("cliphist", "makoctl"):
64 + if command in all_code:
65 + warnings.append(f"transitional external bridge still present: {command}")
67 +if errors:
68 + print("FAIL nugu quickshell audit")
69 + for error in errors:
70 + print(f"ERROR {error}")
71 + for warning in warnings:
72 + print(f"WARN {warning}")
73 + sys.exit(1)
75 +print("PASS nugu quickshell audit")
76 +print(f"qml_files={len(qml_files)}")
77 +for warning in warnings:
78 + print(f"WARN {warning}")
79 +PY

quickshell/nugu/smoke.sh

Modified
133 133 : >"$log_out"
134 134 : >"$log_err"
136 -# Runtime stays self-contained, but the tracked copy must not drift from the
137 -# generated Hypr Nugu palette it mirrors.
138 -if ! cmp -s "$config_dir/nugu.json" "$repo_dir/hypr/generated/nugu.json"; then
139 - fail 'quickshell/nugu/nugu.json differs from hypr/generated/nugu.json'
140 -fi
136 +audit_output=$("$config_dir/audit.sh") || fail 'static Quickshell audit failed'
142 138 cd "$repo_dir"
143 139 HOME="$home_tmp" XDG_CONFIG_HOME="$tmp" QS_NO_RELOAD_POPUP=1 qs -c nugu >"$log_out" 2>"$log_err" &
235 231 printf 'PASS nugu quickshell scaffold smoke\n'
232 +printf '%s\n' "$audit_output"
236 233 printf 'initial=%s\n' "$state_initial"
237 234 printf 'dark_open=%s\n' "$state_dark_open"
238 235 printf 'dark_theme_state=%s\n' "$theme_dark_state"