Some checks are pending
ci / test (push) Waiting to run
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).
86 lines
4.8 KiB
Markdown
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`).
|