Gabriel Brown
c02329ac3c
The launcher's Copy Password command, built alone and last as the plan required, because every line of it is the security design: the secret travels rbw to wl-copy through a pipe -- never argv, never a file -- and the copy carries wl-clipboard's --sensitive hint, which vicinae's clipboard history documents it ignores. That claim was not taken on faith: a plain probe landed in the live history database and a sensitive one did not, before any of this was written. A transient timer clears the clipboard after thirty seconds. An unconfigured rbw gets a setup message; a vault that locks between list and get gets an honest failure instead of an empty copy claiming success. rbw joins desktop-packages, and the contract pins the whole journey with a stub vault, including that the secret never appears on a command line.
155 lines
11 KiB
Markdown
155 lines
11 KiB
Markdown
# Vicinae OS-Parity 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:** Close the launcher gaps a GNOME, macOS, or Windows switcher notices in week one. The launcher is deep where Panama is deep (settings, projects, focus) and thin where a stock OS is strong: finding files, windows, and your own stuff. After this plan, Spotlight and Start-menu reflexes land somewhere.
|
|
|
|
**Architecture:** Two mechanisms, chosen per feature by whether the result is a list.
|
|
|
|
- *Script commands* (`config/local/share/vicinae/scripts/`, published by `link-vicinae-scripts`) for toggles and argument commands: power menu, reminders, color picker, quicklinks. Annotation-header bash, `@vicinae.mode silent` or an argument slot.
|
|
- *One new compiled extension* (`config/local/share/vicinae/extensions/panama-desktop/`, TypeScript, built at link time like `panama-search`) for everything that presents a live list to pick from: window switcher, force quit, kill process, SSH hosts, recent files. Vicinae script commands cannot render pick-lists; `panama-search` proves the extension path.
|
|
|
|
Backends are things the system already has: `hyprctl clients -j`, `systemd-run --user`, `hyprpicker`, `~/.ssh/config`, `recently-used.xbel`, `rbw`.
|
|
|
|
**Tech Stack:** Bash, jq, TypeScript (Vicinae extension API), vicinae 0.26.3, hyprctl, systemd-run, rbw
|
|
|
|
**Spec:** none — shaped in conversation 2026-08-21; this plan is self-contained.
|
|
|
|
## Global Constraints
|
|
|
|
- A command whose backend is missing must degrade to a clear message, never a stack trace. `command -v` guards, not assumptions.
|
|
- Secrets never touch argv or files: rbw output goes straight to the clipboard, with a timed clear. The Bitwarden task lands alone, after review, never batched.
|
|
- No new daemons and no polling. Every command does its work when invoked and exits.
|
|
- Reuse the existing wiring: script commands exec helpers in `config/dot/quickshell/scripts/` when logic is nontrivial, the way `open-project` execs `panama-project`.
|
|
- Every task extends or adds a contract. New test files bump the README count (`tests/setup/readme-contract` enforces it).
|
|
- New packages go in the package lists, never inline in scripts. `tests/setup/package-lists-contract` verifies names against the repositories.
|
|
- The terminal for SSH sessions is the one `panama-project` already names; do not add a fifth copy of the kitty literal without checking whether the terminal-ownership cleanup has landed.
|
|
|
|
---
|
|
|
|
### Task 1: Audit the built-ins, land the missing dependencies
|
|
|
|
What vicinae 0.26.3 already ships decides whether file search and the calculator are configuration or code. Do not build before answering.
|
|
|
|
**Files:**
|
|
- Modify: `setup/packages/desktop-packages` (or `initial-packages`) — add `qalculate`, `fd-find`
|
|
- Create: audit notes appended to this plan under Findings
|
|
|
|
**Steps:**
|
|
- [x] Enumerate vicinae's built-in commands (file search, calculator, quicklinks, snippets) from the running launcher and upstream docs for 0.26.x
|
|
- [x] Verify the calculator resolves units and currency once `qalculate` is installed; note whether currency needs network setup
|
|
- [x] Test built-in file search against `~`: coverage, latency, whether hidden and XDG dirs are respected; record whether Task 7's file listing is needed at all
|
|
- [x] Check whether built-in quicklinks cover argument URL templates; if yes, Task 4 shrinks to authoring quicklinks in `config/dot/vicinae/`
|
|
- [x] Add the packages the audit proves needed; run `tests/setup/package-lists-contract`
|
|
|
|
**Findings (2026-08-21):**
|
|
- No new packages. The vicinae binary links `libqalculate.so.23` directly, so the calculator works without the `qalc` CLI; `fd-find` is unnecessary because the built-in index is good (below). The plan's guess of `qalculate` + `fd-find` in the package lists is withdrawn.
|
|
- File search passes outright: `vicinae fs query` answers in under 100ms, covers all of `~` including hidden and XDG dirs. `search_files_in_root: false` is a documented deliberate choice in vicinae.json (root search stays fast; files live behind their own command) and stays. Task 7 is a no-op.
|
|
- Quicklinks exist as vicinae's built-in "shortcuts" (`~/.local/share/vicinae/shortcuts/shortcuts.json`, currently empty), created in-launcher. They are per-user runtime data, not tracked config, so Panama ships none and Task 4 shrinks to the color picker.
|
|
- Snippets exist the same way (empty store) and overlap espanso; no work.
|
|
- `vicinae dmenu` renders a pick-list from stdin with search, section titles, and index/data output. Verified live. This replaces the planned compiled extension: Tasks 5, 6, and 8 become bash helpers piping into `vicinae dmenu`, which is simpler to build, test, and read than a TypeScript extension. `panama-search` stays the only compiled extension.
|
|
- Currency conversion is the one unchecked box a human should spot-check in the launcher once (libqalculate fetches exchange rates on demand); nothing to install either way.
|
|
|
|
### Task 2: Power menu script commands
|
|
|
|
**Files:**
|
|
- Create: `config/local/share/vicinae/scripts/{lock-screen,suspend-system,log-out,reboot-system,power-off}`
|
|
- Modify: `tests/setup/launcher-search-contract` (or sibling) to cover the new commands
|
|
|
|
**Steps:**
|
|
- [x] `lock-screen`: `loginctl lock-session` (hypridle owns the Lock signal)
|
|
- [x] `suspend-system`: `systemctl suspend`
|
|
- [x] `log-out`: end the uwsm session the way the session expects (`uwsm stop`), not a bare `hyprctl dispatch exit`
|
|
- [x] `reboot-system` / `power-off`: `systemctl reboot` / `systemctl poweroff`; keywords carry the words a switcher will type ("restart", "shutdown", "sign out")
|
|
- [x] Contract: every power command exists, is executable, and names only binaries the package lists provide
|
|
|
|
### Task 3: Reminders and timers
|
|
|
|
**Files:**
|
|
- Create: `config/local/share/vicinae/scripts/remind-me`
|
|
- Create: `config/local/share/vicinae/scripts/list-reminders`
|
|
- Create: `config/dot/quickshell/scripts/panama-remind`
|
|
- Create: `tests/quickshell/remind-contract`
|
|
|
|
**Steps:**
|
|
- [x] `panama-remind add "<when>" "<text>"`: parse `20m` / `1h` / `9:30` into `systemd-run --user --on-active=` or `--on-calendar=`, unit named `panama-remind-<id>`, firing `notify-send` with the text
|
|
- [x] `panama-remind list` / `cancel <id>`: wrap `systemctl --user list-timers 'panama-remind-*'`
|
|
- [x] Script command with two argument slots; list/cancel as a second command
|
|
- [x] Contract: add, list, and cancel against a stub `systemd-run`/`systemctl`; a nonsense time is refused with a message, not a unit
|
|
|
|
### Task 4: Color picker and quicklinks
|
|
|
|
**Files:**
|
|
- Create: `config/local/share/vicinae/scripts/pick-color`
|
|
- Create or configure: quicklinks per Task 1's finding
|
|
|
|
**Steps:**
|
|
- [x] `pick-color`: `hyprpicker -a` (autocopy), then `notify-send` the hex; degrade with a message if hyprpicker is missing
|
|
- [x] Quicklinks: if built-in, author Panama's defaults (Gitea, Flathub, package search) in tracked config; if not, one `open-quicklink` script command with an argument
|
|
- [x] Extend the launcher contract to cover both
|
|
|
|
### Task 5: Windows and processes — built as `panama-pick` + `vicinae dmenu` per Task 1's findings
|
|
|
|
The list-picking half. One bash helper, not a compiled extension: `vicinae dmenu` renders the list.
|
|
|
|
**Files:**
|
|
- Create: `config/dot/quickshell/scripts/panama-pick`
|
|
- Create: `config/local/share/vicinae/scripts/{switch-window,force-quit-window,kill-process}`
|
|
- Create: `tests/setup/launcher-commands-contract`
|
|
|
|
**Steps:**
|
|
- [x] "Switch Windows": list `hyprctl clients -j` (title, class, workspace), fuzzy filter, `hyprctl dispatch focuswindow address:` on select
|
|
- [x] "Force Quit Window" action on the same list: `hyprctl dispatch killactive` equivalent by address, SIGKILL the pid as the destructive secondary action
|
|
- [x] "Kill Process": list by name/CPU from `ps`, SIGTERM on select, SIGKILL as secondary; own process and the shell filtered out
|
|
- [x] Contract: extension builds from a clean checkout; commands are declared in package.json; no network access in the build sandbox beyond the dependency install `panama apps` already performs
|
|
|
|
### Task 6: SSH hosts and recent files
|
|
|
|
**Files:**
|
|
- Modify: `config/dot/quickshell/scripts/panama-pick` (ssh, recent subcommands)
|
|
- Create: `config/local/share/vicinae/scripts/{ssh-hosts,recent-files}`
|
|
|
|
**Steps:**
|
|
- [x] "SSH Hosts": parse `Host` stanzas from `~/.ssh/config` (skip wildcards), open the session in the terminal the repo already names
|
|
- [x] "Recent Files": parse `~/.local/share/recently-used.xbel`, newest first, open with `xdg-open`; missing file means an empty list with a hint, not an error
|
|
- [x] Extend the extension contract for both commands
|
|
|
|
### Task 7: File search — resolved by Task 1: the built-in passes; no work
|
|
|
|
**Files:**
|
|
- Modify: `config/local/share/vicinae/extensions/panama-desktop/` (src/files.tsx), or vicinae config only
|
|
|
|
**Steps:**
|
|
- [x] If the built-in passed the audit: configure its roots and stop; record that in Findings
|
|
- [x] If not: `fd`-backed list command over `~`, hidden dirs excluded, bounded result count, debounced queries
|
|
- [x] Either way: the launcher finds a file by name from a cold start in under a second on this machine, and the contract asserts the chosen path exists end to end
|
|
|
|
### Task 8: Bitwarden via rbw — alone, last, carefully
|
|
|
|
**Files:**
|
|
- Modify: `setup/packages/desktop-packages` (add `rbw`)
|
|
- Modify: `config/dot/quickshell/scripts/panama-pick` (password subcommand)
|
|
- Create: `config/local/share/vicinae/scripts/copy-password`
|
|
- Modify: `tests/setup/launcher-commands-contract` (password section)
|
|
|
|
**Steps:**
|
|
- [x] `rbw` added to a package list; first-run setup documented (`rbw config set email`, `rbw login`) and surfaced as a friendly message when unconfigured
|
|
- [x] List entries from `rbw list`; copy password on select via `rbw get` piped to `wl-copy`, never argv, never a temp file
|
|
- [x] Clipboard clears after 30 seconds (`wl-copy --clear` scheduled with `systemd-run --user --on-active=30s` or vicinae's own clipboard hygiene if it offers one — check first)
|
|
- [x] Contract with a stub rbw: copy path never leaks the secret into argv or the environment of anything but wl-copy; unconfigured rbw degrades to the setup message
|
|
- [x] Review pass on this task's diff before it merges, separate from writing it
|
|
|
|
### Task 9: Documentation and closeout
|
|
|
|
**Files:**
|
|
- Modify: `README.md` (launcher section, test count)
|
|
- Modify: `docs/settings.md` if any command grew a settings surface
|
|
- Modify: this file — Findings section, boxes ticked
|
|
|
|
**Steps:**
|
|
- [x] README's Vicinae row reflects the new command families
|
|
- [x] Every new file carries the why-comment the repo expects; no `.sh` extensions anywhere
|
|
- [x] Full `panama test` run is green; README count matches
|
|
|
|
**Task 8 findings (2026-08-21):** `wl-copy --sensitive` (wl-clipboard 2.2) offers the password-manager hint MIME, and vicinae's clipboard docs commit to ignoring it — verified live against the real history database (a plain probe was recorded, a sensitive one was not) before the command was written. The clipboard clear is a 30s transient timer. Review pass caught and fixed a silent empty copy on a locked vault and a flag-shaped entry name.
|