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)

P0: Missing CSS keyframes (fade-in, scale-up, slide-in) → tambah di custom.css
P1: w-4.5 h-4.5 → ganti w-5 h-5
P2: Tidak ada Error Boundary → not applicable (HTML template)
P2: as any casts → not applicable (Go typed)
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)

10 KiB Raw Blame History

Hostkeeper V2 — AI Session Checkpoint

1. Repository Structure

2. V1 Status — FROZEN 🧊

3. V2 Architecture — HTMX (Keputusan Penting)

4. V2 Status — Sprint 1 Complete

✅ Sudah Selesai

❌ Belum Dimulai / In Progress

🐛 Bug Template (dari template/src/ — catatan saat implementasi)

5. Struktur Folder V2 (Aktual)

6. Yang Harus Dilakukan Selanjutnya (First Actions)

7. Path Penting & Referensi

8. Aturan Penting

10 KiB

Raw Blame History