orbithub/docs/OrbitHub_v0_Spec_CPP_QtWidgets.md

OrbitHub v0 Specification (Pure C++ / Qt6 Widgets)

Overview

OrbitHub is a cross-platform native desktop application for managing and launching remote sessions.

Platforms:

• Windows 11
• Linux (Mint/Ubuntu-family)
• macOS

Implementation:

• 100% C++
• Qt 6 Widgets (no Qt Quick)
• CMake build system
• MIT License

This replaces the earlier Python-based architecture.

---

UX Model

OrbitHub uses a two-window model:

1. Profiles Window (single instance)

• List of saved profiles
• Search box
• New / Edit / Delete
• Double-click connects

2. Session Window(s)

• QTabWidget
• One tab per session
• Close tab destroys session
• Placeholder view widget displays: "OrbitHub Native Surface"

---

Milestone 0

• Fresh C++/Qt repo scaffold
• App builds
• Profiles window launches
• Session window opens with placeholder tab
• Tag: v0-m0-done

---

Milestone 1

• SQLite integration
• Profiles CRUD
• Connect loads profile name into tab
• Tag: v0-m1-done

---

Milestone 2

• Extend profiles schema (host, port, username, protocol, auth_mode)
• Replace prompt-based create/edit with a structured profile dialog form
• Connect loads full profile details into session tab
• Session lifecycle states in UI (Connecting, Connected, Failed) with non-blocking updates
• Tag: v0-m2-done

---

Milestone 3

• Real SSH backend using native ssh process (connect, disconnect, reconnect)
• Protocol backend abstraction with worker-thread execution
• RDP/VNC explicitly marked as not implemented in session UX
• Connect-time credential prompts (password/private key path) with no secret storage in DB
• Session tab controls: Connect, Disconnect, Reconnect, Copy Error
• Per-session timestamped event log and user-friendly error mapping
• Profile schema extended with private_key_path and known_hosts_policy
• Tag: v0-m3-done

---

Milestone 4

• Interactive embedded SSH terminal (KodoTerm + libvterm)
• SSH host-key trust prompt flow for Ask policy
• Improved SSH auth flow for password / private key
• Terminal utilities and UX polish (theme, clear, resize/input behavior)
• Session lifecycle UX cleanup (auto-connect, disconnect on close, tab state indicators)
• Tag: v0-m4-done

---

Milestone 5 - RDP MVP Connectivity

• Implement real RDP protocol backend (replace not-implemented stub for RDP)
• Support RDP connection launch and lifecycle from OrbitHub
• Add RDP-specific connect options in profile/session flows
• Normalize event/error reporting with existing SSH behavior
• Planned Tag: v0-m5-done

---

Milestone 6 - VNC MVP Connectivity

• Implement real VNC protocol backend (replace not-implemented stub for VNC)
• Support VNC connection launch and lifecycle from OrbitHub
• Add VNC-specific connect options in profile/session flows
• Normalize event/error reporting with SSH/RDP behavior
• Planned Tag: v0-m6-done

---

Milestone 7 - Cross-Platform Protocol Hardening

• Validate SSH/RDP/VNC behavior on Windows, Linux, and macOS
• Resolve platform-specific path/process/auth differences
• Improve diagnostics and failure messaging for common protocol issues
• Add protocol regression checklist and repeatable verification scripts
• Planned Tag: v0-m7-done

---

Milestone 8 - Profile and Session UX Completion

• Complete profile fields/validation for all protocols
• Add quality-of-life controls for active sessions (tab context actions, defaults, persistence)
• Persist per-user UI/session preferences (theme, panel visibility, terminal defaults)
• Improve session history/event visibility and filtering
• Planned Tag: v0-m8-done

---

Milestone 9 - Packaging and Distribution

• Produce distributable artifacts for Windows, Linux, and macOS
• Document dependency/runtime requirements per platform
• Add release build scripts for reproducible packaging
• Validate clean install + first-run flow on each platform
• Planned Tag: v0-m9-done

---

Milestone 10 - v1.0 Stabilization

• End-to-end QA pass across core workflows (profile CRUD + SSH/RDP/VNC session lifecycle)
• Fix blocker/critical defects from validation
• Finalize docs (BUILDING, usage notes, known limitations)
• Prepare v1.0 release notes and final acceptance checklist
• Planned Tag: v1.0.0