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
This commit is contained in:
swanadiva
@@ -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
|
||||
@@ -0,0 +1,113 @@
|
||||
# Installation Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Go 1.21+** — for building from source
|
||||
- **Git** — for cloning the repository
|
||||
- **Make** — optional, for build automation
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: Build from Source
|
||||
|
||||
```bash
|
||||
git clone https://git.tukangketik.id/swanadiva/HostKeeper.git
|
||||
cd hostkeeper
|
||||
make build
|
||||
sudo cp bin/hostkeeper /usr/local/bin/
|
||||
```
|
||||
|
||||
### Method 2: Go Install
|
||||
|
||||
```bash
|
||||
go install git.tukangketik.id/swanadiva/hostkeeper/cmd/hostkeeper@latest
|
||||
```
|
||||
|
||||
This installs to `$GOPATH/bin` or `$HOME/go/bin`.
|
||||
|
||||
### Method 3: Cross-Platform Build
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
```
|
||||
|
||||
Binaries will be in the `build/` directory with SHA256 checksums.
|
||||
|
||||
## Platform-Specific Instructions
|
||||
|
||||
### macOS
|
||||
|
||||
```bash
|
||||
# Install Go via Homebrew
|
||||
brew install go
|
||||
|
||||
# Build and install
|
||||
git clone https://git.tukangketik.id/swanadiva/HostKeeper.git
|
||||
cd hostkeeper
|
||||
make build
|
||||
cp bin/hostkeeper /usr/local/bin/
|
||||
```
|
||||
|
||||
### Linux (Ubuntu/Debian)
|
||||
|
||||
```bash
|
||||
# Install Go
|
||||
sudo apt update
|
||||
sudo apt install golang git make
|
||||
|
||||
# Build and install
|
||||
git clone https://git.tukangketik.id/swanadiva/HostKeeper.git
|
||||
cd hostkeeper
|
||||
make build
|
||||
sudo cp bin/hostkeeper /usr/local/bin/
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
# Install Go from https://golang.org/dl/
|
||||
# Clone repository
|
||||
git clone https://git.tukangketik.id/swanadiva/HostKeeper.git
|
||||
cd hostkeeper
|
||||
|
||||
# Build
|
||||
go build -o hostkeeper.exe ./cmd/hostkeeper
|
||||
```
|
||||
|
||||
### Termux (Android)
|
||||
|
||||
```bash
|
||||
pkg install golang git make
|
||||
git clone https://git.tukangketik.id/swanadiva/HostKeeper.git
|
||||
cd hostkeeper
|
||||
make build
|
||||
cp bin/hostkeeper $PREFIX/bin/
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
hostkeeper version
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
hostkeeper dev (built: ...)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
Ensure the binary is in your PATH:
|
||||
```bash
|
||||
export PATH=$PATH:/usr/local/bin
|
||||
```
|
||||
|
||||
### Build Failures
|
||||
|
||||
```bash
|
||||
make clean
|
||||
make deps
|
||||
make build
|
||||
```
|
||||
+151
@@ -0,0 +1,151 @@
|
||||
# Usage Guide
|
||||
|
||||
## Host Management
|
||||
|
||||
### Add a Host
|
||||
|
||||
Interactive mode:
|
||||
```bash
|
||||
hostkeeper add
|
||||
```
|
||||
|
||||
With flags:
|
||||
```bash
|
||||
hostkeeper add myserver --host 192.168.1.10 --user admin --password mypass
|
||||
hostkeeper add myserver --host 10.0.0.1 --port 2222 --user root --key ~/.ssh/id_rsa
|
||||
hostkeeper add webserver --host example.com --user deploy --password secret --group production --tags web,frontend
|
||||
```
|
||||
|
||||
Flags:
|
||||
- `--host` — hostname or IP address
|
||||
- `--port` — SSH port (default: 22)
|
||||
- `--user` — SSH username
|
||||
- `--password` — SSH password
|
||||
- `--key` — path to SSH private key
|
||||
- `--auth-type` — authentication type (password, key, both)
|
||||
- `--group` — host group for categorization
|
||||
- `--tags` — comma-separated tags
|
||||
- `--notes` — notes about the host
|
||||
|
||||
### List Hosts
|
||||
|
||||
```bash
|
||||
hostkeeper list
|
||||
hostkeeper ls # alias
|
||||
```
|
||||
|
||||
Filter by group or tag:
|
||||
```bash
|
||||
hostkeeper list --group production
|
||||
hostkeeper list --tag web
|
||||
```
|
||||
|
||||
Output formats:
|
||||
```bash
|
||||
hostkeeper list --format table # default
|
||||
hostkeeper list --format json
|
||||
```
|
||||
|
||||
Sort options:
|
||||
```bash
|
||||
hostkeeper list --sort name # default
|
||||
hostkeeper list --sort hostname
|
||||
hostkeeper list --sort group
|
||||
```
|
||||
|
||||
### Connect to a Host
|
||||
|
||||
Connect using system SSH (default, full interactive terminal):
|
||||
```bash
|
||||
hostkeeper connect myserver
|
||||
```
|
||||
|
||||
Connect with Go SSH client (direct mode, no interactive shell):
|
||||
```bash
|
||||
hostkeeper connect myserver --direct
|
||||
```
|
||||
|
||||
Custom timeout:
|
||||
```bash
|
||||
hostkeeper connect myserver --timeout 60
|
||||
```
|
||||
|
||||
### Edit a Host
|
||||
|
||||
Interactive mode:
|
||||
```bash
|
||||
hostkeeper edit myserver
|
||||
```
|
||||
|
||||
With flags (only update what you specify):
|
||||
```bash
|
||||
hostkeeper edit myserver --host 10.0.0.1 --port 2222
|
||||
hostkeeper edit myserver --user root --name myserver-renamed
|
||||
hostkeeper edit myserver --group staging --tags backend
|
||||
```
|
||||
|
||||
### Delete a Host
|
||||
|
||||
With confirmation prompt:
|
||||
```bash
|
||||
hostkeeper delete myserver
|
||||
hostkeeper rm myserver # alias
|
||||
```
|
||||
|
||||
Skip confirmation:
|
||||
```bash
|
||||
hostkeeper delete myserver --force
|
||||
```
|
||||
|
||||
## Data Management
|
||||
|
||||
### Export
|
||||
|
||||
Export all hosts, keys, and snippets to a JSON file:
|
||||
```bash
|
||||
hostkeeper export backup
|
||||
hostkeeper export backup.json
|
||||
```
|
||||
|
||||
### Import
|
||||
|
||||
Import from a previously exported JSON file:
|
||||
```bash
|
||||
hostkeeper import backup.json # merge (default)
|
||||
hostkeeper import backup.json --strategy replace
|
||||
hostkeeper import backup.json --dry-run # preview only
|
||||
```
|
||||
|
||||
Merge strategies:
|
||||
- `merge` — keep existing data, add new items (default)
|
||||
- `replace` — replace all existing data with imported data
|
||||
|
||||
## TUI Interface
|
||||
|
||||
Launch the interactive terminal UI:
|
||||
```bash
|
||||
hostkeeper tui
|
||||
```
|
||||
|
||||
Navigation:
|
||||
- `↑`/`k` — move up
|
||||
- `↓`/`j` — move down
|
||||
- `Enter` — select host
|
||||
- `q` — quit
|
||||
|
||||
## Shell Completion
|
||||
|
||||
Generate shell completion scripts:
|
||||
```bash
|
||||
hostkeeper completion bash > /etc/bash_completion.d/hostkeeper
|
||||
hostkeeper completion zsh > /usr/local/share/zsh/site-functions/_hostkeeper
|
||||
hostkeeper completion fish > ~/.config/fish/completions/hostkeeper.fish
|
||||
hostkeeper completion powershell > hostkeeper.ps1
|
||||
```
|
||||
|
||||
## Global Flags
|
||||
|
||||
- `--config` — path to custom config file
|
||||
- `-v`/`--verbose` — verbose output (-v for info, -vv for debug)
|
||||
- `--debug` — enable debug mode
|
||||
- `--help` — display help
|
||||
Reference in New Issue
Block a user