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).
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
- A separately compiled Qt/QML application. Requires shipping and building more Qt tooling and a non-trivial C++ or Rust/Qt binding layer.
- 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.
- A terminal TUI only. Rejected: it is the fallback, not the welcome.
Decision
- 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) andphoebus-install(the wizard). The TUI/CLI remains a working fallback and is selected when Quickshell or Wayland is unavailable. - A narrow, typed JSON bridge is the only interface. A hidden
phoebus-installer --gui-bridgemode 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. - The bridge reuses the audited backend. It constructs the same
Installerand callsInstaller::install_observed, so the graphical install executes the identical stages, in the same order, with the sameDestructiveAuthorizationproduced by the existingauthorizeflow. 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. - Approval is bound to the plan.
approverecords a SHA-256 digest of the configuration plus the step sequence.start_installrefuses 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. - 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. - 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. - 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. - A reusable brand system.
phoebus-core::branddefines charcoal, warm white and restrained amber tokens plus a sun emblem, wordmark and wallpaper as deterministic SVG, emitted through the existing--emit-assetplumbing 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.confnow 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).