gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Drop the extension, and give the test suite a front door

Browse Source 
Phase 6, the last of the fresh-install spec.

159 scripts lose their .sh: 110 contracts, 47 Vicinae commands, 2 compositor
contracts. A shebang and the executable bit already select the interpreter. The
extension only ever added something that had to stay in sync, and the rename
proved the point twice over in the space of an hour.

The spec's stated risk was Vicinae's script discovery. One script was renamed and
reloaded on its own before the other 46 followed; it came back as
scripts:panama.capture and all 47 resolve. What the probe turned up instead is
that the extension was never only a filename: Vicinae's command IDs embed it, so
every ID changed. Nothing in this repository refers to them, so nothing breaks.
The only trace is Vicinae's metadata.json, whose visited map had two Panama
entries that are now orphaned -- two commands lost their usage ranking and will
earn it back. Worth knowing before anyone renames these again on a machine that
has a keybind pointing at one.

Rewriting the references by exact filename missed two things it structurally
could not see: a name built from a variable, settings-$page.sh, and a glob,
-name '*.sh'. Both were in the contract that counts the generated commands, which
promptly reported 47 expected and 0 found. The mechanical part of a rename is the
part that looks finished.

The three subcommands. panama doctor fronts a health check that already existed
and already ran at the end of every install but could not be reached from a
terminal. panama upgrade re-runs the installer from anywhere. panama test runs
the suite, which had no entry point at all -- 121 files that were the main safety
net in this repository and were invisible in it.

Writing that runner found three tests nothing was running.
calendar_agenda_bridge_test, home_assistant_bridge_test and kdeconnect_bridge_test
are unittest suites without the executable bit, so no contract invoked them and
the first draft of the runner skipped them silently. All three pass, and have
passed unobserved for weeks. The runner collects *_test.py as well now, because a
runner with a blind spot is worse than no runner for the same reason a dependency
checker with one is: it reports PASS.

Six worktrees pruned. Each was re-checked rather than trusted to the spec's list,
and two needed it: panama-commands is not on feat/panama-commands but on
feat/gnome-tweaks-parity, and fix/panama-displays-review reads [ahead 3] -- ahead
of its remote, not of main, with every commit patch-equivalent to landed work.
roadmap-completion stays; it has five commits that are genuinely unlanded. The
branches are left alone: pruning a worktree costs nothing, deleting a branch is a
decision.

121 contracts pass.

Claude-Session: https://claude.ai/code/session_01NvgBuSWB5sE43yWmg21ozj
This commit is contained in:
Gabriel Brown
2026-08-20 21:55:55 -04:00
parent 47f29f9fa9
commit e1faaf7a76
185 changed files with 533 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-08-17-home-accessories-customization.md
+52 -52
View File
@@ -31,14 +31,14 @@
- `config/dot/quickshell/scripts/panama-home-assistant` — credential-safe catalog, action authorization, brightness parsing, and Home Assistant REST calls.
- `tests/quickshell/home_assistant_bridge_test.py` — fake-server unit tests for filtering, normalization, authorization, payloads, and redaction.
- `tests/quickshell/home-assistant-helper-contract.sh` — live read-only probe/catalog shape check; it never invokes an action command.
- `tests/quickshell/home-assistant-helper-contract` — live read-only probe/catalog shape check; it never invokes an action command.
- `config/dot/quickshell/config/HomePreferences.qml` — sole durable owner of initialization state and ordered `{id, alias}` favorites.
- `config/dot/quickshell/config/qmldir` — registers `HomePreferences` as a singleton.
- `config/dot/quickshell/home-preferences-harness.qml` — isolated IPC surface for preference mutation and restart tests.
- `tests/quickshell/home-preferences-contract.sh` — first-run, empty-state, alias, reorder, remove, and restart-persistence contract.
- `tests/quickshell/home-preferences-contract` — first-run, empty-state, alias, reorder, remove, and restart-persistence contract.
- `config/dot/quickshell/services/HomeAssistant.qml` — complete catalog, preference resolution, four-item shelf, fixtures, sequential action queue, and per-entity pending/error maps.
- `config/dot/quickshell/shell.qml` — typed Home Assistant diagnostics/actions for fixture-only testing and Home & Phone routing.
- `tests/quickshell/control-center-services-contract.sh` — service-model and per-light action-state contract using fixtures only.
- `tests/quickshell/control-center-services-contract` — service-model and per-light action-state contract using fixtures only.
- `config/dot/quickshell/services/SystemSettings.qml` — BlueBubbles installed-state query and fixed allow-listed launch vector.
- `config/dot/quickshell/modules/settings/HomePhonePage.qml` — page composition, connection health, search, selected/available sections, save error, and phone continuity.
- `config/dot/quickshell/modules/settings/HomeFavoriteCard.qml` — editable alias, source name, first-four badge, remove action, and drag handle.
@@ -47,14 +47,14 @@
- `config/dot/quickshell/modules/settings/SettingsShell.qml` — page loader registration.
- `config/dot/quickshell/modules/settings/qmldir` — component registrations.
- `config/dot/quickshell/services/ShellState.qml` — `home-phone` settings-page allow-list entry.
- `tests/quickshell/settings-pages-contract.sh` — route and single-window behavior.
- `tests/quickshell/home-phone-settings-contract.sh` — static and fixture-driven settings-page behavior without writing the user's real preferences.
- `tests/quickshell/settings-pages-contract` — route and single-window behavior.
- `tests/quickshell/home-phone-settings-contract` — static and fixture-driven settings-page behavior without writing the user's real preferences.
- `config/dot/quickshell/modules/quicksettings/HomeBrightnessSlider.qml` — local preview and one-shot commit interaction.
- `config/dot/quickshell/modules/quicksettings/HomeTile.qml` — polished power, state, percent, dimmer, busy, and inline-error presentation.
- `config/dot/quickshell/modules/quicksettings/HomeControls.qml` — resting/expanded shelf, setup state, stale state, and Manage in Settings row.
- `config/dot/quickshell/modules/quicksettings/PhoneControls.qml` — four equal actions and independent Messages enablement.
- `tests/quickshell/control-center-contract.sh` — mapped panel, exclusive expansion, component presence, and approved shelf structure.
- `tests/quickshell/phone-messages-contract.sh` — BlueBubbles detection/allow-list/independent-enable contract; it never invokes the action.
- `tests/quickshell/control-center-contract` — mapped panel, exclusive expansion, component presence, and approved shelf structure.
- `tests/quickshell/phone-messages-contract` — BlueBubbles detection/allow-list/independent-enable contract; it never invokes the action.
---
@@ -63,7 +63,7 @@
**Files:**
- Modify: `config/dot/quickshell/scripts/panama-home-assistant:44-434`
- Modify: `tests/quickshell/home_assistant_bridge_test.py:25-182`
- Modify: `tests/quickshell/home-assistant-helper-contract.sh:1-29`
- Modify: `tests/quickshell/home-assistant-helper-contract:1-29`
**Interfaces:**
- Consumes: `Config(base_url: str, token: str, entity_ids: tuple[str, ...])`, `request_json(config, method, path, payload)` and current URL/token/legacy resolution.
@@ -225,7 +225,7 @@ Do not print the discovery response, request body, URL, or token on action failu
- [x] **Step 6: Make unit and live read-only contracts GREEN**
Update `home-assistant-helper-contract.sh` to call `catalog`, assert the exact seven entity keys, assert `legacyEntityIds` is an array, and report only the count:
Update `home-assistant-helper-contract` to call `catalog`, assert the exact seven entity keys, assert `legacyEntityIds` is an array, and report only the count:
```bash
catalog="$($helper catalog)"
@@ -242,7 +242,7 @@ Run:
```bash
python3 tests/quickshell/home_assistant_bridge_test.py -v
tests/quickshell/home-assistant-helper-contract.sh
tests/quickshell/home-assistant-helper-contract
```
Expected: all unit tests PASS; the live contract prints a redacted light count and performs GET requests only.
@@ -252,7 +252,7 @@ Expected: all unit tests PASS; the live contract prints a redacted light count a
```bash
git add config/dot/quickshell/scripts/panama-home-assistant \
tests/quickshell/home_assistant_bridge_test.py \
tests/quickshell/home-assistant-helper-contract.sh
tests/quickshell/home-assistant-helper-contract
git commit -m "Add Home Assistant light catalog and dimming"
```
@@ -264,7 +264,7 @@ git commit -m "Add Home Assistant light catalog and dimming"
- Create: `config/dot/quickshell/config/HomePreferences.qml`
- Modify: `config/dot/quickshell/config/qmldir:1-4`
- Create: `config/dot/quickshell/home-preferences-harness.qml`
- Create: `tests/quickshell/home-preferences-contract.sh`
- Create: `tests/quickshell/home-preferences-contract`
**Interfaces:**
- Consumes: top-level helper field `legacyEntityIds: string[]` after the first successful catalog.
@@ -307,7 +307,7 @@ Then remove both records, restart again, call `initialize` with a different lega
Run:
```bash
tests/quickshell/home-preferences-contract.sh
tests/quickshell/home-preferences-contract
```
Expected: FAIL because the singleton and harness do not exist.
@@ -344,7 +344,7 @@ Use a 180 ms single-shot persistence timer. `initialize()` filters IDs through `
Run:
```bash
tests/quickshell/home-preferences-contract.sh
tests/quickshell/home-preferences-contract
```
Expected: PASS for initial migration, trim, reorder, remove, restart persistence, and initialized-empty behavior. The temporary file is valid JSON and contains no credential-like fields.
@@ -355,7 +355,7 @@ Expected: PASS for initial migration, trim, reorder, remove, restart persistence
git add config/dot/quickshell/config/HomePreferences.qml \
config/dot/quickshell/config/qmldir \
config/dot/quickshell/home-preferences-harness.qml \
tests/quickshell/home-preferences-contract.sh
tests/quickshell/home-preferences-contract
git commit -m "Persist Home accessory preferences"
```
@@ -366,7 +366,7 @@ git commit -m "Persist Home accessory preferences"
**Files:**
- Modify: `config/dot/quickshell/services/HomeAssistant.qml:1-185`
- Modify: `config/dot/quickshell/shell.qml:252-272`
- Modify: `tests/quickshell/control-center-services-contract.sh:10-90`
- Modify: `tests/quickshell/control-center-services-contract:10-90`
**Interfaces:**
- Consumes: helper `catalog`, `toggle ENTITY_ID`, and `brightness ENTITY_ID PERCENT`; all `HomePreferences` interfaces from Task 2.
@@ -394,7 +394,7 @@ Add `missing-selected` and `action-error` fixtures. `missing-selected` retains o
Run:
```bash
tests/quickshell/control-center-services-contract.sh
tests/quickshell/control-center-services-contract
```
Expected: the new catalog counts, selected IDs, brightness fixture action, and per-entity errors are absent.
@@ -480,8 +480,8 @@ Fixture actions update only in-memory fixture catalog. `clearFixture()` clears f
Run:
```bash
tests/quickshell/home-preferences-contract.sh
tests/quickshell/control-center-services-contract.sh
tests/quickshell/home-preferences-contract
tests/quickshell/control-center-services-contract
```
Expected: both PASS; fixture cleanup returns live mode and the durable preference contract remains unchanged.
@@ -491,7 +491,7 @@ Expected: both PASS; fixture cleanup returns live mode and the durable preferenc
```bash
git add config/dot/quickshell/services/HomeAssistant.qml \
config/dot/quickshell/shell.qml \
tests/quickshell/control-center-services-contract.sh
tests/quickshell/control-center-services-contract
git commit -m "Compose Home catalog with accessory preferences"
```
@@ -509,8 +509,8 @@ git commit -m "Compose Home catalog with accessory preferences"
- Modify: `config/dot/quickshell/modules/settings/qmldir:1-19`
- Modify: `config/dot/quickshell/services/ShellState.qml:94-99`
- Modify: `config/dot/quickshell/shell.qml:274-299`
- Modify: `tests/quickshell/settings-pages-contract.sh:15-28`
- Create: `tests/quickshell/home-phone-settings-contract.sh`
- Modify: `tests/quickshell/settings-pages-contract:15-28`
- Create: `tests/quickshell/home-phone-settings-contract`
**Interfaces:**
- Consumes: `HomeAssistant.catalog`, `selectedEntities`, `discoveredCount`, phase/stale/error, `refresh()`, `open()`; all `HomePreferences` mutators; `SystemSettings.bluebubblesAvailable` and `openApplication("bluebubbles")`.
@@ -539,8 +539,8 @@ Using the ready fixture, route Settings to `home-phone` and assert one tiled `Pa
Run:
```bash
tests/quickshell/settings-pages-contract.sh
tests/quickshell/home-phone-settings-contract.sh
tests/quickshell/settings-pages-contract
tests/quickshell/home-phone-settings-contract
```
Expected: `home-phone` falls back to Home and the new components are missing.
@@ -629,10 +629,10 @@ Extend settings diagnostics with read-only counts:
Run:
```bash
tests/quickshell/settings-system-contract.sh
tests/quickshell/settings-pages-contract.sh
tests/quickshell/home-phone-settings-contract.sh
tests/quickshell/home-preferences-contract.sh
tests/quickshell/settings-system-contract
tests/quickshell/settings-pages-contract
tests/quickshell/home-phone-settings-contract
tests/quickshell/home-preferences-contract
```
Expected: all PASS; Panama Settings remains one normal tiled client, fixture tests leave real Home preferences unchanged, and no BlueBubbles process starts.
@@ -649,8 +649,8 @@ git add config/dot/quickshell/services/SystemSettings.qml \
config/dot/quickshell/modules/settings/qmldir \
config/dot/quickshell/services/ShellState.qml \
config/dot/quickshell/shell.qml \
tests/quickshell/settings-pages-contract.sh \
tests/quickshell/home-phone-settings-contract.sh
tests/quickshell/settings-pages-contract \
tests/quickshell/home-phone-settings-contract
git commit -m "Add Home and Phone settings"
```
@@ -663,7 +663,7 @@ git commit -m "Add Home and Phone settings"
- Modify: `config/dot/quickshell/modules/quicksettings/HomeTile.qml:1-73`
- Modify: `config/dot/quickshell/modules/quicksettings/HomeControls.qml:1-280`
- Modify: `config/dot/quickshell/modules/quicksettings/qmldir`
- Modify: `tests/quickshell/control-center-contract.sh:19-72`
- Modify: `tests/quickshell/control-center-contract:19-72`
**Interfaces:**
- Consumes: `HomeAssistant.visibleEntities`, `selectedEntities`, `isBusy(id)`, `pendingFor(id)`, `errorFor(id)`, `toggleEntity(id)`, `setBrightness(id, percent)`, phase/stale, refresh/open; `ShellState.openSettings("home-phone")`.
@@ -689,7 +689,7 @@ Keep the live panel mapping and exclusive expansion assertions. Add ready-fixtur
Run:
```bash
tests/quickshell/control-center-contract.sh
tests/quickshell/control-center-contract
```
Expected: the two-column shelf, slider, and Home & Phone management route are absent.
@@ -733,8 +733,8 @@ At the expanded list footer add `Manage in Settings`, which closes Control Cente
Run:
```bash
tests/quickshell/control-center-services-contract.sh
tests/quickshell/control-center-contract.sh
tests/quickshell/control-center-services-contract
tests/quickshell/control-center-contract
```
Expected: PASS. Opening and expanding Home maps one panel, displays the fixture shelf, and does not invoke the real Home Assistant API.
@@ -746,7 +746,7 @@ git add config/dot/quickshell/modules/quicksettings/HomeBrightnessSlider.qml \
config/dot/quickshell/modules/quicksettings/HomeTile.qml \
config/dot/quickshell/modules/quicksettings/HomeControls.qml \
config/dot/quickshell/modules/quicksettings/qmldir \
tests/quickshell/control-center-contract.sh
tests/quickshell/control-center-contract
git commit -m "Build the Home accessory shelf"
```
@@ -756,8 +756,8 @@ git commit -m "Build the Home accessory shelf"
**Files:**
- Modify: `config/dot/quickshell/modules/quicksettings/PhoneControls.qml:1-273`
- Create: `tests/quickshell/phone-messages-contract.sh`
- Modify: `tests/quickshell/control-center-contract.sh:41-72`
- Create: `tests/quickshell/phone-messages-contract`
- Modify: `tests/quickshell/control-center-contract:41-72`
**Interfaces:**
- Consumes: `SystemSettings.bluebubblesAvailable`, `SystemSettings.openApplication("bluebubbles")`, and existing KDE Connect capability/reachability/action interfaces.
@@ -774,7 +774,7 @@ Add a guard that fails if the script contains `openApplication` in an executed `
Run:
```bash
tests/quickshell/phone-messages-contract.sh
tests/quickshell/phone-messages-contract
```
Expected: FAIL because PhoneControls still has three KDE-only actions.
@@ -803,9 +803,9 @@ When BlueBubbles is absent, append one quiet detail row: `BlueBubbles is not ins
Run:
```bash
tests/quickshell/phone-messages-contract.sh
tests/quickshell/control-center-contract.sh
tests/quickshell/control-center-services-contract.sh
tests/quickshell/phone-messages-contract
tests/quickshell/control-center-contract
tests/quickshell/control-center-services-contract
```
Expected: PASS; the offline KDE fixture still exposes an enabled Messages action when BlueBubbles is installed, and no client launches during testing.
@@ -814,8 +814,8 @@ Expected: PASS; the offline KDE fixture still exposes an enabled Messages action
```bash
git add config/dot/quickshell/modules/quicksettings/PhoneControls.qml \
tests/quickshell/phone-messages-contract.sh \
tests/quickshell/control-center-contract.sh
tests/quickshell/phone-messages-contract \
tests/quickshell/control-center-contract
git commit -m "Add BlueBubbles to Phone controls"
```
@@ -850,14 +850,14 @@ Run:
```bash
python3 tests/quickshell/home_assistant_bridge_test.py -v
tests/quickshell/home-assistant-helper-contract.sh
tests/quickshell/home-preferences-contract.sh
tests/quickshell/control-center-services-contract.sh
tests/quickshell/home-phone-settings-contract.sh
tests/quickshell/phone-messages-contract.sh
tests/quickshell/control-center-contract.sh
tests/quickshell/settings-system-contract.sh
tests/quickshell/settings-pages-contract.sh
tests/quickshell/home-assistant-helper-contract
tests/quickshell/home-preferences-contract
tests/quickshell/control-center-services-contract
tests/quickshell/home-phone-settings-contract
tests/quickshell/phone-messages-contract
tests/quickshell/control-center-contract
tests/quickshell/settings-system-contract
tests/quickshell/settings-pages-contract
```
Expected: every command exits 0. The helper contract performs read-only GETs; fixtures perform no real light action; BlueBubbles remains closed unless it was already open.
@@ -867,7 +867,7 @@ Expected: every command exits 0. The helper contract performs read-only GETs; fi
Run:
```bash
for test in tests/quickshell/*contract.sh; do
for test in tests/quickshell/*contract; do
printf 'Running %s\n' "$test"
"$test"
done