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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user