diff --git a/docs/plans/2024-06-22-hostkeeper-design.md b/docs/plans/2024-06-22-hostkeeper-design.md index 725df68..3677711 100644 --- a/docs/plans/2024-06-22-hostkeeper-design.md +++ b/docs/plans/2024-06-22-hostkeeper-design.md @@ -12,8 +12,11 @@ Hostkeeper is a cross-platform SSH/SFTP management tool written in Go, inspired ### Key Design Decisions -- **Architecture:** TUI-first with tab-based session management (embedded terminal replacement) -- **Interface:** TUI for full experience (multiple SSH sessions, host management, SFTP); CLI for quick tasks and automation +- **Architecture:** TUI-first with native SSH delegation — interactive SSH via `tea.ExecProcess` (zero lag, native terminal), SFTP/browsing via in-process Go +- **Interface:** TUI for management + native fullscreen SSH when connecting; CLI for quick tasks and automation +- **SSH Strategy:** Delegate to native `ssh` binary via `tea.ExecProcess` (same approach as tamagosh) — eliminates lag from Go buffering, enables full terminal capability +- **SFTP Strategy:** Use `github.com/pkg/sftp` via Go (in-process) — file operations don't need real-time echo, so Go integration works well +- **Color Theme:** Gruvbox Material Dark Hard palette (`#d4be98`, `#a9b665`, `#e78a4e`, `#504945`) — soft, easy on eyes - **Storage:** JSON/YAML files (Phase 1), encrypted storage (Phase 2) - **Platform:** Cross-platform (Linux, macOS, Windows, Termux/Android) - **Sync:** Manual export/import (Phase 1), cloud sync (future) @@ -146,45 +149,51 @@ hostkeeper completion # Shell completion setup **Framework:** Bubble Tea (event-driven TUI) + Lipgloss (styling) -**Theme:** Orange/light color palette (`#FF6B00`, `#FF9F43`, `#FFB800`) — visually distinct from native terminal to signal the user is inside Hostkeeper +**Theme:** Gruvbox Material Dark Hard palette (`#d4be98`, `#a9b665`, `#e78a4e`, `#504945`, `#ea6962`) — soft, warm, easy on eyes over long sessions #### Tab System Architecture ``` -┌─ Hosts ──── Server Nico ── SFTP ── Keys ── Settings ────────┐ +┌─ Hosts ──── SFTP:server1 ── Keys ── Snippets ────────────────┐ │ │ -│ [content of active tab] │ +│ [content of active tab — host list, SFTP browser, etc.] │ │ │ ├───────────────────────────────────────────────────────────────┤ -│ Ctrl+Q:close Ctrl+Tab:next Shift+Tab:prev ↑↓:nav /:search│ +│ Ctrl+Tab:switch Ctrl+Q:close ↑↓:nav Enter:SSH /:search │ └───────────────────────────────────────────────────────────────┘ ``` **Tab Types:** - **HostsTab** — Host list with search, filter, sort, keyboard navigation -- **SessionTab** — Live interactive SSH session (input/output piped via Go SSH client) -- **SFTPTab** — Remote file browser with upload/download operations -- **KeysTab** — SSH key management (list, generate, import) -- **SnippetsTab** — Command snippets with variable substitution -- **SettingsTab** — Application configuration +- **SFTPTab** — Dual-pane (local ↔ remote) file browser with upload/download/delete/rename +- **KeysTab** — SSH key management (list, add, edit, delete) +- **SnippetsTab** — Command snippets management -**SessionTab Internals:** -- Connect via Go SSH client with stored credentials (password auto-injected) -- 2 goroutines per session: stdin → SSH channel, SSH stdout → TUI render -- Terminal resize event → `WindowChange` via SSH channel -- `Ctrl+Q` disconnects session and closes tab -- Multiple session tabs can be open simultaneously (e.g. connect to 3 servers at once) +**SSH Connect (NOT a tab — fullscreen native SSH delegation):** +- User selects host → presses Enter +- TUI exits alt-screen, runs `tea.ExecProcess` → native `ssh` binary takes over terminal directly +- Zero lag: native SSH handles PTY, echo, resize, signals — no Go buffering +- On SSH exit → TUI resumes, returns to host list +- Password auth via `sshpass -e` (SSHPASS env var) +- Key auth via `ssh -i ` (passphrase via SSH_ASKPASS if needed) +- User can install `tmux` on server for session persistence (optional) + +**Rationale:** In-process SSH (golang.org/x/crypto/ssh with goroutine I/O) introduces ~6 layers of buffering between keystroke and echo. Delegating to native `ssh` via `tea.ExecProcess` eliminates all Go overhead from the real-time I/O path, giving a native-terminal experience. **Keyboard Navigation:** | Key | Action | |-----|--------| | `Ctrl+Tab` / `Shift+Tab` | Cycle tabs forward/backward | -| `Ctrl+N` | New tab (add host / new connection) | -| `Ctrl+Q` | Close current tab / disconnect session | -| `↑` / `↓` | Navigate lists (hosts, keys, files) | -| `Enter` | Select host / open directory / confirm | -| `/` | Search/filter within active tab | -| `q` | Quit Hostkeeper (confirmation dialog) | +| `Ctrl+N` | Add new host | +| `Ctrl+E` | Edit selected host | +| `Ctrl+F` | Open SFTP browser for selected host | +| `Ctrl+K` | SSH Keys management | +| `Ctrl+P` | Snippets management | +| `Enter` | SSH into selected host (fullscreen native SSH) | +| `↑` / `↓` | Navigate lists | +| `D` / `Delete` | Delete selected item | +| `Ctrl+Q` | Close current tab | +| `q` | Quit Hostkeeper | --- @@ -689,17 +698,17 @@ Continue anyway? [y/N] ### Phase 2: TUI Overhaul & Enhanced Features (4-6 weeks) -**Priority 1 — TUI Overhaul:** -- Tab system with orange theme (TabManager, tab bar, keyboard shortcuts) -- Multi-session SSH tabs (live interactive shells within TUI) -- TUI forms for add/edit hosts (replace CLI prompts) -- SFTP file browser in TUI tab +**Priority 1 — TUI Overhaul (Completed):** +- Tab system with Gruvbox Material theme (TabManager, tab bar, keyboard shortcuts) +- Native SSH delegation via `tea.ExecProcess` (zero-lag fullscreen SSH, inspired by tamagosh) +- TUI forms for add/edit hosts +- Dual-pane SFTP browser (local ↔ remote) with upload/download/delete/rename - Key & snippet management in TUI **Priority 2 — Security Enhancement:** -- AES-256 encryption for storage -- Master password protection -- Secure credential export/import +- AES-256-GCM encryption for secrets file (inspired by tamagosh) +- Key passphrase support via SSH_ASKPASS +- Known_hosts verification for SFTP connections **Priority 3 — UX Polish:** - Configuration profiles @@ -784,10 +793,10 @@ Continue anyway? [y/N] ### Phase 2 Success Metrics - ✅ Rich TUI interface for all operations -- ✅ Encrypted credential storage -- ✅ Dual-pane SFTP browser +- ✅ Zero-lag SSH via native binary delegation +- ✅ Dual-pane SFTP browser (local ↔ remote) - ✅ Shell completion and documentation -- ✅ Enhanced user experience +- ✅ Enhanced user experience with Gruvbox palette --- diff --git a/docs/plans/2024-06-22-hostkeeper-implementation.md b/docs/plans/2024-06-22-hostkeeper-implementation.md index d6565a9..f44388b 100644 --- a/docs/plans/2024-06-22-hostkeeper-implementation.md +++ b/docs/plans/2024-06-22-hostkeeper-implementation.md @@ -11,7 +11,7 @@ **Tech Stack:** Go 1.21+, Cobra (CLI framework), Bubble Tea (TUI), golang.org/x/crypto/ssh, Viper (config management), JSON/YAML storage -**Current Status**: Planning Complete → Ready for Implementation (Check PROJECT_STATE.md for latest updates) +**Current Status**: Phase 2 Complete — SSH rewritten with native `ssh` delegation, dual-pane SFTP browser, Gruvbox theme. Next: security encryption + VT emulator multi-session. --- @@ -4933,31 +4933,29 @@ This implementation plan provides a comprehensive roadmap for building the Hostk 11. **Build System** - Cross-platform compilation 12. **Documentation** - Installation and usage guides -### 📋 Phase 2 Planned (TUI Overhaul) +### 📋 Phase 2 Completed (TUI Overhaul) -1. **Task 15** — Tab Framework & Orange Theme -2. **Task 16** — SSH Session Tab (multi-session) +1. **Task 15** — Tab Framework & Gruvbox Theme +2. **Task 16** — SSH Session Rewrite (native `ssh` via `tea.ExecProcess`, zero-lag) 3. **Task 17** — TUI Host Forms (add/edit) -4. **Task 18** — TUI SFTP Browser +4. **Task 18** — Dual-pane SFTP Browser (local ↔ remote) 5. **Task 19** — TUI Key & Snippet Management -### 🎯 MVP Success Criteria +### 🎯 Success Criteria -- ✅ Can establish SSH connections to remote servers +- ✅ Native `ssh` binary delegation via `tea.ExecProcess` — zero lag, full terminal capability +- ✅ Dual-pane SFTP browser (inspired by tamagosh/Midnight Commander) - ✅ Can manage multiple hosts with different auth methods -- ✅ Can perform SFTP operations (native client) - ✅ Can export/import credentials across devices - ✅ Works on Linux, macOS, Windows, and Termux - ✅ Secure credential storage with proper permissions - ✅ User-friendly error messages and help text +- ✅ Gruvbox Material Dark Hard palette for comfortable extended use -### 🚀 Ready for Phase 2 +### 🚀 Phase 3 — Future -After completing the MVP, the next phase focuses on TUI Overhaul: - -1. **Task 15** — TUI Tab Framework & Orange Theme (foundation) -2. **Task 16** — SSH Session Tab (multi-session) -3. **Task 17** — TUI Host Forms (add/edit in TUI) -4. **Task 18** — TUI SFTP Browser -5. **Task 19** — TUI Key & Snippet Management -6. **Future** — Cloud sync, custom terminal emulator, web interface \ No newline at end of file +1. **AES-256-GCM encrypted secrets** (inspired by tamagosh) +2. **Known_hosts verification** for SFTP +3. **In-app SSH key generation** +4. **Multi-session without lag** — PTY multiplexer + VT terminal emulator +5. **Cloud sync, custom terminal emulator, web interface** \ No newline at end of file