repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

test(quickshell): add live readiness check

feeb151760fbabca98013f4f146cada82126d24f

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

docs/super/inventory/2026-06-17-quickshell-live-readiness-check.md

Added
new file mode 100644
1 +# Quickshell live readiness check
3 +Date: 2026-06-17
5 +## Scope
7 +Add a read-only gate for final rollout readiness. This does not link config,
8 +enable/start/stop services, restart DBus, simplify Hypr, or retire Ironbar/Mako.
10 +## Command
12 +```sh
13 +cd /home/oli/Workspace/dotfiles
14 +quickshell/nugu/live-check.sh
15 +```
17 +## Observed
19 +```text
20 +OK command:qs
21 +OK command:systemctl
22 +OK command:systemd-analyze
23 +OK command:busctl
24 +OK command:hyprctl
25 +OK static_audit
26 +OK quickshell_service_unit_verify
27 +BLOCK config_link:not_linked
28 +BLOCK service_link:not_linked
29 +BLOCK service:quickshell.service:inactive expected:active
30 +BLOCK service:ironbar.service:active expected:inactive
31 +BLOCK service:ironbar-workspaces.service:active expected:inactive
32 +BLOCK service:mako.service:active expected:inactive
33 +BLOCK qs_process_absent
34 +BLOCK user_dbus_busctl_failed
35 +OK hypr_config_errors_empty
36 +INFO blocks=8
37 +live_check_exit=0
38 +strict_exit=1
39 +```
41 +Default mode exits `0` so it can be used as a status report while rollout is
42 +intentionally incomplete. `--strict` is available for the final gate and exits
43 +nonzero while any block remains; current strict exit is `1` because rollout is
44 +not complete.
46 +## Boundary
48 +These blockers are expected now. They prove the goal is still incomplete:
50 +- live dorkfiles links are absent;
51 +- `quickshell.service` is inactive;
52 +- Ironbar and Mako remain authoritative;
53 +- no `qs` process is live;
54 +- user DBus is still unhealthy for notification/MPRIS parity.

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`, `SERVICE.md`, `PARITY.md`, `audit.sh`, `smoke.sh`.
16 -- `README.md` links the required inventories, service/parity contracts, smoke/audit gates, named config command, and IPC command form.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `SERVICE.md`, `PARITY.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
16 +- `README.md` links the required inventories, service/parity contracts, smoke/audit/live-check gates, named config command, and IPC command form.
17 17 - every QML component is listed in `COMPONENTS.md` with purpose and rollout status.
18 18 - every `nugu` IPC method from `shell.qml` is listed in `IPC.md` with purpose and rollout status.
19 19 - component, IPC, and external inventory rows reject duplicates, malformed names, thin text, and placeholder wording.
45 45 quickshell/nugu/audit.sh
46 46 systemd-analyze --user verify hypr/systemd/quickshell.service
47 47 sh -n quickshell/nugu/smoke.sh
48 +sh -n quickshell/nugu/live-check.sh
48 49 quickshell/nugu/smoke.sh
49 50 pgrep -a qs || true
61 62 documented_external_commands=25
62 63 detected_external_commands=25
63 64 docs_index=ok
65 +live_check=ok
64 66 inventory_tables=ok
65 67 service_contract=ok
66 68 parity_matrix=ok
68 70 rollout_boundary=ok
69 71 contrast_pairs=12
70 72 contrast_min=5.50
71 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh
73 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
72 74 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
73 75 WARN transitional external bridge still present: cliphist
74 76 WARN transitional external bridge still present: makoctl
82 84 documented_external_commands=25
83 85 detected_external_commands=25
84 86 docs_index=ok
87 +live_check=ok
85 88 inventory_tables=ok
86 89 service_contract=ok
87 90 parity_matrix=ok
89 92 rollout_boundary=ok
90 93 contrast_pairs=12
91 94 contrast_min=5.50
92 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh
95 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
93 96 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
94 97 WARN transitional external bridge still present: cliphist
95 98 WARN transitional external bridge still present: makoctl

quickshell/nugu/README.md

Modified
23 23 ```sh
24 24 quickshell/nugu/audit.sh
25 25 quickshell/nugu/smoke.sh
26 +quickshell/nugu/live-check.sh
26 27 NUGU_QS_SMOKE_SCREENSHOT_DIR=/tmp/nugu-qs-theme-smoke quickshell/nugu/smoke.sh
31 32 `EXTERNALS.md` inventories every approved executable boundary. `SERVICE.md`
32 33 documents the future user-service rollout contract without activating it.
33 34 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
34 -and retirement gates. The audit checks that required named-config files are present, every QML component and IPC method
35 +and retirement gates. `live-check.sh` reports final rollout blockers without mutating live services or links. The audit checks that required named-config files are present, every QML component and IPC method
35 36 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
36 37 early decision/why comment, QML has no unresolved TODO/stub comments, local resources
37 38 are audited, the bundled palette matches

quickshell/nugu/audit.sh

Modified
20 20 qml_files = sorted(config_dir.glob("*.qml"))
21 21 code_by_file = {}
22 22 decision_comment_files = set()
23 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh")
23 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh")
25 25 for name in required_files:
26 26 if not (config_dir / name).exists():
29 29 readme_path = config_dir / "README.md"
30 30 if readme_path.exists():
31 31 readme_text = readme_path.read_text()
32 - for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "qs -c nugu", "qs ipc -c nugu"):
32 + for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
33 33 if marker not in readme_text:
34 34 errors.append(f"README.md missing self-contained entry marker {marker!r}")
35 35 else:
353 353 print(f"documented_external_commands={len(external_commands)}")
354 354 print(f"detected_external_commands={len(detected)}")
355 355 print("docs_index=ok")
356 +print("live_check=ok")
356 357 print("inventory_tables=ok")
357 358 print("service_contract=ok")
358 359 print("parity_matrix=ok")

quickshell/nugu/live-check.sh

Added
new file mode 100755
1 +#!/bin/sh
2 +set -eu
4 +# Read-only rollout check for the Nugu Quickshell replacement. It exists so live
5 +# activation blockers are visible before anyone links, enables, starts, stops, or
6 +# retires companion services.
7 +config_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
8 +repo_dir=$(CDPATH= cd -- "$config_dir/../.." && pwd -P)
9 +strict=${1:-}
10 +blocks=0
12 +ok() {
13 + printf 'OK %s\n' "$1"
16 +info() {
17 + printf 'INFO %s\n' "$1"
20 +block() {
21 + blocks=$((blocks + 1))
22 + printf 'BLOCK %s\n' "$1"
25 +check_command() {
26 + name=$1
27 + if command -v "$name" >/dev/null 2>&1; then
28 + ok "command:$name"
29 + else
30 + block "missing_command:$name"
31 + fi
34 +check_link() {
35 + label=$1
36 + live_path=$2
37 + expected_path=$3
38 + if [ -L "$live_path" ] && [ "$(readlink -f -- "$live_path")" = "$expected_path" ]; then
39 + ok "$label:linked"
40 + elif [ -e "$live_path" ]; then
41 + block "$label:not_managed_by_expected_link"
42 + else
43 + block "$label:not_linked"
44 + fi
47 +check_service_state() {
48 + service=$1
49 + expected=$2
50 + state=$(systemctl --user is-active "$service" 2>/dev/null || true)
51 + state=${state:-unknown}
52 + if [ "$state" = "$expected" ]; then
53 + ok "service:$service:$state"
54 + else
55 + block "service:$service:$state expected:$expected"
56 + fi
59 +check_command qs
60 +check_command systemctl
61 +check_command systemd-analyze
62 +check_command busctl
63 +check_command hyprctl
65 +if "$config_dir/audit.sh" >/dev/null; then
66 + ok 'static_audit'
67 +else
68 + block 'static_audit_failed'
69 +fi
71 +if systemd-analyze --user verify "$repo_dir/hypr/systemd/quickshell.service" >/dev/null 2>&1; then
72 + ok 'quickshell_service_unit_verify'
73 +else
74 + block 'quickshell_service_unit_verify_failed'
75 +fi
77 +check_link 'config_link' "$HOME/.config/quickshell/nugu" "$repo_dir/quickshell/nugu"
78 +check_link 'service_link' "$HOME/.config/systemd/user/quickshell.service" "$repo_dir/hypr/systemd/quickshell.service"
80 +check_service_state quickshell.service active
81 +check_service_state ironbar.service inactive
82 +check_service_state ironbar-workspaces.service inactive
83 +check_service_state mako.service inactive
85 +if pgrep -x qs >/dev/null 2>&1; then
86 + ok 'qs_process_present'
87 +else
88 + block 'qs_process_absent'
89 +fi
91 +if timeout 3 busctl --user --list --no-pager >/dev/null 2>&1; then
92 + ok 'user_dbus_busctl'
93 +else
94 + block 'user_dbus_busctl_failed'
95 +fi
97 +hypr_errors=$(hyprctl configerrors 2>/dev/null || true)
98 +if [ -n "$hypr_errors" ]; then
99 + block 'hypr_config_errors_present'
100 +else
101 + ok 'hypr_config_errors_empty'
104 +info "blocks=$blocks"
105 +if [ "$strict" = "--strict" ] && [ "$blocks" -ne 0 ]; then
106 + exit 1
108 +exit 0