From 1b323c2fa525c3106219c0d6b0481b5d5496cbd2 Mon Sep 17 00:00:00 2001 From: Gabriel Brown Date: Tue, 18 Aug 2026 01:36:30 -0400 Subject: [PATCH] Document Settings completion plan --- .../2026-08-18-settings-completion-codex.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-18-settings-completion-codex.md diff --git a/docs/superpowers/plans/2026-08-18-settings-completion-codex.md b/docs/superpowers/plans/2026-08-18-settings-completion-codex.md new file mode 100644 index 0000000..2babdb0 --- /dev/null +++ b/docs/superpowers/plans/2026-08-18-settings-completion-codex.md @@ -0,0 +1,119 @@ +# Panama Settings Completion Codex Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Complete Codex's portion of Panama Settings with default-application and autostart management, shared page scaffolds, and real controls for every remaining hardcoded shell behavior value. + +**Architecture:** `DefaultApps.qml` is the typed system boundary for freedesktop default handlers and user autostart entries; `ApplicationsPage.qml` binds reactively to `DesktopEntries.applications.values` and never snapshots the asynchronous model. Existing pages adopt `SettingsPage`; schema-bound values use `ChoiceRow`, `SliderRow`, and `ToggleRow`, while specialized controls and genuinely read-only facts remain specialized or use `TextRow`. + +**Tech Stack:** Quickshell 0.3 QML, QtQuick, `xdg-settings`, `xdg-mime`, freedesktop `.desktop` files, Bash/Python contract tests, Hyprland. + +**Spec:** `docs/superpowers/specs/2026-08-17-panama-cohesion-design.md` + +**Status:** Implemented and independently reviewed on 2026-08-18. The combined +verification gate is recorded in the integrating commit history. + +## Global Constraints + +- Claude owns and must be the only editor of `PreferenceSchema.qml`, `SettingsSidebar.qml`, `SettingsShell.qml`, `qmldir`, `ShellState.qml`, `SystemSettings.qml`, `AppearancePage.qml`, `DesktopPage.qml`, `ShortcutsPage.qml`, and `config/dot/hypr/*`. +- Never use `hyprctl keyword`; every `hl.bind` requires a description. +- Use `DesktopEntries.applications.values` in reactive bindings. Do not call `byId()` or `heuristicLookup()` in a one-time initialization path. +- Use `SettingRow.activatable` for whole-row clicks. Nested Repeaters address outer models through explicit ids, never `parent.modelData`. +- Only these verified GNOME panels may be opened: applications, background, bluetooth, color, display, keyboard, mouse, multitasking, network, notifications, online-accounts, power, printers, privacy, search, sharing, sound, system, universal-access, wacom, wellbeing, wifi, wwan. +- No mock phase, new visual direction, color literals, or idle animation. Preserve page copy and behavior unless a dead read-only row is replaced by a real control. +- Automated tests isolate XDG config/state, do not change live defaults or autostart entries, do not launch applications, and do not invoke Home actions. + +--- + +### Task 1: Applications, default handlers, and user autostart + +**Files:** +- Create: `config/dot/quickshell/services/DefaultApps.qml` +- Create: `config/dot/quickshell/modules/settings/ApplicationsPage.qml` +- Create only if needed for a safe parser/writer boundary: `config/dot/quickshell/scripts/panama-default-apps` +- Create: `tests/quickshell/default-apps-contract.sh` +- Create: `tests/quickshell/applications-settings-contract.sh` + +**Interfaces:** +- Consumes: `DesktopEntries.applications.values`, `SettingsPage`, `SettingsCard`, `SettingRow.activatable`, `ActionRow`, `TextRow`, and Claude-owned routing for page id `applications`. +- Produces: a singleton `DefaultApps` with reactive `handlers`, `autostartEntries`, `luaAutostartEntries`, `busy`, `lastError`, `refresh()`, `setDefault(role, desktopId)`, and `setAutostart(desktopId, enabled)`. + +- [x] **Step 1: Write failing helper/service and page contracts** + +Cover seven roles: browser (`xdg-settings default-web-browser`), mail (`x-scheme-handler/mailto`), files (`inode/directory`), terminal (`x-scheme-handler/terminal`), music (`audio/mpeg`), images (`image/png`), and video (`video/mp4`). Use temporary XDG directories and fake `xdg-settings`/`xdg-mime` binaries; assert setters pass separate arguments and reject unknown roles or desktop ids. Fixture user autostart entries must expose id/name/enabled and toggle with standard `Hidden=` semantics; `hl.exec_cmd` entries parsed from `config/dot/hypr/autostart.lua` are read-only and identify their source. + +The page contract must require `DesktopEntries.applications.values`, page id/object name, all seven role labels, user and compositor autostart sections, `SettingRow.activatable`, and must reject `Component.onCompleted` snapshots plus `byId()`/`heuristicLookup()`. + +- [x] **Step 2: Run focused contracts to verify RED** + +```bash +tests/quickshell/default-apps-contract.sh +tests/quickshell/applications-settings-contract.sh +``` + +Expected: fail because the service/page and behavior do not exist. + +- [x] **Step 3: Implement the minimal typed boundary and page** + +All process commands use argument arrays. Validate roles against a fixed map and desktop ids against the reactive applications model or a strict freedesktop id pattern plus discovered entries. The page filters role choices from category/generic-name data, sorts by display name, keeps the current handler visible even when category metadata is sparse, and shows calm inline errors. Toggling applies only to files under `$XDG_CONFIG_HOME/autostart`; Lua entries remain read-only with explanatory copy. + +- [x] **Step 4: Verify and commit** + +```bash +tests/quickshell/default-apps-contract.sh +tests/quickshell/applications-settings-contract.sh +tests/quickshell/settings-pages-contract.sh +``` + +Commit subject: `Add application and autostart settings`. + +--- + +### Task 2: Remaining page scaffolds and hardcoded behavior controls + +**Files:** +- Modify: `config/dot/quickshell/config/Settings.qml` +- Modify: `config/dot/quickshell/modules/settings/HomePage.qml` +- Modify: `config/dot/quickshell/modules/settings/DisplaysPage.qml` +- Modify: `config/dot/quickshell/modules/settings/ConnectivityPage.qml` +- Modify: `config/dot/quickshell/modules/settings/SoundPage.qml` +- Modify: `config/dot/quickshell/modules/settings/NotificationsPage.qml` +- Modify: `config/dot/quickshell/modules/settings/ScreenIntelligencePage.qml` +- Modify: `config/dot/quickshell/modules/settings/ServicesPage.qml` +- Modify: `config/dot/quickshell/modules/settings/AboutPage.qml` +- Modify: `tests/quickshell/settings-pages-contract.sh` +- Create: `tests/quickshell/settings-hardcoded-values-contract.sh` + +**Interfaces:** +- Consumes: Claude-owned schema keys `temperatureUnit`, `weatherRefreshMinutes`, `vitalsIntervalMs`, `notificationTimeoutMs`, `notificationTimeoutCriticalMs`, `notificationHistoryLimit`, `maxVisibleToasts`, `screenshotDir`, `recordingDir`, and `recorderArgs`; shared Settings rows; existing services and system handoffs. +- Produces: the same public `Settings.qml` properties, now each reading `DesktopPreferences.get("key")`, and controls routed to weather/vitals, notifications, and capture pages. + +- [x] **Step 1: Write failing contracts** + +Require all ten `Settings.qml` properties to use `DesktopPreferences.get()` exactly. Require every listed page root to be `SettingsPage` and reject its copied root `Flickable` scaffold. Require weather/vitals controls on `HomePage`, notification controls on `NotificationsPage`, and capture directory/encoder controls on `ScreenIntelligencePage`; every schema-bound control uses a shared row and writes only through `SystemSettings.commitPreference` via that row. + +- [x] **Step 2: Run contracts to verify RED** + +```bash +tests/quickshell/settings-hardcoded-values-contract.sh +tests/quickshell/settings-pages-contract.sh +``` + +Expected: fail on hardcoded properties and copied page scaffolds. + +- [x] **Step 3: Implement controls and migrate scaffolds** + +Use `ChoiceRow` for `temperatureUnit`, `screenshotDir`, `recordingDir`, and `recorderArgs`; use `SliderRow` for numeric refresh, timeout, history, and toast limits. Give `notificationTimeoutCriticalMs` `zeroLabel: "Never"`. Preserve all specialized buttons, service status rows, display diagnostics, permission/privacy explanations, and GNOME handoff actions. Convert genuinely read-only rows to `TextRow`; delete only rows superseded by working controls. + +- [x] **Step 4: Run focused and full suite, then commit** + +```bash +tests/quickshell/settings-hardcoded-values-contract.sh +tests/quickshell/settings-pages-contract.sh +tests/quickshell/settings-preferences-contract.sh +tests/quickshell/settings-search-contract.sh +``` + +Then run every `tests/quickshell/*.sh`, every `tests/hypr/*.sh`, and all three `tests/quickshell/*_test.py` files sequentially. + +Commit subject: `Complete Panama settings controls`.