diff --git a/docs/superpowers/plans/2026-10-13-terminal-ux.md b/docs/superpowers/plans/2026-10-13-terminal-ux.md new file mode 100644 index 0000000..aa46c6d --- /dev/null +++ b/docs/superpowers/plans/2026-10-13-terminal-ux.md @@ -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. diff --git a/docs/superpowers/specs/2026-10-13-terminal-ux-design.md b/docs/superpowers/specs/2026-10-13-terminal-ux-design.md new file mode 100644 index 0000000..5058984 --- /dev/null +++ b/docs/superpowers/specs/2026-10-13-terminal-ux-design.md @@ -0,0 +1,64 @@ +# Hydra OS terminal experience + +The user requested a general UX overhaul inside Hydra, clarified that the +interface should stay in the terminal for control, and specifically requested +one command to download and launch an ISO from a URL. They also requested +Fastfetch with a custom logo and consistent visible branding as **Hydra OS**. +Earlier autonomous-development authorization continues to apply. This work +must not modify the current NixOS configuration or existing user VM disks. + +## Experience + +- The existing recovery terminal becomes a readable VM menu, with names, + running/stopped/error states and memory allocations instead of raw JSON. + A number or name opens one VM; Enter chooses the remembered selection (or + the only VM). Opening explicitly starts a stopped VM and reconnects a + running one. Merely displaying or refreshing the menu never starts VMs. +- Keep `:shell`, `:refresh`, `:quit` and VM names compatible. Offer discoverable + actions for new VM setup, ISO downloading, networking (`sudo nmtui`) and + help. Existing CLI commands remain usable and JSON-compatible. +- `hydra open NAME` starts if needed and displays an existing VM. Selecting a + VM must actually focus its workspace, including a VM other than the first. + Existing independent QEMU lifecycle and identity/locking protections remain. +- `hydra run SOURCE --name NAME` accepts a local ISO or HTTP(S) URL and performs + download (when necessary), profile creation, startup and display. Options + expose RAM, CPUs, disk size, SHA-256 and `--no-view` for headless use. An + existing name is never replaced: report how to use `hydra open NAME` instead. +- `hydra download URL [--sha256 HEX]` stores a reusable ISO locally, reports + progress and final path, and supports Ctrl+C cancellation. Explain direct + image URLs versus HTML download pages. Never treat HTML as an ISO. +- Check available RAM with a 768 MiB host reserve before an explicit new + launch through the new UX. Refuse an obviously insufficient budget clearly; + this is a preflight estimate, not a guarantee against future memory pressure. +- Clear actionable errors, no startup of all VMs, no forced VM shutdowns. + +## Downloads and storage + +Use Python standard-library HTTP(S), no network service or new daemon. Cache +under the user's XDG cache directory in `hydra/iso`, keyed by URL hash and a +safe basename. Reject URL credentials and non-HTTP(S) remote schemes. Download +to a private temporary file; check HTTP status, content length when supplied, +ISO9660/UDF volume signature and optional SHA-256 before atomic publication. +Never overwrite an existing unrelated file. Cancelled/failed downloads cannot +be mistaken for complete images. Check disk space; reuse validated cached +images. Render safe progress and errors without leaking URL query credentials. + +## Branding + +Visible product name is **Hydra OS**. Preserve technical identifiers such as +`hydra`, `hydra-os`, service names, existing profile formats, disk directories +and EFI installation paths. Historical release manifests/evidence keep their +original contents. Add an original compact multi-headed hydra ASCII logo for +Fastfetch, a restrained color scheme and an intentionally short useful system +summary. Include Fastfetch in the Gentoo image, not on NixOS. + +## Delivery and validation + +Work in `feat/ux` under `.worktrees/ux`. Keep the original ISO and manual test +disk. Use meaningful regression tests for download failures/cache integrity, +explicit launch behavior and menu/session focus. Run the existing full suite +once integrated, and an isolated real graphical/VM smoke test where available. +Prepare a reviewable update bundle for the already installed guest and update +the image sources; rebuild/test a new ISO when feasible without a cold toolchain +build. Never claim the running user guest or an old ISO already contains new +code. No keystroke injection into the user's desktop or guest sessions.