kernalix7--winpodx/docs/design/ROADMAP-0.6.0.md

WinPodX 0.6.0 — Consolidation & UX Release

Goal

Single-pass cleanup of accumulated structural debt: unify duplicated implementations, sharpen the command surface, and rethink the AppImage so it stops being fragile. After 0.6.0, the shells (install.sh, uninstall.sh, postinst, postrm) are thin wrappers and the Python CLI is the single source of truth.

This roadmap is the cut-list. Items move from "in scope" to "done" only when the corresponding PR has merged to main. Deferred items are recorded so we don't lose them; "won't do" items are decided no.

In scope (must land in 0.6.0)

Provisioning + AppImage

• A. Thin AppImage. Drop bundled podman / podman-compose / conmon / crun / netavark / pasta. Keep FreeRDP + Python + Qt + WinPodX. Require host podman/docker/libvirt (same model as install.sh). Closes #357 and #363 by removing the root cause (bundled podman shadowing or poisoning the host stack) instead of patching around it. AppImage shrinks ~150 MB → ~50 MB. _hostenv helper collapses to an LD_LIBRARY_PATH strip (no host-first PATH games needed once nothing is shadowing). Effort M / Risk M (recipe rebuild + reporter smoke).
• B. P1 — winpodx provision single source of truth. New core/provisioner.finish_provisioning(cfg, *, wait_timeout, require_agent, with_reverse_open) consolidates the wait-ready → apply-fixes → discovery → reverse-open chain currently duplicated in install.sh, setup_cmd._run_full_provision, migrate, and pending.resume. install.sh collapses ~140 lines → ~5. setup --create-only is dropped. Effort L / Risk M (load-bearing; needs real-Windows smoke). Absorbs I.
• I. Qt GUI bring-up → winpodx provision. gui/_main_window_bringup.py is the 5th copy of the chain. Folded into B. Effort S (inside B).

Hardcoding / single source

• C. P2 — port 8765 constant. core/agent.AGENT_PORT referenced by all host-side callers (compose generation, checks, guest_sync, install.sh health-poll). The guest-side agent.ps1 keeps its own literal (can't import Python); the pairing is documented. 8 literals → 1 host SoT. Effort S / Risk Low.
• D. P3 — dependency / health single detector. Extend utils/deps.py:check_all (+ kvm, + podman-major gate). deps_quickcheck, doctor, setup_cmd all consume it. Drop the re-hardcoded freerdp lists. install.sh keeps a minimal pre-venv bash probe (genuinely shell-unique). 5 places → 1 Python SoT + 1 minimal shell probe. Effort M / Risk Low-M.
• E. P4 — backend selection helper. core/backend/select.py:choose_backend(prefer, present) implementing podman → docker → libvirt + the podman major-version gate. install.sh and setup_cmd both consume it. 3 places → 1. Effort S-M / Risk Low.
• F. P5 — version + edition single source. __init__.__version__ reads from package metadata. Windows-edition help/locale strings generate from _KNOWN_WIN_VERSIONS. Fix stale packaging/rpm/winpodx.spec:8 literal. Effort S / Risk Low.

Command surface

• G. Command taxonomy reorg.
  • Diagnostics: info + check + doctor → single winpodx doctor (--json machine-readable, --quick fast subset, --fix see K).
  • pod keeps lifecycle only: start | stop | restart | recreate | status | wait-ready.
  • New winpodx guest: apply-fixes, sync, sync-password, multi-session, recover-oem.
  • New winpodx install: status, resume, grow-disk, disk-usage.
  • Deprecation aliases: old pod apply-fixes etc. keep working through 0.6.x with a deprecation note; removed in 0.7.0.
  • install.sh / uninstall.sh / postinst / postrm call only public winpodx <command> (no internal Python imports).
  • Effort M-L / Risk Low with aliases.
• K. winpodx doctor --fix auto-remediation. ✅ Implemented (PR feat/doctor-fix); guest-touching fixers smoke-gated before merge. Common recoverable failures: dead agent → keepalive kick, stale lock files → purge, missing desktop entries → re-register, oem-version drift → trigger guest-sync. Each fix idempotent. Effort S-M / Risk Low.

Docs + ops

• H. Documentation refresh (mandatory for G). README, FEATURES, COMPARISON, ARCHITECTURE, LIFECYCLE, USAGE + their docs/*.ko.md mirrors. New-command table + old→new alias map. Install / upgrade flows reflect Thin AppImage + winpodx provision. Effort M / Risk Low.
• J. Config schema versioning. cfg.schema_version: int = 1 field + load-time migration hook. 0.6.0 doesn't change config structure, but the marker lets 0.7.0+ migrate cleanly. Effort S / Risk Low.
• L. Logging hygiene pass. Consistent levels across modules (some INFO too noisy, some WARNING missing). One-pass review. Effort S / Risk Low.
• M. install.sh: drop discovery 6× retry. Agent keepalive (#359) proven; 6× is overkill. 1-2× max. Faster first run. Effort S / Risk Low.
• N. Packaging single-source enforcement. flake.nix already reads pyproject (good); fix winpodx.spec:8 stale literal + a lint that catches future drift. Subset of F. Effort S / Risk Low.

Execution order

1. C — port constant (warm-up, fastest, low risk).
2. J — schema_version (cheap future-proofing before big changes).
3. F + N — version / edition / packaging single-source (quick).
4. D — dep check (prerequisite for cleaner E and install.sh).
5. E — backend select (prerequisite for cleaner A and install.sh).
6. A — Thin AppImage (root-cause kill for #357 / #363).
7. B + I — provision unify + GUI bring-up (biggest piece; real-Windows smoke gate).
8. G — command taxonomy (depends on B; deprecation aliases for back-compat).
9. K — doctor --fix (pairs with G's doctor).
10. L — logging hygiene (pass once everything else has landed).
11. M — install.sh retry trim (final tightening).
12. H — docs refresh (last; reflects final shapes; ko mirrors after EN approved).
13. Cut v0.6.0 + REL-v0.6.0.

Real-Windows smoke gate applies to: A (rebuilt AppImage), B / I (provision chain), G (command renames touching guest paths), K (--fix actions). Other items don't need it.

Deferred to 0.7.0+ (tracked, not started)

• Agent authentication. The listener is localhost-only and only reachable from the host via dockur's port map → low risk today. Future: HMAC or shared-token on /exec to harden against host-local malice.
• Real-Windows smoke CI lane. A cloud Windows VM in CI to gate guest-side install changes. Expensive (~$50/mo + setup); manual user smoke continues for now.
• libvirt backend feature-completeness. podman is primary; libvirt has rougher edges (storage growth, multi-session). Separate effort.
• Manual mode (no backend) testing. Niche path; document constraints rather than build a test surface.
• Performance pass. Discovery cache, FreeRDP launch latency, full-rescan vs. incremental. Current is adequate.
• Reverse-open edge cases. Special chars in paths, multi-monitor positioning, MIME priority conflicts. File as encountered.
• i18n drift detection. A lint that catches keys present in only some locale/*.json. Small but needs CI infra.
• Content-addressed oem_bundle. Currently a counter (#359 bumped to 26). A hash would be drift-proof. Backwards-compat work to migrate existing stamps.
• OBS publish race. Timing race on the publish workflow (intermittent re-runs needed). Workflow refactor.
• Lock-file lifecycle. Stale lock cleanup in ~/.local/share/winpodx/run/ is hit-or-miss. Owned-pid check + boot-time sweep.
• PowerShell window flash regression test. A test that asserts no host→guest op ends up on run_in_windows (the FreeRDP path that flashes) outside of explicitly-flash-okay callers. Locks in the #355 win.

Won't do

• External telemetry. Decided. Local FreeRDP-fallback log markers (already shipped) substitute for the only signal we needed.
• New opt-in flags for behaviour. Decided. Features ship default-on; behaviour-changing flags are debt.
• Bundled-podman "actually works". Option A acknowledges the fat AppImage's "self-contained" promise was always limited by the host-systemd dependency. Thin makes that limit explicit instead of pretending.