feat: complete MVP — all 14 tasks done

- Task 13: Full documentation (README, INSTALLATION, USAGE, ARCHITECTURE) - Task 14: Release prep (CHANGELOG, RELEASE_CHECKLIST) - Update PROJECT_STATE.md to reflect 100% completion
2026-06-23 14:06:31 +07:00
parent c2d6aabea0
commit 48c858df0f
7 changed files with 608 additions and 186 deletions
@@ -0,0 +1,128 @@
+# Architecture
+
+## Overview
+
+Hostkeeper follows a layered architecture:
+
+```
+CLI Layer (cmd/hostkeeper/)
+  |
+  | calls
+  v
+Application Layer (pkg/)
+  |
+  | calls
+  v
+Storage Layer (pkg/config/, pkg/storage/)
+  |
+  | reads/writes
+  v
+File System (~/.config/hostkeeper/)
+```
+
+## Directory Structure
+
+```
+cmd/hostkeeper/       — CLI commands (Cobra)
+  ├── main.go         — Entry point
+  ├── root.go         — Root command setup
+  ├── add.go          — Add host command
+  ├── list.go         — List hosts command
+  ├── connect.go      — Connect command
+  ├── edit.go         — Edit host command
+  ├── delete.go       — Delete host command
+  ├── export.go       — Export command
+  ├── import.go       — Import command
+  ├── tui.go          — TUI command entry
+  ├── version.go      — Version command
+  ├── completion.go   — Shell completion
+  └── *_test.go       — CLI command tests
+
+pkg/                  — Library code
+  ├── config/         — Configuration and data directory
+  ├── models/         — Data models (Host, Key, Snippet)
+  ├── storage/        — File and export/import operations
+  ├── errors/         — Error types
+  └── tui/            — TUI implementation (Bubble Tea)
+
+test/                 — Test suites
+  ├── integration/    — End-to-end integration tests
+  └── storage/        — Storage tests
+
+docs/                 — Documentation
+  ├── plans/          — Design and implementation plans
+  ├── INSTALLATION.md
+  ├── USAGE.md
+  └── ARCHITECTURE.md
+```
+
+## Key Components
+
+### Models (`pkg/models/`)
+
+The core data structures:
+
+- **Host** — SSH host with address, credentials, group, tags
+- **Key** — SSH key metadata
+- **Snippet** — Reusable connection snippets
+
+### Configuration (`pkg/config/`)
+
+Manages application configuration, data directory path, and initialization.
+
+### Storage (`pkg/storage/`)
+
+Handles persistent storage:
+- File-based JSON storage per data type
+- Export/import with replace and merge strategies
+- File permission enforcement (0600)
+
+### CLI Layer (`cmd/hostkeeper/`)
+
+Each command follows a consistent pattern:
+1. Parse flags
+2. Load config and storage
+3. Execute business logic
+4. Format output
+
+### TUI (`pkg/tui/`)
+
+Bubble Tea model with:
+- Screen-based navigation (extensible for future screens)
+- Host list view with styled output
+- Keyboard-driven interaction
+
+## Data Flow
+
+### Adding a Host
+
+```
+User → hostkeeper add (flags) → parse args → Host model → storage.SaveHost() → JSON file
+```
+
+### Connecting to a Host
+
+```
+User → hostkeeper connect <name> → findHost() by ID → resolve key → exec native SSH or Go SSH
+```
+
+### Export/Import
+
+```
+Export: storage → marshal JSON → write file
+Import: read file → unmarshal → strategy (merge/replace) → save all
+```
+
+## Security
+
+- Credential files stored with `0600` permissions
+- SSH key content stored within host credentials
+- Direct mode uses Go SSH client (no shell, command execution only)
+- Native SSH mode delegates all terminal handling to system SSH
+
+## Future Architecture
+
+- SQLite database for improved query capabilities
+- Encrypted credential storage (age/gpg)
+- Configuration encryption
+- Plugin system for custom authentication methods