docs: update design + impl plan — native SSH delegation, Gruvbox theme, dual-pane SFTP
This commit is contained in:
swanadiva
@@ -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 <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:**
|
||||
| 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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
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**
|
||||
Reference in New Issue
Block a user