swanadiva/HostKeeper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update design + impl plan — native SSH delegation, Gruvbox theme, dual-pane SFTP

Browse Source
This commit is contained in:
swanadiva
2026-06-23 15:34:04 +07:00
parent 43858dda87
commit b319f44c3e
2 changed files with 58 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2024-06-22-hostkeeper-design.md
+43 -34
View File
@@ -12,8 +12,11 @@ Hostkeeper is a cross-platform SSH/SFTP management tool written in Go, inspired
### Key Design Decisions ### Key Design Decisions
- **Architecture:** TUI-first with tab-based session management (embedded terminal replacement) - **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 full experience (multiple SSH sessions, host management, SFTP); CLI for quick tasks and automation - **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) - **Storage:** JSON/YAML files (Phase 1), encrypted storage (Phase 2)
- **Platform:** Cross-platform (Linux, macOS, Windows, Termux/Android) - **Platform:** Cross-platform (Linux, macOS, Windows, Termux/Android)
- **Sync:** Manual export/import (Phase 1), cloud sync (future) - **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) **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 #### 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:** **Tab Types:**
- **HostsTab** — Host list with search, filter, sort, keyboard navigation - **HostsTab** — Host list with search, filter, sort, keyboard navigation
- **SessionTab** — Live interactive SSH session (input/output piped via Go SSH client) - **SFTPTab** — Dual-pane (local ↔ remote) file browser with upload/download/delete/rename
- **SFTPTab** — Remote file browser with upload/download operations - **KeysTab** — SSH key management (list, add, edit, delete)
- **KeysTab** — SSH key management (list, generate, import) - **SnippetsTab** — Command snippets management
- **SnippetsTab** — Command snippets with variable substitution
- **SettingsTab** — Application configuration
**SessionTab Internals:** **SSH Connect (NOT a tab — fullscreen native SSH delegation):**
- Connect via Go SSH client with stored credentials (password auto-injected) - User selects host → presses Enter
- 2 goroutines per session: stdin → SSH channel, SSH stdout → TUI render - TUI exits alt-screen, runs `tea.ExecProcess` → native `ssh` binary takes over terminal directly
- Terminal resize event → `WindowChange` via SSH channel - Zero lag: native SSH handles PTY, echo, resize, signals — no Go buffering
- `Ctrl+Q` disconnects session and closes tab - On SSH exit → TUI resumes, returns to host list
- Multiple session tabs can be open simultaneously (e.g. connect to 3 servers at once) - Password auth via `sshpass -e` (SSHPASS env var)
- Key auth via `ssh -i <keypath>` (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:** **Keyboard Navigation:**
| Key | Action | | Key | Action |
|-----|--------| |-----|--------|
| `Ctrl+Tab` / `Shift+Tab` | Cycle tabs forward/backward | | `Ctrl+Tab` / `Shift+Tab` | Cycle tabs forward/backward |
| `Ctrl+N` | New tab (add host / new connection) | | `Ctrl+N` | Add new host |
| `Ctrl+Q` | Close current tab / disconnect session | | `Ctrl+E` | Edit selected host |
| `↑` / `↓` | Navigate lists (hosts, keys, files) | | `Ctrl+F` | Open SFTP browser for selected host |
| `Enter` | Select host / open directory / confirm | | `Ctrl+K` | SSH Keys management |
| `/` | Search/filter within active tab | | `Ctrl+P` | Snippets management |
| `q` | Quit Hostkeeper (confirmation dialog) | | `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) ### Phase 2: TUI Overhaul & Enhanced Features (4-6 weeks)
**Priority 1 — TUI Overhaul:** **Priority 1 — TUI Overhaul (Completed):**
- Tab system with orange theme (TabManager, tab bar, keyboard shortcuts) - Tab system with Gruvbox Material theme (TabManager, tab bar, keyboard shortcuts)
- Multi-session SSH tabs (live interactive shells within TUI) - Native SSH delegation via `tea.ExecProcess` (zero-lag fullscreen SSH, inspired by tamagosh)
- TUI forms for add/edit hosts (replace CLI prompts) - TUI forms for add/edit hosts
- SFTP file browser in TUI tab - Dual-pane SFTP browser (local ↔ remote) with upload/download/delete/rename
- Key & snippet management in TUI - Key & snippet management in TUI
**Priority 2 — Security Enhancement:** **Priority 2 — Security Enhancement:**
- AES-256 encryption for storage - AES-256-GCM encryption for secrets file (inspired by tamagosh)
- Master password protection - Key passphrase support via SSH_ASKPASS
- Secure credential export/import - Known_hosts verification for SFTP connections
**Priority 3 — UX Polish:** **Priority 3 — UX Polish:**
- Configuration profiles - Configuration profiles
@@ -784,10 +793,10 @@ Continue anyway? [y/N]
### Phase 2 Success Metrics ### Phase 2 Success Metrics
- ✅ Rich TUI interface for all operations - ✅ Rich TUI interface for all operations
- ✅ Encrypted credential storage - ✅ Zero-lag SSH via native binary delegation
- ✅ Dual-pane SFTP browser - ✅ Dual-pane SFTP browser (local ↔ remote)
- ✅ Shell completion and documentation - ✅ Shell completion and documentation
- ✅ Enhanced user experience - ✅ Enhanced user experience with Gruvbox palette
--- ---
docs/plans/2024-06-22-hostkeeper-implementation.md
+15 -17
View File
@@ -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 **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 11. **Build System** - Cross-platform compilation
12. **Documentation** - Installation and usage guides 12. **Documentation** - Installation and usage guides
### 📋 Phase 2 Planned (TUI Overhaul) ### 📋 Phase 2 Completed (TUI Overhaul)
1. **Task 15** — Tab Framework & Orange Theme 1. **Task 15** — Tab Framework & Gruvbox Theme
2. **Task 16** — SSH Session Tab (multi-session) 2. **Task 16** — SSH Session Rewrite (native `ssh` via `tea.ExecProcess`, zero-lag)
3. **Task 17** — TUI Host Forms (add/edit) 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 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 manage multiple hosts with different auth methods
- ✅ Can perform SFTP operations (native client)
- ✅ Can export/import credentials across devices - ✅ Can export/import credentials across devices
- ✅ Works on Linux, macOS, Windows, and Termux - ✅ Works on Linux, macOS, Windows, and Termux
- ✅ Secure credential storage with proper permissions - ✅ Secure credential storage with proper permissions
- ✅ User-friendly error messages and help text - ✅ 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. **AES-256-GCM encrypted secrets** (inspired by tamagosh)
2. **Known_hosts verification** for SFTP
1. **Task 15** — TUI Tab Framework & Orange Theme (foundation) 3. **In-app SSH key generation**
2. **Task 16** — SSH Session Tab (multi-session) 4. **Multi-session without lag** — PTY multiplexer + VT terminal emulator
3. **Task 17** — TUI Host Forms (add/edit in TUI) 5. **Cloud sync, custom terminal emulator, web interface**
4. **Task 18** — TUI SFTP Browser
5. **Task 19** — TUI Key & Snippet Management
6. **Future** — Cloud sync, custom terminal emulator, web interface