swanadiva
847989df75
- 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
129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# 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
|