diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..194f0e7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,189 @@ +# AGENTS.md — operating instructions for AI sessions + +This file is the entry point for any AI/LLM session (or human) working on +Phoebus OS. **Read this file first, then follow the reading order below.** +It is deliberately concrete: follow it rather than rediscovering the project. + +--- + +## 1. What Phoebus is + +Phoebus OS is a **modern, stable, Gentoo-based workstation operating system**: +systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast +dwl-style desktop, Flatpak, and an optional AI administration assistant. It is +**AI-first but never AI-dependent**: the system must be fully usable without an +LLM, and the LLM never holds privilege. + +Read next, in order: + +1. `docs/OBJECTIVES.md` — vision, philosophy, non-goals. +2. `docs/ROADMAP.md` — priorities and what is done/next/later. +3. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified. +4. `docs/ARCHITECTURE.md` — components and how they fit together. +5. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow. +6. `docs/CONTRIBUTING.md` — code standards and definition of done. +7. `docs/GIT-WORKFLOW.md` — how changes are committed and published. +8. `git log --oneline -30` and the top of `docs/CHANGELOG.md` — recent history. + +--- + +## 2. Non-negotiable rules + +These are not preferences. Do not violate them, even to make a test pass. + +1. **Never touch a physical host disk.** All destructive testing happens on a + disposable qcow2 image. If a test needs a real disk, stop and say so. +2. **Never send secrets to an LLM.** No passwords, passphrases, API keys or + tokens in prompts, logs, config files, command lines or commits. +3. **Never log secrets.** Register every secret with the redactor; pass + passphrases only over stdin. +4. **Never give the LLM a shell or root.** AI can only emit typed, validated + actions; a privileged, human-approved broker executes them. +5. **Never globally enable Gentoo `~amd64`.** Scoped `accept_keywords` for + hardware/desktop enablement are allowed and must be explicit. +6. **Never disable package signature verification** to make an install pass. +7. **Never weaken** LUKS2, Btrfs, systemd, UEFI or disk protection for + convenience. Fix the real problem. +8. **Stability beats novelty.** No release-candidate kernels, no experimental + filesystem defaults, no unstable snapshots. Prefer stable/LTS and mature + implementations. +9. **Do not regress the proven boot path.** See `docs/STATUS.md` for the exact + configuration that is known to boot. +10. **Do not commit the ISO, build output, session transcripts or secrets.** + `.gitignore` handles this; do not override it. + +--- + +## 3. Repository map + +``` +AGENTS.md this file (read first) +README.md short project overview +docs/ objectives, roadmap, status, architecture, process +installer/ proven Bash installer (reference / fallback) + bin/ai-installer entry point + lib/ deterministic backend modules + tui/ dialog/whiptail UI + config/ defaults, example config, OpenCode manifest + tests/ unit suite + tests/vm/ disposable-VM harness + doc/ environment findings and VM boot verification +installer-rs/ production Rust installer + crates/phoebus-core types, validation, plan, policy, target-root safety + crates/phoebus-executor command layer, storage, Portage, boot, snapshots, ... + crates/phoebus-ai typed proposals + enforced privacy boundary + crates/phoebus-tui ratatui TUI + crates/phoebus-installer CLI, `sys`, `phoebus-release`, orchestration +scripts/ git/dev tooling (hooks, publish, agent-commit) +.githooks/ committed git hooks +``` + +Authoritative design records: + +- `installer/doc/FINDINGS.md` — what the reference live environment contains. +- `installer/doc/VM-BOOT-VERIFICATION.md` — the proven VM install/boot path. +- `installer-rs/README.md` — Rust workspace details. + +--- + +## 4. How to work (loop) + +1. Read this file and the reading order in §1. +2. Inspect `docs/ROADMAP.md` for the highest-priority unfinished item. +3. Inspect `git log --oneline -20` and `docs/CHANGELOG.md` for context. +4. Inspect the relevant code and existing tests **before editing**. +5. Implement the smallest correct change. Prefer upstream tools over new code. +6. Run the quality gates and relevant tests (§5). +7. If you did destructive work, run it in the disposable VM (§6) and record + the evidence. +8. Update `docs/CHANGELOG.md` and `docs/STATUS.md` if behavior/verification + changed. +9. Commit with a conventional commit message (see `docs/GIT-WORKFLOW.md`) and + push when the user's remote is configured. + +Do the actual work; do not stop at a design document. Do not ask for guidance +when the next engineering step is clear. + +--- + +## 5. Build and test gates + +Bash installer (reference): + +```sh +installer/tests/run_tests.sh # unit/regression assertions +shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh +``` + +Rust installer (production): + +```sh +cd installer-rs +cargo fmt --all -- --check +cargo clippy --workspace --all-targets +cargo test --workspace +cargo build --release -p phoebus-installer +``` + +Static binary for the live installer environment: + +```sh +cd installer-rs +RUSTFLAGS="-C target-feature=+crt-static" \ + cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu +``` + +Both test suites must pass before a commit. The pre-commit hook runs the fast +Bash suite and a secret scan; see `docs/GIT-WORKFLOW.md`. + +--- + +## 6. Disposable VM testing + +`installer/tests/vm/` contains a repeatable harness: + +- `serial-driver.py` — host-side pexpect driver (`install` and `boot` modes). +- `install.sh` — guest-side non-interactive install. +- `test.conf.example` — configuration. +- `run-vm.sh` — interactive QEMU launcher. + +Never point `DISK` at a `/dev/*` device. See `docs/DEVELOPMENT.md` for the full +procedure and required host packages. + +--- + +## 7. Code conventions (short form) + +Rust: no `unsafe` (if truly needed, keep it tiny, document invariants, test +it); no `unwrap`/`expect` in privileged paths; structured `thiserror` errors; +never `sh -c`; every command goes through `phoebus-executor::Exec`; every +target write goes through `TargetRoot`; destructive functions require a +`DestructiveAuthorization` token. + +Bash (while it exists): `shellcheck` clean; no `local a="$1" b="$a"` (dynamic +scoping bug class); no writes to host paths without the target root; quote +everything. + +Use `just`-style readability, not cleverness. Fewer lines is not the goal; +correctness, testability and observability are. + +--- + +## 8. Where history lives + +- `git log` — the authoritative change history. +- `docs/CHANGELOG.md` — curated, human-readable milestones. +- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence per iteration. +- `docs/STATUS.md` — current implementation/verification matrix. + +When you finish work, update the changelog and status, then commit. A future +session should be able to reconstruct what happened from these alone. + +--- + +## 9. Known limitations (keep this current) + +See `docs/STATUS.md` for the full list. Highlights: UKI is deferred (BLS is +used); Btrfs rollback is not implemented; the AI OS sandbox is designed but not +enforced; Full Disk Encryption boot, desktop and Flatpak are verified only in +a disposable VM (graphical session via the headless wlroots backend, no +physical seat); NVIDIA is not verified. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..ce2cf51 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,121 @@ +# Architecture + +Phoebus currently ships two installer implementations: + +1. **Bash** (`installer/`) — the proven prototype and executable reference. +2. **Rust** (`installer-rs/`) — the production installer. It reproduces the + proven VM boot path and is the intended long-term backend. + +The Bash implementation stays until hardware-level desktop verification exists. + +## Layering + +``` +TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer) + | + v +Orchestration + plan staged execution, single source of truth + | + v +Executor commands, storage, Portage, boot, services + | + v +Core typed config, models, policy, validation +``` + +### phoebus-core + +Pure, non-privileged logic with no external commands except reading `/proc`, +`/sys` and small system files: + +- `config` — `InstallConfig` (nested sections, enums for closed sets); TOML and + legacy flat-format loading (format is detected structurally). +- `validate` — hostname/username/locale/timezone/keymap/password checks. +- `disk` / `hardware` — models and protection classification (pure). +- `plan` — `InstallPlan` with the canonical step order and human rendering. +- `policy` — deterministic source/binary decisions + policy context. +- `emergelog` — parses Portage `emerge.log` into measured compile times. +- `target` — `TargetRoot`, which rejects absolute paths and `..` traversal. +- `secret` — `SecretString` (redacted `Debug`, zeroized on drop) + `Redactor`. +- `snapshot` — deterministic snapshot names + TOML transaction history. +- `action` — closed `SystemAction` schema and a small deterministic parser. +- `update` — preparation policy and real Portage argument builders. + +### phoebus-executor + +The only crate that runs privileged commands. + +- `command` — `CommandSpec`, `ProcessRunner` (real / recording / never) with + arguments always separate; there is no `sh -c`. +- `exec` — `Exec` centralises logging, redaction, dry-run, chroot mounts and + target writes. +- `log` — file + optional stderr logging; every line is redacted. +- `auth` — `DestructiveAuthorization`, issued only after ERASE + final + confirmation. +- `storage`, `encryption`, `portage`, `kernel`, `boot`, `users`, `services`, + `desktop` — the install backend, mirroring the proven order. +- `probe` — read-only hardware and disk discovery. +- `snapshot`, `update`, `admin`, `actions` — post-install foundations. + +### phoebus-ai + +- Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell). +- `privacy` — `PrivacyPolicy` + `ContextBundle`; forbidden-path checks. The + collector in `phoebus-executor::admin` only reads system sources. + +### phoebus-installer + +- `orchestrate` — `Installer` runs the plan stages and stops on first failure. +- `release` — `ReleaseManifest` create/verify, assemble command. +- Binaries: `phoebus-installer`, `sys`, `phoebus-release`. + +## Safety model + +- Every command goes through `Exec`, which logs a redacted command line, exit + status and duration, and honours dry-run centrally. +- Destructive functions take `&DestructiveAuthorization`; the token is created + only after the destructive preview and confirmations. +- All target writes go through `TargetRoot`; host-versus-target mistakes are + caught by construction and covered by tests. +- Secrets travel over stdin only and are registered with the redactor before + any logging. They never enter the config. +- The AI cannot execute; it can only propose typed changes that the backend + validates and the user approves. + +## Installation order (do not regress) + +``` +storage_prepare -> stage_install -> fstab_generate -> portage_configure +-> packages_base -> kernel_install -> boot_install -> users_configure +-> services_configure -> desktop_install -> finalize +``` + +Storage order: partition GPT, create ESP, LUKS format/open, `mkfs.btrfs`, mount +top-level, create subvolumes, unmount, mount the subvolume layout. `fstab` and +`crypttab` are generated **after** stage3 extraction (stage3 ships its own +`/etc/fstab`). + +## Configuration and plan + +`InstallConfig` is canonical data; the plan and all rendering derive from it. +The same plan drives the review screen, the destructive preview, dry-run and +the actual execution, so the UI cannot diverge from the backend. + +## Post-install foundations + +- **Snapshots**: read-only Btrfs snapshots under `/.snapshots`, recorded in a + TOML history. `/home` is intentionally not snapshotted by default. +- **Background updates**: `emerge --fetchonly` then `--buildpkgonly` stage + distfiles and reusable local binary packages without installing; activation + stays explicit. +- **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel` + (optimized), dracut initramfs, systemd-boot BLS entries, plus a recovery + entry booting `rescue.target`. + +## Extension points + +- `ProcessRunner` — swap the real runner for a recording/never runner in tests, + or for a different execution backend. +- `InstallStep` — add stages in `plan.rs` and handle them in `orchestrate.rs`. +- `SystemAction` — add closed verbs; the policy engine classifies and previews + them, and the broker executes them after approval. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..088f3ba --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,79 @@ +# Changelog + +All notable changes are recorded here. The authoritative history is `git log`; +this file is the curated, human-readable summary. + +Format: Keep a Changelog. Dates are UTC. + +## Unreleased + +### Added +- Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`, + `scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`. +- Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`, + `ARCHITECTURE.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`, `GIT-WORKFLOW.md`, + `CHANGELOG.md`, and the top-level `AGENTS.md`. +- `.gitignore` covering the ISO, build output, transcripts and secrets. + +## 2026-09-20 — Rust installer parity, desktop, and foundations + +### Added +- Rust workspace (`installer-rs/`): `phoebus-core`, `phoebus-executor`, + `phoebus-ai`, `phoebus-tui`, `phoebus-installer` (~9.4k LOC, 45 files). +- Typed `InstallConfig` supporting TOML and the legacy flat format. +- `TargetRoot` (host/target path safety), `SecretString`/`Redactor`, + `DestructiveAuthorization`, central `Exec` command layer with dry-run. +- Storage backend: GPT, ESP, LUKS2, Btrfs layout, fstab/crypttab, swapfile. +- Stage3 fetch with pinned SHA-256 (or signed DIGESTS), Portage configuration, + signed binary use, source builds, kernel, dracut, systemd-boot BLS. +- Desktop/Flatpak: selects `default/linux/amd64/23.0/desktop/systemd`, writes + `/usr/local/bin/phoebus-session`; flathub remote configured. +- Package policy instrumentation: measured compile times parsed from + `emerge.log` (326 entries recorded in the desktop run), persisted to + `/var/lib/phoebus/compile-times.tsv`. +- Snapshots: read-only Btrfs snapshots + TOML transaction history. +- Background update preparation (`--fetchonly` + `--buildpkgonly`). +- Typed `SystemAction` schema, privileged broker, and the `sys` command. +- AI privacy boundary (`PrivacyPolicy`, `ContextBundle`, forbidden paths). +- Release tooling: `phoebus-release` manifest/verify/sha256/assemble. +- ratatui TUI with plan review and ERASE confirmation. +- Recovery BLS entry booting `rescue.target`. + +### Fixed +- Subvolumes mounted before creation. +- fstab/crypttab overwritten by stage3 extraction (moved to `fstab_generate`). +- Missing `/var/tmp` breaking `kernel-install`. +- `installkernel` requiring `uki_generator` even for BLS. +- dracut `crypt` module and `systemd-cryptsetup` missing. +- LUKS cmdline using `rd.luks.uuid` instead of `rd.luks.name`. +- dracut UKI missing the kernel command line (BLS adopted). +- `@swap` not mounted, breaking swap activation. +- Portage GPG verify user unable to read the getuto keyring. +- Transient rsync mirror quarantine (sync retries). +- Pillow/HarfBuzz documentation circular dependency. +- Legacy config silently parsed as TOML with defaults. + +### Verified +- Full encrypted UEFI install and boot with the ISO detached: `systemd` PID 1, + `is-system-running = running`, 0 failed units, 10.73 s boot. +- Desktop stack headless: dwl, waybar, mako, swaybg, `grim` screenshot, + `wl-copy`/`wl-paste`, `wpctl`, `flatpak 1.18.1` + flathub. +- No secret leakage in the installer log. + +## 2026-09-19 — Bash installer prototype and first VM boot + +### Added +- Bash + `dialog` installer (`installer/`) with deterministic backend, TUI, + plan/review, dry-run, logging, and destructive confirmation. +- Read-only hardware/disk discovery with live-medium protection. +- GPT/LUKS2/Btrfs backend, systemd stage3, Portage, kernel, systemd-boot, + users/services/desktop modules. +- Unit/regression suite and a disposable VM harness. + +### Verified +- First complete encrypted UEFI VM install and boot with the Bash installer. + +### Fixed +- The subvolume-ordering, fstab-timing, `/var/tmp`, `rd.luks.name`, + `uki_generator`, cryptsetup, `@swap`, and `local root="$1" dir=...` bugs + (these are the class of bug the Rust port is designed to prevent). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..81dbc57 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing + +## Golden rules + +1. Read `AGENTS.md` and the reading order in it before changing anything. +2. Prefer upstream tools and Gentoo conventions over new code. +3. Keep the proven boot path working. If a change could regress it, verify in + the disposable VM before committing. +4. Never commit secrets, the ISO, build output or session transcripts. +5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior or + verification changes. + +## Rust standards + +- No `unsafe`. If it is genuinely required, keep it tiny, document the + invariants, and test it. (The TUI uses `std::io::IsTerminal` rather than a + foreign `isatty`.) +- No `unwrap`/`expect` in privileged paths. Return structured `thiserror` + errors that carry stage, operation and exit status. +- Never `sh -c`. Every command goes through `phoebus-executor::Exec` with + separate arguments; secrets go over stdin. +- Every target write goes through `TargetRoot`. +- Destructive functions require `&DestructiveAuthorization`. +- Keep unit-testable logic pure and in `phoebus-core`; keep privileged effects + in `phoebus-executor` behind `ProcessRunner`. + +## Bash standards (while it remains) + +- `shellcheck -S warning` clean. +- Never `local a="$1" b="$a"` (the dynamic-scoping bug class). Use two `local` + statements. +- Never write to a host path without the target root. +- Quote all expansions. + +## Tests + +- Add a regression test for every meaningful bug (see the tests in + `installer/tests/` and `installer-rs/crates/*/src`). +- Prefer a fake `ProcessRunner` + `TempDir` over root or real disks. +- Destructive/integration testing only in a disposable qcow2 VM. +- Both suites must pass before a commit. + +## Commit messages + +Conventional Commits, imperative mood: + +``` +(): + + +``` + +Types: `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `chore`. +Scopes: `installer`, `rust`, `core`, `executor`, `ai`, `tui`, `vm`, `docs`, +`git`, `release`. + +Examples: + +``` +feat(rust): add typed SystemAction broker for sys +fix(executor): make getuto keyring readable by the verify user +docs(git): add migration plan and agent workflow +``` + +## Definition of done + +- [ ] The change is implemented, not merely described. +- [ ] Tests added or updated; both suites pass. +- [ ] `cargo fmt`/`clippy` clean (when the components are installed). +- [ ] `docs/CHANGELOG.md` updated; `docs/STATUS.md` updated if verification + changed. +- [ ] No secrets, ISO, build output or transcripts staged. +- [ ] Committed with a conventional message and pushed when a remote exists. + +## Review checklist + +- Does it weaken encryption, signing, boot protection or disk safety? If so, + stop. +- Does it globally enable `~amd64` or disable signature verification? If so, + stop. +- Does it give the LLM a shell, root, secrets or home-directory access? If so, + stop. +- Does it preserve the proven boot path and the fstab/subvolume ordering? +- Is the change observable in the log and covered by a test? diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..c922578 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,117 @@ +# Development + +## Host requirements + +Ubuntu/Debian host names (the development machine is Ubuntu 26.04): + +```sh +sudo apt install qemu-system-x86 qemu-utils ovmf-generic seabios ipxe-qemu \ + dialog xorriso mtools dosfstools squashfs-tools cpio zstd \ + shellcheck python3-pexpect + +# Rust quality gates (names may be versioned; check `apt search rustfmt`) +sudo apt install rust-clippy rustfmt +# or, if cargo is rustup-managed: +# rustup component add rustfmt clippy +``` + +Optional: `expect`, `cryptsetup`, `btrfs-progs`, `parted`, `kpartx` for offline +inspection of VM images. `7z`/`p7zip` is useful for reading the reference ISO. + +## Reference media + +The Gentoo LiveGUI ISO is a **reference artifact**, not source. It is ignored by +`.gitignore`. Keep it outside git; point the VM harness at it by path. + +## Bash installer + +```sh +installer/tests/run_tests.sh +shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh + +# Non-interactive, non-destructive: +installer/bin/ai-installer --config installer/config/example.conf --plan +installer/bin/ai-installer --dry-run --config installer/config/example.conf +``` + +## Rust installer + +```sh +cd installer-rs +cargo fmt --all -- --check +cargo clippy --workspace --all-targets +cargo test --workspace +cargo build --release -p phoebus-installer + +# Static binary for the live environment: +RUSTFLAGS="-C target-feature=+crt-static" \ + cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu +``` + +Useful CLI invocations: + +```sh +target/release/phoebus-installer --config FILE --plan +target/release/phoebus-installer --config FILE --dry-run --install +target/release/phoebus-installer --config FILE --install --yes \ + --luks-passphrase-file /secure/luks.pw --user-password-file /secure/user.pw +``` + +## Disposable VM testing + +Never point the harness at a physical disk. The target is always a qcow2 file. + +`installer/tests/vm/serial-driver.py` drives QEMU over the serial console: + +```sh +cd /path/to/serve +tar czf installer.tar.gz -C /path/to/phoebus_os installer # or the Rust binary +python3 -m http.server 8000 --bind 127.0.0.1 + +QEMU_BIN=qemu-system-x86_64 \ +OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \ +OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \ +DISK=/tmp/phoebus/target.qcow2 \ +ISO=/path/to/livegui-*.iso \ +KERNEL=/tmp/live/boot/gentoo INITRD=/tmp/live/boot/gentoo.igz \ +INSTALL_URL=http://10.0.2.2:8000/install.sh \ +python3 installer/tests/vm/serial-driver.py install + +# Then boot the disk alone (ISO detached): +DISK=/tmp/phoebus/target.qcow2 OVMF_CODE=... OVMF_VARS=... \ +python3 installer/tests/vm/serial-driver.py boot +``` + +`installer/tests/vm/run-vm.sh` launches an interactive VM instead. + +### Verifying the graphical stack + +The serial-only VM has no logind seat, so wlroots' DRM backend cannot start +there. For headless verification use: + +```sh +export WLR_BACKENDS=headless WLR_RENDERER=pixman WLR_RENDERER_ALLOW_SOFTWARE=1 +dwl & # creates wayland-0 +grim /tmp/shot.png # proves the compositor renders +``` + +On a real machine the installer writes `/usr/local/bin/phoebus-session` +(waybar + mako + swaybg + dwl). + +## Inspecting the reference ISO without booting + +```sh +7z l livegui-*.iso +7z x livegui-*.iso image.squashfs boot/gentoo boot/gentoo.igz +unsquashfs -l image.squashfs # file listing +unsquashfs -d /tmp/root image.squashfs etc/portage/make.conf +``` + +## Quality gates before commit + +1. `installer/tests/run_tests.sh` +2. `cd installer-rs && cargo test --workspace` +3. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets` +4. `shellcheck` on the Bash tree (while it exists) +5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes. +6. Commit (see `docs/GIT-WORKFLOW.md`). diff --git a/docs/GIT-WORKFLOW.md b/docs/GIT-WORKFLOW.md new file mode 100644 index 0000000..5374dec --- /dev/null +++ b/docs/GIT-WORKFLOW.md @@ -0,0 +1,101 @@ +# Git workflow and public-repository migration + +## What is tracked + +Tracked: source (`installer/`, `installer-rs/crates/`, `scripts/`, `.githooks/`), +`Cargo.toml`/`Cargo.lock`, documentation (`docs/`, `AGENTS.md`, `README.md`, +`installer/doc/`, `installer-rs/README.md`), installer configs and tests. + +Ignored (see `.gitignore`): the reference ISO and other images, `installer-rs/target/`, +`__pycache__`, `.agent-shell/` transcripts, and any secret material +(`*.pw`, `*.key`, `*.pem`, `credentials`). + +## One-time migration (already performed) + +```sh +cd /path/to/phoebus_os +git init -b main +git add -A +git commit -m "chore: import Phoebus OS installer and Rust migration" +# ... further commits for docs and tooling ... +git config core.hooksPath .githooks # enable the committed hooks +``` + +Then connect the public remote and push: + +```sh +git remote add origin +git push -u origin main +``` + +`scripts/publish.sh` performs the push after re-running the checks. It takes the +remote and branch as arguments: + +```sh +scripts/publish.sh origin main +``` + +> The remote URL is intentionally not hard-coded. Add it once with +> `git remote add origin ` and every later `scripts/publish.sh` uses it. + +## Ongoing loop for a work session + +``` +read AGENTS.md + -> inspect docs/ROADMAP.md and git log + -> implement the smallest correct change + -> run the quality gates + -> update docs/CHANGELOG.md and docs/STATUS.md + -> commit (conventional message) + -> push +``` + +An AI session **must commit the work it does**. The one-line helper: + +```sh +scripts/agent-commit.sh "feat(rust): add typed SystemAction broker + +Adds a closed action schema and a privileged broker. Verified with +cargo test --workspace." +``` + +`agent-commit.sh` refuses to commit if the secret scan finds a credential or if +a staged file is too large, then runs the fast tests. + +## Hooks + +`.githooks/pre-commit` (enabled with `git config core.hooksPath .githooks`): + +1. scans staged files for secrets (`scripts/check-secrets.sh`); +2. blocks staged `*.iso`, `*.qcow2` and files larger than 5 MiB; +3. runs the fast Bash test suite. + +Bypass for a genuine emergency with `git commit --no-verify`, or set +`SKIP_PHOEBUS_HOOKS=1`. Set `PHOEBUS_PRECOMMIT_RUST=1` to also run +`cargo test --workspace` in the hook. + +## Branching and releases + +- Trunk-based: `main` is always green. Short-lived branches are fine for risky + work; merge with a conventional merge/squash. +- Releases are annotated tags `vX.Y.Z` with the manifest produced by + `phoebus-release`. Never replace `latest.iso` until `phoebus-release verify` + passes. +- Never rewrite published history (`push --force` to `main` is forbidden). Fix + mistakes with a new `fix:` commit. + +## Secret policy + +- Never commit passwords, LUKS passphrases, API keys or tokens. +- Secrets are supplied at runtime through 0600 files or stdin and registered + with the redactor. +- The pre-commit scan is a safety net, not a licence to be careless. + +## What a future session should do + +1. `git log --oneline -20` and `head docs/CHANGELOG.md` for context. +2. Work as described in `AGENTS.md`. +3. Before committing: `scripts/check-secrets.sh` and the test gates. +4. Commit with `scripts/agent-commit.sh` (or `git commit`), then + `scripts/publish.sh`. +5. Confirm `git status` is clean and the push succeeded. diff --git a/docs/OBJECTIVES.md b/docs/OBJECTIVES.md new file mode 100644 index 0000000..906c1b0 --- /dev/null +++ b/docs/OBJECTIVES.md @@ -0,0 +1,66 @@ +# Objectives + +## Vision + +Phoebus OS is a modern, stable, Gentoo-based workstation operating system that +provides Gentoo-level flexibility, performance and control **without requiring +the user to act as a full-time Gentoo administrator**. + +It combines a mature modern architecture with a conservative update policy and +real recovery: + +``` +Modern architecture + mature implementations ++ conservative updates + snapshots/rollback +``` + +## Pillars + +- **Gentoo + Portage** remain the package foundation. Phoebus is an integration + layer, not a parallel Linux ecosystem. +- **systemd** is the init and service architecture; OpenRC is out of scope. +- **Wayland-first**, with XWayland only for compatibility. +- **PipeWire + WirePlumber** are the audio stack. PulseAudio is not the target. +- **UEFI/GPT-first.** Legacy BIOS is not a v0.1 priority. +- **LUKS2** whole-root encryption with a passphrase (TPM2 later, never + mandatory). +- **Btrfs** with subvolumes, snapshots and (eventually) rollback. +- **Stability over novelty.** Stable/LTS kernels, mature filesystems, no + release candidates, no globally unmasked testing tree. +- **Pragmatic builds.** Compile when it is cheap or genuinely beneficial; use + signed Gentoo binaries when compilation is expensive and the benefit is + negligible. +- **Friendly to proprietary software** (drivers, firmware, codecs, Steam, + browsers) where legally distributable. No moralising warnings; respect + licences. +- **AI-first, never AI-dependent.** The system is fully usable without an LLM. + +## The AI contract + +The LLM is an interface, explainer, planner and reasoning assistant. It is +**not** the source of truth, the root shell, or the privilege boundary. + +``` +user request -> LLM -> typed structured action -> policy engine +-> human-readable preview -> explicit approval -> authentication +-> privileged deterministic broker -> verification -> history +``` + +The model never receives the user's sudo password (authentication happens +through sudo/polkit/PAM outside model context), and it has no code path to +read private files: system access is not home-directory access. + +## Non-goals + +- A custom init system, package manager, audio stack or compositor. +- A giant kernel fork or a large downstream patch set. +- Bleeding-edge/experimental defaults. +- Making the LLM required for installation or normal operation. +- Rebuilding the world on a small release VPS. + +## Definition of a successful distribution + +Phoebus installs a **bootable, encrypted, systemd** system in a disposable UEFI +VM, boots with the installer media removed, unlocks LUKS, reaches a login and +a functional Wayland desktop, and can be maintained without the user becoming +a Gentoo expert. This is verified per `docs/STATUS.md`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..4c36668 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,44 @@ +# Roadmap + +Priority order is deliberate. Do not skip a higher item because a later one is +more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. + +| # | Item | Status | Evidence / notes | +|---|------|--------|------------------| +| 1 | Verify the Bash baseline | Done | `installer/tests/run_tests.sh`, `installer/doc/VM-BOOT-VERIFICATION.md` | +| 2 | Build the Rust architecture | Done | `installer-rs/` workspace, 5 crates | +| 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) | +| 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s | +| 6 | Finish the desktop | Partial | dwl/waybar/mako/swaybg/pipewire verified headless; physical seat + interactive login pending | +| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; no app installed yet | +| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries) | +| 9 | Background update preparation | Partial | `--fetchonly` + `--buildpkgonly` implemented and unit-tested; not VM-tested | +| 10 | Snapshots / rollback | Partial | snapshot create + history done; rollback not implemented | +| 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary; OS sandbox not implemented | +| 12 | `sys` operations | Partial | history, enable/disable service, inspect, install, prepare-updates | +| 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists | +| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; no scheduling/publish/smoke test | +| 15 | Recovery environment | Later | recovery BLS entry generated; full recovery image not built | +| — | Rust TUI | Partial | ratatui UI with plan/ERASE; not yet the default on all paths | +| — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` | + +## Immediate next steps + +1. **Physical-seat desktop**: run `phoebus-session`/dwl on a real VT (or a + `seatd`-backed session) and verify kitty, wofi, XWayland, the polkit agent, + logout and reboot interactively. +2. **Desktop binary strategy**: match the desktop USE set to a signed binhost + (or publish one) so desktop installs stop compiling ~26 minutes of packages. +3. **Snapshots and safe updates end-to-end**: prove `sys` snapshot + + `prepare-updates` on an installed system, then implement and test rollback + before wiring `sys undo`. + +## Later + +- Full recovery environment (network, LUKS, Btrfs, Portage/kernel repair). +- Automated biweekly ISO candidate build with tiered tests and atomic publish. +- AI OS sandbox (systemd sandboxing / namespaces / bubblewrap / Landlock). +- Local model support; richer provider onboarding. +- Optimised kernel profiles with real hardware detection. +- Risk-class update policy (CORE / PROVEN / EDGE) and update preflight. diff --git a/docs/STATUS.md b/docs/STATUS.md new file mode 100644 index 0000000..450d395 --- /dev/null +++ b/docs/STATUS.md @@ -0,0 +1,88 @@ +# Status + +Truthful implementation/verification matrix. Vocabulary: + +- **Implemented** — code exists. +- **Unit tested** — covered by automated tests that run on any host. +- **VM verified** — exercised in the disposable QEMU/OVMF VM. +- **Hardware verified** — exercised on real hardware. +- **Not verified** — do not claim it works. + +## Proven baseline (do not regress) + +A complete installation in a disposable UEFI VM, booted with the ISO detached: + +``` +QEMU + OVMF (UEFI) +30 GiB qcow2, virtio-blk (/dev/vda); live ISO at /dev/sr0 +GPT: 1 GiB FAT32 ESP + LUKS2 remainder +Btrfs: @ @home @var @snapshots @swap +Gentoo systemd stage3 (default/linux/amd64/23.0/systemd) +systemd-boot + BLS entry + dracut initramfs +LUKS2 passphrase unlock at boot +systemd PID 1, login, networking +systemctl is-system-running = running; 0 failed units +``` + +Boot timing (Rust installer): 1.378 s kernel + 5.238 s initrd + 4.114 s +userspace = 10.730 s. + +## Matrix + +| Area | Implemented | Unit tested | VM verified | Hardware verified | +|------|-------------|-------------|-------------|-------------------| +| Config (TOML + legacy), validation | yes | yes | yes | n/a | +| Hardware/disk discovery, protection | yes | yes | yes | no | +| Install plan + destructive preview | yes | yes | yes | n/a | +| Destructive authorization (ERASE) | yes | yes | yes | n/a | +| GPT partitioning + ESP | yes | yes | yes | no | +| LUKS2 format/open/close | yes | yes | yes | no | +| Btrfs subvolumes + swapfile | yes | yes | yes | no | +| fstab / crypttab generation | yes | yes | yes | no | +| stage3 fetch + SHA-256 verify + extract | yes | yes | yes | n/a | +| Portage config + sync + getuto | yes | yes | yes | n/a | +| Signed Gentoo binary install | yes | yes | yes | n/a | +| Source package compilation | yes | yes | yes | n/a | +| Kernel install + dracut initramfs | yes | yes | yes | no | +| systemd-boot + BLS | yes | yes | yes | no | +| Recovery BLS entry (rescue.target) | yes | yes | no | no | +| Users, passwords, sudo | yes | yes | yes | n/a | +| Locale/timezone/keymap/services | yes | yes | yes | n/a | +| Rust VM boot parity | yes | yes | yes | no | +| Rust TUI | yes | yes | smoke test | no | +| Desktop profile (dwl/waybar/mako/swaybg) | yes | partial | headless only | no | +| PipeWire/WirePlumber | yes | no | headless (`wpctl`) | no | +| Flatpak + flathub | yes | no | installed + remote | no | +| XWayland / polkit agent / kitty / wofi | yes | no | installed, not launched | no | +| Package policy + measured history | yes | yes | yes (326 entries) | no | +| Background update preparation | yes | yes | no | no | +| Btrfs snapshots + history | yes | yes | no | no | +| Btrfs rollback | no | no | no | no | +| AI typed proposals | yes | yes | no | n/a | +| AI privacy boundary | yes | yes | no | n/a | +| AI OS sandbox | no | no | no | no | +| `sys` verbs | yes | yes | no | no | +| OpenCode pinned bootstrap | yes | yes | no | n/a | +| Release manifest/verify | yes | yes | no | n/a | +| NVIDIA proprietary | architecture only | no | no | no | +| UKI | no (deferred) | no | no | no | + +## Known limitations + +- **Desktop graphical session** was verified with the *headless* wlroots + backend because the serial-only VM has no logind seat. The DRM path and a + real VT login are not yet exercised. `phoebus-session` is written by the + installer for that purpose. +- **Flatpak apps** were not installed from the remote; only the runtime and + the flathub remote were verified. +- **NVIDIA** is architecturally allowed but not verified on hardware. +- **UKI** is deferred; the dracut UKI generator did not embed the kernel + command line, so BLS is used (and verified). +- **Rollback** is not implemented; snapshots and history are. +- **AI sandbox** is not enforced; only typed actions and the privacy boundary. +- **Release automation** stops at manifest/verify; no scheduler, smoke test, + signing or atomic publish. +- The desktop transaction compiles heavily because desktop USE does not match + the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM). +- The installer rebuilds `sys-apps/systemd` from source because + boot/policykit/cryptsetup USE differ from the binhost.