Omarchy becomes a first-class host, and the host grows a control surface #428
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: unom/punktfunk#428
Reference in New Issue
Block a user
Implements
punktfunk-planning'sdesign/omarchy-integration.md+ its implementation plan, then takes the result to a real Omarchy 4.0.1 box and fixes what that found. 39 files, +3970/−62.punktfunk-host ctl(design WP8)A subcommand, not a second binary —
main.rsalready dispatches a dozen verbs, and in-crate means no second declaration of the mgmt types to drift. 16 verbs over the existing admin lane: pairing arm/pending/approve/deny, the Moonlight PIN, both planes' device lists with rename/unpair/access presets, session stop/end-game,console-url, andwatch, which bridges the SSE stream to line-JSON withLast-Event-IDresume and a syntheticctl.resync.The load-bearing property is pin before token: the agent pins the host's own leaf and rustls rejects a mismatch during the handshake, so ureq never gets as far as serialising an
Authorizationheader. That closes the local port-squat vector with zero server-side change —mgmt/auth.rshas no diff. There is deliberately no--tokenflag and no token env read; both are readable cross-uid through/proc.Two corrections to the plan, both from reading the code:
native-cert.pem→cert.pem. Pinningcert.pemas the plan said exits 4 on every healthy host — confirmed on glass: the port serves306d95…,cert.pemis34a4cb….punktfunk-core's existingPinVerifyrather than a new bytes-compare.What the box changed
Five defects that only a real Omarchy box could surface:
pacman -Syu <pkgs>installs nothing. A libalpm PreTransaction hook aborts any transaction carrying both-Sand-u. The Arch line this branch originally shipped for Omarchy died with "Woah partner…".-Sythen-Sworks. This was a first-run blocker on the documented path.omarchy-toggle-idle statusprints JSON, and its tooltip names the action the button would take — so"Stay Awake"appears exactly when stay-awake is off. Every arm fell through to "do nothing".statuslied twice — claimed no ufw rules seconds after adding six (a failedsudo -nread treated as absence), and claimed xdph was missing on a box capturing through it (pgrep -xcan never match a 27-char name; comm truncates at 15).graphical-session.targetstarts only under the uwsm one. On the plain one Omarchy's own units that want it are enabled-and-dead too. Setup and status now detect and say which you have.ctl watchleaked an SSE stream per dead consumer — six orphans after three shell restarts on an idle host, because a read-only stream never notices its stdout pipe closed. The keep-alive now surfaces asctl.heartbeat, giving a write to fail on.The xdph landmine (design D6)
Omarchy ships its own
~/.config/hypr/xdph.confnaminghyprland-preview-share-picker— the picker every browser share goes through — and our Hyprland backend takes that key over. The merge was already right; the way back did not exist.The fix that does not depend on teardown: the shim delegates, exec'ing whatever was configured before us when no selection is pending. Plus a marker recorded in the same atomic write, and the hand-back moved to host shutdown. Restoring per-cast turned out to restart xdph mid-session, which is its own black screen — the portal runtime caches its D-Bus connection process-globally.
Verified end to end on the box: real capture (xdph → PipeWire 1920×1080 →
cuda-import → nvenc), shim picked up their picker automatically, restore fired,xdph.confbyte-identical.#283 on the Lua era
hyprctl dispatch focusmonitor <name>parses ashl.dispatch(focusmonitor <name>)and dies. The code documented this as unfixable because "hl.dsp.focusmonitordoes not exist" — true, and the wrong name. It ishl.dsp.focus({ monitor = "…" }), which the compositor volunteers if you ask with any other key. Not cosmetic: an unfocused headless output stays empty, an empty output produces no damage, and no damage means no frames.Console: log in once, follow the desktop's theme
ctl console-urlmints a ticket signed with the management token; the console verifies with the copy it already holds. Not "skip the login" — the console binds0.0.0.0:47992, so trusting the network would hand pairing/unpair/session-control to the LAN. Trusting the 0600 token is the same bar reached differently: whoever can read it already holds the credential the console's own proxy presents. 60 s TTL, single use, one 401 for every rejection. A visitor without a ticket still meets the login page.The theme template rendered fine all along and nothing consumed it. Now
ui-configcarries it and the root appliesmodeandaccent— both brand variables, since.darkderives--primaryfrom--pf-brand-lightand the console ships pinned dark.Also: Super+Space gains a Punktfunk submenu (merged into the user's JSONC on a copy, validated as JSONC and checked that our rows landed, with a byte-exact
remove), and the launcher entry finally has an icon — the host package never shipped one.Rest of the design
WP1 detection + notify-only updates (enforced at the apply route, not merely reported — a direct POST would otherwise run
pacman -Syupast their snapper snapshot), WP2 packaging (+ thehyprland/xdg-desktop-portal-hyprlandoptdepends owed since before Omarchy), WP3punktfunk-omarchy setup|remove|status, WP4 docs, WP5/6/7 hooks/idle/theme, and two diagnostics rows for failures that report nothing at all.Verification
Gates: fmt, clippy
-D warnings(punktfunk-host + pf-vdisplay), 57 host tests, 268 pf-vdisplay tests, 14 web tests, 13 shell self-checks, docs-drift, shellcheck, biome. Rebased ontod12d494fwith zero file overlap.On the box: all four ctl exit codes (4 by pointing ctl at the host's own legacy cert), the D6 round trip, the ticket verified against an independent HMAC, the theme template rendered and parsed, setup/remove end to end. The tree builds on Omarchy in 8m16s.
Not verified on glass: the two console-side changes need a
punktfunk-webbuild to reach a box — it ships as a prebuilt Nitro.outputand the testbox has no bun — so the handoff route and the theme are unit-tested and file-verified but have not served a request. Also unfixed and out of scope here:topology: exclusivedisables the operator's heads and does not restore them on the pipeline-build failure path, leaving the desk dark (hyprctl reloadrecovers). That belongs to #284's in-flight work; recorded with its evidence rather than half-fixed in a file another effort is editing.Three things an Omarchy user meets in the first minute, all of which were wrong. The login (the handoff) ----------------------- Asking for a password to open your own console from your own app menu buys nothing — but the obvious fix, dropping the login, is not available: the console binds **0.0.0.0:47992** so it can be reached from a phone, and its admin surface is pairing, unpair and session control. Trusting the network would hand that to the LAN. So trust what actually distinguishes the operator: the **management token**, a 0600 file inside the 0700 config dir. `punktfunk-host ctl console-url` mints a ticket signed with it; the console verifies with the copy it already holds and seals the ordinary session cookie. Whoever can read that file can already drive the whole admin API — it is the credential the console's own proxy presents — so skipping a password they could simply read widens nothing, and a visitor without a ticket still meets the login page. `<unix-seconds>.<nonce>.<HMAC-SHA256>` over `pf-console-handoff:v1:ts:nonce`. 60 s TTL, single use, symmetric window (a ticket from the future is as wrong as an old one), one 401 for every rejection so probing learns nothing. No new host route and no shared state: both sides already hold the key. The decision lives in `util/handoff` rather than the route so it is testable without an h3 event — and the test suite includes a vector minted by the real Rust host and cross-checked against python's `hmac`, so a drift in the message format fails here instead of six weeks later in the field. The launcher entry ------------------ `Icon=` was empty, so the entry drew nothing. Two causes: the host package never shipped an app icon (only the CLIENT package installed `io.unom.Punktfunk.svg`), and `omarchy-webapp-install` derives an icon name with `${ref%.*}` + slugify, which turns a dotted theme name into `io-unom` — resolving to nothing. The host package now ships the scalable mark, and setup writes `Icon=` and `Exec=` itself after letting their tool create the entry. The Omarchy menu ---------------- Super+Space had only the webapp. There is now a Punktfunk submenu — open console, pair a device, devices waiting, paired devices, stop the session, status, restart — with `when` guards so a row the box cannot honour does not show. D7 avoided writing the user's `omarchy-menu.jsonc` because it is a single document where one parse error silently drops EVERY row they own. That risk is real, so the merge earns its place: work on a copy, insert between markers so a re-run replaces rather than stacks, validate the result as JSONC AND confirm our rows actually landed, and only then move it into place. A file that does not parse to begin with is left completely alone — it is not ours to repair. `remove` takes the block back out and restores their file byte for byte. Two bugs the self-check caught before the box did: `awk -v` refuses a newline inside a `-v` assignment, so the rows silently never landed while the function reported success (hence the merge now verifies its own output, not just that the file still parses); and `MENU_FILE` was a `readonly` computed at LOAD time, so it ignored an `XDG_CONFIG_HOME` set afterwards and edited the real config of the machine running the test. Paths resolve at call time now, like `write_hooks` already did. Gates: fmt, clippy -D warnings, 13 ctl tests, 7 handoff tests, 13 shell self-checks, docs-drift, shellcheck. On the box: the ticket verifies against an independent HMAC, two tickets in the same second differ, and the launcher entry carries the right Exec and Icon. ⚠ The console half needs a `punktfunk-web` build to reach a box — it ships as a prebuilt Nitro `.output`, and there is no bun on the Omarchy testbox — so the route itself is unit-tested but has not served a request on glass.WP7 shipped a template and no consumer. `punktfunk.json.tpl` rendered fine — Omarchy globs `~/.config/omarchy/themed/*.tpl` and writes the result to `~/.local/state/omarchy/current/theme/` on every `omarchy-theme-set`, and the keys the template asks for (`mode`, `accent`, `background`, `foreground`) all exist in a theme's `colors.toml`, verified against tokyo-night on the box. Nothing read it, so nothing changed, which is exactly what "the theme is not applied" looks like from the outside. Now: the server reads the rendered file and `ui-config` carries it; the root applies `mode` as the `.dark` class the whole stylesheet already keys off, and `accent` as the brand variable `--primary`, `--accent` and `--ring` all derive from. One value re-tints the buttons, the active nav and the focus rings together. BOTH brand variables, not just `--pf-brand`. The light palette derives `--primary` from it, but `.dark` derives `--primary` from `--pf-brand-light`, and the console ships pinned dark — so setting only the first would have re-tinted light mode and done nothing whatsoever in the mode people actually see. The accent reaches a style attribute, so the reader validates it as a colour rather than trusting the file: hex and the functional notations Omarchy themes use, nothing else. That is not theoretical tidiness — an UNRENDERED template contains the literal `{{ accent }}`, and a theme switch can be caught mid-write. Both are "no theme" here, and no theme means the console's own violet, which is also what SSR paints and what shows for the moment before the fetch resolves. Every failure is the fallback; none is an error page. Read per request rather than cached, because `omarchy-theme-set` rewrites the file whenever the user switches and a console that only looked at startup would be wrong until it restarted. Verified on the box: the template renders (`"mode":"dark","accent":"#7aa2f7"`), and the reader parses that exact file. 14 tests, biome clean. ⚠ Like the handoff, the console half needs a `punktfunk-web` build to reach a box — it ships as a prebuilt Nitro `.output` and the Omarchy testbox has no bun — so this is unit-tested and file-verified but has not painted a pixel on glass.`tsc --noEmit` under `noUncheckedIndexedAccess`: destructuring `ticket.split(".")` yields `string | undefined` per element, and `parts.length !== 3` does not narrow a plain array — so five type errors on the regex tests and the compare. An explicit `!ts || !nonce || !mac` guard proves it to the compiler AND rejects the empty segments a `"1..2"` ticket would otherwise reach the regexes with, which is what the removed `parts.some(p => p.length === 0)` was doing less directly. Caught by CI's `web` job, not by me: I ran `bun test` and biome and stopped there. The typecheck needs `node_modules`, which a fresh worktree has none of, and I took the two h3 import failures as "pre-existing" without noticing that the same missing install was hiding the type check entirely. With the deps in place the full web suite is 36/36 and `tsc --noEmit` exits 0.