phoebus_os/docs/adr/0010-graphical-installer-frontend.md
Phoebus 7e9fa9c2a3
Some checks are pending
ci / test (push) Waiting to run
feat(installer): graphical welcome and install wizard over a typed bridge
Add a branded live welcome window and a Quickshell/QML installer frontend
over a narrow, fail-closed JSON bridge (phoebus-installer --gui-bridge)
that reuses the same InstallConfig, plan, validation, authorization and
staged executor as the TUI/CLI. Add the Phoebus brand system (emblem,
wordmark, wallpaper, tokens), suppress DMS first-run dialogs on the live
medium, identify the live medium as protected, make the installer
shortcut live-only, and fix the installed boot default so systemd-boot
never selects the recovery entry.

Verified in a disposable graphical VM (welcome/installer journey,
duplicate prevention, keyboard navigation, blocked AI prerequisite) plus
a real non-interactive install and detached boot (INSTALL-RC=0,
NO_SECRET_LEAK, systemd running, 0 failed units, LUKS2, Btrfs, network).
2026-09-21 13:13:40 -07:00

4.8 KiB

ADR 0010: Graphical installer frontend and typed bridge

  • Status: Accepted
  • Date: 2026-09-21

Context

The installer ISO boots into Mango + DankMaterialShell, but the only installer frontend was the ratatui TUI inside a terminal. The product direction makes installation the ISO's primary purpose: a welcoming, branded entry point and a coherent graphical setup flow. The core requirement is that the graphical frontend must not duplicate installation logic or scrape terminal output; the existing InstallConfig, plan, validation, orchestration and executor remain the single source of truth.

Options considered

  1. A separately compiled Qt/QML application. Requires shipping and building more Qt tooling and a non-trivial C++ or Rust/Qt binding layer.
  2. A Quickshell configuration. Quickshell is already present (DMS is a Quickshell configuration) and provides windows plus process/socket I/O. A configuration is plain QML and needs no extra packages.
  3. A terminal TUI only. Rejected: it is the fallback, not the welcome.

Decision

  1. Quickshell/QML is the graphical frontend, because it is the desktop's existing stack, is already in the live ISO, and needs no new package or build step. There are two configurations: phoebus-welcome (the live welcome and launcher) and phoebus-install (the wizard). The TUI/CLI remains a working fallback and is selected when Quickshell or Wayland is unavailable.
  2. A narrow, typed JSON bridge is the only interface. A hidden phoebus-installer --gui-bridge mode reads newline-delimited JSON requests on stdin and writes typed JSON responses and progress events on stdout. The operations are bounded: handshake, disks, set_config, set_secrets, validate, plan, destructive_preview, ai_check, approve, start_install, log_tail, quit. Unknown ops and unknown request fields fail closed.
  3. The bridge reuses the audited backend. It constructs the same Installer and calls Installer::install_observed, so the graphical install executes the identical stages, in the same order, with the same DestructiveAuthorization produced by the existing authorize flow. A progress observer (a small trait added to the orchestrator) reports the real stage transitions; categories name downloads, compilation, configuration and verification. No percentage is ever estimated.
  4. Approval is bound to the plan. approve records a SHA-256 digest of the configuration plus the step sequence. start_install refuses unless the presented digest still matches the current plan, so any change — including an AI-applied change — invalidates a previous approval and forces a re-review.
  5. Secrets go over the stdin pipe, never argv, config or logs. The GUI sends the LUKS passphrase, user password and API key through set_secrets; the bridge registers them with the redactor immediately and reports only presence. The model never receives them.
  6. The frontend is unprivileged. It runs as the live user and starts the bridge with /usr/bin/sudo -n; only the bridge process holds privilege, and it exposes no shell.
  7. Live-only and installed surfaces stay separate. The welcome window, its autostart and the "Install Phoebus OS" desktop entry are installed only on the live medium (gated by /etc/phoebus/live). The installed desktop has no reinstall shortcut. Upstream DMS first-run dialogs are suppressed on the live medium by pre-seeding DMS's own "already welcomed" marker files.
  8. A reusable brand system. phoebus-core::brand defines charcoal, warm white and restrained amber tokens plus a sun emblem, wordmark and wallpaper as deterministic SVG, emitted through the existing --emit-asset plumbing and applied to the boot menu, wallpaper, welcome window, installer and icons. A test pins the QML palette to the Rust tokens.

Consequences

  • The frontend cannot diverge from the backend: the protocol is the contract and the backend is unchanged.
  • The bridge and its protocol are fully unit-testable (dry-run) on any host; the QML is exercised in the disposable graphical VM.
  • The recovery-boot default bug exposed during GUI testing was fixed at the source: loader.conf now pins the newest real kernel entry, and the snapshot recovery entry carries a sort-key that keeps it last, so a low machine-id can never make the installed system boot into recovery.
  • A new frontend means ongoing QML maintenance; it is deliberately small.

Verification

Unit tests cover the protocol, validation wiring, approval binding, approval invalidation after a config change, blocked AI prerequisite, secret non-disclosure, readiness facts and the installed dry-run stage sequence. The GUI journey and a real install + detached boot are verified in the disposable VM (docs/VM-BOOT-VERIFICATION.md).