feat(installer): graphical welcome and install wizard over a typed bridge
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).
This commit is contained in:
Phoebus 2026-09-21 13:13:40 -07:00
parent 0f6d503c2e
commit 7e9fa9c2a3
48 changed files with 4834 additions and 162 deletions

View file

@ -12,6 +12,9 @@ Rust binary.
## Layering ## Layering
``` ```
Graphical welcome + installer Quickshell/QML (live only; typed JSON protocol)
| phoebus-welcome, phoebus-install
v
TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer) TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer)
| |
v v
@ -24,6 +27,13 @@ Executor commands, storage, Portage, boot, services
Core typed config, models, policy, validation Core typed config, models, policy, validation
``` ```
The graphical frontend is one of several front-ends; it never contains
installation logic. `phoebus-installer --gui-bridge` speaks newline-delimited
JSON on stdin/stdout, reuses the same `Installer`, plan, validation and
`DestructiveAuthorization` flow, and reports real stages through
`Installer::install_observed`. The QML only renders typed state and submits
bounded requests (ADR 0010).
### phoebus-core ### phoebus-core
Pure, non-privileged logic with no external commands except reading `/proc`, Pure, non-privileged logic with no external commands except reading `/proc`,
@ -44,6 +54,8 @@ Pure, non-privileged logic with no external commands except reading `/proc`,
- `effects` — parse `emerge --pretend` into resolved effects + plan digest. - `effects` — parse `emerge --pretend` into resolved effects + plan digest.
- `transaction` — the user-queryable log of executed actions and outcomes. - `transaction` — the user-queryable log of executed actions and outcomes.
- `action` — closed `SystemAction` schema and a small deterministic parser. - `action` — closed `SystemAction` schema and a small deterministic parser.
- `brand` — the visual identity (palette tokens, sun emblem, wordmark,
wallpaper) as deterministic SVG/tokens shared by the QML frontend.
- `update` — preparation policy and real Portage argument builders. - `update` — preparation policy and real Portage argument builders.
### phoebus-executor ### phoebus-executor

View file

@ -7,6 +7,47 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased ## Unreleased
### Added
- **Graphical installation experience.** The live ISO now boots into a branded
Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the
dominant action, shows ISO version and readiness (network, firmware, memory,
cores) and keeps network/display/accessibility/help/keyboard-test/power tools
available, with troubleshooting tools under Advanced. A full graphical setup
wizard (`phoebus-install`) guides language and keyboard, network and
prerequisites, AI model connection, destination disk (with protected disks
and the installer medium identified), account and encryption, review,
`ERASE` authorization, progress and completion. Duplicate installer sessions
are prevented. The TUI/CLI remains the fallback. See ADR 0010 and
`docs/VM-BOOT-VERIFICATION.md`.
- **Typed JSON GUI bridge.** `phoebus-installer --gui-bridge` exposes a narrow,
fail-closed protocol over stdin/stdout that reuses the same `InstallConfig`,
validation, plan, `DestructiveAuthorization` and staged executor as the TUI.
Approval is bound to a plan digest, secrets travel only over the stdin pipe,
and real backend stages are reported with categories (no invented
percentages). `Installer::install_observed` and an `InstallObserver` trait
were added; `Installer::install` is unchanged.
- **Phoebus brand system.** `phoebus-core::brand` provides charcoal/warm
white/amber tokens plus a sun emblem, wordmark and wallpaper as deterministic
SVG (emitted via `--emit-asset`, shared with the QML frontend), applied to the
GRUB menu, live wallpaper, welcome window, installer, application icon and
completion screen. Readable contrast and the QML/Rust palette are pinned by
tests.
### Fixed
- **Installed systems no longer default into recovery.** `loader.conf` now pins
the newest real kernel entry, and the snapshot recovery entry carries a
`sort-key` that keeps it after every kernel, so a low machine-id can never
make systemd-boot select the recovery entry by filename tie-break. Previously
an installed system could boot `systemd.unit=rescue.target` after reboot.
- **DMS first-run dialogs are suppressed on the live medium** by pre-seeding
DMS's own onboarding and changelog markers, so the installer is the first
thing the user sees.
- **The live-medium device is now identified.** `probe_disks` also inspects
`/run/live/medium` and `/run/live/rootfs`, so the ISO is labelled as the
installation medium (and remains protected).
- **The installer shortcut is live-only.** `phoebus-install` and its desktop
entry are no longer written to an installed system.
### Changed ### Changed
- **Mango + DankMaterialShell is now the default desktop** for both the - **Mango + DankMaterialShell is now the default desktop** for both the
installation ISO and the installed system (explicit owner decision). Omitted installation ISO and the installed system (explicit owner decision). Omitted

View file

@ -3,68 +3,67 @@
Rolling note between work sessions. **Update this file before you finish**, then Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail. commit it. It should be short and current; use `git log` for detail.
- **Last updated:** commit `639cb33` + this session (2026-09-21) - **Last updated:** this session (2026-09-21), graphical installer ISO.
- **Current focus:** Mango + DankMaterialShell as the default desktop. The - **Current focus:** The ISO now boots into a branded **welcome window** and a
installed default is `desktop.profile = "mango"` with greetd authenticated full **graphical installer wizard** over a typed JSON bridge
login (Mango default, dwl fallback), and `installer/live/build.sh` now builds (`phoebus-installer --gui-bridge`), with the TUI/CLI as fallback. The brand
a Mango live desktop ISO from a rootless Debian testing rootfs plus pinned system, boot-menu identity, live-medium detection and the recovery-boot
Mango/DMS releases. Graphical VM verification of the installed desktop and default bug are fixed. See ADR 0010 and `docs/VM-BOOT-VERIFICATION.md`.
the built ISO is the remaining evidence gap. - **Last verified (this session):**
- **Last verified:** static Rust binary install + detached boot and the 2026-09-21 - `gui-driver.py gui`: welcome autostarts; DMS first-run dialogs suppressed;
appliance baseline (`INSTALL-RC=0`, `NO_SECRET_LEAK`, coordinated initial installer opens; duplicate sessions prevented (`n1=n2=1`); keyboard
snapshot + recovery entry) in `docs/VM-BOOT-VERIFICATION.md`; unit/functional navigation reaches network + AI steps; the AI step blocks without a model.
tests for the Mango default, explicit overrides, greetd login, live/installed - `gui-driver.py install` + `boot` on the built ISO: `INSTALL-RC=0`,
separation, session entries, pinned release checksums and the live ISO guards; `NO_SECRET_LEAK`, and a **detached** boot with systemd `running`,
and the built Mango live ISO booted in a graphical seat-providing VM (Mango + **0 failed units**, LUKS2, all Btrfs subvolumes and network, and the boot
DMS + Quickshell running, DMS panel/welcome captured by `screendump`). menu defaulting to **Gentoo Linux** (not recovery).
- Rust suite: GUI bridge dry-run protocol, approval binding/invalidation,
secret non-disclosure, brand tokens/contrast, boot default pinning.
- ISO: `installer/live/phoebus-installer-amd64.iso` 1.6 GiB,
`sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee`.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os> - **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222). (remote `origin`, SSH port 2222).
## Next actions (in order) ## Next actions (in order)
1. **Mango graphical verification** (default, so highest priority): install the 1. **Live AI provider call**: exercise the GUI AI step (and `sys ask`) with a
default profile and boot the built live ISO in a graphical, seat-providing real 0600 key or a downloaded local model; the path is fixture-verified only.
VM; verify the panel/launcher/terminal/Install-Phoebus entry, audio/network, 2. **Installed Mango desktop**: install the default profile in a graphical VM
lock/idle, logout/reboot and the dwl fallback, plus authenticated login on and verify the panel/launcher/terminal/audio/network/lock/idle, the dwl
the installed system (`docs/VM-BOOT-VERIFICATION.md`). fallback, and the welcome/installer absence on the installed system.
2. **Rollback VM acceptance**: deliberately break an update in the disposable 3. **Rollback VM acceptance**: deliberately break an update, run `sys undo`,
VM, run `sys undo`, reboot detached, verify package-state consistency reboot detached, verify `/var/db/pkg` matches `/`, then boot the recovery
(`/var/db/pkg` matches `/`), then boot the snapshot recovery entry with no entry with no network or model (ADR 0007).
network or model (ADR 0007). 4. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
3. **Live AI provider call**: exercise `sys ask` with a real 0600 key file and
confirm the `systemd-run` sandbox properties apply; the path is
fixture-verified only.
3. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit `phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`). agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
4. **Matching signed binhost / binary strategy**: keep the official binhost for 5. **Release gates on a CI runner**: `phoebus-release gates --execute` and
matching USE and Flatpak/Nix elsewhere; do not publish a private binhost `publish` once a runner exists; no gate has executed.
(ADR 0006). Verify with `emerge -pv`.
5. **Release gates on a CI runner**: run `phoebus-release gates --execute` and
`phoebus-release publish` once a runner exists; no gate has executed.
## Known blockers / risks ## Known blockers / risks
- No live DeepSeek/OpenAI call has been made (no key in this environment). - No live DeepSeek/OpenAI call has been made (no key in this environment); the
- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml` only AI step is verified as a blocked prerequisite and with a fixture transport.
runs once one is registered. - **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor
- Desktop graphical login / physical seat has not been exercised; the serial is the dwl fallback session.
VM has no logind seat.
- NVIDIA is not verified on hardware.
- Rollback and the AI sandbox are implemented and unit-tested but not - Rollback and the AI sandbox are implemented and unit-tested but not
VM-verified. VM-verified. NVIDIA is not verified.
- The GUI bridge reaches Quickshell via `Process` + `/usr/bin/sudo -n`; it
relies on the live user's passwordless sudo.
## Environment notes ## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy installed. - Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick present.
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso` - Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`); the appliance ISO builds without root. (matches `installer/live/base.sha256`); the appliance ISO builds without root.
- The appliance harness is `installer/tests/vm/appliance-driver.py` + - Local QML iteration: `/tmp/opencode/run-qml.sh <config-dir>` runs a config on
`appliance-guest.sh` + `appliance-test.conf.example`; serve the stage3, a nested Mango over the host X11 using the built rootfs libraries, and
config and 0600 secret files over `python3 -m http.server 8000`. `grim` captures it. The sanctioned verification is the disposable VM.
- The VM harness disks are disposable qcow2 files on `/` (not `/tmp`, which is - VM harnesses: `installer/tests/vm/gui-driver.py` (graphical live ISO:
a small tmpfs); never point `DISK` at `/dev/*`. `gui`/`install`/`boot`), `appliance-driver.py`, `serial-driver.py`.
- The VM harness honours `CHECKS_TIMEOUT` / `INSTALL_TIMEOUT` for long runs. `DISK` must be a disposable qcow2; never point it at `/dev/*`.
- Serve the install fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
## Definition of a good stopping point ## Definition of a good stopping point

View file

@ -10,7 +10,7 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| 3 | Port the deterministic core | Done | `phoebus-core` (config, plan, policy, validation, models) | | 3 | Port the deterministic core | Done | `phoebus-core` (config, plan, policy, validation, models) |
| 4 | Port the destructive backend | Done | `phoebus-executor` (storage, LUKS2, Btrfs, Portage, boot, users, services) | | 4 | Port the destructive backend | Done | `phoebus-executor` (storage, LUKS2, Btrfs, Portage, boot, users, services) |
| 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s | | 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s |
| 6 | Finish the desktop | Partial | **Mango + DankMaterialShell is the default** (dwl fallback); greetd login; live ISO builds a Mango desktop; graphical-VM verification pending | | 6 | Finish the desktop | Partial | **Mango + DankMaterialShell is the default** (dwl fallback); greetd login; the live ISO boots the branded welcome + graphical installer and was verified in a graphical VM; installed-desktop verification pending |
| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; bounded typed `flatpak_*` actions added; no app installed yet | | 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; bounded typed `flatpak_*` actions added; no app installed yet |
| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries); resolved-effect previews added | | 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries); resolved-effect previews added |
| 9 | Background update preparation | Partial | distfile fetch VM-verified; `--buildpkgonly` skipped while deps need merging (recorded Ready); activation explicit | | 9 | Background update preparation | Partial | distfile fetch VM-verified; `--buildpkgonly` skipped while deps need merging (recorded Ready); activation explicit |
@ -21,6 +21,7 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; release gates, atomic publish and signing helpers added; no CI runner has executed a gate | | 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; release gates, atomic publish and signing helpers added; no CI runner has executed a gate |
| 15 | Recovery environment | Later | recovery BLS entry generated; snapshot-based recovery entry written at install; full recovery image not built | | 15 | Recovery environment | Later | recovery BLS entry generated; snapshot-based recovery entry written at install; full recovery image not built |
| — | Rust TUI | Partial | ratatui UI with plan/ERASE and AI provider selection; not yet the default on all paths | | — | Rust TUI | Partial | ratatui UI with plan/ERASE and AI provider selection; not yet the default on all paths |
| — | Graphical installer (welcome + wizard) | Partial | Quickshell/QML over the typed `--gui-bridge`; live graphical VM verified, including a detached install+boot; live AI call pending (ADR 0010) |
| — | AI-guided install optimization | Partial | DeepSeek/OpenAI/local providers, evidence-gated typed review, mandatory at install with `--no-ai` break-glass; fixture-verified, no live call | | — | AI-guided install optimization | Partial | DeepSeek/OpenAI/local providers, evidence-gated typed review, mandatory at install with `--no-ai` break-glass; fixture-verified, no live call |
| — | Nix as a built-in second lane | Partial | pinned-release bootstrap; `nix-daemon` active and `nix shell nixpkgs#hello` VM-verified; on by default | | — | Nix as a built-in second lane | Partial | pinned-release bootstrap; `nix-daemon` active and `nix shell nixpkgs#hello` VM-verified; on by default |
| — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` | | — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` |

View file

@ -58,11 +58,15 @@ still not VM-verified.
| Source package compilation | yes | yes | yes | n/a | | Source package compilation | yes | yes | yes | n/a |
| Kernel install + dracut initramfs | yes | yes | yes | no | | Kernel install + dracut initramfs | yes | yes | yes | no |
| systemd-boot + BLS | yes | yes | yes | no | | systemd-boot + BLS | yes | yes | yes | no |
| Recovery BLS entry (rescue.target) | yes | yes | no | no | | Boot default pins the real kernel (not recovery) | yes | yes | yes | no |
| Recovery BLS entry (rescue.target) | yes | yes | boots (not default) | no |
| Users, passwords, sudo | yes | yes | yes | n/a | | Users, passwords, sudo | yes | yes | yes | n/a |
| Locale/timezone/keymap/services | yes | yes | yes | n/a | | Locale/timezone/keymap/services | yes | yes | yes | n/a |
| Rust VM boot parity | yes | yes | yes | no | | Rust VM boot parity | yes | yes | yes | no |
| Rust TUI | yes | yes | smoke test | no | | Rust TUI | yes | yes | smoke test | no |
| Typed GUI bridge (`--gui-bridge`) | yes | yes (dry-run) | live VM | n/a |
| Graphical welcome + install wizard (Quickshell) | yes | guards tested | live graphical VM | no |
| Phoebus brand system (SVG + tokens) | yes | yes | live VM | n/a |
| Desktop profile (dwl/waybar/mako/swaybg) | yes | partial | headless only | no | | Desktop profile (dwl/waybar/mako/swaybg) | yes | partial | headless only | no |
| Desktop session script (socket wait, polkit, cleanup) | yes | yes | functional test (stubs) | no | | Desktop session script (socket wait, polkit, cleanup) | yes | yes | functional test (stubs) | no |
| PipeWire/WirePlumber | yes | no | headless (`wpctl`) | no | | PipeWire/WirePlumber | yes | no | headless (`wpctl`) | no |
@ -85,9 +89,10 @@ still not VM-verified.
| Flatpak/Nix bounded typed actions | yes | yes | no | no | | Flatpak/Nix bounded typed actions | yes | yes | no | no |
| Desktop session helpers (menu/lock/idle) | yes | yes | functional test (stubs) | no | | Desktop session helpers (menu/lock/idle) | yes | yes | functional test (stubs) | no |
| Mango + DankMaterialShell profile | yes | yes | live graphical VM yes; installed no | no | | Mango + DankMaterialShell profile | yes | yes | live graphical VM yes; installed no | no |
| Mango is the default desktop | yes | yes | install pending | no | | Mango is the default desktop | yes | yes | live graphical VM yes; installed install pending | no |
| greetd login (Mango default, dwl fallback) | yes | yes | no | no | | greetd login (Mango default, dwl fallback) | yes | yes | no | no |
| Live desktop ISO (Mango + DMS) | yes | guards tested | graphical VM verified | no | | Live desktop ISO (Mango + DMS) | yes | guards tested | graphical VM + GUI journey + detached boot | no |
| Live welcome autostart + duplicate prevention | yes | guards tested | live graphical VM | no |
| GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no | | GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no |
| Release gates + atomic publish | yes | yes | no | n/a | | Release gates + atomic publish | yes | yes | no | n/a |
| `sys` verbs | yes | yes | yes | no | | `sys` verbs | yes | yes | yes | no |
@ -123,12 +128,20 @@ still not VM-verified.
distinguishes "default in configuration", "successfully built" and distinguishes "default in configuration", "successfully built" and
"graphically verified". "graphically verified".
- **The live desktop ISO** (`installer/live/build.sh`) builds a Debian testing - **The live desktop ISO** (`installer/live/build.sh`) builds a Debian testing
rootfs with Mango + DMS, live-only autologin and an "Install Phoebus" rootfs with Mango + DMS, live-only autologin, a branded welcome window and a
launcher. Its desktop-payload guards are unit-tested, and the built ISO graphical installer frontend over the typed bridge. Its desktop-payload
(`sha256 c235b873…`) was booted in a graphical, seat-providing VM: Mango, guards are unit-tested, and the built ISO
DMS and Quickshell were running and a `screendump` showed the DMS panel and (`sha256 2a52178c…`, 1.6 GiB) was booted in a graphical, seat-providing VM:
welcome window. The **installed** Mango system (GURU + compiled the welcome window opened automatically, the installer launched (a second
Quickshell/DMS) and the dwl fallback in a VM are not yet verified. launch created no duplicate), keyboard navigation reached the network and AI
steps, and advancing without a connected model was refused. The same ISO was
then installed non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and
booted **with the ISO detached** (systemd running, 0 failed units, LUKS2,
all Btrfs subvolumes, network). A live AI provider call was **not** possible
(no key in this environment); the AI step is verified as a blocked
prerequisite and with a fixture transport in unit tests. The **installed**
Mango system (GURU + compiled Quickshell/DMS) and the dwl fallback in a VM
are not yet verified.
- **AI sandbox** is implemented (`systemd-run` hardening properties, tested at - **AI sandbox** is implemented (`systemd-run` hardening properties, tested at
the argv level) and fails closed without `systemd-run`; it has not been the argv level) and fails closed without `systemd-run`; it has not been
exercised in a VM. Only typed actions and the privacy boundary were previously exercised in a VM. Only typed actions and the privacy boundary were previously

View file

@ -497,6 +497,61 @@ example `-device virtio-gpu-pci` with the serial console still attached);
Until results are recorded here, the default stands by owner decision but no Until results are recorded here, the default stands by owner decision but no
stability is claimed. stability is claimed.
## Graphical installer ISO and typed bridge (2026-09-21)
A dedicated driver, `installer/tests/vm/gui-driver.py`, boots the built live
ISO with a **graphical device** and a serial console, drives the graphical
frontend through the compositor, and captures QEMU framebuffer screenshots.
Artifact: `installer/live/phoebus-installer-amd64.iso`, 1.6 GiB,
`sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee`
(Mango 0.17.2 + DankMaterialShell 1.6.2).
What was observed (`gui` mode):
1. The live session autologins into Mango + DMS; the branded
`phoebus-welcome` window opens automatically. The DMS first-run greeter and
changelog dialogs do **not** appear (markers pre-seeded).
2. The welcome shows the wordmark, emblem, wallpaper, ISO version (`0.1.0`) and
readiness (network connected, UEFI, memory, cores), with "Install Phoebus
OS" dominant and the secondary tools plus Advanced present.
3. Launching `phoebus-install` opens the wizard; running it again leaves the
session count at 1 (`DUP n1=1 n2=1`), so duplicate installer sessions are
prevented.
4. Keyboard navigation (Ctrl+Right / Enter / Tab) reaches step 2 (network and
prerequisites, with real UEFI/memory/CPU/network values) and step 3 (AI
model). Provider selection, the secret API-key field and the model field
render; advancing without a connected model is refused with
"Connect and validate an AI model before continuing."
5. A backend probe on the real guest lists `/dev/vda` as unprotected and
selectable, and `/dev/sr0` as the `live_medium` installation medium,
protected (the model tests cover the classification logic).
6. Screenshots: `docs/screenshots/01-welcome.png` … `05-ai-blocked.png`. The
destination-disk, review and confirmation screens
(`06`–`08`) were rendered from the same QML against a dry-run backend
because a real provider call was not available in this environment.
What was **not** possible: a live AI provider call (no key/model in this
environment). The AI step is verified as a blocked prerequisite and in unit
tests with a fixture transport; it is **not** a passed live call.
Real install + detached boot on the same ISO (`install` then `boot` modes):
- Guest install used the same deterministic backend as the GUI
(`phoebus-installer --install --yes --no-ai`): `INSTALL-RC=0`,
`installation complete`, `NO_SECRET_LEAK`.
- Detached boot (no ISO, `-boot order=c`): systemd PID 1, `running`, **0
failed units**, `systemd-boot` menu shows **Gentoo Linux first**, LUKS2
unlocked, `/dev/vda1 -> /efi`, `cryptroot` Btrfs with
`/ /home /var /.snapshots /swap`, network up.
Bug found and fixed during this work: the snapshot recovery BLS entry shared
the kernel's `sort-key`, and the specification's final filename tie-break
(decreasing) made it first when the random machine-id sorted low; with
`default *` the installed system booted `systemd.unit=rescue.target`. Fixed by
pinning `loader.conf` to the newest real kernel entry and giving the recovery
entry `sort-key zzzz-phoebus-recovery`; unit tests pin both.
## Known remaining work ## Known remaining work
- The graphical session was verified with the **headless** wlroots backend - The graphical session was verified with the **headless** wlroots backend

View file

@ -0,0 +1,86 @@
# 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`).

Binary file not shown.

After

Width:  |  Height:  |  Size: 129 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 165 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 70 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

View file

@ -0,0 +1,18 @@
# Screenshots
Captured from the graphical installer ISO during the 2026-09-21 verification.
See `docs/VM-BOOT-VERIFICATION.md` for the commands and results.
| File | Source | Notes |
|------|--------|-------|
| `01-welcome.png` | disposable graphical VM | Live welcome window, autostarted |
| `02-installer-language.png` | disposable graphical VM | Wizard opened from the welcome action |
| `03-network-prerequisites.png` | disposable graphical VM | Real UEFI/memory/CPU/network values |
| `04-ai-model.png` | disposable graphical VM | Provider, secret key field, model |
| `05-ai-blocked.png` | disposable graphical VM | Advancing without a model is refused |
| `06-destination-disk.png` | host QML preview (dry-run backend) | No live AI call was possible in the VM, so the disk/review/confirm steps were rendered from the same QML against a dry-run backend. Protected disks and the reason are shown; in the VM `/dev/sr0` is additionally labelled the installation medium. |
| `07-review.png` | host QML preview | Plan/erase review |
| `08-confirm.png` | host QML preview | ERASE authorization |
The VM screenshots are the authoritative evidence for the graphical journey.
The host-preview screenshots are layout evidence only and are labelled as such.

View file

@ -112,6 +112,20 @@ impl BlsEntry {
entry.title = title.to_string(); entry.title = title.to_string();
entry entry
} }
/// Return a copy whose `sort-key` is `key`. Used to keep the recovery entry
/// sorted after the normal kernel entries: the specification's final
/// tie-break is by file name in decreasing order, so a recovery entry that
/// inherits the kernel's sort-key can otherwise sort first (and, with
/// `default *`, boot the installed system into recovery).
pub fn with_sort_key(&self, key: &str) -> Self {
let mut entry = self.clone();
entry
.extra
.retain(|line| !line.trim_start().starts_with("sort-key"));
entry.extra.push(format!("sort-key {key}"));
entry
}
} }
/// Replace the `rootflags=subvol=<name>` component of a kernel command line. /// Replace the `rootflags=subvol=<name>` component of a kernel command line.
@ -243,6 +257,21 @@ mod tests {
assert!(updated.options.contains("rootfstype=btrfs")); assert!(updated.options.contains("rootfstype=btrfs"));
} }
#[test]
fn with_sort_key_replaces_an_inherited_key() {
let with_key = "title Gentoo Linux\n\
linux /abcd/6.12.9/linux\n\
sort-key gentoo\n\
options root=/dev/x\n";
let entry = BlsEntry::parse("abcd-6.12.9.conf", with_key).unwrap();
let recovery = entry.with_sort_key("zzzz-phoebus-recovery");
let rendered = recovery.render();
assert!(rendered.contains("sort-key zzzz-phoebus-recovery"));
assert!(!rendered.contains("sort-key gentoo"));
// The kernel sort-key sorts before the recovery one (A-Z increasing).
assert!("gentoo" < "zzzz-phoebus-recovery");
}
#[test] #[test]
fn replace_handles_missing_subvol_and_rejects_empty() { fn replace_handles_missing_subvol_and_rejects_empty() {
assert!(replace_root_subvol("root=/dev/x rootflags=rw", "@new") assert!(replace_root_subvol("root=/dev/x rootflags=rw", "@new")

View file

@ -0,0 +1,270 @@
//! Phoebus visual identity: a small, reusable branding system.
//!
//! Everything here is deterministic text so it can be emitted by the static
//! installer (see `--emit-asset`) and unit-tested without a display. The same
//! assets are used by the live desktop, the boot menu, the welcome window and
//! the graphical installer, so the identity never diverges between surfaces.
//!
//! Palette (established here because none existed): charcoal, warm white and
//! restrained amber accents. Tokens are exported as JSON for the Quickshell/QML
//! frontend so no surface hard-codes its own copy.
use serde::Serialize;
/// The shared colour tokens. Contrast on `charcoal`/`surface` is checked by the
/// tests, so a token change that breaks readability fails the build.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct Palette {
/// Page/backdrop charcoal.
pub charcoal: &'static str,
/// Raised surface (cards, panels).
pub surface: &'static str,
/// Hairline border.
pub border: &'static str,
/// Primary body text: warm white.
pub warm_white: &'static str,
/// Secondary/muted text.
pub muted: &'static str,
/// Restrained amber accent (primary action, focus).
pub amber: &'static str,
/// Deeper amber for pressed/hover states.
pub amber_deep: &'static str,
/// Success.
pub success: &'static str,
/// Warning.
pub warning: &'static str,
/// Danger / destructive.
pub danger: &'static str,
}
pub const PALETTE: Palette = Palette {
charcoal: "#17171b",
surface: "#232329",
border: "#3a3a42",
warm_white: "#f4efe6",
muted: "#a8a29a",
amber: "#e8a33d",
amber_deep: "#c97f24",
success: "#7fb069",
warning: "#e0a24a",
danger: "#d2564b",
};
/// Parse a `#rrggbb` token into `(r, g, b)`; used for the contrast tests.
pub fn rgb(hex: &str) -> (u8, u8, u8) {
let h = hex.trim_start_matches('#');
(
u8::from_str_radix(&h[0..2], 16).expect("red"),
u8::from_str_radix(&h[2..4], 16).expect("green"),
u8::from_str_radix(&h[4..6], 16).expect("blue"),
)
}
/// WCAG relative luminance.
pub fn relative_luminance(hex: &str) -> f64 {
fn channel(c: u8) -> f64 {
let c = c as f64 / 255.0;
if c <= 0.03928 {
c / 12.92
} else {
((c + 0.055) / 1.055).powf(2.4)
}
}
let (r, g, b) = rgb(hex);
0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
}
/// WCAG contrast ratio between two `#rrggbb` colours.
pub fn contrast_ratio(a: &str, b: &str) -> f64 {
let (la, lb) = (relative_luminance(a), relative_luminance(b));
let (hi, lo) = if la > lb { (la, lb) } else { (lb, la) };
(hi + 0.05) / (lo + 0.05)
}
/// The colour tokens as a stable JSON document consumed by the QML frontend.
pub fn palette_json() -> String {
serde_json::to_string_pretty(&PALETTE).expect("palette serialises")
}
/// The sun-inspired emblem: a warm core, a soft ring and tapered rays. Kept as
/// a single, scalable vector with no external references.
pub const EMBLEM_SVG: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Phoebus sun emblem">
<title>Phoebus OS</title>
<g fill="none" stroke="#e8a33d" stroke-linecap="round">
<g stroke-width="10">
<line x1="128" y1="16" x2="128" y2="52"/>
<line x1="128" y1="204" x2="128" y2="240"/>
<line x1="16" y1="128" x2="52" y2="128"/>
<line x1="204" y1="128" x2="240" y2="128"/>
<line x1="49" y1="49" x2="74" y2="74"/>
<line x1="182" y1="182" x2="207" y2="207"/>
<line x1="49" y1="207" x2="74" y2="182"/>
<line x1="182" y1="74" x2="207" y2="49"/>
</g>
<g stroke-width="7" opacity="0.75">
<line x1="76" y1="27" x2="92" y2="59"/>
<line x1="180" y1="229" x2="164" y2="197"/>
<line x1="229" y1="76" x2="197" y2="92"/>
<line x1="27" y1="180" x2="59" y2="164"/>
<line x1="27" y1="76" x2="59" y2="92"/>
<line x1="229" y1="180" x2="197" y2="164"/>
<line x1="76" y1="229" x2="92" y2="197"/>
<line x1="180" y1="27" x2="164" y2="59"/>
</g>
</g>
<circle cx="128" cy="128" r="56" fill="#e8a33d"/>
<circle cx="128" cy="128" r="40" fill="#f4efe6"/>
</svg>
"##;
/// The wordmark for headers and the boot menu. Text is drawn with the generic
/// `sans-serif` family so it renders in any environment; the emblem is inlined
/// so the file is self-contained.
pub const WORDMARK_SVG: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 160" width="640" height="160" role="img" aria-label="Phoebus OS wordmark">
<title>Phoebus OS</title>
<g transform="translate(24 28) scale(0.42)">
<g fill="none" stroke="#e8a33d" stroke-linecap="round" stroke-width="10">
<line x1="128" y1="16" x2="128" y2="52"/>
<line x1="128" y1="204" x2="128" y2="240"/>
<line x1="16" y1="128" x2="52" y2="128"/>
<line x1="204" y1="128" x2="240" y2="128"/>
<line x1="49" y1="49" x2="74" y2="74"/>
<line x1="182" y1="182" x2="207" y2="207"/>
<line x1="49" y1="207" x2="74" y2="182"/>
<line x1="182" y1="74" x2="207" y2="49"/>
</g>
<circle cx="128" cy="128" r="56" fill="#e8a33d"/>
<circle cx="128" cy="128" r="40" fill="#f4efe6"/>
</g>
<text x="168" y="104" fill="#f4efe6" font-family="sans-serif" font-size="72" font-weight="600" letter-spacing="2">PHOEBUS</text>
<text x="500" y="104" fill="#e8a33d" font-family="sans-serif" font-size="72" font-weight="300">OS</text>
</svg>
"##;
/// The live wallpaper: charcoal field, a soft horizon glow and a faint emblem.
/// Emitted as SVG so it scales to any display without a raster build step.
pub const WALLPAPER_SVG: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="1920" height="1080" preserveAspectRatio="xMidYMid slice">
<defs>
<radialGradient id="glow" cx="50%" cy="64%" r="62%">
<stop offset="0%" stop-color="#e8a33d" stop-opacity="0.30"/>
<stop offset="42%" stop-color="#c97f24" stop-opacity="0.10"/>
<stop offset="100%" stop-color="#17171b" stop-opacity="0"/>
</radialGradient>
<linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#1c1c22"/>
<stop offset="60%" stop-color="#17171b"/>
<stop offset="100%" stop-color="#121215"/>
</linearGradient>
</defs>
<rect width="1920" height="1080" fill="url(#bg)"/>
<rect width="1920" height="1080" fill="url(#glow)"/>
<g transform="translate(960 620)" opacity="0.10" fill="none" stroke="#f4efe6" stroke-linecap="round" stroke-width="10">
<circle r="150"/>
<circle r="96" fill="#f4efe6" stroke="none"/>
</g>
<text x="960" y="880" text-anchor="middle" fill="#f4efe6" fill-opacity="0.10" font-family="sans-serif" font-size="120" font-weight="600" letter-spacing="16">PHOEBUS</text>
</svg>
"##;
/// A named branding asset, for the existing `--emit-asset` plumbing.
pub fn brand_asset(name: &str) -> Option<String> {
Some(match name {
"brand-emblem" => EMBLEM_SVG.to_string(),
"brand-wordmark" => WORDMARK_SVG.to_string(),
"brand-wallpaper" => WALLPAPER_SVG.to_string(),
"brand-tokens" => palette_json(),
_ => return None,
})
}
#[cfg(test)]
mod tests {
use super::*;
fn assert_svg(doc: &str) {
assert!(
doc.trim_start().starts_with("<svg "),
"not an SVG: {doc:.40}"
);
assert!(doc.trim_end().ends_with("</svg>"));
assert!(doc.contains("viewBox="));
assert!(!doc.contains("http://") || doc.contains("http://www.w3.org/2000/svg"));
}
#[test]
fn assets_are_well_formed_svg() {
assert_svg(EMBLEM_SVG);
assert_svg(WORDMARK_SVG);
assert_svg(WALLPAPER_SVG);
}
#[test]
fn assets_use_the_shared_palette() {
for doc in [EMBLEM_SVG, WORDMARK_SVG, WALLPAPER_SVG] {
assert!(
doc.contains(PALETTE.amber) || doc.contains(PALETTE.amber_deep),
"asset is missing the amber accent"
);
assert!(
doc.contains(PALETTE.warm_white) || doc.contains(PALETTE.charcoal),
"asset is missing a core palette colour"
);
}
}
#[test]
fn wordmark_names_the_product() {
assert!(WORDMARK_SVG.contains("PHOEBUS"));
assert!(WORDMARK_SVG.contains("OS"));
}
#[test]
fn palette_tokens_are_valid_hex_and_readable() {
let all = [
PALETTE.charcoal,
PALETTE.surface,
PALETTE.border,
PALETTE.warm_white,
PALETTE.muted,
PALETTE.amber,
PALETTE.amber_deep,
PALETTE.success,
PALETTE.warning,
PALETTE.danger,
];
for token in all {
assert_eq!(token.len(), 7, "token {token} is not #rrggbb");
assert!(token.starts_with('#'));
assert!(token[1..].chars().all(|c| c.is_ascii_hexdigit()));
}
// Body text must clear WCAG AA (4.5:1) on both page and surface.
assert!(contrast_ratio(PALETTE.warm_white, PALETTE.charcoal) >= 4.5);
assert!(contrast_ratio(PALETTE.warm_white, PALETTE.surface) >= 4.5);
// Accent text/controls clear AA as large/UI text (3:1).
assert!(contrast_ratio(PALETTE.amber, PALETTE.charcoal) >= 3.0);
// Muted text still clears AA on the page.
assert!(contrast_ratio(PALETTE.muted, PALETTE.charcoal) >= 4.5);
}
#[test]
fn tokens_round_trip_as_json() {
let json = palette_json();
let back: serde_json::Value = serde_json::from_str(&json).unwrap();
assert_eq!(back["charcoal"], serde_json::json!(PALETTE.charcoal));
assert_eq!(back["amber"], serde_json::json!(PALETTE.amber));
assert!(json.contains("charcoal"));
}
#[test]
fn named_lookup_is_exact() {
for name in [
"brand-emblem",
"brand-wordmark",
"brand-wallpaper",
"brand-tokens",
] {
assert!(brand_asset(name).is_some(), "{name} missing");
}
assert!(brand_asset("brand-nope").is_none());
}
}

View file

@ -5,6 +5,7 @@
pub mod action; pub mod action;
pub mod boot; pub mod boot;
pub mod brand;
pub mod config; pub mod config;
pub mod disk; pub mod disk;
pub mod effects; pub mod effects;

View file

@ -814,6 +814,13 @@ elif [ "$started" = 0 ]; then
echo "phoebus-session-mango: dms not found; the shell will not start" >&2 echo "phoebus-session-mango: dms not found; the shell will not start" >&2
fi fi
# Live medium only: open the branded welcome/installation launcher once the
# session is up. The marker exists only on the live rootfs, so an installed
# system never starts it. This never authorizes or starts disk changes.
if [ -e /etc/phoebus/live ] && command -v phoebus-welcome >/dev/null 2>&1; then
start_helper phoebus-welcome
fi
# Run until the compositor exits; the EXIT trap stops the shell and helpers. # Run until the compositor exits; the EXIT trap stops the shell and helpers.
wait "$MANGO_PID" wait "$MANGO_PID"
"#; "#;
@ -992,6 +999,7 @@ pub fn desktop_asset(name: &str) -> Option<String> {
"session-dwl" => PHOEBUS_SESSION_SCRIPT.to_string(), "session-dwl" => PHOEBUS_SESSION_SCRIPT.to_string(),
"assistant" => PHOEBUS_ASSISTANT_SCRIPT.to_string(), "assistant" => PHOEBUS_ASSISTANT_SCRIPT.to_string(),
"install" => PHOEBUS_INSTALL_SCRIPT.to_string(), "install" => PHOEBUS_INSTALL_SCRIPT.to_string(),
"welcome" => PHOEBUS_WELCOME_SCRIPT.to_string(),
"menu" => PHOEBUS_MENU_SCRIPT.to_string(), "menu" => PHOEBUS_MENU_SCRIPT.to_string(),
"lock" => PHOEBUS_LOCK_SCRIPT.to_string(), "lock" => PHOEBUS_LOCK_SCRIPT.to_string(),
"idle" => PHOEBUS_IDLE_SCRIPT.to_string(), "idle" => PHOEBUS_IDLE_SCRIPT.to_string(),
@ -1004,47 +1012,57 @@ pub fn desktop_asset(name: &str) -> Option<String> {
"greetd-live" => greetd_config_live(LIVE_USER, live_cmd), "greetd-live" => greetd_config_live(LIVE_USER, live_cmd),
"wayland-session-mango" => wayland_session_entry(DesktopProfile::Mango)?.1, "wayland-session-mango" => wayland_session_entry(DesktopProfile::Mango)?.1,
"wayland-session-dwl" => wayland_session_entry(DesktopProfile::Dwl)?.1, "wayland-session-dwl" => wayland_session_entry(DesktopProfile::Dwl)?.1,
_ => return None, // The brand system lives in `brand`; route the shared `--emit-asset`
// plumbing through it so the live build has one source of assets.
_ => return crate::brand::brand_asset(name),
}) })
} }
/// `phoebus-install`: open the existing installer UI. It never starts a /// `phoebus-install`: open the graphical installer frontend, falling back to
/// destructive operation by itself: the plan, disk protection, AI requirement, /// the deterministic TUI/CLI. It never starts a destructive operation by
/// credential handling and the ERASE confirmation all stay in force. /// itself: the plan, disk protection, AI requirement, credential handling and
/// the ERASE confirmation all stay in force. A second invocation never opens a
/// duplicate installer session.
pub const PHOEBUS_INSTALL_SCRIPT: &str = r#"#!/bin/bash pub const PHOEBUS_INSTALL_SCRIPT: &str = r#"#!/bin/bash
# Open the Phoebus installer. This only launches the installer UI; the user # Open the Phoebus installer. This only launches the installer UI; the user
# still reviews the plan, supplies credentials and confirms ERASE. # still reviews the plan, supplies credentials and confirms ERASE.
set -u set -u
# Prevent duplicate installer sessions. Quickshell's --no-duplicate also
# guards this, but the check lets us tell the user why nothing opened.
if pgrep -f "quickshell.*phoebus-install" >/dev/null 2>&1; then
echo "The Phoebus installer is already open." >&2
exit 0
fi
# The graphical installer is the primary path; it needs a Wayland session.
if [ "${XDG_SESSION_TYPE:-}" = "wayland" ] || [ -n "${WAYLAND_DISPLAY:-}" ]; then
if command -v quickshell >/dev/null 2>&1 \
&& [ -f /etc/xdg/quickshell/phoebus-install/shell.qml ]; then
exec quickshell --no-duplicate -c phoebus-install
fi
fi
# Deterministic fallback (TUI, then CLI) works with no model and no Wayland.
conf="/etc/phoebus/install.conf" conf="/etc/phoebus/install.conf"
args=() args=()
[ -f "$conf" ] && args+=(--config "$conf") [ -f "$conf" ] && args+=(--config "$conf")
run() { installer=""
local installer="" for candidate in /usr/local/bin/phoebus-installer phoebus-installer; do
for candidate in \
/run/live/medium/phoebus/bin/phoebus \
/phoebus/bin/phoebus \
/usr/local/bin/phoebus-installer \
phoebus-installer; do
if command -v "$candidate" >/dev/null 2>&1; then if command -v "$candidate" >/dev/null 2>&1; then
installer="$candidate" installer="$candidate"
break break
fi fi
done done
if [ -z "$installer" ]; then if [ -z "$installer" ]; then
echo "phoebus-install: installer not found" >&2 echo "phoebus-install: installer not found" >&2
return 1 exit 1
fi fi
if [ "$(id -u)" -eq 0 ]; then
"$installer" "${args[@]}"
else
sudo -n "$installer" "${args[@]}"
fi
}
# Re-entrant wrapper: the inner invocation (inside the terminal) just runs. # Re-entrant wrapper: the inner invocation (inside the terminal) just runs.
if [ "${1:-}" = "--in-terminal" ]; then if [ "${1:-}" = "--in-terminal" ]; then
run "$installer" "${args[@]}"
rc=$? rc=$?
echo echo
read -rp "Press Enter to close" _ || true read -rp "Press Enter to close" _ || true
@ -1052,24 +1070,45 @@ if [ "${1:-}" = "--in-terminal" ]; then
fi fi
if command -v kitty >/dev/null 2>&1; then if command -v kitty >/dev/null 2>&1; then
exec kitty --title "Install Phoebus" -e "$0" --in-terminal exec kitty --title "Install Phoebus OS" -e "$0" --in-terminal
fi fi
run if [ "$(id -u)" -eq 0 ]; then
exec "$installer" "${args[@]}"
else
exec sudo -n "$installer" "${args[@]}"
fi
"#;
/// `phoebus-welcome`: open (or focus, via the single-instance guard) the live
/// welcome window. Only installed on the live medium.
pub const PHOEBUS_WELCOME_SCRIPT: &str = r#"#!/bin/bash
# Live-medium welcome and installation launcher.
set -u
if pgrep -f "quickshell.*phoebus-welcome" >/dev/null 2>&1; then
exit 0
fi
if command -v quickshell >/dev/null 2>&1 \
&& [ -f /etc/xdg/quickshell/phoebus-welcome/shell.qml ]; then
exec quickshell --no-duplicate -c phoebus-welcome
fi
echo "phoebus-welcome: quickshell or the welcome config is missing" >&2
exit 1
"#; "#;
/// The application entry that makes the installer discoverable in the desktop /// The application entry that makes the installer discoverable in the desktop
/// launcher ("Install Phoebus"). /// launcher ("Install Phoebus OS"). It is live-medium only.
pub const PHOEBUS_INSTALL_DESKTOP_ENTRY: &str = "\ pub const PHOEBUS_INSTALL_DESKTOP_ENTRY: &str = "\
[Desktop Entry]\n\ [Desktop Entry]\n\
Type=Application\n\ Type=Application\n\
Name=Install Phoebus\n\ Name=Install Phoebus OS\n\
GenericName=System installer\n\
Comment=Install Phoebus OS to disk\n\ Comment=Install Phoebus OS to disk\n\
Exec=/usr/local/bin/phoebus-install\n\ Exec=/usr/local/bin/phoebus-install\n\
TryExec=/usr/local/bin/phoebus-install\n\ TryExec=/usr/local/bin/phoebus-install\n\
Icon=system-software-install\n\ Icon=phoebus\n\
Terminal=false\n\ Terminal=false\n\
Categories=System;\n\ Categories=System;Settings;\n\
Keywords=install;phoebus;\n"; Keywords=install;phoebus;setup;\n";
/// Btrfs mount options, matching the proven behavior. /// Btrfs mount options, matching the proven behavior.
pub fn btrfs_mount_opts(compress: &str, ssd: bool) -> String { pub fn btrfs_mount_opts(compress: &str, ssd: bool) -> String {

View file

@ -48,14 +48,56 @@ pub fn install_systemd_boot(exec: &Exec, config: &InstallConfig) -> Result<()> {
pub fn write_loader_conf(exec: &Exec, config: &InstallConfig) -> Result<()> { pub fn write_loader_conf(exec: &Exec, config: &InstallConfig) -> Result<()> {
let dir = esp_path(exec, config).join("loader"); let dir = esp_path(exec, config).join("loader");
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?; std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let text = "# systemd-boot configuration\ndefault *\ntimeout 3\nconsole-mode keep\neditor no\n"; // Pin the default to the newest real kernel entry. `default *` picks the
// first entry by systemd-boot's ordering, and the recovery entry (written
// later) can sort first, which would boot the installed system into rescue
// mode by default.
let default = default_entry_id(&dir.join("entries")).unwrap_or_else(|| "*".to_string());
let text = format!(
"# systemd-boot configuration\ndefault {default}\ntimeout 3\nconsole-mode keep\neditor no\n"
);
std::fs::write(dir.join("loader.conf"), text) std::fs::write(dir.join("loader.conf"), text)
.map_err(|e| ExecError::io(dir.join("loader.conf"), e))?; .map_err(|e| ExecError::io(dir.join("loader.conf"), e))?;
exec.logger exec.logger.info(format!(
.info(format!("wrote {}", dir.join("loader.conf").display())); "wrote {} (default {default})",
dir.join("loader.conf").display()
));
Ok(()) Ok(())
} }
/// The id (file name without `.conf`) of the newest non-recovery kernel entry,
/// so `loader.conf` can pin it as the default.
fn default_entry_id(entries: &Path) -> Option<String> {
use phoebus_core::boot::{version_key, BlsEntry};
let mut best: Option<(Vec<u64>, String)> = None;
for entry in std::fs::read_dir(entries).ok()? {
let entry = entry.ok()?;
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("conf") {
continue;
}
let name = entry.file_name().to_string_lossy().to_string();
if name.starts_with("phoebus-") {
continue;
}
let id = name.trim_end_matches(".conf").to_string();
let Ok(text) = std::fs::read_to_string(&path) else {
continue;
};
let Some(parsed) = BlsEntry::parse(&name, &text) else {
continue;
};
let key = parsed
.kernel_version()
.map(|v| version_key(&v))
.unwrap_or_default();
if best.as_ref().map(|(k, _)| key > *k).unwrap_or(true) {
best = Some((key, id));
}
}
best.map(|(_, id)| id)
}
pub fn generate_entries(exec: &Exec) -> Result<()> { pub fn generate_entries(exec: &Exec) -> Result<()> {
portage::chroot(exec, Path::new(&exec.root), "kernel-install", &["add-all"]) portage::chroot(exec, Path::new(&exec.root), "kernel-install", &["add-all"])
} }
@ -219,6 +261,9 @@ pub fn write_snapshot_recovery_entry(
.with_root_subvol(&subvol) .with_root_subvol(&subvol)
.map_err(|e| ExecError::operation("boot_install", "rewrite recovery entry", e))? .map_err(|e| ExecError::operation("boot_install", "rewrite recovery entry", e))?
.with_title("Phoebus Recovery (known-good snapshot)") .with_title("Phoebus Recovery (known-good snapshot)")
// Force the recovery entry to sort after every normal kernel entry, so
// it can never become the default by filename tie-break.
.with_sort_key("zzzz-phoebus-recovery")
.with_option("ro systemd.unit=rescue.target"); .with_option("ro systemd.unit=rescue.target");
let dest = entries.join("phoebus-recovery.conf"); let dest = entries.join("phoebus-recovery.conf");
std::fs::write(&dest, recovery.render()).map_err(|e| ExecError::io(dest.clone(), e))?; std::fs::write(&dest, recovery.render()).map_err(|e| ExecError::io(dest.clone(), e))?;
@ -297,4 +342,37 @@ mod tests {
assert!(text.contains("/token/6.18.48/initrd")); assert!(text.contains("/token/6.18.48/initrd"));
assert!(text.contains("systemd.unit=rescue.target")); assert!(text.contains("systemd.unit=rescue.target"));
} }
#[test]
fn loader_default_is_the_newest_normal_entry_not_a_recovery_entry() {
let dir = tempfile::tempdir().unwrap();
let entries = dir.path();
std::fs::write(
entries.join("gentoo-6.18.48.conf"),
"title Gentoo Linux\nlinux /gentoo/6.18.48/linux\noptions root=/dev/mapper/cryptroot rw quiet\n",
)
.unwrap();
std::fs::write(
entries.join("gentoo-6.19.2.conf"),
"title Gentoo Linux\nlinux /gentoo/6.19.2/linux\noptions root=/dev/mapper/cryptroot rw quiet\n",
)
.unwrap();
std::fs::write(
entries.join("phoebus-recovery.conf"),
"title Phoebus Recovery (known-good snapshot)\nlinux /gentoo/6.19.2/linux\noptions ro systemd.unit=rescue.target\n",
)
.unwrap();
assert_eq!(default_entry_id(entries).as_deref(), Some("gentoo-6.19.2"));
}
#[test]
fn loader_default_is_none_without_a_normal_entry() {
let dir = tempfile::tempdir().unwrap();
std::fs::write(
dir.path().join("phoebus-recovery.conf"),
"title Recovery\nlinux /gentoo/6.19.2/linux\noptions ro systemd.unit=rescue.target\n",
)
.unwrap();
assert_eq!(default_entry_id(dir.path()), None);
}
} }

View file

@ -64,17 +64,9 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> {
sysgen::PHOEBUS_ASSISTANT_SCRIPT, sysgen::PHOEBUS_ASSISTANT_SCRIPT,
)?; )?;
// "Install Phoebus": discoverable in the launcher, opens the installer UI // The "Install Phoebus OS" entry point and welcome launcher are live-medium
// without starting any destructive operation. // only: an installed system has no business offering to reinstall itself.
write_script( // They are installed by the live build, not here.
&target,
"usr/local/bin/phoebus-install",
sysgen::PHOEBUS_INSTALL_SCRIPT,
)?;
target.write(
"usr/share/applications/phoebus-install.desktop",
sysgen::PHOEBUS_INSTALL_DESKTOP_ENTRY,
)?;
match config.desktop.profile { match config.desktop.profile {
DesktopProfile::Mango => { DesktopProfile::Mango => {
@ -370,7 +362,7 @@ mod tests {
} }
#[test] #[test]
fn mango_profile_configures_greetd_login_and_install_launcher() { fn mango_profile_configures_greetd_login_and_no_install_shortcut() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();
let exec = make_exec(runner.clone()); let exec = make_exec(runner.clone());
let mut cfg = InstallConfig::default(); let mut cfg = InstallConfig::default();
@ -378,13 +370,14 @@ mod tests {
write_session_script(&exec, &cfg).unwrap(); write_session_script(&exec, &cfg).unwrap();
configure_login(&exec, &cfg).unwrap(); configure_login(&exec, &cfg).unwrap();
for rel in [ assert!(exec.root.join("etc/greetd/config.toml").is_file());
"usr/local/bin/phoebus-install", // The installer shortcut is live-medium only; an installed system must
"usr/share/applications/phoebus-install.desktop", // not advertise a reinstall entry point.
"etc/greetd/config.toml", assert!(!exec.root.join("usr/local/bin/phoebus-install").exists());
] { assert!(!exec
assert!(exec.root.join(rel).is_file(), "{rel} was not installed"); .root
} .join("usr/share/applications/phoebus-install.desktop")
.exists());
let login = std::fs::read_to_string(exec.root.join("etc/greetd/config.toml")).unwrap(); let login = std::fs::read_to_string(exec.root.join("etc/greetd/config.toml")).unwrap();
assert!(login.contains("phoebus-session-mango")); assert!(login.contains("phoebus-session-mango"));
assert!(login.contains("tuigreet")); assert!(login.contains("tuigreet"));
@ -398,6 +391,22 @@ mod tests {
assert!(commands.iter().any(|a| a.contains("useradd"))); assert!(commands.iter().any(|a| a.contains("useradd")));
} }
#[test]
fn live_autostart_is_gated_on_the_live_marker() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let mut cfg = InstallConfig::default();
cfg.desktop.profile = DesktopProfile::Mango;
write_session_script(&exec, &cfg).unwrap();
let mango =
std::fs::read_to_string(exec.root.join("usr/local/bin/phoebus-session-mango")).unwrap();
assert!(
mango.contains("/etc/phoebus/live"),
"the welcome autostart must be gated on the live marker"
);
assert!(mango.contains("phoebus-welcome"));
}
#[test] #[test]
fn explicit_none_writes_no_login_configuration() { fn explicit_none_writes_no_login_configuration() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();

View file

@ -318,6 +318,10 @@ fn live_source_disks(runner: &dyn ProcessRunner) -> Vec<String> {
"/", "/",
"/run/initramfs", "/run/initramfs",
"/run/live", "/run/live",
// Debian live-boot mounts the medium here; the ISO/medium device must
// be identified so the installer can label and protect it.
"/run/live/medium",
"/run/live/rootfs",
"/mnt/cdrom", "/mnt/cdrom",
"/mnt/live", "/mnt/live",
"/lib/live", "/lib/live",

File diff suppressed because it is too large Load diff

View file

@ -1,7 +1,8 @@
//! Phoebus installer orchestration and CLI support. //! Phoebus installer orchestration and CLI support.
pub mod ai_guide; pub mod ai_guide;
pub mod gui_bridge;
pub mod orchestrate; pub mod orchestrate;
pub mod release; pub mod release;
pub use orchestrate::Installer; pub use orchestrate::{InstallObserver, Installer, NoopObserver};

View file

@ -115,6 +115,11 @@ struct Cli {
/// Used by the live ISO build so it reuses the installer's exact assets. /// Used by the live ISO build so it reuses the installer's exact assets.
#[arg(long, value_name = "NAME", hide = true)] #[arg(long, value_name = "NAME", hide = true)]
emit_asset: Option<String>, emit_asset: Option<String>,
/// Speak the typed JSON protocol used by the graphical installer frontend
/// (stdin/stdout). Not intended for direct interactive use.
#[arg(long, hide = true)]
gui_bridge: bool,
} }
struct TerminalConfirm; struct TerminalConfirm;
@ -265,6 +270,11 @@ fn main() -> ExitCode {
fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> { fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
let cli = Cli::parse(); let cli = Cli::parse();
if cli.gui_bridge {
phoebus_installer::gui_bridge::run_stdio()?;
return Ok(ExitCode::SUCCESS);
}
if let Some(name) = &cli.emit_asset { if let Some(name) = &cli.emit_asset {
return match phoebus_core::system::desktop_asset(name) { return match phoebus_core::system::desktop_asset(name) {
Some(text) => { Some(text) => {

View file

@ -27,6 +27,23 @@ pub struct Installer {
pub state: StorageState, pub state: StorageState,
} }
/// Receives stage transitions during [`Installer::install_observed`]. The GUI
/// bridge uses this to show real backend stages; it is deliberately a narrow
/// trait so no frontend can influence execution.
pub trait InstallObserver {
fn stage_started(&mut self, step: phoebus_core::InstallStep);
/// `error` is `None` on success, otherwise a redactable message.
fn stage_finished(&mut self, step: phoebus_core::InstallStep, error: Option<&str>);
}
/// Does nothing; the default for callers that do not report progress.
pub struct NoopObserver;
impl InstallObserver for NoopObserver {
fn stage_started(&mut self, _step: phoebus_core::InstallStep) {}
fn stage_finished(&mut self, _step: phoebus_core::InstallStep, _error: Option<&str>) {}
}
impl Installer { impl Installer {
pub fn new(config: InstallConfig, exec: Exec) -> Self { pub fn new(config: InstallConfig, exec: Exec) -> Self {
let hardware = probe::probe_hardware(exec.runner.as_ref()); let hardware = probe::probe_hardware(exec.runner.as_ref());
@ -64,6 +81,21 @@ impl Installer {
InstallPlan::for_config(&self.config) InstallPlan::for_config(&self.config)
} }
/// Replace the configuration after a frontend edit, recomputing the derived
/// policy context so package decisions reflect the new selection. Hardware
/// and disks are unchanged by a configuration edit.
pub fn reconfigure(&mut self, config: InstallConfig) {
let binhost_available = config.packages.binary_packages
&& !phoebus_core::system::resolved_binhost_uri(&config).is_empty();
self.policy_ctx = PolicyContext {
policy: config.packages.policy,
binhost_available,
memory_mib: self.hardware.memory_mib,
cores: self.hardware.cpu.cores,
};
self.config = config;
}
pub fn render_plan(&self) -> String { pub fn render_plan(&self) -> String {
self.plan().render_human(&self.config, Some(&self.hardware)) self.plan().render_human(&self.config, Some(&self.hardware))
} }
@ -144,14 +176,36 @@ impl Installer {
luks_passphrase: Option<&SecretString>, luks_passphrase: Option<&SecretString>,
user_password: Option<&SecretString>, user_password: Option<&SecretString>,
root_password: Option<&SecretString>, root_password: Option<&SecretString>,
) -> Result<()> {
self.install_observed(
auth,
luks_passphrase,
user_password,
root_password,
&mut NoopObserver,
)
}
/// As [`Installer::install`], reporting each stage to `observer`. This is
/// the real executor loop, not a re-implementation: the observer only sees
/// transitions the backend actually performs.
pub fn install_observed(
&mut self,
auth: &phoebus_executor::DestructiveAuthorization,
luks_passphrase: Option<&SecretString>,
user_password: Option<&SecretString>,
root_password: Option<&SecretString>,
observer: &mut dyn InstallObserver,
) -> Result<()> { ) -> Result<()> {
let steps = self.plan().steps.clone(); let steps = self.plan().steps.clone();
for step in steps { for step in steps {
let name = step.name(); let name = step.name();
self.exec.logger.section(name); self.exec.logger.section(name);
observer.stage_started(step);
let result = self.run_step(step, auth, luks_passphrase, user_password, root_password); let result = self.run_step(step, auth, luks_passphrase, user_password, root_password);
if let Err(e) = result { if let Err(e) = result {
self.exec.logger.error(format!("stage failed: {name}: {e}")); self.exec.logger.error(format!("stage failed: {name}: {e}"));
observer.stage_finished(step, Some(&self.exec.redactor().redact(&e.to_string())));
if !self.exec.dry_run { if !self.exec.dry_run {
let _ = self.exec.export_log(); let _ = self.exec.export_log();
let _ = self.exec.umount_chroot(); let _ = self.exec.umount_chroot();
@ -159,6 +213,7 @@ impl Installer {
return Err(e); return Err(e);
} }
self.exec.logger.info(format!("stage complete: {name}")); self.exec.logger.info(format!("stage complete: {name}"));
observer.stage_finished(step, None);
} }
Ok(()) Ok(())
} }

View file

@ -147,3 +147,82 @@ fn build_script_is_syntax_declared_shell() {
assert!(build.contains("mksquashfs")); assert!(build.contains("mksquashfs"));
let _ = Path::new("."); let _ = Path::new(".");
} }
#[test]
fn live_build_installs_the_branded_launcher_and_marker() {
let build = read("installer/live/build.sh");
// The welcome/installer Quickshell configs and branding are part of the
// payload, and the live marker gates live-only autostart.
for needle in [
"etc/xdg/quickshell/phoebus-welcome",
"etc/xdg/quickshell/phoebus-install",
"phoebus-welcome",
"usr/share/phoebus/branding",
"etc/phoebus/live",
"brand-wallpaper",
"splash.png",
] {
assert!(build.contains(needle), "build.sh is missing {needle}");
}
// The live help text is shipped and read by the welcome window.
let help = read("installer/live/install-help.txt");
assert!(help.contains("ERASE"));
assert!(help.contains("LUKS2"));
}
#[test]
fn assets_include_the_welcome_launcher_and_branding() {
let welcome = system::desktop_asset("welcome").expect("welcome asset");
assert!(welcome.contains("quickshell --no-duplicate -c phoebus-welcome"));
// Duplicate installer sessions are prevented.
let install = system::desktop_asset("install").expect("install asset");
assert!(install.contains("quickshell --no-duplicate -c phoebus-install"));
assert!(install.contains("pgrep -f"));
// Branding assets are reachable through the same `--emit-asset` dispatch.
for name in [
"brand-emblem",
"brand-wordmark",
"brand-wallpaper",
"brand-tokens",
] {
assert!(system::desktop_asset(name).is_some(), "{name} missing");
}
}
#[test]
fn installed_session_never_starts_the_welcome() {
// The live-only marker is the gate; the installed session script must not
// autostart the welcome unless the marker exists.
let script = system::desktop_asset("session-mango").unwrap();
assert!(script.contains("/etc/phoebus/live"));
assert!(script.contains("phoebus-welcome"));
}
#[test]
fn qml_theme_matches_the_backend_palette() {
let qml = read("installer/live/desktop/common/Theme.qml");
for token in [
phoebus_core::brand::PALETTE.charcoal,
phoebus_core::brand::PALETTE.surface,
phoebus_core::brand::PALETTE.border,
phoebus_core::brand::PALETTE.warm_white,
phoebus_core::brand::PALETTE.muted,
phoebus_core::brand::PALETTE.amber,
phoebus_core::brand::PALETTE.amber_deep,
phoebus_core::brand::PALETTE.success,
phoebus_core::brand::PALETTE.warning,
phoebus_core::brand::PALETTE.danger,
] {
assert!(
qml.contains(token),
"Theme.qml is missing brand token {token}"
);
}
}
#[test]
fn installer_help_is_available_to_the_gui() {
let help = read("installer/live/install-help.txt");
assert!(help.contains("deterministic `sys`"));
assert!(help.contains("installation medium"));
}

View file

@ -20,15 +20,21 @@ The build runs entirely unprivileged and never touches a host disk:
provides wlroots 0.20, scenefx 0.5 and quickshell, which Mango and DMS need. provides wlroots 0.20, scenefx 0.5 and quickshell, which Mango and DMS need.
The Debian archive keyring is fetched from Debian and handed to mmdebstrap. The Debian archive keyring is fetched from Debian and handed to mmdebstrap.
3. A customize hook (`livefs-hook.sh`) runs inside the rootfs: it creates the 3. A customize hook (`livefs-hook.sh`) runs inside the rootfs: it creates the
unprivileged `phoebus` user, installs the shared session assets emitted by unprivileged `phoebus` user, **builds Mango from source**, installs the
the static installer (`phoebus-installer --emit-asset ...`), **builds Mango pinned DMS release, and enables `greetd`, networking and the serial console.
from source**, installs the pinned DMS release, and enables `greetd`, 4. After the rootfs is extracted, `build.sh` installs the live payload:
networking and the serial console. the static installer, the shared desktop assets emitted by
4. The rootfs is extracted as the current user and packed with `mksquashfs `phoebus-installer --emit-asset`, the **branding** (emblem, wordmark,
wallpaper, tokens), the **Quickshell welcome/installer configs**, the
live-only marker `/etc/phoebus/live`, the version/build files, the help
text, and DMS's "already welcomed" markers. Keeping this post-extract lets
`PHOEBUS_REUSE_ROOTFS=1` pick up asset changes without a new mmdebstrap.
5. The rootfs is extracted as the current user and packed with `mksquashfs
-all-root`; a tmpfiles rule restores the live user's home ownership at boot. -all-root`; a tmpfiles rule restores the live user's home ownership at boot.
5. The base Debian-Live ISO (`base.sha256`) is used only for its boot 6. The base Debian-Live ISO (`base.sha256`) is used only for its boot
equipment: the live squashfs, kernel, initramfs and a serial-patched GRUB equipment: the live squashfs, kernel, initramfs and a serial-patched,
configuration are replaced, and `xorriso -boot_image any keep` preserves the **Phoebus-branded** GRUB configuration (menu names, colours and a rasterised
wallpaper) are replaced, and `xorriso -boot_image any keep` preserves the
UEFI/BIOS boot path. UEFI/BIOS boot path.
No `curl | sh`, no live/git packages, and signature verification is never No `curl | sh`, no live/git packages, and signature verification is never
@ -63,15 +69,33 @@ launcher is missing; it never silently emits a text-only ISO.
- It auto-boots to a serial-visible live system and **logs in automatically** - It auto-boots to a serial-visible live system and **logs in automatically**
as `phoebus` (only on the live medium). as `phoebus` (only on the live medium).
- The graphical session starts automatically. The **Install Phoebus** entry in - The graphical session starts automatically and opens the branded **Phoebus
the launcher opens the installer UI; it never starts a destructive operation welcome** window: "Install Phoebus OS" is the dominant action, with network,
by itself (the plan, disk protection, AI requirement, credential handling and display/keyboard, accessibility, help, keyboard-test and power tools, and
the `ERASE` confirmation all remain in force). troubleshooting tools under **Advanced**. It never authorizes or starts disk
changes. DMS's upstream first-run dialogs are suppressed on the live medium.
- The welcome's action (and the **Install Phoebus OS** desktop entry) opens the
graphical installer wizard, which talks to the Rust backend over the typed
`phoebus-installer --gui-bridge` JSON protocol: language/keyboard/timezone,
network and prerequisites, AI model connection, destination disk (protected
disks and the installation medium are identified and unselectable), account
and encryption, review, `ERASE` authorization, real-stage progress and
completion. A second launch never opens a duplicate session. If Quickshell or
Wayland is unavailable the launcher falls back to the TUI/CLI.
- A text recovery console is available on the serial line and on another VT - A text recovery console is available on the serial line and on another VT
(`Ctrl+Alt+F2`): log in as `phoebus` / `phoebus` (live-only credential), (`Ctrl+Alt+F2`): log in as `phoebus` / `phoebus` (live-only credential),
passwordless `sudo`. passwordless `sudo`.
- The `phoebus-dwl` session remains selectable as a fallback. - The `phoebus-dwl` session remains selectable as a fallback.
## Verification
`installer/tests/vm/gui-driver.py` drives the graphical ISO in a disposable
UEFI VM: `gui` (welcome + wizard journey and screenshots), `install`
(non-interactive install with the static binary and a secret-leak scan) and
`boot` (detached boot of the installed disk). See
`docs/VM-BOOT-VERIFICATION.md` for the recorded evidence.
## Installed system ## Installed system
An installed system always authenticates through `greetd` and defaults to the An installed system always authenticates through `greetd` and defaults to the

View file

@ -42,6 +42,12 @@ say "preflight"
for c in mmdebstrap xorriso mksquashfs curl dpkg-deb unshare sha256sum; do for c in mmdebstrap xorriso mksquashfs curl dpkg-deb unshare sha256sum; do
command -v "$c" >/dev/null || { echo "missing tool: $c" >&2; exit 1; } command -v "$c" >/dev/null || { echo "missing tool: $c" >&2; exit 1; }
done done
if ! command -v magick >/dev/null 2>&1 \
&& ! command -v convert >/dev/null 2>&1 \
&& ! command -v inkscape >/dev/null 2>&1; then
echo "missing an SVG rasteriser for the boot background (magick, convert or inkscape)" >&2
exit 1
fi
for b in phoebus-installer sys; do for b in phoebus-installer sys; do
[[ -x "$release_src/$b" ]] || { [[ -x "$release_src/$b" ]] || {
echo "missing $release_src/$b; build it first:" >&2 echo "missing $release_src/$b; build it first:" >&2
@ -93,10 +99,11 @@ echo "releases OK"
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
say "emit shared desktop assets" say "emit shared desktop assets"
assets=( assets=(
session-mango session-dwl assistant install menu lock idle session-mango session-dwl assistant install welcome menu lock idle
mango-config mango-session-target install-desktop mango-config mango-session-target install-desktop
wayland-session-mango wayland-session-dwl wayland-session-mango wayland-session-dwl
waybar-config waybar-style greetd-live waybar-config waybar-style greetd-live
brand-emblem brand-wordmark brand-wallpaper brand-tokens
) )
for name in "${assets[@]}"; do for name in "${assets[@]}"; do
"$release_dir/phoebus-installer" --emit-asset "$name" > "$work/assets/$name" || { "$release_dir/phoebus-installer" --emit-asset "$name" > "$work/assets/$name" || {
@ -151,7 +158,7 @@ fi
[[ -s "$rootfs_tar" ]] || { echo "mmdebstrap did not produce $rootfs_tar" >&2; exit 1; } [[ -s "$rootfs_tar" ]] || { echo "mmdebstrap did not produce $rootfs_tar" >&2; exit 1; }
say "unpack and verify the desktop payload" say "unpack the rootfs"
rootfs="$work/rootfs" rootfs="$work/rootfs"
rm -rf "$rootfs" rm -rf "$rootfs"
mkdir -p "$rootfs" mkdir -p "$rootfs"
@ -163,6 +170,75 @@ install -d -m 0755 "$rootfs/dev"
echo "${LIVE_HOSTNAME:-phoebus-live}" > "$rootfs/etc/hostname" echo "${LIVE_HOSTNAME:-phoebus-live}" > "$rootfs/etc/hostname"
printf '127.0.1.1\t%s\n' "${LIVE_HOSTNAME:-phoebus-live}" >> "$rootfs/etc/hosts" printf '127.0.1.1\t%s\n' "${LIVE_HOSTNAME:-phoebus-live}" >> "$rootfs/etc/hosts"
say "install the live payload"
# Everything below is installed after the (cached) rootfs is extracted, so
# PHOEBUS_REUSE_ROOTFS=1 still picks up new binaries, UI and branding.
iso_version="${PHOEBUS_VERSION:-0.1.0}"
build_id="${PHOEBUS_BUILD_ID:-$(date -u +%Y%m%dT%H%M%SZ)}"
install -d -m 0755 "$rootfs/etc/phoebus"
install -D -m 0755 "$release_dir/phoebus-installer" "$rootfs/usr/local/bin/phoebus-installer"
install -D -m 0755 "$release_dir/sys" "$rootfs/usr/local/bin/sys"
install_asset() {
local name="$1" dest="$2" mode="${3:-0644}"
local src="$work/assets/$name"
[[ -f "$src" ]] || { echo "missing emitted asset $name" >&2; exit 1; }
install -D -m "$mode" "$src" "$rootfs/$dest"
}
install_asset session-mango /usr/local/bin/phoebus-session-mango 0755
install_asset session-dwl /usr/local/bin/phoebus-session 0755
install_asset assistant /usr/local/bin/phoebus-assistant 0755
install_asset install /usr/local/bin/phoebus-install 0755
install_asset welcome /usr/local/bin/phoebus-welcome 0755
install_asset menu /usr/local/bin/phoebus-menu 0755
install_asset lock /usr/local/bin/phoebus-lock 0755
install_asset idle /usr/local/bin/phoebus-idle 0755
install_asset mango-config /etc/xdg/mango/config.conf
install_asset mango-session-target /usr/lib/systemd/user/mango-session.target
install_asset install-desktop /usr/share/applications/phoebus-install.desktop
install_asset wayland-session-mango /usr/share/wayland-sessions/phoebus-mango.desktop
install_asset wayland-session-dwl /usr/share/wayland-sessions/phoebus-dwl.desktop
install_asset waybar-config /etc/xdg/waybar/config
install_asset waybar-style /etc/xdg/waybar/style.css
# Live-only automatic login (never copied to an installed system).
install_asset greetd-live /etc/greetd/config.toml
# Branding: shared vector assets, the app icon and the live-only marker.
install_asset brand-emblem /usr/share/phoebus/branding/emblem.svg
install_asset brand-wordmark /usr/share/phoebus/branding/wordmark.svg
install_asset brand-wallpaper /usr/share/phoebus/branding/wallpaper.svg
install_asset brand-tokens /usr/share/phoebus/branding/tokens.json
install -D -m 0644 "$work/assets/brand-emblem" \
"$rootfs/usr/share/icons/hicolor/scalable/apps/phoebus.svg"
install -D -m 0644 "$here/install-help.txt" "$rootfs/usr/share/phoebus/install-help.txt"
printf '%s\n' "$iso_version" > "$rootfs/etc/phoebus/version"
printf 'PHOEBUS_BUILD_ID=%s\n' "$build_id" > "$rootfs/etc/phoebus/build"
# The live marker gates live-only autostart; it is never written to a target.
: > "$rootfs/etc/phoebus/live"
# Suppress DankMaterialShell's upstream first-run dialogs on the live medium:
# the installer is the first thing the user should see. DMS writes these
# markers itself when the dialogs are dismissed; pre-seeding them is its
# supported "already welcomed" state. The tmpfiles `Z /home/phoebus` rule
# chowns them to the live user at boot. The changelog marker is versioned by
# DMS (major.minor), so it is derived from the pinned DMS release.
install -d -m 0700 "$rootfs/home/phoebus/.config/DankMaterialShell"
: > "$rootfs/home/phoebus/.config/DankMaterialShell/.firstlaunch"
: > "$rootfs/home/phoebus/.config/DankMaterialShell/.changelog-${dms_version%.*}"
# Quickshell frontend: the welcome window and the graphical installer, each a
# self-contained config with the shared Common module materialised.
if [[ -d "$here/desktop" ]]; then
for cfgname in phoebus-welcome phoebus-install; do
[[ -f "$here/desktop/$cfgname/shell.qml" ]] || {
echo "live build: missing desktop config $cfgname" >&2; exit 1; }
install -d -m 0755 "$rootfs/etc/xdg/quickshell/$cfgname"
cp -rL "$here/desktop/$cfgname/." "$rootfs/etc/xdg/quickshell/$cfgname/"
done
fi
# Fail clearly rather than shipping a text ISO labelled as a desktop image. # Fail clearly rather than shipping a text ISO labelled as a desktop image.
for bin in usr/bin/mango usr/bin/dms; do for bin in usr/bin/mango usr/bin/dms; do
[[ -e "$rootfs/$bin" ]] || { echo "live rootfs is missing $bin" >&2; exit 1; } [[ -e "$rootfs/$bin" ]] || { echo "live rootfs is missing $bin" >&2; exit 1; }
@ -176,6 +252,16 @@ grep -q "initial_session" "$rootfs/etc/greetd/config.toml" || {
echo "live rootfs greetd config is missing live autologin" >&2; exit 1; } echo "live rootfs greetd config is missing live autologin" >&2; exit 1; }
[[ -f "$rootfs/usr/share/applications/phoebus-install.desktop" ]] || { [[ -f "$rootfs/usr/share/applications/phoebus-install.desktop" ]] || {
echo "live rootfs has no Install Phoebus launcher" >&2; exit 1; } echo "live rootfs has no Install Phoebus launcher" >&2; exit 1; }
for check in \
usr/local/bin/phoebus-welcome \
etc/xdg/quickshell/phoebus-welcome/shell.qml \
etc/xdg/quickshell/phoebus-install/shell.qml \
usr/share/phoebus/branding/emblem.svg \
usr/share/phoebus/branding/wallpaper.svg \
etc/phoebus/live; do
[[ -e "$rootfs/$check" ]] || {
echo "live rootfs is missing payload: $check" >&2; exit 1; }
done
echo "desktop payload verified" echo "desktop payload verified"
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
@ -186,7 +272,7 @@ say "pack live filesystem"
install -d -m 0755 "$rootfs/etc/tmpfiles.d" install -d -m 0755 "$rootfs/etc/tmpfiles.d"
cat > "$rootfs/etc/tmpfiles.d/phoebus-live.conf" <<'EOF' cat > "$rootfs/etc/tmpfiles.d/phoebus-live.conf" <<'EOF'
d /home/phoebus 0700 phoebus phoebus - d /home/phoebus 0700 phoebus phoebus -
z /home/phoebus 0700 phoebus phoebus - Z /home/phoebus 0700 phoebus phoebus -
EOF EOF
# `tar` run as an unprivileged user drops setuid/setgid/sticky bits; restore # `tar` run as an unprivileged user drops setuid/setgid/sticky bits; restore
# them from the archive so e.g. `sudo` and `pkexec` work in the live image. # them from the archive so e.g. `sudo` and `pkexec` work in the live image.
@ -228,12 +314,13 @@ cp "$vmlinuz" "$work/vmlinuz"
cp "$initrd" "$work/initrd.img" cp "$initrd" "$work/initrd.img"
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
say "patch boot config for serial console" say "patch boot config for serial console and Phoebus branding"
bootcfg="$work/bootcfg"; mkdir -p "$bootcfg" bootcfg="$work/bootcfg"; mkdir -p "$bootcfg"
xorriso -osirrox on -indev "$base" \ xorriso -osirrox on -indev "$base" \
-extract /boot/grub/grub.cfg "$bootcfg/grub.cfg" \ -extract /boot/grub/grub.cfg "$bootcfg/grub.cfg" \
-extract /boot/grub/config.cfg "$bootcfg/config.cfg" >/dev/null 2>&1 -extract /boot/grub/config.cfg "$bootcfg/config.cfg" \
chmod u+w "$bootcfg/grub.cfg" "$bootcfg/config.cfg" -extract /boot/grub/live-theme/theme.txt "$bootcfg/theme.txt" >/dev/null 2>&1
chmod u+w "$bootcfg/grub.cfg" "$bootcfg/config.cfg" "$bootcfg/theme.txt"
sed -i 's#boot=live components quiet splash findiso=#boot=live components console=ttyS0,115200 noautologin findiso=#' "$bootcfg/grub.cfg" sed -i 's#boot=live components quiet splash findiso=#boot=live components console=ttyS0,115200 noautologin findiso=#' "$bootcfg/grub.cfg"
python3 - "$bootcfg/config.cfg" <<'PY' python3 - "$bootcfg/config.cfg" <<'PY'
import sys import sys
@ -246,6 +333,57 @@ t = t.replace("terminal_output gfxterm", "terminal_output gfxterm serial")
open(p, "w").write(t) open(p, "w").write(t)
PY PY
# Phoebus identity on the boot menu: rename the entries and use the brand
# colours and wallpaper. This only rewrites text/theme files; the boot path is
# untouched.
python3 - "$bootcfg/grub.cfg" <<'PY'
import sys
p = sys.argv[1]
t = open(p).read()
t = t.replace('menuentry "Live system (amd64)"',
'menuentry "Start Phoebus OS (live medium)"')
t = t.replace('menuentry "Live system (amd64 fail-safe mode)"',
'menuentry "Phoebus OS (fail-safe graphics)"')
open(p, "w").write(t)
PY
cat > "$bootcfg/theme.cfg" <<'EOF'
set color_normal=light-gray/black
set color_highlight=black/brown
if [ -e /boot/grub/splash.png ]; then
set theme=/boot/grub/live-theme/theme.txt
else
set menu_color_normal=light-gray/black
set menu_color_highlight=white/brown
fi
EOF
python3 - "$bootcfg/theme.txt" <<'PY'
import sys
p = sys.argv[1]
t = open(p).read()
t = t.replace('title-text: "Live Boot Menu with GRUB"', 'title-text: "Phoebus OS"')
t = t.replace('title-color: "#ffffff"', 'title-color: "#e8a33d"')
t = t.replace('item_color = "#a8a8a8"', 'item_color = "#f4efe6"')
t = t.replace('selected_item_color= "#ffffff"', 'selected_item_color= "#e8a33d"')
t = t.replace('fg_color = "#ffffff"', 'fg_color = "#e8a33d"')
t = t.replace('bg_color = "#a8a8a8"', 'bg_color = "#3a3a42"')
t = t.replace('border_color = "#ffffff"', 'border_color = "#e8a33d"')
open(p, "w").write(t)
PY
# Rasterise the brand wallpaper for the GRUB background (GRUB does not read
# SVG). ImageMagick or Inkscape is required; the build fails clearly otherwise.
if command -v magick >/dev/null 2>&1; then
magick -background none "$work/assets/brand-wallpaper" -resize 1024x768 "$bootcfg/splash.png"
elif command -v convert >/dev/null 2>&1; then
convert -background none "$work/assets/brand-wallpaper" -resize 1024x768 "$bootcfg/splash.png"
elif command -v inkscape >/dev/null 2>&1; then
inkscape "$work/assets/brand-wallpaper" -w 1024 -h 768 -o "$bootcfg/splash.png"
else
echo "no SVG rasteriser (magick/convert/inkscape) for the boot background" >&2
exit 1
fi
[[ -s "$bootcfg/splash.png" ]] || { echo "branded boot background is empty" >&2; exit 1; }
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
say "assemble ISO" say "assemble ISO"
rm -f "$out" rm -f "$out"
@ -269,6 +407,9 @@ xorriso -indev "$base" -outdev "$out" \
"${kmap[@]}" \ "${kmap[@]}" \
-map "$bootcfg/grub.cfg" /boot/grub/grub.cfg \ -map "$bootcfg/grub.cfg" /boot/grub/grub.cfg \
-map "$bootcfg/config.cfg" /boot/grub/config.cfg \ -map "$bootcfg/config.cfg" /boot/grub/config.cfg \
-map "$bootcfg/theme.cfg" /boot/grub/theme.cfg \
-map "$bootcfg/theme.txt" /boot/grub/live-theme/theme.txt \
-map "$bootcfg/splash.png" /boot/grub/splash.png \
-boot_image any keep >/dev/null -boot_image any keep >/dev/null
sha256sum "$out" | tee "$out.sha256" sha256sum "$out" | tee "$out.sha256"

View file

@ -0,0 +1,173 @@
pragma Singleton
import QtQuick
import Quickshell
import Quickshell.Io
// Typed JSON bridge to the privileged Rust installer. The frontend never
// scrapes terminal output: every call is a typed request and every reply is a
// typed JSON object. Secrets are written over the process stdin only.
Singleton {
id: root
// True once the bridge process is running and accepting requests.
property bool ready: false
property bool crashed: false
property string crashMessage: ""
property string lastError: ""
property var handshake: null
property var config: null
property var pending: ({})
property int nextId: 1
signal event(string name, var data)
signal availabilityChanged
signal handshakeReady
readonly property var bridgeCommand: {
const override = Quickshell.env("PHOEBUS_BRIDGE_CMD");
if (override && override.length > 0)
return override.split(" ").filter(part => part.length > 0);
// Absolute paths: Quickshell's Process execs the command directly and
// does not perform PATH lookup.
return ["/usr/bin/sudo", "-n", "/usr/local/bin/phoebus-installer", "--gui-bridge"];
}
// Retried until the first successful handshake, so a process-start race can
// never leave the frontend permanently stuck.
Timer {
interval: 400
repeat: true
running: proc.running && root.handshake === null
onTriggered: root.refreshHandshake(null)
}
function start() {
if (!proc.running)
proc.running = true;
}
function stop() {
if (proc.running)
proc.running = false;
}
function call(op, payload, onDone) {
const id = root.nextId++;
if (onDone)
root.pending[id] = onDone;
const request = Object.assign({ id: id, op: op }, payload || {});
const line = JSON.stringify(request) + "\n";
if (!proc.running) {
// Quickshell's Process.write() returns void, so it cannot be used
// to detect a failed write. Check the process state instead.
delete root.pending[id];
root.lastError = "backend not running";
if (onDone)
onDone({ ok: false, error: "the installer backend is not running" });
return;
}
proc.write(line);
}
function handleLine(line) {
const text = ("" + line).trim();
if (text.length === 0)
return;
let msg;
try {
msg = JSON.parse(text);
} catch (e) {
console.log("bridge: unparsable line: " + text);
return;
}
if (msg.event === "progress") {
root.event("progress", msg);
return;
}
if (msg.id !== undefined && root.pending[msg.id]) {
const cb = root.pending[msg.id];
delete root.pending[msg.id];
cb(msg);
}
}
// Convenience wrappers.
function refreshHandshake(cb) {
call("handshake", {}, reply => {
if (reply.ok) {
root.handshake = reply.data;
root.handshakeReady();
}
if (cb)
cb(reply);
});
}
function listDisks(cb) {
call("disks", {}, cb);
}
function setConfig(cfg, cb) {
call("set_config", { config: cfg }, reply => {
if (reply.ok)
root.config = cfg;
if (cb)
cb(reply);
});
}
function setSecrets(secrets, cb) {
call("set_secrets", { secrets: secrets }, cb);
}
function validate(cb) {
call("validate", {}, cb);
}
function plan(cb) {
call("plan", {}, cb);
}
function destructivePreview(cb) {
call("destructive_preview", {}, cb);
}
function aiCheck(cb) {
call("ai_check", {}, cb);
}
function approve(eraseText, finalConfirmed, cb) {
call("approve", { erase: eraseText, final_confirm: finalConfirmed }, cb);
}
function startInstall(planDigest, eraseText, cb) {
call("start_install", {
erase: eraseText,
final_confirm: true,
plan_digest: planDigest
}, cb);
}
function logTail(lines, cb) {
call("log_tail", { lines: lines }, cb);
}
Process {
id: proc
command: root.bridgeCommand
stdinEnabled: true
running: false
onStarted: {
root.ready = true;
root.crashed = false;
root.crashMessage = "";
root.availabilityChanged();
}
onExited: exitCode => {
root.ready = false;
root.crashed = true;
root.crashMessage = "The installer backend stopped (exit " + exitCode + ").";
root.availabilityChanged();
}
stdout: SplitParser {
onRead: line => root.handleLine(line)
}
stderr: SplitParser {
onRead: line => {
root.lastError = line;
console.log("phoebus-bridge: " + line);
}
}
}
}

View file

@ -0,0 +1,68 @@
import QtQuick
// A keyboard-focusable, branded button. Primary buttons are amber; secondary
// buttons are a raised surface. Focus is always visible.
Rectangle {
id: btn
property string label: ""
property bool primary: false
property bool danger: false
property bool compact: false
property bool actionEnabled: true
signal clicked
readonly property bool hovered: mouse.containsMouse
readonly property color baseBg: {
if (danger)
return Qt.darker(Theme.danger, 1.25);
if (primary)
return hovered ? Theme.amber : Theme.amberDeep;
return hovered ? Theme.surfaceRaised : Theme.surface;
}
implicitHeight: compact ? 34 : 46
implicitWidth: Math.max(compact ? 80 : 120, labelText.implicitWidth + (compact ? 28 : 48))
radius: Theme.radiusSmall
color: actionEnabled ? baseBg : Theme.surface
border.width: (primary || danger) ? 0 : 1
border.color: activeFocus ? Theme.focusRing : Theme.border
opacity: actionEnabled ? 1 : 0.55
activeFocusOnTab: true
Accessible.role: Accessible.Button
Accessible.name: label
Accessible.onPressAction: if (actionEnabled) btn.clicked()
Keys.onReturnPressed: if (btn.actionEnabled) btn.clicked()
Keys.onEnterPressed: if (btn.actionEnabled) btn.clicked()
Keys.onSpacePressed: if (btn.actionEnabled) btn.clicked()
Rectangle {
anchors.fill: parent
anchors.margins: -3
radius: btn.radius + 3
color: "transparent"
border.width: 2
border.color: Theme.focusRing
visible: btn.activeFocus
}
Text {
id: labelText
anchors.centerIn: parent
text: btn.label
color: (btn.primary || btn.danger) ? Theme.charcoal : Theme.warmWhite
font.family: Theme.family
font.pixelSize: btn.compact ? Theme.fontSmall : Theme.fontBody
font.weight: btn.primary ? Font.DemiBold : Font.Normal
}
MouseArea {
id: mouse
anchors.fill: parent
hoverEnabled: true
cursorShape: Qt.PointingHandCursor
enabled: btn.actionEnabled
onClicked: btn.clicked()
}
}

View file

@ -0,0 +1,32 @@
import QtQuick
// A raised surface with a hairline border and the standard radius.
//
// Put children in the `content` column; they should set `width: parent.width`
// for full-width content, and their implicit heights determine the card's.
Rectangle {
id: card
default property alias content: col.data
property int padding: Theme.pad
property int spacing: 10
property color fill: Theme.surface
property bool outlined: true
color: fill
radius: Theme.radius
border.width: outlined ? 1 : 0
border.color: Theme.border
implicitWidth: 320
implicitHeight: col.implicitHeight + padding * 2
Column {
id: col
anchors.left: parent.left
anchors.right: parent.right
anchors.top: parent.top
anchors.margins: card.padding
spacing: card.spacing
}
}

View file

@ -0,0 +1,22 @@
import QtQuick
// A small inline status pill.
Rectangle {
id: chip
property string text: ""
property color tone: Theme.muted
height: 24
implicitWidth: chipText.implicitWidth + 20
radius: 12
color: "transparent"
border.width: 1
border.color: tone
Text {
id: chipText
anchors.centerIn: parent
text: chip.text
color: chip.tone
font.family: Theme.family
font.pixelSize: Theme.fontSmall
}
}

View file

@ -0,0 +1,27 @@
import QtQuick
// A wrapping row of selectable pills. Used for small, closed option sets
// (filesystem, kernel profile, AI provider, ...). Keyboard-navigable.
Flow {
id: choice
property var options: []
property string value: ""
property bool compact: true
signal selected(string value)
spacing: 8
width: parent ? parent.width : implicitWidth
Repeater {
model: choice.options
delegate: PhoebusButton {
required property var modelData
label: modelData.label !== undefined ? modelData.label : modelData
primary: (modelData.value !== undefined ? modelData.value : modelData) === choice.value
compact: choice.compact
onClicked: choice.selected(modelData.value !== undefined ? modelData.value : modelData)
}
}
}

View file

@ -0,0 +1,62 @@
import QtQuick
// The Phoebus sun emblem, drawn with Canvas so it never depends on an SVG
// image plugin. The installed vector is still emitted for the desktop and
// boot surfaces; this is the in-app rendering.
Item {
id: emblem
property color accent: Theme.amber
property color core: Theme.warmWhite
implicitWidth: 128
implicitHeight: 128
onAccentChanged: canvas.requestPaint()
onCoreChanged: canvas.requestPaint()
Canvas {
id: canvas
anchors.fill: parent
onWidthChanged: requestPaint()
onHeightChanged: requestPaint()
Component.onCompleted: requestPaint()
onPaint: {
const ctx = getContext("2d");
ctx.reset();
const w = width;
const h = height;
const cx = w / 2;
const cy = h / 2;
const r = Math.min(w, h) / 2;
const rays = 8;
ctx.lineCap = "round";
ctx.strokeStyle = emblem.accent;
ctx.fillStyle = emblem.accent;
ctx.lineWidth = r * 0.09;
for (let i = 0; i < rays; i++) {
const a = i * (Math.PI * 2 / rays);
ctx.beginPath();
ctx.moveTo(cx + Math.cos(a) * r * 0.62, cy + Math.sin(a) * r * 0.62);
ctx.lineTo(cx + Math.cos(a) * r * 0.92, cy + Math.sin(a) * r * 0.92);
ctx.stroke();
}
ctx.lineWidth = r * 0.06;
for (let j = 0; j < rays; j++) {
const a = (j + 0.5) * (Math.PI * 2 / rays);
ctx.beginPath();
ctx.moveTo(cx + Math.cos(a) * r * 0.66, cy + Math.sin(a) * r * 0.66);
ctx.lineTo(cx + Math.cos(a) * r * 0.84, cy + Math.sin(a) * r * 0.84);
ctx.stroke();
}
ctx.beginPath();
ctx.arc(cx, cy, r * 0.40, 0, Math.PI * 2);
ctx.fill();
ctx.beginPath();
ctx.arc(cx, cy, r * 0.25, 0, Math.PI * 2);
ctx.fillStyle = emblem.core;
ctx.fill();
}
}
}

View file

@ -0,0 +1,99 @@
import QtQuick
// A labelled single-line input with an inline error and optional secret echo.
Column {
id: field
property string label: ""
property string placeholder: ""
property string error: ""
property bool secret: false
property bool showSecret: false
property alias text: input.text
property alias inputItem: input
property int maxLength: 256
signal edited(string value)
signal accepted
width: parent ? parent.width : implicitWidth
spacing: 6
Text {
width: parent.width
text: field.label
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontSmall
font.weight: Font.DemiBold
visible: field.label.length > 0
}
Rectangle {
width: parent.width
height: 42
radius: Theme.radiusSmall
color: Theme.charcoal
border.width: input.activeFocus ? 2 : 1
border.color: field.error.length > 0 ? Theme.danger
: input.activeFocus ? Theme.focusRing
: Theme.border
TextInput {
id: input
anchors.fill: parent
anchors.leftMargin: 12
anchors.rightMargin: 44
verticalAlignment: TextInput.AlignVCenter
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontBody
selectionColor: Theme.amberDeep
selectedTextColor: Theme.warmWhite
echoMode: (field.secret && !field.showSecret) ? TextInput.Password : TextInput.Normal
passwordCharacter: "\u2022"
selectByMouse: true
activeFocusOnTab: true
maximumLength: field.maxLength
clip: true
onTextEdited: field.edited(text)
onAccepted: field.accepted()
Text {
anchors.fill: parent
verticalAlignment: Text.AlignVCenter
text: field.placeholder
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontBody
visible: input.text.length === 0 && !input.activeFocus
}
}
Text {
anchors.right: parent.right
anchors.rightMargin: 12
anchors.verticalCenter: parent.verticalCenter
visible: field.secret
text: field.showSecret ? "hide" : "show"
color: Theme.amber
font.family: Theme.family
font.pixelSize: Theme.fontSmall
MouseArea {
anchors.fill: parent
anchors.margins: -6
cursorShape: Qt.PointingHandCursor
onClicked: field.showSecret = !field.showSecret
}
}
}
Text {
width: parent.width
text: field.error
color: Theme.danger
font.family: Theme.family
font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap
visible: field.error.length > 0
}
}

View file

@ -0,0 +1,83 @@
import QtQuick
// A label + switch. Clickable and keyboard-operable (Space/Enter).
Item {
id: toggle
property string label: ""
property string description: ""
property bool checked: false
signal toggled(bool value)
implicitHeight: description.length > 0 ? 52 : 36
width: parent ? parent.width : implicitWidth
activeFocusOnTab: true
Accessible.role: Accessible.CheckBox
Accessible.name: label
Accessible.checked: checked
Keys.onSpacePressed: {
toggle.checked = !toggle.checked;
toggle.toggled(toggle.checked);
}
Keys.onReturnPressed: Keys.onSpacePressed(event)
Keys.onEnterPressed: Keys.onSpacePressed(event)
Column {
anchors.left: parent.left
anchors.right: switchBox.left
anchors.rightMargin: 16
anchors.verticalCenter: parent.verticalCenter
spacing: 2
Text {
width: parent.width
text: toggle.label
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontBody
}
Text {
width: parent.width
text: toggle.description
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap
visible: toggle.description.length > 0
}
}
Rectangle {
id: switchBox
anchors.right: parent.right
anchors.verticalCenter: parent.verticalCenter
width: 44
height: 24
radius: 12
color: toggle.checked ? Theme.amberDeep : Theme.border
border.width: toggle.activeFocus ? 2 : 0
border.color: Theme.focusRing
Rectangle {
width: 18
height: 18
radius: 9
y: 3
x: toggle.checked ? parent.width - width - 3 : 3
color: toggle.checked ? Theme.warmWhite : Theme.muted
Behavior on x {
NumberAnimation { duration: 90 }
}
}
MouseArea {
anchors.fill: parent
cursorShape: Qt.PointingHandCursor
onClicked: {
toggle.forceActiveFocus();
toggle.checked = !toggle.checked;
toggle.toggled(toggle.checked);
}
}
}
}

View file

@ -0,0 +1,45 @@
pragma Singleton
import QtQuick
// Phoebus brand tokens. Kept in sync with phoebus_core::brand::PALETTE by a
// Rust test, so the QML frontend and the backend cannot drift.
QtObject {
id: theme
// Palette: charcoal, warm white, restrained amber.
readonly property color charcoal: "#17171b"
readonly property color surface: "#232329"
readonly property color surfaceRaised: "#2b2b33"
readonly property color border: "#3a3a42"
readonly property color warmWhite: "#f4efe6"
readonly property color muted: "#a8a29a"
readonly property color amber: "#e8a33d"
readonly property color amberDeep: "#c97f24"
readonly property color success: "#7fb069"
readonly property color warning: "#e0a24a"
readonly property color danger: "#d2564b"
readonly property color focusRing: amber
readonly property color overlay: Qt.rgba(0.09, 0.09, 0.10, 0.72)
// Layout.
readonly property int radius: 12
readonly property int radiusSmall: 8
readonly property int gutter: 20
readonly property int pad: 16
readonly property int padLarge: 28
// Type scale.
readonly property int fontDisplay: 30
readonly property int fontTitle: 22
readonly property int fontHeading: 17
readonly property int fontBody: 14
readonly property int fontSmall: 12
readonly property string family: "DejaVu Sans, Noto Sans, sans-serif"
// Branding assets installed by the live build.
readonly property string brandDir: "/usr/share/phoebus/branding"
readonly property string emblem: brandDir + "/emblem.svg"
readonly property string wordmark: brandDir + "/wordmark.svg"
readonly property string wallpaper: brandDir + "/wallpaper.svg"
}

View file

@ -0,0 +1,10 @@
module Common
singleton Theme 1.0 Theme.qml
singleton Bridge 1.0 Bridge.qml
PhoebusChip 1.0 PhoebusChip.qml
PhoebusButton 1.0 PhoebusButton.qml
PhoebusCard 1.0 PhoebusCard.qml
PhoebusField 1.0 PhoebusField.qml
PhoebusToggle 1.0 PhoebusToggle.qml
PhoebusChoice 1.0 PhoebusChoice.qml
PhoebusEmblem 1.0 PhoebusEmblem.qml

View file

@ -0,0 +1 @@
../common

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1 @@
../common

View file

@ -0,0 +1,388 @@
import QtQuick
import Quickshell
import Quickshell.Io
import "Common"
// Phoebus OS live welcome. This is the ISO's launcher: it shows the identity,
// the system's readiness, a dominant "Install Phoebus OS" action and secondary
// troubleshooting tools under Advanced. It never authorizes or starts disk
// changes; only the installer does that, behind its own ERASE confirmation.
ShellRoot {
id: shell
property string isoVersion: "0.1.0"
property bool networkUp: false
property string firmware: "UEFI"
property string memory: "?"
property string cores: "?"
property bool showAdvanced: false
property bool showPower: false
property bool showKeyboardTest: false
function run(cmd) {
Quickshell.execDetached(cmd);
}
Process {
id: readiness
command: ["sh", "-c",
"echo VERSION=$(cat /etc/phoebus/version 2>/dev/null || cat /usr/share/phoebus/version 2>/dev/null || echo 0.1.0); " +
"awk 'NR>1 && $2==\"00000000\" {print \"NET=up\"; found=1; exit} END {if (!found) print \"NET=down\"}' /proc/net/route; " +
"if [ -d /sys/firmware/efi ]; then echo FW=UEFI; else echo FW=BIOS; fi; " +
"awk '/MemTotal/ {printf \"MEM=%.1f GiB\\n\", $2/1048576}' /proc/meminfo; " +
"echo CORES=$(nproc)"]
running: true
stdout: SplitParser {
onRead: line => {
const parts = ("" + line).split("=");
if (parts.length !== 2)
return;
switch (parts[0]) {
case "VERSION": shell.isoVersion = parts[1]; break;
case "NET": shell.networkUp = parts[1] === "up"; break;
case "FW": shell.firmware = parts[1]; break;
case "MEM": shell.memory = parts[1]; break;
case "CORES": shell.cores = parts[1]; break;
}
}
}
}
FloatingWindow {
id: window
Component.onCompleted: { if (typeof window.requestActivate === "function") window.requestActivate(); }
visible: true
color: Theme.charcoal
implicitWidth: 940
implicitHeight: 620
title: "Phoebus OS"
// Backdrop: wallpaper when available, a calm charcoal gradient always.
Rectangle {
anchors.fill: parent
gradient: Gradient {
GradientStop { position: 0.0; color: "#1c1c22" }
GradientStop { position: 1.0; color: "#121215" }
}
}
Image {
anchors.fill: parent
source: Theme.wallpaper
fillMode: Image.PreserveAspectCrop
smooth: true
visible: status === Image.Ready
}
Rectangle {
anchors.fill: parent
color: Theme.overlay
}
Column {
id: page
anchors.fill: parent
anchors.margins: Theme.padLarge
spacing: 18
// -- header ----------------------------------------------------
Item {
width: parent.width
height: 56
Row {
anchors.left: parent.left
anchors.verticalCenter: parent.verticalCenter
spacing: 14
PhoebusEmblem {
width: 56
height: 56
anchors.verticalCenter: parent.verticalCenter
}
Column {
anchors.verticalCenter: parent.verticalCenter
spacing: 2
Text {
text: "PHOEBUS <font color=\"" + Theme.amber + "\">OS</font>"
textFormat: Text.StyledText
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: 26
font.weight: Font.DemiBold
font.letterSpacing: 3
}
Text {
text: "A modern, encrypted, AI-first workstation"
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontSmall
}
}
}
Rectangle {
anchors.right: parent.right
anchors.verticalCenter: parent.verticalCenter
height: 30
width: versionText.implicitWidth + 24
radius: 15
color: Theme.surface
border.width: 1
border.color: Theme.border
Text {
id: versionText
anchors.centerIn: parent
text: "Live medium · " + shell.isoVersion
color: Theme.amber
font.family: Theme.family
font.pixelSize: Theme.fontSmall
}
}
}
// -- hero + primary action ------------------------------------
PhoebusCard {
width: parent.width
padding: Theme.padLarge
Text {
width: parent.width
text: "Welcome to Phoebus OS"
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontDisplay
font.weight: Font.DemiBold
}
Text {
width: parent.width
text: "This medium installs Phoebus to your computer. The installer guides you through language, networking, a connected AI model, the target disk, your account and encryption."
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontBody
wrapMode: Text.WordWrap
}
Row {
width: parent.width
spacing: 20
PhoebusButton {
label: "Install Phoebus OS"
primary: true
implicitHeight: 58
implicitWidth: 300
focus: true
activeFocusOnTab: true
Accessible.name: "Install Phoebus OS"
onClicked: shell.run(["/usr/local/bin/phoebus-install"])
}
Column {
width: parent.width - 320
spacing: 6
anchors.verticalCenter: parent.verticalCenter
Row {
spacing: 8
PhoebusChip {
text: shell.networkUp ? "Network connected" : "Network offline"
tone: shell.networkUp ? Theme.success : Theme.warning
}
PhoebusChip { text: shell.firmware; tone: Theme.muted }
PhoebusChip { text: shell.memory + " RAM"; tone: Theme.muted }
PhoebusChip { text: shell.cores + " cores"; tone: Theme.muted }
}
Text {
width: parent.width
text: "Nothing is written until you review the plan and type ERASE. An installed system boots without a network or a model."
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap
}
}
}
}
// -- secondary actions ----------------------------------------
Flow {
width: parent.width
spacing: 12
PhoebusButton {
label: "Network"
onClicked: shell.run(["sh", "-c",
"command -v dms >/dev/null && exec dms ipc call settings focusOrToggle || exec kitty -e sh -c 'nmcli device status; read -r _'"])
}
PhoebusButton {
label: "Display & keyboard"
onClicked: shell.run(["sh", "-c",
"command -v dms >/dev/null && dms ipc call settings focusOrToggle || kitty -e wlr-randr"])
}
PhoebusButton {
label: "Accessibility"
onClicked: shell.run(["sh", "-c",
"command -v dms >/dev/null && dms ipc call settings focusOrToggle || true"])
}
PhoebusButton {
label: "Installation help"
onClicked: shell.run(["sh", "-c",
"kitty -e sh -c 'cat /usr/share/phoebus/install-help.txt 2>/dev/null || echo Help is not installed; read -r || true'"])
}
PhoebusButton {
label: "Keyboard test"
onClicked: shell.showKeyboardTest = true
}
PhoebusButton {
label: "Power"
onClicked: shell.showPower = true
}
}
// -- advanced / troubleshooting -------------------------------
PhoebusButton {
label: (shell.showAdvanced ? "Hide advanced tools" : "Advanced tools")
compact: true
onClicked: shell.showAdvanced = !shell.showAdvanced
}
PhoebusCard {
width: parent.width
visible: shell.showAdvanced
fill: Theme.overlay
Text {
width: parent.width
text: "Troubleshooting and recovery tools"
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontHeading
font.weight: Font.DemiBold
}
Text {
width: parent.width
text: "These tools are working and supported on the live medium. Recovery-image features are not shipped yet and are not listed here."
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontSmall
wrapMode: Text.WordWrap
}
Flow {
width: parent.width
spacing: 12
PhoebusButton {
label: "Terminal"
compact: true
onClicked: shell.run(["kitty"])
}
PhoebusButton {
label: "System log"
compact: true
onClicked: shell.run(["kitty", "-e", "sh", "-c", "journalctl -b --no-pager | less; read -r _"])
}
PhoebusButton {
label: "Installer log"
compact: true
onClicked: shell.run(["kitty", "-e", "sh", "-c", "tail -n 200 /var/log/phoebus-installer/install.log 2>/dev/null | less; read -r _"])
}
PhoebusButton {
label: "Disk information"
compact: true
onClicked: shell.run(["kitty", "-e", "sh", "-c", "lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS; read -r _"])
}
PhoebusButton {
label: "Network settings"
compact: true
onClicked: shell.run(["sh", "-c", "command -v dms >/dev/null && exec dms ipc call settings focusOrToggle || exec kitty -e sh -c 'nmcli device status; read -r _'"])
}
}
}
Item { width: 1; height: 1 }
}
// -- keyboard test overlay ----------------------------------------
Rectangle {
anchors.fill: parent
color: Theme.overlay
visible: shell.showKeyboardTest
MouseArea { anchors.fill: parent; onClicked: shell.showKeyboardTest = false }
PhoebusCard {
anchors.centerIn: parent
width: 520
padding: Theme.padLarge
Text {
width: parent.width
text: "Keyboard test"
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontTitle
font.weight: Font.DemiBold
}
Text {
width: parent.width
text: "Type in the field below to confirm your layout produces the characters you expect."
color: Theme.muted
font.family: Theme.family
font.pixelSize: Theme.fontBody
wrapMode: Text.WordWrap
}
PhoebusField {
id: keyTest
label: "Type here"
placeholder: "The quick brown fox…"
}
Row {
spacing: 12
PhoebusButton {
label: "Close"
primary: true
onClicked: shell.showKeyboardTest = false
}
}
Component.onCompleted: keyTest.inputItem.forceActiveFocus()
}
}
// -- power overlay -------------------------------------------------
Rectangle {
anchors.fill: parent
color: Theme.overlay
visible: shell.showPower
MouseArea { anchors.fill: parent; onClicked: shell.showPower = false }
PhoebusCard {
anchors.centerIn: parent
width: 420
padding: Theme.padLarge
Text {
width: parent.width
text: "Power"
color: Theme.warmWhite
font.family: Theme.family
font.pixelSize: Theme.fontTitle
font.weight: Font.DemiBold
}
PhoebusButton {
label: "Restart"
onClicked: {
shell.showPower = false;
shell.run(["systemctl", "reboot"]);
}
}
PhoebusButton {
label: "Shut down"
onClicked: {
shell.showPower = false;
shell.run(["systemctl", "poweroff"]);
}
}
PhoebusButton {
label: "Cancel"
compact: true
onClicked: shell.showPower = false
}
}
}
}
}

View file

@ -0,0 +1,45 @@
Phoebus OS installation help
============================
What the installer does
-----------------------
The installer creates a GPT disk layout with an EFI system partition, a LUKS2
encrypted container and a Btrfs filesystem with the @ / @home / @var
/@snapshots / @swap subvolumes. It then installs a verified Gentoo stage3 and
the packages needed for a Mango + DankMaterialShell desktop with PipeWire,
Flatpak and Nix.
Nothing is written to a disk until you have reviewed the plan and typed ERASE
on the confirmation screen.
Requirements
------------
- 64-bit UEFI machine.
- At least 4 GiB of RAM and enough disk space (32 GiB or more recommended).
- A network connection during installation (the stage3 and packages are
downloaded; the installed system can boot and run offline).
- A connected AI model. Phoebus ships no model. Connect a hosted provider
(DeepSeek or OpenAI) or point the installer at a model you serve locally.
The installed system works without the model; you can always use the
deterministic `sys` command instead.
Choosing a disk
---------------
Only whole, writable disks are offered. Disks that hold mounted filesystems,
the live installation medium, optical/loop device-mapper devices and read-only
devices are protected and cannot be selected.
Destructive changes
-------------------
Everything on the selected disk is destroyed. If the installation fails, the
screen tells you whether disk changes occurred and what the safe next actions
are. A failed installation can be restarted from the review screen; the disk is
re-created from scratch.
Getting help
------------
- The full installer log is at /var/log/phoebus-installer/install.log.
- The serial console (Ctrl+Alt+F2) logs in as phoebus / phoebus on the live
medium; sudo is passwordless there.
- Open "Advanced tools" on the welcome screen for a terminal, system log,
installer log and disk information.

View file

@ -2,15 +2,19 @@
# mmdebstrap customize hook: turn a Debian testing rootfs into the Phoebus live # mmdebstrap customize hook: turn a Debian testing rootfs into the Phoebus live
# desktop (Mango + DankMaterialShell). Runs as root inside mmdebstrap's userns. # desktop (Mango + DankMaterialShell). Runs as root inside mmdebstrap's userns.
# #
# Payload installation (binaries, branding, Quickshell UI, the live marker) is
# done by build.sh after the rootfs is extracted, so a cached rootfs
# (PHOEBUS_REUSE_ROOTFS=1) still picks up changed assets. This hook only does
# the expensive, root-requiring work: user accounts, the Mango build and the
# DMS install.
#
# Environment (set by build.sh): # Environment (set by build.sh):
# PHOEBUS_SRC directory with the verified pinned source tarballs # PHOEBUS_SRC directory with the verified pinned source tarballs
# PHOEBUS_RELEASE directory with the static phoebus-installer and sys
# PHOEBUS_ASSETS directory with assets emitted by `phoebus-installer --emit-asset`
# MANGO_VERSION, DMS_VERSION # MANGO_VERSION, DMS_VERSION
set -euo pipefail set -euo pipefail
root="$1" root="$1"
: "${PHOEBUS_SRC:?}" "${PHOEBUS_RELEASE:?}" "${PHOEBUS_ASSETS:?}" : "${PHOEBUS_SRC:?}"
MANGO_VERSION="${MANGO_VERSION:-0.17.2}" MANGO_VERSION="${MANGO_VERSION:-0.17.2}"
DMS_VERSION="${DMS_VERSION:-1.6.2}" DMS_VERSION="${DMS_VERSION:-1.6.2}"
LIVE_USER=phoebus LIVE_USER=phoebus
@ -21,13 +25,6 @@ in_root() {
"$@" "$@"
} }
install_asset() {
local name="$1" dest="$2" mode="${3:-0644}"
local src="$PHOEBUS_ASSETS/$name"
[ -f "$src" ] || { echo "livefs-hook: missing asset $name" >&2; exit 1; }
install -D -m "$mode" "$src" "$root/$dest"
}
say() { echo "livefs-hook: $*"; } say() { echo "livefs-hook: $*"; }
say "live user" say "live user"
@ -49,28 +46,6 @@ if ! in_root id greeter >/dev/null 2>&1; then
--shell /sbin/nologin --comment "Phoebus greeter" greeter --shell /sbin/nologin --comment "Phoebus greeter" greeter
fi fi
say "installer and system broker"
install -D -m 0755 "$PHOEBUS_RELEASE/phoebus-installer" "$root/usr/local/bin/phoebus-installer"
install -D -m 0755 "$PHOEBUS_RELEASE/sys" "$root/usr/local/bin/sys"
say "shared desktop assets"
install_asset session-mango /usr/local/bin/phoebus-session-mango 0755
install_asset session-dwl /usr/local/bin/phoebus-session 0755
install_asset assistant /usr/local/bin/phoebus-assistant 0755
install_asset install /usr/local/bin/phoebus-install 0755
install_asset menu /usr/local/bin/phoebus-menu 0755
install_asset lock /usr/local/bin/phoebus-lock 0755
install_asset idle /usr/local/bin/phoebus-idle 0755
install_asset mango-config /etc/xdg/mango/config.conf
install_asset mango-session-target /usr/lib/systemd/user/mango-session.target
install_asset install-desktop /usr/share/applications/phoebus-install.desktop
install_asset wayland-session-mango /usr/share/wayland-sessions/phoebus-mango.desktop
install_asset wayland-session-dwl /usr/share/wayland-sessions/phoebus-dwl.desktop
install_asset waybar-config /etc/xdg/waybar/config
install_asset waybar-style /etc/xdg/waybar/style.css
# Live-only automatic login (never copied to an installed system).
install_asset greetd-live /etc/greetd/config.toml
say "build Mango ${MANGO_VERSION}" say "build Mango ${MANGO_VERSION}"
tar -xzf "$PHOEBUS_SRC/mango-${MANGO_VERSION}.tar.gz" -C "$root/tmp" tar -xzf "$PHOEBUS_SRC/mango-${MANGO_VERSION}.tar.gz" -C "$root/tmp"
in_root sh -c "cd /tmp/mango-${MANGO_VERSION} && \ in_root sh -c "cd /tmp/mango-${MANGO_VERSION} && \

View file

@ -0,0 +1,56 @@
#!/bin/bash
# Guest-side, non-interactive install for the graphical Phoebus live ISO.
#
# Fetched and run by gui-driver.py inside the live guest. Configuration and
# secrets are fetched from the host over QEMU user networking so they never
# appear in the serial transcript. The installer log is scanned for the LUKS
# passphrase so a leak fails the run.
#
# This uses the same deterministic backend as the graphical installer; the GUI
# is a typed frontend over it, so a CLI install and a GUI install execute the
# same stages.
set -uo pipefail
SERVE="${SERVE_URL:-http://10.0.2.2:8000}"
WORK=/tmp/phoebus-guest
mkdir -p "$WORK"
cd "$WORK" || exit 1
for f in test.conf luks.pw user.pw; do
if ! curl -fsSL "$SERVE/$f" -o "$f"; then
echo "===FETCH-FAIL=== ($f)"
exit 1
fi
done
chmod 600 luks.pw user.pw
PHOEBUS=/usr/local/bin/phoebus-installer
if [ ! -x "$PHOEBUS" ]; then
echo "===FETCH-FAIL=== (no phoebus-installer)"
exit 1
fi
"$PHOEBUS" --version || true
sudo -n "$PHOEBUS" --config "$WORK/test.conf" --install --yes --no-ai \
--luks-passphrase-file "$WORK/luks.pw" \
--user-password-file "$WORK/user.pw"
RC=$?
LEAK=0
for log in /run/phoebus-installer/install.log /tmp/phoebus-installer/install.log; do
if [ -f "$log" ] && grep -F -q "$(cat "$WORK/luks.pw")" "$log"; then
LEAK=1
fi
done
if [ "$LEAK" = 1 ]; then
echo "===SECRET_LEAK==="
RC=99
else
echo "===NO_SECRET_LEAK==="
fi
echo "===INSTALL-RC=$RC==="
sync
sudo -n poweroff -f || poweroff -f
echo "===POWEROFF==="

View file

@ -0,0 +1,346 @@
#!/usr/bin/env python3
"""Headless driver for the Phoebus graphical live/installer ISO.
The live medium boots into Mango + DankMaterialShell and opens the branded
welcome window. This driver boots it with a graphical device and a serial
console, checks the launcher/branding payload, drives the graphical installer
with `wtype` over the live session, and captures QEMU framebuffer screenshots.
Modes:
gui : boot, log in on serial, verify the welcome/branding payload, open
the installer, prove duplicate prevention, walk the first steps and
capture screenshots.
install : boot, log in on serial, fetch a non-interactive config and 0600
secrets over QEMU user networking, run the deterministic install
with the static binary, scan the log for a secret leak, power off.
boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run
verification commands.
`DISK` must always be a disposable qcow2 image. This script never touches a
physical disk.
"""
import os
import socket
import sys
import time
import pexpect
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS = os.environ["OVMF_VARS"]
ISO = os.environ.get("ISO", "")
DISK = os.environ.get("DISK", "")
SERIAL_LOG = os.environ.get("SERIAL_LOG", "/tmp/phoebus-gui-serial.log")
MONITOR = os.environ.get("MONITOR", "/tmp/phoebus-gui-monitor.sock")
SHOT_DIR = os.environ.get("SHOT_DIR", "/tmp/phoebus-gui-shots")
LIVE_USER = os.environ.get("LIVE_USER", "phoebus")
LIVE_PW = os.environ.get("LIVE_PASSWORD", "phoebus")
USER = os.environ.get("USERNAME", "phoebus")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000")
MEM = os.environ.get("VM_MEM", "8192")
SMP = os.environ.get("VM_SMP", "8")
BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900"))
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
WAYLAND_ENV = "XDG_RUNTIME_DIR=/run/user/1000"
def args(attach_iso=True, boot_disk=False):
a = [
"-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={OVMF_VARS}",
]
if DISK:
a += ["-drive", f"file={DISK},if=virtio,format=qcow2"]
a += [
# A real GPU device so the compositor gets a DRM node and a seat.
"-device", "virtio-gpu-pci",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci",
]
if attach_iso and ISO:
a += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
a += [
"-boot", "order=c" if boot_disk else "order=d",
"-vga", "none", "-display", "none",
"-serial", "stdio",
"-monitor", f"unix:{MONITOR},server,nowait",
"-no-reboot",
]
return a
def spawn(attach_iso=True, boot_disk=False):
if os.path.exists(MONITOR):
os.unlink(MONITOR)
child = pexpect.spawn(QEMU, args(attach_iso, boot_disk), timeout=BOOT_TIMEOUT,
encoding="utf-8", codec_errors="replace", maxread=65536)
child.delaybeforesend = 0.4
return child
def screendump(name):
"""Capture the QEMU framebuffer to SHOT_DIR/<name>.ppm (and .png if
ImageMagick is available)."""
os.makedirs(SHOT_DIR, exist_ok=True)
target = os.path.join(SHOT_DIR, name + ".ppm")
if not os.path.exists(MONITOR):
return None
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.settimeout(20)
try:
s.connect(MONITOR)
time.sleep(0.5)
try:
s.recv(65536)
except socket.timeout:
pass
s.sendall(b"screendump %s\n" % target.encode())
time.sleep(2)
try:
s.recv(65536)
except socket.timeout:
pass
finally:
s.close()
if not os.path.exists(target):
return None
os.system(f"magick '{target}' '{target[:-4]}.png' 2>/dev/null || "
f"convert '{target}' '{target[:-4]}.png' 2>/dev/null")
return target
def login_live(child):
# The live serial getty shows `<hostname> login:` and the password is the
# known live-only credential.
idx = child.expect([r"login:", r"[$#] $"], timeout=BOOT_TIMEOUT)
if idx == 0:
child.sendline(LIVE_USER)
child.expect(r"[Pp]assword:", timeout=90)
child.sendline(LIVE_PW)
child.expect(r"[$#] $", timeout=180)
def live_shell(child, command, end_marker, timeout=180):
child.sendline(command)
child.expect(end_marker, timeout=timeout)
def set_wayland(child):
# Export the live user's Wayland socket for wtype-based GUI driving.
child.sendline(
'export XDG_RUNTIME_DIR=/run/user/1000; '
'export WAYLAND_DISPLAY="$(basename "$(ls /run/user/1000/wayland-* 2>/dev/null | head -1)")"; '
'echo WAYLAND=$WAYLAND_DISPLAY'
)
child.expect(r"WAYLAND=wayland-\d+", timeout=60)
def sendkey(*keys):
"""Inject keys through the QEMU monitor (hardware keyboard level). This is
independent of the guest's input-method/portal setup."""
if not os.path.exists(MONITOR):
return
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.settimeout(10)
try:
s.connect(MONITOR)
time.sleep(0.3)
try:
s.recv(65536)
except socket.timeout:
pass
for k in keys:
s.sendall(("sendkey %s\n" % k).encode())
time.sleep(0.2)
time.sleep(0.3)
try:
s.recv(65536)
except socket.timeout:
pass
finally:
s.close()
def key(child, *wtype_args):
quoted = " ".join(f"'{a}'" for a in wtype_args)
child.sendline(f"wtype {quoted} >/dev/null 2>&1; echo KEY-DONE")
child.expect("KEY-DONE", timeout=60)
def do_gui():
child = spawn()
log = open(SERIAL_LOG, "w")
child.logfile = log
try:
login_live(child)
# Give greetd/the session time to bring up Mango + DMS + the welcome
# window (it starts after the shell is ready).
time.sleep(int(os.environ.get("SESSION_SETTLE", "30")))
for _ in range(12):
child.sendline(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)"
)
child.expect(r"WELCOME=(\d+)", timeout=60)
if int(child.match.group(1)) > 0:
break
time.sleep(5)
# Payload checks (no secrets here).
checks = (
"echo ===GUI-CHECKS-$(printf START)===; "
"test -e /etc/phoebus/live && echo LIVE-MARKER; "
"test -s /usr/share/phoebus/branding/wallpaper.svg && echo BRAND-WALLPAPER; "
"test -s /usr/share/icons/hicolor/scalable/apps/phoebus.svg && echo BRAND-ICON; "
"test -s /etc/xdg/quickshell/phoebus-install/shell.qml && echo INSTALL-QML; "
"test -s /usr/share/applications/phoebus-install.desktop && echo DESKTOP-ENTRY; "
"test -f /home/phoebus/.config/DankMaterialShell/.firstlaunch && echo ONBOARDING-SUPPRESSED; "
"echo ===GUI-CHECKS-$(printf END)==="
)
live_shell(child, checks, "===GUI-CHECKS-END===", timeout=180)
shot = screendump("01-welcome")
print("welcome screenshot:", shot, flush=True)
set_wayland(child)
# Backend disk protection on the real VM: the live medium must be
# reported protected and never selectable.
child.sendline(
"printf '%s\\n%s\\n' '{\"id\":1,\"op\":\"disks\"}' '{\"id\":2,\"op\":\"quit\"}' "
"| sudo -n /usr/local/bin/phoebus-installer --gui-bridge 2>/dev/null "
"| head -1 > /tmp/disks.json; "
"echo DISKS=$(wc -c </tmp/disks.json); cat /tmp/disks.json"
)
child.expect(r"DISKS=(\d+)", timeout=120)
print("disks probe bytes:", child.match.group(1), flush=True)
# Activate the focused "Install Phoebus OS" button with Return. This is
# the real launcher-to-installer journey (no shell shortcut).
sendkey("ret")
time.sleep(8)
child.sendline("echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)")
child.expect(r"INST=(\d+)", timeout=60)
if int(child.match.group(1)) == 0:
# The window manager may not have focused the welcome; fall back to
# the launcher so the rest of the journey can still be exercised.
child.sendline(
"setsid /usr/local/bin/phoebus-install >/tmp/install-gui.log 2>&1 & echo LAUNCHED"
)
child.expect("LAUNCHED", timeout=30)
time.sleep(7)
# Surface the installer frontend's own log (it contains bridge errors).
child.sendline(
"echo QMLLOG-$(printf START); "
"cat /run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | "
"grep -aiE 'phoebus-bridge|error|failed|sudo|handshake' | tail -30; "
"echo NOTTY-SUDO; setsid sh -c 'sudo -n true' ; echo NOTTYSUDO=$?; "
"echo QMLLOG-$(printf END)"
)
child.expect("QMLLOG-END", timeout=60)
screendump("02-installer-language")
# The first handshake probes hardware and disks; wait for it before
# driving the wizard so the backend is ready to validate.
time.sleep(int(os.environ.get("BACKEND_SETTLE", "30")))
# Close the welcome so the installer window has the keyboard focus
# (Mango tiles both windows; the welcome would otherwise receive keys).
child.sendline("pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED")
child.expect("CLOSED", timeout=30)
# Duplicate prevention: a second launch must not create a second session.
child.sendline(
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n1; "
"/usr/local/bin/phoebus-install >/tmp/install-gui2.log 2>&1; "
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n2; "
"echo DUP n1=$(cat /tmp/n1) n2=$(cat /tmp/n2)"
)
child.expect(r"DUP n1=(\d+) n2=(\d+)", timeout=60)
print("duplicate check:", child.match.group(0), flush=True)
# Move forward through the wizard with the keyboard shortcut.
sendkey("ctrl-right")
time.sleep(2)
screendump("03-network-prerequisites")
sendkey("ctrl-right")
time.sleep(2)
screendump("04-ai-model")
# Advancing without a connected model must be refused (blocked prereq).
sendkey("ctrl-right")
time.sleep(2)
screendump("05-ai-blocked")
print("gui checks complete", flush=True)
finally:
child.close(force=True)
log.close()
def do_install():
child = spawn()
log = open(SERIAL_LOG, "w")
child.logfile = log
try:
login_live(child)
child.sendline(
f"curl -fsSL {SERVE_URL}/appliance-guest-gui.sh -o /tmp/gi.sh && bash /tmp/gi.sh"
)
child.expect([r"===INSTALL-RC=([0-9]+)===", "===FETCH-FAIL===",
"Kernel panic", pexpect.EOF, pexpect.TIMEOUT],
timeout=INSTALL_TIMEOUT)
if "INSTALL-RC" in (child.after or ""):
print("INSTALL_RC", child.match.group(1), flush=True)
else:
print("INSTALL did not report a status", flush=True)
child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600)
child.expect(pexpect.EOF, timeout=300)
finally:
child.close(force=True)
log.close()
def do_boot():
# Detached: no ISO, boot from the installed disk only.
child = spawn(attach_iso=False, boot_disk=True)
log = open(SERIAL_LOG, "w")
child.logfile = log
checks = os.environ.get(
"BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; "
"cat /proc/1/comm; systemctl is-system-running; "
"systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
)
try:
child.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT)
if "assphrase" in (child.after or ""):
child.sendline(LUKS_PW)
for _ in range(5):
child.expect(r"phoebus login:", timeout=300)
child.sendline(USER)
idx = child.expect([r"[Pp]assword:", r"phoebus login:", r"Login incorrect"],
timeout=60)
if idx == 0:
child.sendline(USER_PW)
if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0:
break
child.sendline(checks)
child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")))
print("checks complete", flush=True)
finally:
child.close(force=True)
log.close()
if __name__ == "__main__":
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode == "gui":
do_gui()
elif mode == "install":
do_install()
elif mode == "boot":
do_boot()
else:
print(__doc__)
sys.exit(2)