refactor: move V1 code into v1/ subdirectory

- git mv cmd/ internal/ pkg/ test/ go.mod go.sum Makefile build.sh docs/ v1/ - Create v1/README.md with V1 documentation - Update root README for V1 + V2 structure - V1 still builds (cd v1 && go build ./cmd/hostkeeper) and 105 tests pass - Root is now clean for V2 development
2026-07-07 11:56:27 +07:00
parent 8ebdebedc8
commit 847989df75
68 changed files with 58 additions and 116 deletions
@@ -0,0 +1,640 @@
+# Hostkeeper Project State & Handoff Guide
+
+> **Purpose**: Enable seamless continuation of development by any agent/LLM across sessions
+> 
+> **Last Updated**: 2025-01-31 (Phase 3 Testing Complete)
+> **Current Status**: ✅ MVP Complete — Phase 1 Done, Phase 2 Done, Phase 3 Testing Done
+> **Phase**: Phase 3 (Documentation)
+
+---
+
+## 🚀 Quick Start for New Agents
+
+### Immediate Context (Read This First)
+
+**Project**: Hostkeeper - Cross-platform SSH/SFTP management tool
+**Tech Stack**: Go 1.21+, Cobra, Bubble Tea, golang.org/x/crypto/ssh
+**Architecture**: Monolithic CLI with embedded TUI
+**Current Phase**: MVP Implementation (estimated 3-4 weeks)
+
+### What's Already Done
+✅ Complete design documentation (`docs/plans/2024-06-22-hostkeeper-design.md`)
+✅ Detailed implementation plan (`docs/plans/2024-06-22-hostkeeper-implementation.md`)
+✅ Git repository initialized
+✅ Project structure defined
+✅ **Task 1**: Project setup (go.mod, Makefile, .gitignore, main.go)
+✅ **Task 2**: Core data models (`internal/models/models.go`) + JSON storage (`pkg/storage/`)
+✅ **Task 3**: Configuration management (`pkg/config/config.go`)
+✅ **Task 4**: Error handling framework (`internal/errors/`) + tests passing
+✅ **Task 5**: SSH client (`pkg/ssh/`) + tests passing
+✅ **Task 6**: CLI Framework Setup - Cobra root, version, completion (`cmd/hostkeeper/`)
+✅ **Task 7**: Add command (`cmd/hostkeeper/add.go`) - add hosts with flags/interactive + tests
+✅ **Task 8**: List command (`cmd/hostkeeper/list.go`) - list/filter/sort hosts + tests
+✅ **Bug Fix**: Fixed deadlock in JSON storage (RLock within Lock)
+
+### What's Been Done
+✅ **Task 13**: Documentation — README, INSTALLATION, USAGE, ARCHITECTURE
+✅ **Task 14**: Release — CHANGELOG, RELEASE_CHECKLIST, git tag v1.0.0
+
+**🔥 All 14 MVP tasks complete! Project is ready for deployment.**
+
+### Post-MVP Fixes
+✅ TUI layout overhaul: centered border boxes, per-row centering, context-specific footers
+✅ Status bar removed; keybindings moved inside each tab's border box footer
+✅ SFTP browser: full-width panes, SFTP-specific keybindings
+✅ Host list footer: added `Ctrl+E:edit`
+✅ UUID + timestamps auto-generated in TUI form `submit()` methods
+✅ UUID + timestamps auto-generated in storage layer (`SaveHost`, `SaveKeyPair`, `SaveSnippet`)
+✅ Git history cleaned of committed binary; `.gitignore` fixed
+✅ **host_form_tab.go**: Space/Left/Right passthrough to text input (fixes typing spaces + cursor nav)
+✅ **tui.go**: Key + snippet list refresh on save/delete
+✅ **tabs.go**: WindowSizeMsg forwarded to all tabs on resize
+✅ **sftp_browser_tab.go footer**: Added `Enter/→:open`, `←/Backspace:up`
+✅ **Form tab footers**: Added `Shift+Tab:prev`, `↑↓:nav`
+
+### Done: Responsive Layout Overhaul
+✅ **NEW `responsive.go`**: Shared helpers for adaptive layout (`wrapFooter`, `adaptiveSidePad`, `clampWidth`, `truncateStr`)
+✅ Footer auto-wraps to multi-line (full labels preserved) — no more overflow on narrow terminals
+✅ Box width clamped to terminal width across all tabs
+✅ Host/key/snippet rows truncated with `…` for long names; compact format on narrow screens
+✅ SFTP panes stack vertically when terminal < 50 cols
+✅ Tab bar truncates names on overflow
+✅ Form contentW minimum lowered from 50 to 30 for mobile (Termux)
+✅ Fixed bug: key_list_tab.go & snippet_list_tab.go dropped last row (`rows[:len(rows)-1]` excluded real data)
+✅ Breakpoints: compact (<60 cols / mobile), medium (60–100 / tablet), wide (≥100 / desktop)
+
+### Done: SFTP Stacked Mode Fix
+✅ **File**: `pkg/tui/sftp_browser_tab.go`
+✅ Stacked mode (<50 cols): render cuma ACTIVE pane (bukan 2 pane)
+✅ Pane indicator bar: `[Local]  Remote` — active disorot hijau (StatusBarStyle)
+✅ Side-by-side mode (>=50 cols): tidak diubah, tetap 2 pane
+✅ Default active pane: Local (bukan Remote)
+✅ Border height fix: `renderPane` sekarang terima `maxH` parameter, `paneStyle.Height(maxH)` → border selalu konsisten tingginya, tidak naik-turun sesuai scroll
+✅ Stacked mode: `maxH = t.height - 6` (title + indicator + border + footer)
+✅ Side-by-side mode: `maxH = t.height - 5` (title + border + footer)
+
+---
+
+## 📊 Current Project Status
+
+### Completion Matrix
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| **Planning** | ✅ 100% | Design and implementation plans complete |
+| **Setup** | ✅ 100% | go.mod, Makefile, .gitignore, main.go |
+| **Core Models** | ✅ 100% | Host, KeyPair, Snippet, AppConfig models + JSON storage |
+| **Config** | ✅ 100% | Cross-platform config management |
+| **Errors** | ✅ 100% | AppError + ConnectionError + SSH error handler |
+| **SSH Client** | ✅ 100% | Password + key auth, Execute, Connect/Close |
+| **CLI Framework** | ✅ 100% | Cobra root, version, completion commands |
+| **CLI Commands** | ✅ 100% | All 11 commands: add, list, connect, edit, delete, export, import, tui, completion, version, help |
+| **TUI** | ✅ 100% | Bubble Tea TUI with host list navigation |
+| **Testing** | ✅ 100% | All unit + integration tests passing |
+| **Documentation** | ✅ 100% | README, INSTALLATION, USAGE, ARCHITECTURE guides |
+
+### Overall Progress: **🎉 100% Complete** (All 14 MVP Tasks Done)
+
+---
+
+## 🎯 Implementation Task Status
+
+### Task Breakdown (from implementation plan)
+
+#### ✅ Task 1: Project Setup and Dependencies
+- **Status**: ✅ Completed
+- **Priority**: CRITICAL (must be first)
+- **Deliverables**: go.mod, project structure, Makefile
+- **Files Created**: 
+  - `go.mod`, `go.sum` (module: `git.tukangketik.id/swanadiva/hostkeeper`)
+  - `Makefile`, `.gitignore`
+  - `cmd/hostkeeper/main.go`
+
+#### ✅ Task 2: Core Data Models and Storage Layer
+- **Status**: ✅ Completed
+- **Priority**: CRITICAL
+- **Deliverables**: Host, KeyPair, Snippet, AppConfig models + JSON storage
+- **Files Created**:
+  - `internal/models/models.go` — all data models + `DefaultConfig()`
+  - `pkg/storage/storage.go` — Storage interface, ExportData, MergeStrategy
+  - `pkg/storage/json_storage.go` — JSONStorage implementation with file locking
+
+#### ✅ Task 3: Configuration Management
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Cross-platform config load/save functionality
+- **Files Created**:
+  - `pkg/config/config.go` — Config struct, OS-aware paths (macOS/Linux/Windows), auto-create defaults
+
+#### ✅ Task 4: Error Handling Framework
+- **Status**: ✅ Completed (all tests passing)
+- **Priority**: HIGH
+- **Deliverables**: Error types, SSH error handler
+- **Files Created**:
+  - `internal/errors/errors.go` — AppError type with codes, Unwrap support
+  - `internal/errors/connection_errors.go` — ConnectionError, HandleSSHError, FormatConnectionError
+  - `test/errors_test.go` — 5 test functions, all passing
+
+#### ✅ Task 5: SSH Client Implementation
+- **Status**: ✅ Completed (all tests passing)
+- **Priority**: CRITICAL
+- **Deliverables**: SSH connection client with auth
+- **Files Created**:
+  - `pkg/ssh/client.go` — Client struct, Connect, Execute, Close, IsConnected
+  - `pkg/ssh/auth.go` — Password/key/both auth, default key discovery
+  - `test/ssh/ssh_test.go` — 4 test functions, all passing
+
+#### ✅ Task 6: CLI Framework Setup
+- **Status**: ✅ Completed
+- **Priority**: CRITICAL
+- **Deliverables**: Cobra framework, basic commands
+- **Files Created**:
+  - `cmd/hostkeeper/main.go` — Entry point with Execute() function
+  - `cmd/hostkeeper/root.go` — Root command with PersistentPreRunE config init
+  - `cmd/hostkeeper/completion.go` — Shell completion (bash/zsh/fish/powershell)
+  - Includes `version` subcommand and `-v/--verbose`, `--debug` flags
+
+#### ✅ Task 7: Add Command
+- **Status**: ✅ Completed (all tests passing)
+- **Priority**: CRITICAL
+- **Deliverables**: `add` command for registering hosts
+- **Files Created**:
+  - `cmd/hostkeeper/add.go` — add host with flags/interactive, password/key auth, groups, tags, notes
+  - `cmd/hostkeeper/add_test.go` — tests for add command (flag parsing, storage integration)
+
+#### ✅ Task 8: List Command
+- **Status**: ✅ Completed (all tests passing)
+- **Priority**: CRITICAL
+- **Deliverables**: `list` command for displaying hosts
+- **Files Created**:
+  - `cmd/hostkeeper/list.go` — list hosts with filter (group/tag), sort, table/JSON/wide output formats
+  - `cmd/hostkeeper/list_test.go` — tests for list command (filtering, formatting)
+
+#### ✅ Task 9: Connect Host Command
+- **Status**: ✅ Completed
+- **Priority**: CRITICAL
+- **Deliverables**: Connect to saved SSH hosts via native SSH or Go SSH client
+- **Files Created**:
+  - `cmd/hostkeeper/connect.go` — Connect command with native SSH (default) and direct Go SSH (--direct) modes
+  - `cmd/hostkeeper/connect_test.go` — Tests for command existence, flags, and SSH arg building
+
+#### ✅ Edit Host Command
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Edit existing SSH host configurations
+- **Files Created**:
+  - `cmd/hostkeeper/edit.go` — Edit command with flag-based and interactive modes
+  - `cmd/hostkeeper/edit_test.go` — Tests for command existence and flags
+
+#### ✅ Delete Host Command
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Delete SSH hosts with confirmation prompt
+- **Files Created**:
+  - `cmd/hostkeeper/delete.go` — Delete command with --force flag to skip confirmation
+  - `cmd/hostkeeper/delete_test.go` — Tests for command existence, alias, and flags
+
+#### ✅ Task 10: Basic TUI Implementation
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Bubble Tea TUI with host list screen
+- **Files Created**:
+  - `pkg/tui/tui.go` — TUI model with Init/Update/View (Bubble Tea)
+  - `pkg/tui/host_list.go` — Host list renderer with keyboard navigation
+  - `pkg/tui/tui_test.go` — Tests for TUI initialization and host loading
+  - `cmd/hostkeeper/tui.go` — CLI `tui` command
+
+#### ✅ Task 11: Export/Import Commands
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Export/import hosts, keys, snippets for backup/transfer
+- **Files Created**:
+  - `cmd/hostkeeper/export.go` — Export command with JSON format (default) and include-keys flag
+  - `cmd/hostkeeper/import.go` — Import command with replace/merge strategies and dry-run preview
+  - `test/storage/export_import_test.go` — Integration test for export/import round-trip
+
+#### ✅ Task 12: Build and Testing
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Build system and integration tests
+- **Files Created/Modified**:
+  - `Makefile` — Added test-coverage, verify targets; updated clean to remove coverage files
+  - `build.sh` — Cross-platform build script with SHA256 checksums
+  - `test/integration/integration_test.go` — End-to-end workflow tests (add, list, get, update, export/import, delete, config)
+
+#### ✅ Task 13: Documentation
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: README, INSTALLATION, USAGE, ARCHITECTURE guides
+- **Files Created/Updated**:
+  - `README.md` — Full rewrite with features, quick start, commands, tech info
+  - `docs/INSTALLATION.md` — Cross-platform installation guide
+  - `docs/USAGE.md` — Detailed command usage with examples
+  - `docs/ARCHITECTURE.md` — System architecture overview
+
+#### ✅ Task 14: Final Testing and Release
+- **Status**: ✅ Completed
+- **Priority**: HIGH
+- **Deliverables**: Release preparation, CHANGELOG, git tag v1.0.0
+- **Files Created**:
+  - `CHANGELOG.md` — Release changelog
+  - `RELEASE_CHECKLIST.md` — Pre/post-release checklist
+- **Git Tag**: `v1.0.0`
+
+---
+
+## 🗺️ Development Roadmap
+
+### Current Week Focus
+**Target**: Complete Tasks 12+ (Build, Testing, Docs, Release)
+
+### This Sprint
+- [x] Project setup and dependencies
+- [x] Core data models and storage
+- [x] Configuration management
+- [x] Error handling framework
+- [x] SSH client implementation
+- [x] CLI framework setup
+- [x] Add host command
+- [x] List hosts command
+- [x] Connect host command
+- [x] Edit host command
+- [x] Delete host command
+- [x] TUI implementation
+- [x] Export/Import commands
+- [x] Build system and integration tests
+
+### Next Sprint
+- [ ] SFTP Performance: caching directory listings, batch directory reads
+- [ ] SFTP File Transfer: download (remote→local), upload (local→remote)
+- [ ] Phase 2 Priority 2: Security Enhancement (AES-256-GCM, key passphrase, known_hosts)
+
+### Final Sprint
+- [ ] Phase 2 Priority 3: UX Polish (configuration profiles, theme customization, enhanced error messages)
+- [ ] Testing and integration
+- [ ] Documentation completion
+
+---
+
+## 🛠️ Technical Stack & Dependencies
+
+### Go Dependencies
+```go
+// Required packages (to be installed in Task 1)
+github.com/spf13/cobra@latest        // CLI framework
+github.com/spf13/viper@latest      // Configuration
+github.com/charmbracelet/bubbletea // TUI framework
+github.com/charmbracelet/lipgloss  // TUI styling
+golang.org/x/crypto@latest         // SSH/SFTP
+github.com/google/uuid@latest      // UUID generation
+github.com/joho/godotenv@latest    // Environment variables
+```
+
+### Build Tools
+- `make` - Build automation
+- `go test` - Testing framework
+- `go fmt` - Code formatting
+
+### Platform Support
+- Linux (x86_64, ARM64, ARM)
+- macOS (x86_64, ARM64)  
+- Windows (x86_64)
+- Termux/Android (ARM)
+
+---
+
+## 📁 Project Structure
+
+```
+hostkeeper/
+├── cmd/
+│   └── hostkeeper/          # Main application
+│       ├── main.go          # Entry point
+│       ├── root.go          # Root command
+│       └── *.go             # Subcommands
+├── pkg/
+│   ├── ssh/                 # SSH client
+│   ├── sftp/                # SFTP client (Phase 2)
+│   ├── storage/             # Data persistence
+│   ├── config/              # Configuration
+│   └── tui/                 # Terminal UI
+├── internal/
+│   ├── models/              # Data models
+│   └── errors/              # Error handling
+├── test/                    # Tests
+├── docs/
+│   └── plans/               # Design docs
+├── utils/                   # Utilities
+├── build/                   # Build output
+├── go.mod
+├── go.sum
+├── Makefile
+├── README.md
+└── PROJECT_STATE.md         # THIS FILE
+```
+
+---
+
+## 🔄 Handoff Procedures
+
+### For New Agents/LLMs
+
+#### Step 1: Read This File
+- **Start here**: This `PROJECT_STATE.md` file
+- **Then read**: `docs/plans/2024-06-22-hostkeeper-design.md` (architecture)
+- **Then read**: `docs/plans/2024-06-22-hostkeeper-implementation.md` (tasks)
+
+#### Step 2: Check Current Status
+```bash
+# Check git status
+git status
+
+# Check recent commits
+git log --oneline -5
+
+# Check what files exist
+find . -name "*.go" -type f
+```
+
+#### Step 3: Determine Next Action
+1. Look at "Implementation Task Status" above
+2. Find first incomplete task
+3. Refer to implementation plan for detailed instructions
+4. Execute following TDD approach
+
+#### Step 4: Update This File
+After completing any task, update the corresponding status section:
+```markdown
+#### ✅ Task X: [Task Name]
+- **Status**: Completed
+- **Completion Date**: [Date]
+- **Notes**: [Any important notes]
+- **Commits**: [Relevant commit hashes]
+```
+
+### For Returning Agents
+
+#### Quick Status Check
+```bash
+# What's been done recently?
+git log --oneline --since="2 weeks ago" | head -10
+
+# What tests are passing?
+make test 2>&1 | tail -20
+
+# What's the current state?
+go run cmd/hostkeeper/main.go --version
+```
+
+#### Resume Work
+1. Check "Implementation Task Status" in this file
+2. Find last completed task
+3. Continue with next incomplete task
+4. Update status as you progress
+
+---
+
+## 🧪 Testing Strategy
+
+### Test Categories
+1. **Unit Tests** - Individual component testing
+2. **Integration Tests** - Cross-component testing  
+3. **E2E Tests** - Full workflow testing
+
+### Running Tests
+```bash
+# All tests
+make test
+
+# With coverage
+make test-coverage
+
+# Specific package
+go test ./pkg/storage -v
+
+# Watch mode (if installed)
+go test ./... -watch
+```
+
+### Current Test Coverage
+- **Target**: 80%+ coverage
+- **Current**: ~30% (error handling + SSH client tests passing)
+- **Priority**: Write tests first (TDD approach)
+
+---
+
+## 🚨 Known Issues & Limitations
+
+### Current Limitations (MVP Scope)
+- No encryption (Phase 2)
+- No cloud sync (Phase 3)
+- No custom terminal emulator (Phase 2)
+- Basic SFTP only (native client, no TUI)
+
+### Technical Debt
+- None yet (project just started)
+
+### Security Considerations
+- File permissions must be 0600 for sensitive files
+- No password/key logging in errors
+- Memory clearing for sensitive data (Phase 2)
+
+---
+
+## 📚 Documentation Index
+
+### Essential Reading (Priority Order)
+1. **`PROJECT_STATE.md`** (this file) - Current status and handoff
+2. **`docs/plans/2024-06-22-hostkeeper-design.md`** - Architecture and design
+3. **`docs/plans/2024-06-22-hostkeeper-implementation.md`** - Implementation tasks
+
+### Additional Documentation
+- `README.md` - Project overview and quick start
+- `docs/INSTALLATION.md` - Installation guide
+- `docs/USAGE.md` - Usage documentation
+- `docs/ARCHITECTURE.md` - Detailed architecture
+
+---
+
+## 🎯 Success Criteria
+
+### MVP Success Metrics
+- ✅ Can establish SSH connections (via native SSH)
+- ✅ Can manage multiple hosts
+- ✅ Can perform SFTP operations
+- ✅ Can export/import credentials
+- ✅ Works on all target platforms
+- ✅ Secure credential storage
+- ✅ User-friendly error messages
+
+### Current Progress: 5/7 criteria met (SFTP + encrypted storage deferred to Phase 2)
+
+---
+
+## 🔄 Version Control Strategy
+
+### Branch Strategy
+- `main` - Production code
+- `feature/*` - Feature branches
+- `bugfix/*` - Bug fixes
+
+### Commit Conventions
+```bash
+# Feature commits
+git commit -m "feat: add SSH client implementation"
+
+# Bug fixes
+git commit -m "fix: handle connection timeout properly"
+
+# Documentation
+git commit -m "docs: update installation guide"
+
+# Tests
+git commit -m "test: add SSH client integration tests"
+```
+
+### Release Tagging
+```bash
+# Format: v[MAJOR].[MINOR].[PATCH]
+git tag -a v1.0.0 -m "Initial MVP release"
+```
+
+---
+
+## 💻 Development Workflow
+
+### Getting Started (Fresh Clone)
+```bash
+# Clone repository
+git clone <repo-url>
+cd hostkeeper
+
+# Install dependencies
+go mod download
+
+# Run tests
+make test
+
+# Build project
+make build
+
+# Run application
+./build/hostkeeper --help
+```
+
+### Daily Workflow
+```bash
+# Pull latest changes
+git pull origin main
+
+# Check status (THIS FILE)
+# Look at "Current Project Status" section
+
+# Find next task
+# Look at "Implementation Task Status" section
+
+# Work on task
+# Follow implementation plan
+
+# Test changes
+make test
+
+# Commit changes
+git add .
+git commit -m "feat: descriptive message"
+
+# Push changes
+git push origin main
+```
+
+---
+
+## 🔧 Debugging & Troubleshooting
+
+### Common Issues
+
+#### Build Failures
+```bash
+# Clean and retry
+make clean
+make build
+
+# Check dependencies
+go mod verify
+go mod tidy
+```
+
+#### Test Failures
+```bash
+# Run with verbose output
+go test -v ./...
+
+# Run specific test
+go test ./test -run TestSpecificFunction
+```
+
+#### Import Errors
+```bash
+# Verify module structure
+go mod tidy
+
+# Check go.mod
+cat go.mod
+```
+
+---
+
+## 📞 Contact & Support
+
+### Project Links
+- Repository: [GitHub URL]
+- Issues: [GitHub Issues URL]
+- Discussions: [GitHub Discussions URL]
+
+### Getting Help
+1. Check documentation in `docs/`
+2. Search existing issues
+3. Create new issue with:
+   - Clear description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment details
+
+---
+
+## 🎓 Learning Resources
+
+### For New Contributors
+- Go Documentation: https://golang.org/doc/
+- Cobra Framework: https://github.com/spf13/cobra
+- Bubble Tea: https://github.com/charmbracelet/bubbletea
+- SSH in Go: https://pkg.go.dev/golang.org/x/crypto/ssh
+
+### Project-Specific
+- Design decisions: `docs/plans/2024-06-22-hostkeeper-design.md`
+- Implementation guide: `docs/plans/2024-06-22-hostkeeper-implementation.md`
+- Code examples: `test/` directory
+
+---
+
+## 📊 Progress Tracking
+
+### Completion Timeline
+- **Start Date**: 2024-06-22
+- **Planning Complete**: 2024-06-22 ✅
+- **Target MVP**: 2024-07-20 (3-4 weeks)
+- **Current Phase**: MVP Release
+
+### Milestone Tracking
+- [x] Milestone 1: Foundation (Tasks 1-6) - Week 1 ✅ COMPLETE
+- [x] Task 7-9: Add, List, Connect commands ✅ COMPLETE
+- [x] Edit & Delete commands ✅ COMPLETE
+- [x] Milestone 2: Core Features (Tasks 7-10) - Week 2-3 ✅ COMPLETE
+- [x] Milestone 3: Polish & Release (Tasks 11-14) - Week 4 ✅ COMPLETE
+- [x] **🏆 ALL 14 MVP TASKS COMPLETE** 🏆
+
+---
+
+**🔄 Remember**: After completing any task, update the "Implementation Task Status" section above to maintain accurate project state for future agents/sessions.
+
+**📝 Note**: This file should be updated after every significant development session to ensure continuity across agents and time.