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

86 lines
4.8 KiB
Markdown

# 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`).