phoebus_os/installer-rs/README.md
Phoebus 4c59a1f3ad test(rust): replace the Bash parity test with golden plan tests
parity.rs compared the Rust plan to the Bash installer. The Bash tree is
being retired, so pin the exact Rust plan and destructive preview to golden
files instead (UPDATE_GOLDEN=1 to regenerate).
2026-09-20 03:56:57 -07:00

121 lines
4.3 KiB
Rust

# Phoebus OS installer (Rust)
The production installer/backend for Phoebus OS. It is being built beside the
proven Bash implementation and only becomes primary once it reproduces the
known-good encrypted UEFI VM boot.
## Workspace
```
crates/
phoebus-core configuration types, validation, plan, package policy,
hardware/disk models, target-root safety, secrets,
snapshot history, typed system actions, update policy
phoebus-executor command runner, logging, storage, encryption, Btrfs,
stage3, Portage, kernel, boot, users, services, desktop,
snapshots, background-update preparation, admin context
phoebus-ai typed AI proposals + enforced privacy boundary
phoebus-tui ratatui terminal UI
phoebus-installer CLI, `sys`, orchestration
```
Binaries: `phoebus-installer` (installer) and `sys` (typed system interface).
## `sys`
```sh
sys enable sshd # deterministic phrase -> typed action
sys disable bluetooth
sys history # snapshot/transaction history
sys what are you compiling # background update status
sys --action '{"action":"inspect_service","name":"ssh"}'
sys --action-file proposal.json # the AI path: same typed schema
```
Mutating actions require root (run under `sudo`); the model never receives the
password. High-risk actions are preceded by a Btrfs snapshot when available.
There is no `run_shell` action; unknown actions fail closed.
## Snapshots and background updates
- `phoebus-core::snapshot` defines deterministic snapshot names and a TOML
transaction history. `phoebus-executor::snapshot` creates read-only Btrfs
snapshots. `/home` is intentionally not snapshotted by default.
- `phoebus-core::update` / `phoebus-executor::update` implement **preparation
only**: `emerge --fetchonly` then `emerge --buildpkgonly` stage distfiles and
reusable local binary packages without installing. Activation stays explicit.
## Building
```sh
cargo test --workspace
cargo build --release -p phoebus-installer
# A static binary is preferred for the live installer environment:
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
```
Formatting and lints are part of the gate:
```sh
cargo fmt --all -- --check
cargo clippy --workspace --all-targets
```
## CLI
```sh
phoebus-installer --config FILE --plan
phoebus-installer --config FILE --dry-run --install
phoebus-installer --config FILE --install --yes \
--luks-passphrase-file /run/luks.pw \
--user-password-file /run/user.pw
```
Both TOML and the legacy flat `KEY='value'` format are supported. Format is
detected structurally (the flat format is also valid TOML because single
quotes are TOML literal strings).
```toml
[system]
hostname = "phoebus"
timezone = "UTC"
[storage]
disk = "/dev/vda"
filesystem = "btrfs"
[encryption]
mode = "luks2"
```
Secrets are never stored in the configuration. They are supplied through 0600
files and registered with the redactor before anything is logged.
## Safety model
- Every command goes through `phoebus-executor::Exec`, which logs redacted
arguments, exit status and duration, and honours dry-run centrally.
- Arguments are always passed separately; there is no `sh -c`.
- `TargetRoot` rejects absolute paths and `..` traversal, so host-versus-target
bugs are caught by construction and covered by tests.
- Destructive functions require a `DestructiveAuthorization` token produced
only after the ERASE confirmation and a final confirmation.
- `phoebus-ai` can only emit a closed set of typed configuration changes;
unknown actions fail closed and there is no shell action.
## Package policy
`phoebus-core::policy` implements the deterministic source/binary rule and
records *measured* compile times parsed from Portage's `emerge.log`
(`phoebus-core::emergelog`). No performance value is ever invented.
## Verification
`crates/phoebus-installer/tests/plan_golden.rs` pins the rendered plan and
destructive preview to golden files under `tests/golden/` (regenerate with
`UPDATE_GOLDEN=1`). `crates/phoebus-installer/tests/cli_coverage.rs` pins the
command-line surface to the reference Bash installer. The disposable VM harness
in `../installer/tests/vm` drives the static binary through a full encrypted
install and boot.