# Hostkeeper V2 — AI Session Checkpoint > **Purpose**: Memungkinkan AI agent berikutnya melanjutkan development tanpa mengulang atau merusak. > **Last Updated**: 2026-07-07 > **Current Phase**: Sprint 1 selesai, Sprint 2 sedang dikerjakan --- ## 1. Repository Structure ``` hostkeeper/ (root — bersih untuk V2) ├── v1/ ← FROZEN — V1 CLI/TUI, jangan disentuh │ ├── cmd/hostkeeper/ V1 cobra CLI commands │ ├── internal/errors/ V1 error handling │ ├── internal/models/ V1 data models │ ├── pkg/ Shared packages (ssh, crypto, storage, config, knownhosts, tui) │ ├── test/ V1 integration & unit tests (105 passing) │ ├── docs/plans/ V1 design & implementation docs │ ├── go.mod module git.tukangketik.id/swanadiva/hostkeeper │ ├── Makefile │ └── PROJECT_STATE.md V1 full project state ├── app/ ← (BELUM DIBUAT) V2 backend GoFiber + views + static ├── mobile/ ← (BELUM DIBUAT) V2 mobile wrapper ├── template/ ← Referensi UI React (Lumina System) — hanya untuk desain │ └── src/components/ 7 React screens ├── docs/ ← Dokumentasi perencanaan V2 (HTMX) │ ├── ARCHITECTURE_HTMX.md Arsitektur HTMX (dokumen utama) │ ├── ARCHITECTURE.md Ringkasan + pointer ke HTMX │ ├── API.md REST + WebSocket spec │ ├── DATA_MODELS.md Data models (Host, Snippet, Key, dll) │ ├── UI_COMPONENTS.md HTMX component tree (bukan React) │ ├── SPRINT_PLAN.md Sprint 0-6 untuk HTMX │ ├── BUILD_SYSTEM.md Build pipeline (Go + CSS, tanpa Vite) │ ├── TIMELINE.md Timeline 3.5 minggu │ ├── PERFROMANCE.md Performance & stability │ ├── UI_TERMIUS_REFERENCE.md Termius visual reference │ └── PROGRESS.md Status tracker ├── AGENTS.md ← file ini (checkpoint AI) └── README.md Git branches: - main → V2 development (current) - v1-snapshot → V1 snapshot before move (safety backup) ``` --- ## 2. V1 Status — FROZEN 🧊 | Aspek | Detail | |-------|--------| | Kode | Semua di `v1/` — cmd/, internal/, pkg/, test/ | | Build | `cd v1 && go build ./cmd/hostkeeper` | | Test | `cd v1 && go test ./...` — 105 tests passing | | Branch backup | `v1-snapshot` — snapshot sebelum dipindah ke subdirektori | | Aturan | **JANGAN** mengubah file di `v1/` | --- ## 3. V2 Architecture — HTMX (Keputusan Penting) **Hostkeeper V2 menggunakan GoFiber + HTMX, BUKAN React.** Alasan: - Developer lebih nyaman dengan Go daripada JavaScript - ~90% kode adalah Go + HTML template - Hanya ~410 baris JS yang diperlukan (xterm.js, clipboard, toggle) - Build lebih sederhana — tanpa Vite, npm, TypeScript, Webpack - Bisa berjalan di browser biasa tanpa Electron ``` ┌───────────────────────────────────────────────────┐ │ Browser / Electron WebView │ │ ┌─────────────────────────────────────────────┐ │ │ │ HTMX (14kb) + Alpine.js (15kb) + xterm.js │ │ │ │ ● HTMX: search, filter, modal, form, nav │ │ │ │ ● Alpine: client state (toast, toggle) │ │ │ │ ● xterm.js: terminal (halaman terminal) │ │ │ │ ● Vanilla JS: clipboard, toggle, utils │ │ │ └────────────────┬────────────────────────────┘ │ │ │ hx-get/hx-post/hx-ws │ │ ┌────────────────▼────────────────────────────┐ │ │ │ GoFiber v2 (localhost:1947) │ │ │ │ ┌──────────────┐ ┌────────────────────┐ │ │ │ │ │ HTML handler │ │ WebSocket/SSH │ │ │ │ │ │ (html/templ.) │ │ (xterm.js I/O) │ │ │ │ │ └──────┬───────┘ └────────────────────┘ │ │ │ │ ┌────▼────┐ │ │ │ │ │ v1/pkg/ │ (via replace directive) │ │ │ │ └─────────┘ │ │ │ └──────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ ``` | Library | Ukuran | Fungsi | |---------|--------|--------| | HTMX | 14kb | HTML-over-HTTP interaktivitas | | Alpine.js | 15kb | Client state (modal, toast, tab) | | xterm.js | ~100kb | Terminal emulator (WAJIB) | | TailwindCSS v4 | ~27kb | Utility-first CSS | --- ## 4. V2 Status — Sprint 1 Complete ### ✅ Sudah Selesai - Semua dokumentasi diupdate ke HTMX (10 file di `docs/`) - Template UI dianalisis (Lumina System — bright-tech glassmorphic, TailwindCSS v4) - Root dibersihkan — V1 di `v1/`, V2 siap dimulai di `app/` - `template/` tetap sebagai referensi desain (warna, layout, spacing) - Bug template sudah diidentifikasi (animasi CSS, w-4.5, error boundary, dll) - **Sprint 0**: GoFiber v2 server + HTMX + Alpine.js + TailwindCSS v4 + custom CSS + layout + nav + health endpoint - **Sprint 1**: Host model (8 mock hosts), dashboard CRUD, search/filter HTMX, grid/list Alpine toggle, add host modal (Alpine events), delete host (hx-delete), transfers panel ### ❌ Belum Dimulai / In Progress - **Sprint 2 (IN PROGRESS)**: Snippets + Keychain - Sprint 3: Settings + Brief - Sprint 4: SFTP Dual-Pane - Sprint 5: Terminal + xterm.js - Sprint 6: Storage Integration ### 🐛 Bug Template (dari template/src/ — catatan saat implementasi) 1. **P0**: Missing CSS keyframes (fade-in, scale-up, slide-in) → tambah di `custom.css` 2. **P1**: `w-4.5 h-4.5` → ganti `w-5 h-5` 3. **P2**: Tidak ada Error Boundary → not applicable (HTML template) 4. **P2**: `as any` casts → not applicable (Go typed) 5. **P3**: Auto-focus loss → handle via JS `focus()` di Alpine --- ## 5. Struktur Folder V2 (Aktual) ``` app/backend/ ├── main.go ← Fiber app entry ├── go.mod ← module git.tukangketik.id/swanadiva/hostkeeper/v2 ├── internal/ │ ├── handler/ ← HTTP handlers (render HTML) │ │ ├── dashboard.go │ │ ├── snippets.go │ │ ├── keychain.go │ │ ├── terminal.go │ │ ├── sftp.go │ │ ├── settings.go │ │ ├── brief.go │ │ └── health.go │ ├── model/ ← Go structs (Host, Snippet, Key, dll) │ │ ├── host.go │ │ ├── snippet.go │ │ └── keychain.go │ ├── template/ ← Template helper funcs │ └── middleware/ ← View data injection ├── static/ │ ├── css/ ← output.css + custom.css │ ├── js/ ← htmx.min.js, alpine.min.js, utils.js, clipboard.js, terminal.js │ └── xterm/ ← xterm.js lib └── views/ ← Semua template flat (tidak ada subfolder partials/) ├── layout.html ├── nav.html ├── index.html ├── host_list.html ├── host_modal.html ├── snippets.html ├── snippet_grid.html ├── snippet_modal.html ├── keychain.html ├── key_grid.html ├── key_modal.html ├── terminal.html ├── sftp.html ├── settings.html └── brief.html ``` --- ## 6. Yang Harus Dilakukan Selanjutnya (First Actions) Urutan eksekusi saat development dimulai: ``` Sprint 0 — Setup: Step 1: mkdir -p app/backend Step 2: cd app/backend && go mod init git.tukangketik.id/swanadiva/hostkeeper/v2 Step 3: go get github.com/gofiber/fiber/v2 Step 4: go get github.com/gofiber/template/html/v2 Step 5: Buat main.go (Fiber app skeleton + static + template engine) Step 6: Download htmx.min.js, alpine.min.js ke static/js/ Step 7: Setup TailwindCSS v4: input.css → npx @tailwindcss/cli Step 8: Buat custom.css (dot-grid, glassmorphism, keyframes) Step 9: Buat views/layout.html + views/index.html + nav.html Step 10: Buat handler/health.go + handler/dashboard.go Step 11: Verify: buka http://localhost:1947 — layout terlihat ``` --- ## 7. Path Penting & Referensi | Untuk | Lihat di | |-------|----------| | Arsitektur HTMX lengkap | `docs/ARCHITECTURE_HTMX.md` | | API spec | `docs/API.md` | | Data models (Go struct) | `docs/DATA_MODELS.md` | | HTMX component tree | `docs/UI_COMPONENTS.md` | | Sprint plan detail | `docs/SPRINT_PLAN.md` | | Timeline 3.5 minggu | `docs/TIMELINE.md` | | Build system | `docs/BUILD_SYSTEM.md` | | Status tracker | `docs/PROGRESS.md` | | Template desain (React) | `template/AGENTS.md` (Lumina System) | | Template komponen (referensi) | `template/src/components/` | | V1 shared packages | `v1/pkg/ssh/`, `v1/pkg/crypto/`, `v1/pkg/storage/`, `v1/pkg/config/`, `v1/pkg/knownhosts/` | | V1 build & test | `cd v1 && go build ./cmd/hostkeeper && go test ./...` | --- ## 8. Aturan Penting - **JANGAN** mengubah file di `v1/` — V1 FROZEN - **JANGAN** mengubah `template/` — itu referensi desain, bukan source aktif - Semua kode V2 baru di `app/` - Saat reuse `v1/pkg/*`, pakai `go.mod replace` — jangan copy - Template React hanya untuk referensi visual (warna, layout, spacing) - Gunakan TailwindCSS v4 + custom CSS (Lumina System) - Pakai bahasa Indonesia untuk komunikasi dengan user (swanadiva)