docs: update references after retiring the Bash installer
Point AGENTS.md, README.md and the docs at the Rust-only toolchain and the moved VM-BOOT-VERIFICATION.md, and drop the Bash installer from DEVELOPMENT.md.
This commit is contained in:
parent
1e5337e7a5
commit
fc64793aec
12 changed files with 80 additions and 55 deletions
|
|
@ -78,8 +78,9 @@ scripts/ git/dev tooling (hooks, publish, agent-commit)
|
|||
|
||||
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.
|
||||
- `docs/FINDINGS.md` — what the reference live environment contains.
|
||||
- `docs/VM-BOOT-VERIFICATION.md` — the proven VM install/boot path.
|
||||
- `docs/BASH-MIGRATION.md` — the evidence-gated retirement of the Bash installer.
|
||||
- `installer-rs/README.md` — Rust workspace details.
|
||||
|
||||
---
|
||||
|
|
@ -165,7 +166,7 @@ correctness, testability and observability are.
|
|||
|
||||
- `git log` — the authoritative change history.
|
||||
- `docs/CHANGELOG.md` — curated, human-readable milestones.
|
||||
- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence per iteration.
|
||||
- `docs/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
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ exact implementation/verification matrix and known limitations.
|
|||
```
|
||||
AGENTS.md entry point for AI/human contributors (read first)
|
||||
docs/ objectives, roadmap, status, architecture, process
|
||||
installer/ proven Bash installer (reference / fallback) + VM harness
|
||||
installer/tests/vm/ disposable UEFI VM harness (static Rust binary)
|
||||
installer-rs/ production Rust installer (crates/ workspace)
|
||||
scripts/ git/dev tooling (hooks, publish, agent-commit)
|
||||
.githooks/ committed git hooks
|
||||
|
|
@ -62,7 +62,7 @@ the user approves; it never holds root or a shell.
|
|||
- `docs/DEVELOPMENT.md` — host setup, build, VM testing.
|
||||
- `docs/CONTRIBUTING.md` — standards and definition of done.
|
||||
- `docs/GIT-WORKFLOW.md` — how to commit, push and release.
|
||||
- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence.
|
||||
- `docs/VM-BOOT-VERIFICATION.md` — boot evidence.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,13 @@
|
|||
# Architecture
|
||||
|
||||
Phoebus currently ships two installer implementations:
|
||||
Phoebus ships one installer implementation: the **Rust** workspace in
|
||||
`installer-rs/`. It reproduces the proven encrypted UEFI VM boot path and is the
|
||||
only implementation on the install path. The retired Bash prototype is kept in
|
||||
git history, tagged `v0.1.0-bash-reference`; see `docs/BASH-MIGRATION.md` for
|
||||
the evidence-gated retirement.
|
||||
|
||||
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.
|
||||
The disposable VM harness lives in `installer/tests/vm/` and drives the static
|
||||
Rust binary.
|
||||
|
||||
## Layering
|
||||
|
||||
|
|
|
|||
|
|
@ -196,7 +196,7 @@ only proven boot path.
|
|||
- [ ] Run the full encrypted UEFI install with the static binary, then boot
|
||||
the disk with the ISO detached and unlock LUKS.
|
||||
- [ ] Record the serial log, boot timing, `systemctl is-system-running`, and
|
||||
the failed-unit count in `installer/doc/VM-BOOT-VERIFICATION.md`.
|
||||
the failed-unit count in `docs/VM-BOOT-VERIFICATION.md`.
|
||||
- [ ] Update `docs/STATUS.md` so the "Rust VM boot parity" row reflects the
|
||||
static-binary harness.
|
||||
|
||||
|
|
@ -329,7 +329,7 @@ exit gate has been run and recorded.
|
|||
| 1 | Close product gaps (opencode) | VERIFIED | `cargo test --workspace`: opencode 7 passed, `cli_coverage` 2 passed, clippy rc 0 (`4071c7d`) |
|
||||
| 2 | VM harness on the Rust binary | VERIFIED | static-binary install `INSTALL-RC=0` + detached boot (systemd PID1, running, 0 failed units, LUKS, login) |
|
||||
| 3 | Retire the tests | VERIFIED | `make test` green; `git grep "run_tests.sh\|ai-installer\|installer/lib"` outside docs/installer returns nothing (`875278b`) |
|
||||
| 4 | Delete the Bash tree | TODO | |
|
||||
| 4 | Delete the Bash tree | VERIFIED | no tracked file references the Bash installer (`git grep` empty); `make test` green (`TBD4`) |
|
||||
| 5 | Developer tooling (optional) | TODO | |
|
||||
|
||||
### Task ledger
|
||||
|
|
@ -350,16 +350,16 @@ exit gate has been run and recorded.
|
|||
| 2.3 | Harness docs updated | VERIFIED | | `installer/tests/vm/README.md`, `run-vm.sh` (`f984b01`) |
|
||||
| 2.4 | VM install with Rust binary | VERIFIED | | serial log: `phoebus-installer 0.1.0`, `===INSTALL-RC=0===`, `NO_SECRET_LEAK`, `===POWEROFF===` (commit `54701bd`) |
|
||||
| 2.5 | VM detached boot | VERIFIED | | `systemd-boot` -> LUKS unlock -> login -> `running`, `0 loaded units listed`, `enp0s2 10.0.2.15/24` (commit `54701bd`) |
|
||||
| 2.6 | Boot evidence recorded | VERIFIED | | `installer/doc/VM-BOOT-VERIFICATION.md` "Official harness on the static binary" (commit `54701bd`) |
|
||||
| 2.6 | Boot evidence recorded | VERIFIED | | `docs/VM-BOOT-VERIFICATION.md` "Official harness on the static binary" (commit `54701bd`) |
|
||||
| 3.1 | Bash-test coverage mapping | VERIFIED | | map below; no Bash test lacks a Rust equivalent (`4c59a1f`) |
|
||||
| 3.2 | Golden plan tests; remove `parity.rs` | VERIFIED | | `cargo test -p phoebus-installer --test plan_golden` -> 3 passed; `parity.rs` deleted (`4c59a1f`) |
|
||||
| 3.3 | CI updated | VERIFIED | | `.forgejo/workflows/ci.yml` -> fmt + clippy + test (`875278b`) |
|
||||
| 3.4 | Pre-commit hook updated | VERIFIED | | Bash-suite block removed; image-size + secret scan kept (`875278b`) |
|
||||
| 3.5 | `Makefile` updated | VERIFIED | | `test: test-rust`; `test-bash` removed (`875278b`) |
|
||||
| 4.1 | Relocate `installer/doc` | TODO | | |
|
||||
| 4.2 | Delete Bash tree | TODO | | |
|
||||
| 4.3 | Update all references | TODO | | |
|
||||
| 4.4 | No dangling references | TODO | | |
|
||||
| 4.1 | Relocate `installer/doc` | VERIFIED | | `FINDINGS.md`, `VM-BOOT-VERIFICATION.md` -> `docs/`; Bash-only `TESTING.md` deleted (`TBD4`) |
|
||||
| 4.2 | Delete Bash tree | VERIFIED | | `installer/{bin,lib,tui,config,tests/*.sh,README.md}` removed; `installer/tests/vm/` kept (`TBD4`) |
|
||||
| 4.3 | Update all references | VERIFIED | | `AGENTS.md`, `README.md`, `docs/{ARCHITECTURE,DEVELOPMENT,CONTRIBUTING,ROADMAP,STATUS,GIT-WORKFLOW}.md` (`TBD4`) |
|
||||
| 4.4 | No dangling references | VERIFIED | | `git grep "installer/bin\|installer/lib\|ai-installer\|run_tests.sh"` -> nothing (`TBD4`) |
|
||||
|
||||
### Recorded gaps (from task 1.5)
|
||||
|
||||
|
|
@ -446,6 +446,6 @@ detail.
|
|||
`--bootstrap-opencode` (`4071c7d`); harness moved to the static binary
|
||||
(`f984b01`); full VM install `INSTALL-RC=0` + detached boot (systemd PID1,
|
||||
`running`, 0 failed units, LUKS, login) recorded in
|
||||
`installer/doc/VM-BOOT-VERIFICATION.md`; golden plan tests replace `parity.rs`
|
||||
`docs/VM-BOOT-VERIFICATION.md`; golden plan tests replace `parity.rs`
|
||||
(`4c59a1f`); CI/hook/Makefile/scripts now gate on Rust only and `git grep` has
|
||||
no dangling Bash reference (`875278b`). No blockers. Phase 4 next.
|
||||
|
|
|
|||
|
|
@ -15,6 +15,32 @@ Format: Keep a Changelog. Dates are UTC.
|
|||
`CHANGELOG.md`, and the top-level `AGENTS.md`.
|
||||
- `.gitignore` covering the ISO, build output, transcripts and secrets.
|
||||
|
||||
## 2026-09-20 — Retire the Bash installer (migration Phases 0–4)
|
||||
|
||||
### Added
|
||||
- `phoebus-executor::opencode`: pinned-manifest parsing, architecture
|
||||
detection, fetch through `Exec`, SHA-256 verification, fail-closed
|
||||
placeholder checks, extraction and config writer (7 unit tests).
|
||||
- `--bootstrap-opencode` on the CLI; `PHOEBUS_OPENCODE_MANIFEST` overrides the
|
||||
embedded manifest for fixture verification.
|
||||
- `cli_coverage` and golden plan tests (`plan_golden.rs`, `tests/golden/`).
|
||||
- `docs/BASH-MIGRATION.md`: the evidence-gated retirement plan and ledger.
|
||||
|
||||
### Changed
|
||||
- The disposable VM harness installs with the static Rust binary; full
|
||||
encrypted install + detached boot re-verified (systemd PID 1, `running`,
|
||||
0 failed units, LUKS, login).
|
||||
- CI, the pre-commit hook, the Makefile and the commit/publish scripts gate on
|
||||
Rust only (`cargo fmt`, `clippy`, `test`).
|
||||
- `installer/doc/VM-BOOT-VERIFICATION.md` and `installer/doc/FINDINGS.md`
|
||||
moved to `docs/`.
|
||||
|
||||
### Removed
|
||||
- The Bash installer tree (entry point, libraries, TUI, configuration, shell
|
||||
test suite and README), retired in favour of `installer-rs/`. The Bash
|
||||
reference remains tagged `v0.1.0-bash-reference`. The disposable VM harness
|
||||
under `installer/tests/vm/` is retained.
|
||||
|
||||
## 2026-09-20 — Rust installer parity, desktop, and foundations
|
||||
|
||||
### Added
|
||||
|
|
|
|||
|
|
@ -24,7 +24,10 @@
|
|||
- Keep unit-testable logic pure and in `phoebus-core`; keep privileged effects
|
||||
in `phoebus-executor` behind `ProcessRunner`.
|
||||
|
||||
## Bash standards (while it remains)
|
||||
## Bash standards (developer tooling only)
|
||||
|
||||
`scripts/`, `.githooks/` and the `Makefile` are Bash host tooling, not the
|
||||
product:
|
||||
|
||||
- `shellcheck -S warning` clean.
|
||||
- Never `local a="$1" b="$a"` (the dynamic-scoping bug class). Use two `local`
|
||||
|
|
@ -35,10 +38,11 @@
|
|||
## Tests
|
||||
|
||||
- Add a regression test for every meaningful bug (see the tests in
|
||||
`installer/tests/` and `installer-rs/crates/*/src`).
|
||||
`installer-rs/crates/*/src`; unit tests live next to the code).
|
||||
- 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.
|
||||
- Destructive/integration testing only in a disposable qcow2 VM
|
||||
(`installer/tests/vm/`).
|
||||
- The Rust suite must pass before a commit.
|
||||
|
||||
## Commit messages
|
||||
|
||||
|
|
|
|||
|
|
@ -6,8 +6,7 @@ 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
|
||||
xorriso mtools dosfstools squashfs-tools cpio zstd python3-pexpect
|
||||
|
||||
# Rust quality gates (names may be versioned; check `apt search rustfmt`)
|
||||
sudo apt install rust-clippy rustfmt
|
||||
|
|
@ -23,19 +22,11 @@ inspection of VM images. `7z`/`p7zip` is useful for reading the reference ISO.
|
|||
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
|
||||
|
||||
The Bash prototype has been retired (see `docs/BASH-MIGRATION.md`); the Rust
|
||||
workspace is the only installer.
|
||||
|
||||
```sh
|
||||
cd installer-rs
|
||||
cargo fmt --all -- --check
|
||||
|
|
@ -65,7 +56,8 @@ Never point the harness at a physical disk. The target is always a qcow2 file.
|
|||
|
||||
```sh
|
||||
cd /path/to/serve
|
||||
tar czf installer.tar.gz -C /path/to/phoebus_os installer # or the Rust binary
|
||||
cp /path/to/phoebus_os/installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer .
|
||||
cp /path/to/phoebus_os/installer/tests/vm/install.sh .
|
||||
python3 -m http.server 8000 --bind 127.0.0.1
|
||||
|
||||
QEMU_BIN=qemu-system-x86_64 \
|
||||
|
|
@ -117,8 +109,8 @@ prerequisites, and `make test`, `make check`, `make build`, `make static`,
|
|||
|
||||
## Continuous integration
|
||||
|
||||
`.forgejo/workflows/ci.yml` mirrors the local gates (Bash suite, shellcheck,
|
||||
Rust suite). It runs only once a Forgejo Actions runner is registered for the
|
||||
`.forgejo/workflows/ci.yml` mirrors the local gates (`cargo fmt`, `cargo clippy`,
|
||||
`cargo test`). It runs only once a Forgejo Actions runner is registered for the
|
||||
repository; see Forgejo's documentation for `act_runner`. Until then, run
|
||||
`make test` before pushing.
|
||||
|
||||
|
|
@ -134,9 +126,7 @@ Restore with `git clone /path/to/phoebus-<stamp>.bundle phoebus_os`.
|
|||
|
||||
## 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`).
|
||||
1. `make test` (`cd installer-rs && cargo test --workspace`)
|
||||
2. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets`
|
||||
3. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes.
|
||||
4. Commit (see `docs/GIT-WORKFLOW.md`).
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
## 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.
|
||||
Tracked: source (`installer/tests/vm/`, `installer-rs/crates/`, `scripts/`,
|
||||
`.githooks/`), `Cargo.toml`/`Cargo.lock`, documentation (`docs/`, `AGENTS.md`,
|
||||
`README.md`, `installer-rs/README.md`) and tests (`installer-rs/**/tests/`).
|
||||
|
||||
Ignored (see `.gitignore`): the reference ISO and other images, `installer-rs/target/`,
|
||||
`__pycache__`, `.agent-shell/` transcripts, and any secret material
|
||||
|
|
|
|||
|
|
@ -3,10 +3,11 @@
|
|||
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.
|
||||
|
||||
- **Last updated:** commit `e680084` (2026-09-20)
|
||||
- **Current focus:** repository/context setup and git workflow.
|
||||
- **Last verified:** Rust installer full encrypted UEFI VM boot with the ISO
|
||||
detached (`installer/doc/VM-BOOT-VERIFICATION.md`); desktop stack and Flatpak
|
||||
- **Last updated:** commit `TBD4` (2026-09-20)
|
||||
- **Current focus:** the Bash installer is retired (migration Phases 0–4, see
|
||||
`docs/BASH-MIGRATION.md`); `installer-rs/` is the only installer.
|
||||
- **Last verified:** static Rust binary, full encrypted UEFI VM install +
|
||||
detached boot (`docs/VM-BOOT-VERIFICATION.md`); desktop stack and Flatpak
|
||||
verified headless.
|
||||
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
|
||||
(remote `origin`, SSH port 2222).
|
||||
|
|
@ -33,6 +34,8 @@ commit it. It should be short and current; use `git log` for detail.
|
|||
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy installed.
|
||||
- Reference ISO is `livegui-amd64-20260913T163055Z.iso` (gitignored).
|
||||
- Forgejo token for API tasks: `~/.config/phoebus/forgejo.token` (0600).
|
||||
- The VM harness disks are disposable qcow2 files on `/` (not `/tmp`, which is
|
||||
a small tmpfs on the dev host); never point `DISK` at `/dev/*`.
|
||||
|
||||
## Definition of a good stopping point
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ 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` |
|
||||
| 1 | Verify the Bash baseline | Done (retired) | tagged `v0.1.0-bash-reference`; retired with evidence in `docs/BASH-MIGRATION.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) |
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ userspace = 10.730 s.
|
|||
The committed VM harness (`installer/tests/vm/serial-driver.py` +
|
||||
`install.sh`) drives the **static Rust binary**; the Bash installer is no longer
|
||||
on the install path (Bash migration Phase 2, see
|
||||
`installer/doc/VM-BOOT-VERIFICATION.md`).
|
||||
`docs/VM-BOOT-VERIFICATION.md`).
|
||||
|
||||
## Matrix
|
||||
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ else
|
|||
fi
|
||||
|
||||
line "last VM verification evidence"
|
||||
git log -1 --format='%h %ad %s' --date=short -- installer/doc/VM-BOOT-VERIFICATION.md 2>/dev/null \
|
||||
git log -1 --format='%h %ad %s' --date=short -- docs/VM-BOOT-VERIFICATION.md 2>/dev/null \
|
||||
|| echo "(none)"
|
||||
|
||||
line "open markers (TODO/FIXME/XXX)"
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue