docs: define Gentoo HydraOS target and implementation plan
This commit is contained in:
Codex
@@ -0,0 +1,91 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,130 @@
|
||||
# HydraOS: минимальная графическая сессия хоста
|
||||
|
||||
Решение первого этапа, 13 октября 2026 года. Пользователь подтвердил Gentoo,
|
||||
устанавливаемый ISO, ASUS TUF Dash F15 FX517ZC и автономную разработку.
|
||||
|
||||
## Назначение
|
||||
|
||||
HydraOS должна стать устанавливаемым Linux-дистрибутивом для одновременной
|
||||
работы нескольких виртуальных машин. Пользователь видит рабочий стол выбранной
|
||||
VM на весь экран и переключает машины горячими клавишами. Хост обеспечивает
|
||||
оборудование, сеть и управление VM; его графический интерфейс обычно незаметен.
|
||||
|
||||
Подтверждённые требования: минимальная оболочка хоста по умолчанию, отсутствие
|
||||
впечатления вложенных окон, переключение клавишами, совместимость управления
|
||||
VM с другими окружениями хоста. Гостевые окружения выбираются независимо.
|
||||
Gentoo выбрана основой будущего дистрибутива. Первый этап проверяет
|
||||
графическую сессию до изготовления установочного ISO.
|
||||
|
||||
## Решение первого этапа
|
||||
|
||||
Предлагается labwc как композитор стандартной сессии и отдельный SPICE-просмотрщик
|
||||
для каждой VM. Панель, меню рабочего стола, оформление окон и обычные сочетания
|
||||
оконного менеджера в этой сессии не нужны. На физическом экране всегда находится
|
||||
один полноэкранный просмотрщик. Его обычный интерфейс должен быть скрыт; выбор
|
||||
USB и восстановление доступа к хосту остаются доступны по явному действию.
|
||||
|
||||
Первый прототип рассчитан на один физический экран. Режим без рамок включает
|
||||
отсутствие всплывающей панели просмотрщика при подведении указателя к краю.
|
||||
До основной реализации отдельно проверяются два условия: сохранение
|
||||
зарезервированных клавиш хоста при захвате ввода SPICE и возможность явно
|
||||
открыть управление USB при скрытом интерфейсе просмотрщика. Если выбранный
|
||||
режим remote-viewer этого не допускает, способ управления пересматривается;
|
||||
доступность этих функций пока не считается подтверждённой.
|
||||
|
||||
Несколько VM и их просмотрщики продолжают работать при переключении. Меняется
|
||||
видимый просмотрщик, а не питание или состояние гостя. Переключение не должно
|
||||
требовать повторной загрузки ОС или подключения к SPICE.
|
||||
|
||||
Существующий прототип `/home/workspaces/niri-vm-lab` служит источником проверенных
|
||||
решений для виртуального оборудования и сети. Его работающие VM и диски не
|
||||
используются как тестовые объекты новой графической сессии.
|
||||
|
||||
## Границы компонентов и совместимость
|
||||
|
||||
- Управление VM: параметры QEMU, отдельные диски, запуск, состояние, штатное
|
||||
выключение, приватные сокеты QMP и SPICE. Этот компонент не вызывает labwc
|
||||
или Niri и не требует работающей графической сессии.
|
||||
- Запуск просмотрщика: подключение к выбранной VM. В обычном окружении хоста
|
||||
просмотрщик может работать окном; графический backend определяется средой.
|
||||
- Сессия HydraOS: настройка labwc, полноэкранный показ, фокус, горячие клавиши
|
||||
переключения и восстановление после закрытия просмотрщика.
|
||||
- Упаковка дистрибутива: ядро, драйверы, пакеты, запуск сессии, установка и
|
||||
обновления. Это следующий самостоятельный этап после проверки оболочки.
|
||||
|
||||
В KDE, GNOME и других окружениях хоста должны оставаться доступны общие команды
|
||||
управления и оконные просмотрщики. Специальная политика захвата клавиатуры и
|
||||
переключения полноэкранных VM гарантируется только после проверки конкретной
|
||||
сессии. Установка другой оболочки не должна менять формат профилей или дисков.
|
||||
Одновременная работа нескольких полноценных сессий хоста и передача физического
|
||||
экрана между ними в первый этап не входят.
|
||||
|
||||
## Ввод и поведение при сбоях
|
||||
|
||||
В стандартной сессии Meta, Alt+Tab и переключение раскладки передаются гостю.
|
||||
Для хоста резервируются Ctrl+Alt+Shift+Left/Right для смены VM и отдельное
|
||||
аварийное сочетание Ctrl+Alt+Shift+Escape для освобождения ввода и доступа к
|
||||
локальному управлению. Клавиши яркости управляют физическим экраном хоста.
|
||||
Общий буфер обмена и общие папки не включаются автоматически.
|
||||
|
||||
Завершение или сбой просмотрщика либо композитора не выключает VM. Повторный
|
||||
запуск сессии подключается к работающим машинам. Ошибка подключения показывается
|
||||
коротким сообщением с возможностью повторить подключение или открыть аварийный
|
||||
терминал; она не приводит к автоматическому сбросу VM.
|
||||
|
||||
Управляющие команды не передаются через гостевую клавиатуру. Горячие клавиши
|
||||
хоста должны срабатывать и при захваченном вводе просмотрщика. Отключение всех
|
||||
привязок labwc через ToggleKeybinds не подходит без проверки аварийного выхода
|
||||
и переключения VM.
|
||||
|
||||
## Проверка перед упаковкой в ISO
|
||||
|
||||
Используются отдельные временные VM и диски. Сначала проверяется вложенная
|
||||
тестовая сессия, затем самостоятельная сессия на TTY: первая не доказывает
|
||||
корректность захвата клавиш или работу физического экрана.
|
||||
|
||||
Критерии приёмки:
|
||||
|
||||
1. Два гостя переключаются клавишами без рамок, панели и интерфейса просмотрщика.
|
||||
2. Фоновая задача в скрытой VM продолжает работу; QEMU не перезапускается.
|
||||
3. Meta, Alt+Tab, раскладка и указатель работают в госте, а переключение VM,
|
||||
яркость и аварийный выход остаются доступны хосту.
|
||||
Проверяется также смена VM при удерживаемых модификаторах и кнопке мыши:
|
||||
в покинутом госте не остаются зажатыми клавиши, а в новом не возникают
|
||||
случайные действия из-за переданных отпусканий или состояния ввода.
|
||||
4. После закрытия просмотрщика или сессии VM остаются доступны по сети;
|
||||
повторное подключение восстанавливает изображение.
|
||||
5. В обычной сессии хоста работает оконный просмотрщик и общее управление VM.
|
||||
6. Измеряются задержка переключения и обновление скрытых поверхностей. Замена
|
||||
композитора не считается доказательством исправления ограничений VirGL/SPICE
|
||||
или достижения 144 FPS. Если существующие просмотрщики не обеспечивают
|
||||
требуемое поведение, выбор способа вывода пересматривается до сборки ISO.
|
||||
|
||||
На этом этапе не создаются собственный композитор, графическая панель управления,
|
||||
установщик или механизм обновления дистрибутива. Сначала проверяется пригодность
|
||||
минимальной сессии для ежедневного использования.
|
||||
|
||||
## Основания выбора
|
||||
|
||||
- [labwc](https://labwc.github.io/) и его
|
||||
[действия](https://labwc.github.io/labwc-actions.5.html): готовые механизмы окон,
|
||||
полноэкранного режима, рабочих пространств и клавиатурного управления.
|
||||
- [Cage](https://github.com/cage-kiosk/cage): вариант для одного собственного
|
||||
приложения HydraOS; самостоятельное управление несколькими просмотрщиками
|
||||
потребует дополнительной реализации.
|
||||
- [Weston kiosk-shell](https://wayland.pages.freedesktop.org/weston/toc/kiosk-shell.html):
|
||||
полноэкранные приложения и распределение по экранам; переключение VM придётся
|
||||
дополнительно проектировать.
|
||||
- [Smithay](https://github.com/Smithay/smithay): основа собственного композитора
|
||||
на Rust, с существенно большим объёмом ответственности за графику и ввод.
|
||||
|
||||
## Уточнения реализации
|
||||
|
||||
- Python 3.11+ и стандартная библиотека для переносимого CLI `hydra`.
|
||||
- labwc >= 0.20.0: обязательные host bindings используют overrideInhibition.
|
||||
- Профили TOML, состояние и приватные Unix-сокеты QMP/SPICE разделены.
|
||||
- Meta/Alt+Tab и default mouse bindings хоста не подключаются.
|
||||
- Полный проект ведётся автономно; локальные патчи зависимостей разрешены.
|
||||
- Сборка Gentoo идёт в отдельном builder; физические диски не являются целями тестов.
|
||||
- Для первой версии выбран Gentoo systemd stage3: logind, cgroups и независимые
|
||||
службы VM; выбор init является реализационной деталью, не требованием пользователя.
|
||||
Reference in New Issue
Block a user