104 lines
5.5 KiB
Markdown
104 lines
5.5 KiB
Markdown
# Hydra OS terminal experience implementation plan
|
|
|
|
> **For agentic workers:** Use superpowers:subagent-driven-development. Tasks
|
|
> are implemented in the shared feature worktree with disjoint owned files,
|
|
> then reviewed and integrated before publication.
|
|
|
|
**Goal:** Download and open VMs through a concise terminal workflow and ship
|
|
consistent Hydra OS branding with Fastfetch.
|
|
|
|
**Architecture:** Retain Runtime as the VM lifecycle authority. Add a safe ISO
|
|
download module and explicit launch orchestration. Replace recovery's JSON
|
|
prompt with a terminal menu and use the existing session-refresh boundary to
|
|
focus a selected workspace without changing QEMU lifetimes.
|
|
|
|
**Tech stack:** Python standard library, existing labwc/Foot/SPICE, Gentoo,
|
|
Fastfetch. No GUI toolkit or host NixOS changes.
|
|
|
|
**Spec:** `docs/superpowers/specs/2026-10-13-terminal-ux-design.md`
|
|
|
|
## Global constraints
|
|
|
|
- Visible product name is **Hydra OS**; preserve technical identifiers and data.
|
|
- No NixOS configuration changes, user-disk replacement or guest input injection.
|
|
- Opening a selected stopped VM is explicit; menu display never starts all VMs.
|
|
- Existing CLI output and runtime ownership guarantees remain compatible.
|
|
- Downloads publish only verified complete ISO files; SHA-256 is optional.
|
|
- New launch preflight reserves 768 MiB of available RAM for the Hydra host.
|
|
|
|
## Review focus
|
|
|
|
- Concurrent downloads or interruption must not publish partial ISO files (T1).
|
|
- Existing names/disks and unknown VM identities must not be replaced (T1).
|
|
- Selecting a second VM must focus it and preserve other QEMU processes (T2).
|
|
- Invalid profiles, missing ISO, absent network tools must leave a usable menu (T2).
|
|
- Branding must not invalidate existing IDs or rewrite historical evidence (T3).
|
|
|
|
## Task 1: Download and explicit launch commands
|
|
|
|
Owned: `hydra/media.py`, `hydra/launch.py`, `hydra/cli.py`,
|
|
`tests/test_media.py`, `tests/test_launch.py`, relevant new CLI tests.
|
|
|
|
Interfaces:
|
|
- `media.download_iso(url, *, sha256=None, cache=None, progress=None) -> Path`.
|
|
`progress(received_bytes, total_bytes_or_none)` is optional.
|
|
- `launch.open_vm(runtime, name, *, windowed=False, no_view=False,
|
|
manifest=None) -> int`. For a session manifest call
|
|
`session.request_refresh(manifest, selected=name)` after successful launch;
|
|
outside a session use existing `session.view`. No GUI check for `no_view`.
|
|
- CLI: `open NAME`, `run SOURCE --name NAME`, `download URL`; plain `hydra`
|
|
and `hydra menu` call `menu.run_menu(runtime, manifest=...)` lazily.
|
|
- Manifest defaults from `HYDRA_SESSION_MANIFEST` when valid; launch errors
|
|
remain actionable and never silently restart an unknown/foreign VM.
|
|
|
|
- [x] Write and observe failing tests using a local HTTP fixture (ISO, HTML,
|
|
truncation, checksum, cancellation, cache reuse, collision).
|
|
- [x] Implement downloader and explicit open/run commands, preserve existing CLI.
|
|
- [x] Test no accidental overwrite/start, headless operation, RAM preflight and
|
|
view-only reconnection. Run scoped tests and commit only owned files.
|
|
|
|
## Task 2: Terminal menu and focused session handoff
|
|
|
|
Owned: `hydra/menu.py`, `hydra/session.py`, `tests/test_menu.py`,
|
|
`tests/test_session.py`, relevant `dev/session-refresh-smoke.py` extensions.
|
|
|
|
Interfaces:
|
|
- `menu.run_menu(runtime, *, manifest=None) -> int`: clear readable menu,
|
|
numbers/names/Enter, persistent last selection, old colon commands, controlled
|
|
guided `run`/`download`, network and shell actions. Use Task 1's launch API.
|
|
- `session.request_refresh(manifest: Path, *, selected=None) -> int`: backwards
|
|
compatible empty refresh requests, optional validated selected VM name.
|
|
- Session env carries `HYDRA_SESSION_MANIFEST`; next compositor starts on the
|
|
requested configured VM. Recovery delegates to menu; automatic clients remain
|
|
view-only. Errors stay in menu, and operations use fresh runtime profiles.
|
|
|
|
- [x] Write failing menu/refresh tests for stopped/running selection, unknown
|
|
identity, names such as s/q, empty/invalid profiles and second-workspace focus.
|
|
- [x] Implement terminal flow, visible command previews and recovery fallback.
|
|
- [x] Run scoped tests plus an isolated session probe where feasible; commit
|
|
owned files. Existing reserved chords and VM independence remain intact.
|
|
|
|
## Task 3: Hydra OS branding and Fastfetch
|
|
|
|
Owned: `image/packages`, `image/rootfs` (Fastfetch config/logo/motd only),
|
|
`hydra/image.py`, `image/grub.cfg`, `session` metadata, new branding tests.
|
|
Coordinate session/CLI visible names with their owners; do not edit their files.
|
|
|
|
- [x] Confirm Fastfetch's Gentoo atom, supported logo/config format and search path.
|
|
- [x] Add original terminal logo and restrained summary configuration; retain
|
|
technical IDs while updating visible OS/boot/session labels.
|
|
- [x] Verify config with actual Fastfetch in a temporary/container environment,
|
|
preview logo, and test resulting image metadata. Commit owned files.
|
|
|
|
## Task 4: Integration and delivery
|
|
|
|
Owner: controller. README/install docs, update bundle, isolated validation.
|
|
|
|
- [x] Review each task diff with concrete test reports; resolve findings.
|
|
- [x] Integrate task interfaces; document terminal usage and branded name.
|
|
- [x] Run complete suite and isolated smoke covering run/open/menu with new code.
|
|
- [x] Prepare a reversible guest update with exact file inventory and checksums;
|
|
preserve old ISO and test disk. Assess cached image rebuild and test new output.
|
|
- [x] Review whole branch, commit/publish authorized repository changes and report
|
|
exactly which artifacts and guest states have actually been updated.
|