repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit component inventory

f5ae0d935c460655317f6fde700082ea62d3660d

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`, `audit.sh`, `smoke.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `audit.sh`, `smoke.sh`.
16 +- every QML component is listed in `COMPONENTS.md` with purpose and rollout status.
16 17 - QML imports are limited to Qt, Quickshell, and local `import "."`.
17 18 - every QML component has an early decision comment.
18 19 - local resource references are audited; currently only bundled `nugu.json` is allowed via `Qt.resolvedUrl`.
44 45 ```text
45 46 PASS nugu quickshell audit
46 47 qml_files=29
47 -required_files=shell.qml,Theme.qml,nugu.json,README.md,audit.sh,smoke.sh
48 +documented_components=29
49 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,audit.sh,smoke.sh
48 50 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
49 51 WARN transitional external bridge still present: cliphist
50 52 WARN transitional external bridge still present: makoctl
51 53 PASS nugu quickshell scaffold smoke
52 54 PASS nugu quickshell audit
53 55 qml_files=29
54 -required_files=shell.qml,Theme.qml,nugu.json,README.md,audit.sh,smoke.sh
56 +documented_components=29
57 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,audit.sh,smoke.sh
55 58 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
56 59 WARN transitional external bridge still present: cliphist
57 60 WARN transitional external bridge still present: makoctl

quickshell/nugu/COMPONENTS.md

Added
new file mode 100644
1 +# Nugu Quickshell component inventory
3 +This file is part of the self-contained named config. It documents why each QML
4 +file exists so the replacement stays understandable while Ironbar, Mako,
5 +hyprlauncher, and the old Hypr helper paths are retired in stages.
7 +| Component | Why it exists | Current rollout status |
8 +| --- | --- | --- |
9 +| `shell.qml` | Owns shared state, IPC, and surface wiring so Hypr binds can later target one stable Quickshell namespace. | Scaffold root; hidden-by-default rollout. |
10 +| `Theme.qml` | Loads bundled Nugu tokens and follows or previews dark/light mode without writing global desktop state. | Verified by token, auto, preview, and screenshot smoke. |
11 +| `Commands.qml` | Keeps external process boundaries out of widgets so Hypr config simplification becomes IPC calls, not per-widget archaeology. | Transitional command bridge; destructive paths gated. |
12 +| `Diagnostics.qml` | Provides a safe visual probe for theme tokens and IPC before replacing live services. | Verified in dark/light screenshots. |
13 +| `Bar.qml` | Recreates the Ironbar top bar as one Quickshell layer-shell surface per monitor. | Hidden until parity approval. |
14 +| `BarButton.qml` | Shared small text/icon primitive for bar controls that need consistent Nugu hover/active states. | Internal primitive. |
15 +| `StatusItem.qml` | Shared status widget primitive that enforces Nugu signal/contrast semantics across bar modules. | Internal primitive; contrast checked. |
16 +| `WorkspaceWidget.qml` | Replaces Ironbar workspace display/click behavior using Quickshell Hyprland service data. | Implemented; full live parity pending. |
17 +| `ClockWidget.qml` | Replaces Ironbar clock and anchors the calendar popup without external applets. | Implemented; screenshot checked. |
18 +| `CalendarPopup.qml` | Keeps the clock calendar inside Quickshell/Nugu instead of launching a separate calendar UI. | Implemented; style parity pending. |
19 +| `MediaWidget.qml` | Replaces media status using Quickshell MPRIS data rather than shell polling. | Implemented; blocked by user DBus/MPRIS health. |
20 +| `VolumeWidget.qml` | Replaces volume status and click/scroll controls using PipeWire service state. | Implemented; wheel parity still needs live validation. |
21 +| `BrightnessWidget.qml` | Replaces brightness status and scroll actions while keeping brightnessctl as the system backend. | Implemented; live wheel validation pending. |
22 +| `BatteryWidget.qml` | Replaces battery status using UPower service data. | Implemented. |
23 +| `CpuWidget.qml` | Replaces CPU percentage display with lightweight `/proc/stat` polling. | Implemented. |
24 +| `WifiWidget.qml` | Replaces WiFi status using the current iwd backend. | Implemented. |
25 +| `BluetoothWidget.qml` | Replaces Bluetooth status with Quickshell Bluetooth service data. | Implemented. |
26 +| `TrayWidget.qml` | Replaces Ironbar tray display and menu forwarding with Quickshell tray services. | Implemented; real tray-client menu validation pending. |
27 +| `NotificationBridgeWidget.qml` | Preserves Mako count/restore/dismiss bar parity while native notifications are gated. | Transitional Mako bridge. |
28 +| `NotificationDaemon.qml` | Native notification daemon candidate to replace Mako after DBus parity tests. | Implemented but disabled by default. |
29 +| `NotificationToast.qml` | Renders native notification toasts in Nugu style when the daemon is enabled. | Implemented but gated. |
30 +| `ClipboardWidget.qml` | Provides small bar clipboard preview parity while the full picker handles search/selection. | Transitional cliphist bridge. |
31 +| `ClipboardPicker.qml` | Replaces the old launcher-based clipboard picker frontend while retaining cliphist storage for safety. | Implemented; storage replacement deferred. |
32 +| `Launcher.qml` | Replaces the old launcher with native DesktopEntries search and app execution. | Implemented; bind migration pending. |
33 +| `Osd.qml` | Replaces transient `hyprctl notify` surfaces with a Nugu Quickshell OSD. | Implemented; remaining actions need live validation. |
34 +| `PowerWidget.qml` | Keeps bar power affordances while destructive actions remain dry-run during rollout. | Transitional bar popup. |
35 +| `PowerMenu.qml` | Provides the future confirmed power menu with two-step destructive actions. | Implemented; non-lock actions gated. |
36 +| `InhibitWidget.qml` | Preserves manual keep-awake bar control without coupling the button to a specific window. | Implemented. |
37 +| `BindModeWidget.qml` | Keeps a hidden bind-mode surface for future Hypr submap visibility. | Implemented; hidden until bind migration. |

quickshell/nugu/README.md

Modified
26 26 NUGU_QS_SMOKE_SCREENSHOT_DIR=/tmp/nugu-qs-theme-smoke quickshell/nugu/smoke.sh
29 -The audit checks that required named-config files are present, QML imports stay
30 -local/Qt/Quickshell, every component has an early decision comment, local
31 -resources are audited, the bundled palette matches `hypr/generated/nugu.json`,
32 -and retired companion launchers are not executable dependencies. It intentionally
33 -warns while transitional `cliphist` and `makoctl` bridges remain; those warnings
34 -must disappear before final retirement.
29 +`COMPONENTS.md` inventories every QML file with why it exists and current rollout
30 +status. The audit checks that required named-config files are present, every QML
31 +component is documented there, QML imports stay local/Qt/Quickshell, every
32 +component has an early decision comment, local resources are audited, the bundled
33 +palette matches `hypr/generated/nugu.json`, and retired companion launchers are
34 +not executable dependencies. It intentionally warns while transitional `cliphist`
35 +and `makoctl` bridges remain; those warnings must disappear before final
36 +retirement.
36 38 The smoke runner creates a temporary `HOME` and `XDG_CONFIG_HOME`, symlinks only
37 39 this config as `quickshell/nugu`, runs the audit, starts `qs -c nugu`, checks

quickshell/nugu/audit.sh

Modified
18 18 warnings = []
19 19 qml_files = sorted(config_dir.glob("*.qml"))
20 20 code_by_file = {}
21 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "audit.sh", "smoke.sh")
21 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "audit.sh", "smoke.sh")
23 23 for name in required_files:
24 24 if not (config_dir / name).exists():
27 27 if not qml_files:
28 28 errors.append("no QML files found")
30 +components_doc = config_dir / "COMPONENTS.md"
31 +if components_doc.exists():
32 + documented = set(re.findall(r"`([^`]+\.qml)`", components_doc.read_text()))
33 + actual = {path.name for path in qml_files}
34 + missing = sorted(actual - documented)
35 + stale = sorted(documented - actual)
36 + for name in missing:
37 + errors.append(f"COMPONENTS.md missing QML component {name}")
38 + for name in stale:
39 + errors.append(f"COMPONENTS.md references missing QML component {name}")
40 +else:
41 + documented = set()
30 43 allowed_imports = ("QtQuick", "Quickshell")
31 44 for path in qml_files:
32 45 text = path.read_text()
145 158 print("PASS nugu quickshell audit")
146 159 print(f"qml_files={len(qml_files)}")
160 +print(f"documented_components={len(documented)}")
147 161 print("required_files=" + ",".join(required_files))
148 162 if detected:
149 163 print("external_commands=" + ",".join(command for command, _reason in detected))