feat(git): add session context, host doctor, ADRs and git hygiene
Some checks are pending
ci / test (push) Waiting to run
Some checks are pending
ci / test (push) Waiting to run
Adds scripts/context.sh + 'make context' (one-screen session briefing), scripts/doctor.sh + 'make doctor' (host prerequisites), docs/HANDOFF.md (rolling cross-session note), docs/adr/ (BLS, desktop profile, keyring, Rust), .githooks/commit-msg (Conventional Commits), .gitattributes, scripts/backup-git.sh + 'make backup', and a Forgejo Actions CI workflow. Updates AGENTS.md reading order/work loop and DEVELOPMENT.md.
This commit is contained in:
parent
e680084f83
commit
83368f774c
15 changed files with 489 additions and 17 deletions
36
.forgejo/workflows/ci.yml
Normal file
36
.forgejo/workflows/ci.yml
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Forgejo Actions CI. Runs only once an Actions runner is registered with this
|
||||
# label (see docs/DEVELOPMENT.md). It mirrors the local quality gates.
|
||||
#
|
||||
# If your runner uses different labels, change `runs-on` accordingly.
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Bash test suite
|
||||
run: bash installer/tests/run_tests.sh
|
||||
|
||||
- name: shellcheck
|
||||
run: |
|
||||
if command -v shellcheck >/dev/null 2>&1; then
|
||||
shellcheck -S warning installer/bin/ai-installer \
|
||||
installer/lib/*.sh installer/tui/*.sh
|
||||
else
|
||||
echo "shellcheck not installed on this runner; skipping"
|
||||
fi
|
||||
|
||||
- name: Rust test suite
|
||||
run: |
|
||||
if command -v cargo >/dev/null 2>&1; then
|
||||
cd installer-rs && cargo test --workspace
|
||||
else
|
||||
echo "cargo not installed on this runner; skipping"
|
||||
fi
|
||||
19
.gitattributes
vendored
Normal file
19
.gitattributes
vendored
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# Normalize line endings; never let git mangle binary or generated files.
|
||||
* text=auto eol=lf
|
||||
|
||||
*.iso binary -diff
|
||||
*.qcow2 binary -diff
|
||||
*.img binary -diff
|
||||
*.fd binary -diff
|
||||
*.png binary
|
||||
*.jpg binary
|
||||
|
||||
# Keep generated lockfile out of diffs and language stats.
|
||||
Cargo.lock linguist-generated=true -diff
|
||||
|
||||
# Help repository language detection.
|
||||
installer/** linguist-language=Shell
|
||||
installer-rs/** linguist-language=Rust
|
||||
scripts/** linguist-language=Shell
|
||||
.githooks/** linguist-language=Shell
|
||||
docs/** linguist-documentation=true
|
||||
42
.githooks/commit-msg
Executable file
42
.githooks/commit-msg
Executable file
|
|
@ -0,0 +1,42 @@
|
|||
#!/usr/bin/env bash
|
||||
# Enforce Conventional Commit subjects so the history is machine-readable.
|
||||
#
|
||||
# Bypass with: git commit --no-verify or SKIP_PHOEBUS_HOOKS=1 git commit ...
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
[[ "${SKIP_PHOEBUS_HOOKS:-0}" == "1" ]] && exit 0
|
||||
|
||||
msg_file="${1:?commit message file}"
|
||||
subject="$(grep -v '^#' "$msg_file" | sed '/^[[:space:]]*$/d' | head -n 1)"
|
||||
|
||||
if [[ -z "$subject" ]]; then
|
||||
echo "commit-msg: empty commit message" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Permit generated/merge/revert subjects.
|
||||
case "$subject" in
|
||||
Merge\ *|Revert\ *|fixup!\ *|squash!\ *) exit 0 ;;
|
||||
esac
|
||||
|
||||
if ! [[ "$subject" =~ ^(feat|fix|refactor|perf|test|docs|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?:\ .+ ]]; then
|
||||
cat >&2 <<'EOF'
|
||||
commit-msg: subject must be a Conventional Commit, e.g.
|
||||
|
||||
feat(rust): add typed SystemAction broker
|
||||
fix(executor): make the getuto keyring readable by the verify user
|
||||
docs(git): record the Forgejo remote and clone/setup steps
|
||||
|
||||
Types: feat fix refactor perf test docs build ci chore revert
|
||||
Bypass with: git commit --no-verify
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if (( ${#subject} > 72 )); then
|
||||
echo "commit-msg: subject is ${#subject} chars; keep it <= 72" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
exit 0
|
||||
32
AGENTS.md
32
AGENTS.md
|
|
@ -14,16 +14,21 @@ 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:
|
||||
Fastest start: run `make context` (prints repository state, the roadmap's
|
||||
immediate next steps, the rolling handoff and open markers).
|
||||
|
||||
Then read, 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.
|
||||
3. `docs/HANDOFF.md` — where the last session stopped and the next actions.
|
||||
4. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified.
|
||||
5. `docs/ARCHITECTURE.md` — components and how they fit together.
|
||||
6. `docs/adr/` — why significant decisions were made (BLS, profile, ...).
|
||||
7. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow.
|
||||
8. `docs/CONTRIBUTING.md` — code standards and definition of done.
|
||||
9. `docs/GIT-WORKFLOW.md` — how changes are committed and published.
|
||||
10. `git log --oneline -30` and the top of `docs/CHANGELOG.md` — recent history.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -87,18 +92,19 @@ Authoritative design records:
|
|||
|
||||
## 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.
|
||||
1. Read this file and the reading order in §1; run `make context`.
|
||||
2. Run `make doctor` before VM work, and inspect `docs/ROADMAP.md` for the
|
||||
highest-priority unfinished item.
|
||||
3. Inspect `git log --oneline -20`, `docs/CHANGELOG.md` and `docs/HANDOFF.md`.
|
||||
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.
|
||||
8. Update `docs/CHANGELOG.md`, `docs/STATUS.md` and `docs/HANDOFF.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.
|
||||
push (`scripts/publish.sh` or `make publish`).
|
||||
|
||||
Do the actual work; do not stop at a design document. Do not ask for guidance
|
||||
when the next engineering step is clear.
|
||||
|
|
|
|||
14
Makefile
14
Makefile
|
|
@ -8,10 +8,12 @@
|
|||
|
||||
SHELL := /bin/bash
|
||||
|
||||
.PHONY: help test test-bash test-rust fmt fmt-check clippy check build static vm hooks commit publish forgejo-init public private release clean
|
||||
.PHONY: help context doctor test test-bash test-rust fmt fmt-check clippy check build static vm hooks commit publish backup forgejo-init public private release clean
|
||||
|
||||
help:
|
||||
@printf 'Phoebus OS targets:\n'
|
||||
@printf ' make context session briefing (state, roadmap, handoff)\n'
|
||||
@printf ' make doctor check host prerequisites\n'
|
||||
@printf ' make test run Bash + Rust test suites\n'
|
||||
@printf ' make test-bash fast Bash suite only\n'
|
||||
@printf ' make test-rust cargo test --workspace\n'
|
||||
|
|
@ -25,6 +27,13 @@ help:
|
|||
@printf ' make forgejo-init store the API token and make the repo public\n'
|
||||
@printf ' make public make the Forgejo repository public\n'
|
||||
@printf ' make release TAG=v0.2.0 create a Forgejo release\n'
|
||||
@printf ' make backup bundle the whole repo (all refs)\n'
|
||||
|
||||
context:
|
||||
scripts/context.sh
|
||||
|
||||
doctor:
|
||||
scripts/doctor.sh
|
||||
|
||||
test: test-bash test-rust
|
||||
|
||||
|
|
@ -62,6 +71,9 @@ commit:
|
|||
publish:
|
||||
scripts/publish.sh
|
||||
|
||||
backup:
|
||||
scripts/backup-git.sh
|
||||
|
||||
forgejo-init:
|
||||
scripts/forgejo.sh init
|
||||
|
||||
|
|
|
|||
|
|
@ -109,9 +109,28 @@ unsquashfs -d /tmp/root image.squashfs etc/portage/make.conf
|
|||
|
||||
## Make targets
|
||||
|
||||
`make help` lists the common tasks. `make test`, `make check`, `make build`,
|
||||
`make static`, `make hooks`, `make commit MSG="..."` and `make publish` wrap the
|
||||
commands above and the git workflow.
|
||||
`make help` lists the common tasks. `make context` prints a session briefing
|
||||
(state, roadmap next steps, handoff), `make doctor` checks the host
|
||||
prerequisites, and `make test`, `make check`, `make build`, `make static`,
|
||||
`make hooks`, `make commit MSG="..."`, `make publish`, `make backup`,
|
||||
`make forgejo-init`, `make public` and `make release TAG=...` wrap the rest.
|
||||
|
||||
## 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
|
||||
repository; see Forgejo's documentation for `act_runner`. Until then, run
|
||||
`make test` before pushing.
|
||||
|
||||
## Backups
|
||||
|
||||
The only remotes are self-hosted, so keep off-box copies:
|
||||
|
||||
```sh
|
||||
make backup # writes ~/backups/phoebus/phoebus-<stamp>.bundle
|
||||
```
|
||||
|
||||
Restore with `git clone /path/to/phoebus-<stamp>.bundle phoebus_os`.
|
||||
|
||||
## Quality gates before commit
|
||||
|
||||
|
|
|
|||
41
docs/HANDOFF.md
Normal file
41
docs/HANDOFF.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Handoff
|
||||
|
||||
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
|
||||
verified headless.
|
||||
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
|
||||
(remote `origin`, SSH port 2222).
|
||||
|
||||
## Next actions (in order)
|
||||
|
||||
1. **Physical-seat desktop**: run `phoebus-session`/dwl on a real VT and verify
|
||||
kitty, wofi, XWayland, the polkit agent, logout and reboot interactively.
|
||||
2. **Desktop binary strategy**: match desktop USE to a signed binhost (or
|
||||
publish one) to stop compiling ~26 minutes of desktop packages.
|
||||
3. **Snapshots + safe updates end-to-end**: prove `sys` snapshot and
|
||||
`prepare-updates` on an installed system, then implement and test rollback
|
||||
before wiring `sys undo`.
|
||||
|
||||
## Known blockers / risks
|
||||
|
||||
- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml`
|
||||
only runs once one is registered.
|
||||
- Desktop graphical login has not been exercised with a real logind seat.
|
||||
- NVIDIA is not verified on hardware.
|
||||
|
||||
## Environment notes
|
||||
|
||||
- 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).
|
||||
|
||||
## Definition of a good stopping point
|
||||
|
||||
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
|
||||
`docs/HANDOFF.md` updated; committed and pushed
|
||||
(`scripts/agent-commit.sh` + `scripts/publish.sh`).
|
||||
29
docs/adr/0001-rust-installer.md
Normal file
29
docs/adr/0001-rust-installer.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# ADR 0001: Rust installer as production; Bash retained as reference
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-09-20
|
||||
|
||||
## Context
|
||||
|
||||
System software that partitions disks, formats LUKS2, installs Portage and
|
||||
writes bootloaders should not permanently live in several thousand lines of
|
||||
privileged, dynamically scoped shell. The Bash prototype proved the full path
|
||||
in a VM and exposed the exact failure modes (subvolume ordering, fstab timing,
|
||||
host-versus-target writes, secret handling).
|
||||
|
||||
## Decision
|
||||
|
||||
Move the production installer/backend to Rust (`installer-rs/`) with strong
|
||||
types, structured errors, a central command layer, a `TargetRoot` abstraction
|
||||
and a `DestructiveAuthorization` token. Keep the Bash installer (`installer/`)
|
||||
as the executable reference and fallback until hardware-level desktop
|
||||
verification exists; then retire or archive it.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Host/target path bugs and word-splitting are eliminated by construction.
|
||||
- Privileged logic is unit-testable with a fake `ProcessRunner`.
|
||||
- Two implementations must be kept in step during the migration (a plan-parity
|
||||
test compares them).
|
||||
- The Rust installer must reproduce the proven VM boot before becoming primary
|
||||
(it now does).
|
||||
25
docs/adr/0002-bls-over-uki.md
Normal file
25
docs/adr/0002-bls-over-uki.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# ADR 0002: BLS entries instead of UKI for the boot path
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-09-20
|
||||
|
||||
## Context
|
||||
|
||||
UKIs are desirable, but the available dracut UKI generator produced a UKI that
|
||||
did **not** embed `/etc/kernel/cmdline`; the image booted with no `root=` and
|
||||
fell into an initramfs emergency shell. Boot reliability is a defining value.
|
||||
|
||||
## Decision
|
||||
|
||||
Use `layout=bls`: installkernel places the kernel and dracut initramfs on the
|
||||
ESP and creates Boot Loader Specification entries whose `options` carry the
|
||||
kernel command line. Defer UKI until a generator that embeds the command line
|
||||
is proven in the VM.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The proven path boots reliably with systemd-boot and BLS.
|
||||
- UKI/Secure Boot remain future work; do not switch the default to UKI without
|
||||
a VM boot test.
|
||||
- `uki_generator=none` is required in `/etc/kernel/install.conf` because
|
||||
installkernel always expects a `uki_generator` key.
|
||||
27
docs/adr/0003-desktop-systemd-profile.md
Normal file
27
docs/adr/0003-desktop-systemd-profile.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# ADR 0003: Desktop installs inherit the Gentoo desktop/systemd profile
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-09-20
|
||||
|
||||
## Context
|
||||
|
||||
Reconstructing Wayland/X/dbus/policykit USE flags by hand on top of the minimal
|
||||
systemd profile produced REQUIRED_USE conflicts (`cairo[X]`, `libglvnd[X]`,
|
||||
`libxkbcommon[X]`) and a circular dependency through Sphinx/Pillow documentation
|
||||
(`pillow[truetype]` vs `harfbuzz[introspection]`).
|
||||
|
||||
## Decision
|
||||
|
||||
A desktop install selects the supported stable Gentoo profile
|
||||
`default/linux/amd64/23.0/desktop/systemd`, and the minimal
|
||||
`default/linux/amd64/23.0/systemd` is used only for core/server installs. An
|
||||
explicit non-default profile always wins. Base storage tools disable the `man`
|
||||
docs (`sys-fs/{btrfs-progs,cryptsetup} -man`) to avoid the documentation chain.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The transaction resolves and installs; desktop packages compile heavily
|
||||
because desktop USE does not match the signed binhost (a future optimization).
|
||||
- Phoebus stays a thin layer over Gentoo profiles rather than carrying its own
|
||||
USE reconstruction.
|
||||
- An explicit non-default profile always wins.
|
||||
25
docs/adr/0004-portage-verify-keyring.md
Normal file
25
docs/adr/0004-portage-verify-keyring.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# ADR 0004: Relax the getuto keyring for the dropped-privilege verifier
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-09-20
|
||||
|
||||
## Context
|
||||
|
||||
Portage verifies signed binary packages as `GPG_VERIFY_USER_DROP` (default
|
||||
`nobody`), but `getuto` leaves `pubring.kbx` mode 0600 and the keyring
|
||||
directory non-writable. Verification therefore failed with `NO_PUBKEY` /
|
||||
"can't create random_seed: Permission denied".
|
||||
|
||||
## Decision
|
||||
|
||||
Keep signature verification **enabled**. Make the *public* key material
|
||||
world-readable and the keyring directory group-writable for the verify user,
|
||||
and add `no-random-seed-file` to `gpg.conf`. `pass` and the private key
|
||||
directories stay 0600/0700.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Signed Gentoo binaries verify without disabling or weakening signature
|
||||
checking (which the project forbids).
|
||||
- Public keys are, by definition, not secret; private keys are untouched.
|
||||
- Implemented by `portage::relax_verify_keyring` with a regression test.
|
||||
14
docs/adr/README.md
Normal file
14
docs/adr/README.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
# Architecture Decision Records
|
||||
|
||||
Short records of significant decisions, so a new session understands *why*
|
||||
rather than only *what*. Add a new numbered file for each meaningful decision
|
||||
and link it here.
|
||||
|
||||
| ADR | Title | Status |
|
||||
|-----|-------|--------|
|
||||
| [0001](0001-rust-installer.md) | Rust installer as production; Bash retained as reference | Accepted |
|
||||
| [0002](0002-bls-over-uki.md) | BLS entries instead of UKI for the boot path | Accepted |
|
||||
| [0003](0003-desktop-systemd-profile.md) | Desktop installs inherit the Gentoo desktop/systemd profile | Accepted |
|
||||
| [0004](0004-portage-verify-keyring.md) | Relax the getuto keyring for the dropped-privilege verifier | Accepted |
|
||||
|
||||
Format: Context / Decision / Consequences / Status.
|
||||
31
scripts/backup-git.sh
Executable file
31
scripts/backup-git.sh
Executable file
|
|
@ -0,0 +1,31 @@
|
|||
#!/usr/bin/env bash
|
||||
# Make a self-contained bundle of the whole repository (all branches and tags).
|
||||
#
|
||||
# Useful because the only remote is a single VPS. Store bundles off-box.
|
||||
#
|
||||
# scripts/backup-git.sh [DEST_DIR] (default ~/backups/phoebus)
|
||||
#
|
||||
# Keeps the 10 newest bundles. Restore with:
|
||||
# git clone /path/to/phoebus-<stamp>.bundle phoebus_os
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
root="$(git rev-parse --show-toplevel)"
|
||||
cd "$root"
|
||||
|
||||
dest="${1:-$HOME/backups/phoebus}"
|
||||
mkdir -p "$dest"
|
||||
|
||||
stamp="$(date -u +%Y%m%dT%H%M%SZ)"
|
||||
bundle="$dest/phoebus-${stamp}.bundle"
|
||||
|
||||
git bundle create "$bundle" --all >/dev/null
|
||||
git bundle verify "$bundle" >/dev/null
|
||||
|
||||
printf 'bundle: %s (%s)\n' "$bundle" "$(du -h "$bundle" | cut -f1)"
|
||||
|
||||
# Retain the 10 most recent bundles.
|
||||
mapfile -t old < <(ls -1t "$dest"/phoebus-*.bundle 2>/dev/null | tail -n +11)
|
||||
((${#old[@]})) && rm -f "${old[@]}"
|
||||
|
||||
exit 0
|
||||
69
scripts/context.sh
Executable file
69
scripts/context.sh
Executable file
|
|
@ -0,0 +1,69 @@
|
|||
#!/usr/bin/env bash
|
||||
# Print a one-screen briefing for a new work session.
|
||||
#
|
||||
# scripts/context.sh (or: make context)
|
||||
#
|
||||
# Intended to be the first command run in a fresh session: it gathers the
|
||||
# repository state, the roadmap's immediate next steps, the rolling handoff and
|
||||
# any open markers, so an agent does not have to rediscover them.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
|
||||
echo "not inside a git repository" >&2
|
||||
exit 1
|
||||
}
|
||||
cd "$root"
|
||||
|
||||
line() { printf '\n===== %s =====\n' "$1"; }
|
||||
|
||||
printf 'Phoebus OS session briefing %s\n' "$(date -u '+%Y-%m-%d %H:%M UTC')"
|
||||
|
||||
line "repository"
|
||||
printf 'branch : %s\n' "$(git rev-parse --abbrev-ref HEAD)"
|
||||
printf 'head : %s\n' "$(git log -1 --format='%h %s (%ad)' --date=short)"
|
||||
printf 'describe: %s\n' "$(git describe --tags --always 2>/dev/null || echo none)"
|
||||
if upstream="$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)"; then
|
||||
ahead_behind="$(git rev-list --left-right --count "$upstream"...HEAD 2>/dev/null)"
|
||||
printf 'tracking: %s (behind/ahead: %s)\n' "$upstream" "${ahead_behind:-?}"
|
||||
fi
|
||||
status="$(git status --porcelain)"
|
||||
if [[ -z "$status" ]]; then
|
||||
printf 'tree : clean\n'
|
||||
else
|
||||
printf 'tree : %s changed path(s)\n' "$(wc -l <<<"$status")"
|
||||
sed 's/^/ /' <<<"$status" | head -n 12
|
||||
fi
|
||||
|
||||
line "recent commits"
|
||||
git log --oneline -10
|
||||
|
||||
line "roadmap: immediate next steps"
|
||||
if [[ -r docs/ROADMAP.md ]]; then
|
||||
awk '/^## Immediate next steps/{f=1;next} /^## /{f=0} f' docs/ROADMAP.md
|
||||
else
|
||||
echo "(docs/ROADMAP.md missing)"
|
||||
fi
|
||||
|
||||
line "handoff (docs/HANDOFF.md)"
|
||||
if [[ -r docs/HANDOFF.md ]]; then
|
||||
cat docs/HANDOFF.md
|
||||
else
|
||||
echo "(docs/HANDOFF.md missing)"
|
||||
fi
|
||||
|
||||
line "last VM verification evidence"
|
||||
git log -1 --format='%h %ad %s' --date=short -- installer/doc/VM-BOOT-VERIFICATION.md 2>/dev/null \
|
||||
|| echo "(none)"
|
||||
|
||||
line "open markers (TODO/FIXME/XXX)"
|
||||
grep -rInE 'TODO|FIXME|XXX' installer installer-rs/crates docs 2>/dev/null \
|
||||
| grep -v 'installer-rs/target' | head -n 20 || echo "(none)"
|
||||
|
||||
line "next"
|
||||
cat <<'EOF'
|
||||
- Read AGENTS.md if you have not, then docs/OBJECTIVES.md and docs/ROADMAP.md.
|
||||
- Run `scripts/doctor.sh` before VM work and `make test` before committing.
|
||||
- Update docs/HANDOFF.md and docs/CHANGELOG.md, then `scripts/agent-commit.sh`
|
||||
and `scripts/publish.sh`.
|
||||
EOF
|
||||
77
scripts/doctor.sh
Executable file
77
scripts/doctor.sh
Executable file
|
|
@ -0,0 +1,77 @@
|
|||
#!/usr/bin/env bash
|
||||
# Check that this machine can build, test and VM-test Phoebus.
|
||||
#
|
||||
# Exit status is advisory: 0 if the essentials are present, 1 otherwise.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ok=0; warn=0; fail=0
|
||||
result() { # result STATUS name detail
|
||||
case "$1" in
|
||||
OK) printf ' [ok] %-28s %s\n' "$2" "$3"; ok=$((ok+1)) ;;
|
||||
WARN) printf ' [warn] %-28s %s\n' "$2" "$3"; warn=$((warn+1)) ;;
|
||||
FAIL) printf ' [FAIL] %-28s %s\n' "$2" "$3"; fail=$((fail+1)) ;;
|
||||
esac
|
||||
}
|
||||
|
||||
have() { command -v "$1" >/dev/null 2>&1; }
|
||||
|
||||
echo "Phoebus host doctor"
|
||||
echo "==================="
|
||||
|
||||
# Essentials for any work.
|
||||
for c in git bash make; do
|
||||
if have "$c"; then result OK "$c" "$(command -v "$c")"; else result FAIL "$c" "not found"; fi
|
||||
done
|
||||
|
||||
# Bash reference tooling.
|
||||
if have shellcheck; then result OK shellcheck "$(shellcheck --version | awk '/version:/{print $2}')"; else result WARN shellcheck "install for lint"; fi
|
||||
if have dialog; then result OK dialog present; else result WARN dialog "only whiptail available"; fi
|
||||
|
||||
# Rust workspace.
|
||||
if have cargo; then
|
||||
result OK cargo "$(cargo --version | awk '{print $2}')"
|
||||
if cargo fmt --version >/dev/null 2>&1; then result OK rustfmt present; else result FAIL rustfmt "cargo fmt unavailable"; fi
|
||||
if cargo clippy --version >/dev/null 2>&1; then result OK clippy present; else result FAIL clippy "cargo clippy unavailable"; fi
|
||||
else
|
||||
result FAIL cargo "not found"
|
||||
fi
|
||||
|
||||
# VM tooling.
|
||||
for c in qemu-system-x86_64 qemu-img; do
|
||||
if have "$c"; then result OK "$c" present; else result FAIL "$c" "install qemu for VM tests"; fi
|
||||
done
|
||||
ovmf=""
|
||||
for f in /usr/share/OVMF/OVMF_CODE_4M.fd /usr/share/OVMF/OVMF_CODE.fd /usr/share/edk2/x64/OVMF_CODE.fd; do
|
||||
[[ -r "$f" ]] && { ovmf="$f"; break; }
|
||||
done
|
||||
if [[ -n "$ovmf" ]]; then result OK OVMF "$ovmf"; else result FAIL OVMF "install ovmf-generic"; fi
|
||||
if [[ -r /dev/kvm ]]; then result OK /dev/kvm "hardware acceleration"; else result WARN /dev/kvm "KVM unavailable; VM will be slow"; fi
|
||||
|
||||
# ISO / image tooling.
|
||||
for c in xorriso 7z unsquashfs cpio zstd; do
|
||||
if have "$c"; then result OK "$c" present; else result WARN "$c" "optional"; fi
|
||||
done
|
||||
|
||||
# Python VM driver.
|
||||
if have python3 && python3 -c 'import pexpect' >/dev/null 2>&1; then
|
||||
result OK pexpect "python3 pexpect available"
|
||||
else
|
||||
result FAIL pexpect "install python3-pexpect"
|
||||
fi
|
||||
|
||||
# Reference ISO (not required for unit tests).
|
||||
iso="$(find "$(git rev-parse --show-toplevel)" -maxdepth 1 -name 'livegui-*.iso' -print -quit 2>/dev/null || true)"
|
||||
if [[ -n "$iso" ]]; then result OK reference-iso "$(basename "$iso")"; else result WARN reference-iso "not found in repo root"; fi
|
||||
|
||||
# Disk space for qcow2 targets.
|
||||
avail="$(df -Pk /tmp 2>/dev/null | awk 'NR==2{print $4}')"
|
||||
if [[ -n "$avail" && "$avail" -gt 20000000 ]]; then
|
||||
result OK disk-space "$(( avail / 1024 / 1024 )) GiB free in /tmp"
|
||||
elif [[ -n "$avail" ]]; then
|
||||
result WARN disk-space "$(( avail / 1024 / 1024 )) GiB free in /tmp (want >=20 GiB)"
|
||||
fi
|
||||
|
||||
echo
|
||||
printf 'summary: %d ok, %d warnings, %d failures\n' "$ok" "$warn" "$fail"
|
||||
(( fail == 0 ))
|
||||
Loading…
Add table
Reference in a new issue