# Hostkeeper V2 — AI Session Checkpoint > **Purpose**: Memungkinkan AI agent berikutnya melanjutkan development tanpa mengulang atau merusak. > **Last Updated**: 2026-07-07 > **Current Phase**: UI Fix — memperbaiki 107 visual issue dari `docs/PERBAIKANUI.md` --- ## 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/ ← 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 │ └── PERBAIKANUI.md UI fix checklist (107 task) ├── 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 0—6 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 - **Sprint 2**: Snippets + Keychain CRUD, clipboard.js, utils.js - **Sprint 3**: Settings + Brief, tabs, toggles, danger zone - **Sprint 4**: SFTP Dual-Pane, breadcrumb, file icons by type, create/delete - **Sprint 5**: Terminal + xterm.js + WebSocket mock shell, tab management - **Sprint 6**: JSON file persistence (store package), `go.mod replace` directive for V1 crypto+knownhosts, model SSH fields, real SSH client for terminal (falls back to mock), dynamic host list from server ### 🐛 UI Fix Checklist — Lihat `docs/PERBAIKANUI.md` - **107 task** teridentifikasi dari audit visual vs template React - Acuan utama: 7 file di `template/src/components/` - Setiap task dihapus dari checklist setelah selesai - Urutan: Dashboard (P0) → Terminal (P0) → Snippets (P0) → Keychain/SFTP/Settings/Brief (P1) --- ## 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 │ ├── store/ ← JSON file persistence (store package) │ │ ├── store.go │ │ ├── host.go │ │ ├── snippet.go │ │ ├── key.go │ │ ├── settings.go │ │ └── devices.go │ ├── sshconn/ ← Real SSH client for terminal │ │ └── client.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/) ├── 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 (UI Fix) 1. Baca `docs/PERBAIKANUI.md` — 107 task teridentifikasi 2. Urutan: Dashboard (P0) → Terminal (P0) → Snippets (P0) → Keychain (P1) → SFTP (P1) → Settings (P1) → Brief (P1) → Global (P1) 3. Setiap selesai satu task, hapus dari checklist `docs/PERBAIKANUI.md` 4. Verify: `cd app/backend && go build && ./backend` lalu buka http://localhost:1947 --- ## 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` | | UI fix checklist | `docs/PERBAIKANUI.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)