92 lines
6.2 KiB
Markdown
92 lines
6.2 KiB
Markdown
# HydraOS Graphics Session Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Steps use checkbox syntax for tracking.
|
||
|
||
**Goal:** Validate independent VM management and fullscreen switching before Gentoo ISO packaging.
|
||
|
||
**Architecture:** Python CLI owns validated profiles, disks and private QMP connections. A separate labwc session owns viewer windows, workspaces and host shortcuts. Gentoo packaging follows in its own plan.
|
||
|
||
**Tech Stack:** Python3.11+ standard library, QEMU/KVM, virt-viewer/SPICE, labwc>=0.20.0.
|
||
|
||
**Spec:** ../specs/2026-10-13-graphics-session-design.md
|
||
|
||
## Global Constraints
|
||
|
||
- Gentoo, first target ASUS FX517ZC, UEFI, Secure Boot disabled.
|
||
- Preserve current NixOS, Ubuntu, VM lab and existing disks.
|
||
- Source in Ubuntu-owned project; temporary development tools permitted.
|
||
- QEMU lifetime independent of compositor/viewer.
|
||
- Tests use explicitly separate config/state/runtime paths.
|
||
- Private Unix QMP/SPICE sockets; no public management listener.
|
||
- Guest Meta/Alt+Tab; host Ctrl+Alt+Shift+Left/Right/Escape and brightness.
|
||
- No clipboard/directory sharing or USB auto-redirection by default.
|
||
- No overwrite of existing disks or unattended physical disk installation.
|
||
|
||
## Review Focus
|
||
|
||
- Stale records/reused PID must never stop another process: Task1 identity tests.
|
||
- Concurrent starts must never attach one writable disk twice: Task1 lock tests.
|
||
- Profile names and paths must not become shell syntax: Tasks1/2 escaping tests.
|
||
- Held keys/buttons during switches must not stick: Task3 input test.
|
||
- Missing display/GPU/ISO and viewer crash preserve guests: Tasks1–3 failure tests.
|
||
|
||
## File Structure
|
||
|
||
`bin/hydra` is the source-checkout entry point. `hydra/profiles.py`, `qmp.py`,
|
||
`runtime.py`, `cli.py` implement validated profiles, protocol, lifecycle, parsing.
|
||
`hydra/session.py` owns session configuration/viewer launch. `session/` contains
|
||
launcher assets; `patches/` holds necessary upstream adaptations. `tests/` uses
|
||
unittest; `dev/` holds pinned tools and disposable integration probes.
|
||
|
||
### Task 1: Independent VM lifecycle
|
||
|
||
**Files:** Create `bin/hydra`, `hydra/{__init__,profiles,qmp,runtime,cli}.py`, `tests/test_{profiles,qmp,runtime}.py`.
|
||
|
||
**Interfaces:**
|
||
- CLI globals `--config PATH`, `--state PATH`, `--runtime PATH`; defaults from XDG.
|
||
- Commands `add NAME --iso PATH [--memory 4096] [--cpus 2] [--disk-size 40G]`, `list`, `start NAME`, `status [NAME]`, `shutdown NAME`, `stop NAME --force`.
|
||
- Names match `[a-z][a-z0-9-]{0,31}`; individual `NAME.toml` profiles.
|
||
- `Profile` fields: name, iso, memory, cpus, disk_size, graphics(auto|software), network(user|bridge), bridge. Defaults: graphics auto, network user, bridge hydrabr0. Distribution networking follows later.
|
||
- `load_profile(path: Path) -> Profile`, `build_qemu_argv(profile: Profile, paths: VMPaths) -> list[str]`, `QMPClient.command(name: str, arguments: dict | None = None) -> dict`.
|
||
- `VMPaths` provides disk, log, lock and private QMP/SPICE sockets. Session consumes stable name and socket paths only.
|
||
|
||
- [ ] Write validation/QMP fake-server tests: invalid names/resources, missing ISO, paths containing spaces, greeting/capabilities, asynchronous events, IDs, timeouts.
|
||
- [ ] Run `python3 -m unittest discover -s tests -v`; observe failure before implementation.
|
||
- [ ] Implement validation and bounded QMP; subprocess argv arrays, named environment tool overrides for tests.
|
||
- [ ] Add lifecycle tests: simultaneous start, existing-disk preservation, stale socket, failed boot, shutdown vs force, QMP VM identity.
|
||
- [ ] Implement locked safe disk creation, detached QEMU, virtio disk/network, SPICE no clipboard/file transfer, optional Intel GL. No display dependency in manager and no PID-only stop.
|
||
- [ ] Run complete suite, help, scratch QEMU lifecycle probe. Commit `feat: add independent VM manager`.
|
||
|
||
### Task 2: Minimal fullscreen session
|
||
|
||
**Files:** Create `hydra/session.py`, `session/hydra-session`, `tests/test_session.py`, `dev/tools.nix`; amend CLI; optional narrow virt-viewer patch.
|
||
|
||
**Interfaces:** Consumes Task1 Profile/VMPaths. Produces `hydra view NAME [--windowed]`, `hydra session [--nested]`, labwc config only in selected runtime. Viewer title is deterministic from validated name; each VM maps to one workspace. Recovery opens host terminal; session never shuts down a VM.
|
||
|
||
- [ ] Probe actual labwc version/overrideInhibition and remote-viewer kiosk USB behavior on disposable state; record versions.
|
||
- [ ] Resolve manual USB dialog with a small upstream viewer adaptation if necessary; never auto-redirect USB.
|
||
- [ ] Write tests for valid escaped XML, exact window/workspace/fullscreen rules, no default keyboard/mouse bindings, overrideInhibition on host keys, missing viewer/display errors.
|
||
- [ ] Run session tests and observe missing implementation failure.
|
||
- [ ] Implement session/viewer commands and pinned temporary tool environment; no host installation.
|
||
- [ ] Run full tests and labwc config parsing. Commit `feat: add fullscreen HydraOS session`.
|
||
|
||
### Task 3: Integration and recovery
|
||
|
||
**Files:** Create `dev/smoke.py`, `docs/verification.md`; update README with verified commands.
|
||
|
||
**Interfaces:** Consumes Tasks1/2, produces disposable-VM integration evidence.
|
||
|
||
- [ ] Run two disposable KVM instances/viewers, never existing lab disks; verify private QMP and independent lifecycle.
|
||
- [ ] Verify viewer/session exit preserves QEMU and reattach works; switching neither restarts nor reconnects guests.
|
||
- [ ] Check input only in disposable session, without injecting into current host or user's guests; add regression tests for discovered defects.
|
||
- [ ] Record held-key, physical brightness and 144Hz checks needing dedicated TTY. Nested tests cannot prove them.
|
||
- [ ] Run full suite and independent review; fix material findings with reproducing tests.
|
||
- [ ] Commit evidence and push reviewed prototype branch to supplied repository.
|
||
|
||
## Next plan
|
||
|
||
Stage3/rootfs, signed official binpkgs where suitable, kernel/firmware, dracut live
|
||
boot, squashfs/UEFI ISO and guarded installer. Acceptance: ISO boot, install to
|
||
blank disposable disk, reboot without ISO, persistent changes and working VM
|
||
session. Real laptop installation requires a selected disk and final consent.
|