Add hey setup omarchy and the bar unread indicator

Merged
JE
2mo ago
+1994-5

Second of the three-PR stack (theming #220 → this → toasts #222). Includes the docs commit: README's Omarchy section and docs/omarchy.md, the full design record.

What

hey setup omarchy installs hey-cli into the Omarchy desktop: a HEY TUI launcher entry under app-id org.omarchy.hey, a HEY row in the SUPER+SPACE menu, an inline hey-unread command module on the bar, and a hey.toml.tpl theme template so theme authors can tune the TUI's accent overlay. Every step is idempotent, reported separately, and --remove reverses them all. The keybinding is printed, never written — bindings.lua stays the user's; the hint spells out the focus command because the lua helper's { tui = ... } form would derive a non-matching app-id from a multi-word command.

hey omarchy bar-status (hidden) is what the bar module runs every three minutes: a Waybar-style JSON object when the Imbox has unread mail and nothing otherwise. An indicator, not a count. Logged out, offline, or a failed account selection all print nothing and exit 0 — a bar is no place for an error message. One Imbox page decides: HEY orders postings unseen-first (boxes_controller.rb orders by [:seen, observed_at desc]), so any unread mail is on page 1.

Review hardening (from the bots' first pass)

  • A fresh shell.json is seeded with "version": 1 — the shell ignores a version-less config entirely (shell.qml warns and falls back to defaults) — and an existing version-less or non-object file fails the step with a hint instead of being edited into dead config.
  • --remove restores an initially-absent bar layout: if what remains after removing our module equals Omarchy's current default layout, the layout is dropped so the user goes back to inheriting future default changes.
  • The omarchy command is exempt from pre-run account scoping and selects the configured account itself, treating failure as a dark indicator — preserving both scoping and the never-fails contract.
  • The rendered hey.toml template now carries the reference colors (background, blue/bright_blue, bright_foreground) the accent gate needs, since a rendered file is the only theme file the TUI reads.

Summary by cubic

Installs HEY into the Omarchy desktop and adds an Imbox unread bar indicator. Old: no desktop integration. New: hey setup omarchy installs a HEY TUI launcher, a SUPER+SPACE menu row, an inline hey-unread bar module, and a hey.toml.tpl theme template; --remove reverses.

  • One app-id focus: all surfaces use org.omarchy.hey. The bar runs every 180s via hey omarchy bar-status and prints a Waybar-style JSON module only when unread; logged out, offline, or degraded config stays silent and exits 0.
  • Safe config writes: inserts a marker block into ~/.config/omarchy/extensions/omarchy-menu.jsonc. Seeds ~/.config/omarchy/shell.json with "version": 1; refuses non-JSON or version-less files with a hint. Writes are atomic, preserve modes, and follow symlinks. Seeds the default bar layout when absent and restores it on --remove.
  • Theme template: writes ~/.config/omarchy/themed/hey.toml.tpl; triggers omarchy-theme-refresh when available; templates not written by hey are kept on install/remove.
  • Keybinding: prints an o.bind(...) hint and never edits bindings.lua.
  • Trust and JSON output: install requires ~/.local/state/omarchy or OMARCHY_PATH (and an absolute HOME); removal works without Omarchy. omarchy commands ignore repository-local config and are exempt from account scoping; setup omarchy edits fixed desktop paths only and does not use runtime config. List-only formats are refused up front. JSON errors include per-step results in Meta.steps.

Required action: if ~/.config/omarchy/shell.json exists without "version": 1, add it before running hey setup omarchy.