docs: define Hydra OS terminal experience overhaul

2026-10-13 15:05:28 +03:00
parent 78cdedf220
commit 9abedf29f0
2 changed files with 167 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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.
+
+- [ ] Write and observe failing tests using a local HTTP fixture (ISO, HTML,
+  truncation, checksum, cancellation, cache reuse, collision).
+- [ ] Implement downloader and explicit open/run commands, preserve existing CLI.
+- [ ] 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.
+
+- [ ] Write failing menu/refresh tests for stopped/running selection, unknown
+  identity, names such as s/q, empty/invalid profiles and second-workspace focus.
+- [ ] Implement terminal flow, visible command previews and recovery fallback.
+- [ ] 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.
+
+- [ ] Confirm Fastfetch's Gentoo atom, supported logo/config format and search path.
+- [ ] Add original terminal logo and restrained summary configuration; retain
+  technical IDs while updating visible OS/boot/session labels.
+- [ ] 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.
+
+- [ ] Review each task diff with concrete test reports; resolve findings.
+- [ ] Integrate task interfaces; document terminal usage and branded name.
+- [ ] Run complete suite and isolated smoke covering run/open/menu with new code.
+- [ ] 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.
+- [ ] Review whole branch, commit/publish authorized repository changes and report
+  exactly which artifacts and guest states have actually been updated.