HostKeeper/AGENTS.md

# 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)