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**: Pre-development (setup completed, scaffolding not yet started)

---

## 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 + frontend + electron
├── mobile/                          ← (BELUM DIBUAT) V2 mobile wrapper
├── template/                        ← Referensi UI React (Lumina System)
│   └── src/components/              7 React screens (Dashboard, Terminal, SFTP, Snippets, Keychain, Settings, Brief)
├── docs/                            ← Dokumentasi perencanaan V2 (10 file, 6,310 baris)
└── AGENTS.md                        ← file ini (checkpoint AI)

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 Status — Pre-Development

### ✅ Sudah Selesai
- 10 dokumen perencanaan di `docs/`:
  - `ARCHITECTURE.md` — GoFiber v2 + React + Electron + mobile WebView
  - `API.md` — REST + WebSocket spec (1,303 baris)
  - `DATA_MODELS.md` — Host, Group, Snippet, Key, PortForward, Workspace, Config
  - `UI_COMPONENTS.md` — React component tree + Zustand stores
  - `SPRINT_PLAN.md` — Sprint 0-6 breakdown
  - `BUILD_SYSTEM.md` — Cross-platform pipeline
  - `PERFORMANCE.md` — Performance & stability
  - `TIMELINE.md` — 6-week timeline
  - `TEMPLATE_ANALYSIS.md` — Template feature map + 5 bugs found
  - `PROGRESS.md` — Status tracker
- Template UI dianalisis (Lumina System — bright-tech glassmorphic, TailwindCSS v4)
- Root dibersihkan — V1 di `v1/`, V2 siap dimulai di `app/` + `mobile/`

### ❌ Belum Dimulai (Scaffolding)
- `app/backend/` — GoFiber v2 HTTP server
- `app/frontend/` — React + TailwindCSS v4 + xterm.js
- `app/electron/` — Electron wrapper
- `mobile/` — Android + iOS WebView shells

### 🐛 Bug Template yang Perlu Diperbaiki (saat copy)
1. **P0**: Missing CSS keyframes (fade-in, scale-up, slide-in) di `index.css`
2. **P1**: `w-4.5 h-4.5` invalid di `SettingsView.tsx:200` → ganti `w-5 h-5`
3. **P1**: Tidak ada Error Boundary di `App.tsx`
4. **P2**: `as any` casts di `DashboardView.tsx:402`, `KeychainView.tsx:302`
5. **P3**: Auto-focus loss di shortcut terminal `TerminalView.tsx`

---

## 4. Arsitektur V2 (Ringkasan)

```
┌─────────────────────────────────────────────────────┐
│  Electron / WebView Shell                           │
│  ┌──────────────────────────────────────────────┐   │
│  │  React SPA (Vite + TailwindCSS v4 + xterm.js)│   │
│  │  ┌─────────────┐ ┌──────────────────────────┐│   │
│  │  │  Zustand     │ │  Components (template)   ││   │
│  │  │  Stores      │ │  + 3 new screens         ││   │
│  │  └─────────────┘ └──────────────────────────┘│   │
│  │           │ fetch/WS                          │   │
│  └───────────┼──────────────────────────────────┘   │
│              ▼                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  GoFiber v2 (fasthttp) — localhost:1947      │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │   │
│  │  │ REST API │ │ SFTP RPC │ │ WebSocket/SSH │ │   │
│  │  └──────────┘ └──────────┘ └──────────────┘ │   │
│  │              │                               │   │
│  │         ┌────┴────┐                          │   │
│  │         │ pkg/ssh │ ← dari v1/pkg/ssh        │   │
│  │         │ pkg/... │    (via replace directive)│   │
│  │         └─────────┘                          │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

**Key decisions**:
- GoFiber v2 (fasthttp) — replaces chi/net/http
- gofiber/contrib/websocket — replaces gorilla/websocket
- React 19 + Zustand — state management
- v1/pkg/ssh, crypto, storage, config, knownhosts — di-reuse via `go.mod replace`
- V2 module name suggestion: `git.tukangketik.id/swanadiva/hostkeeper/v2`

---

## 5. Yang Harus Dilakukan Selanjutnya (First Actions)

Urutan eksekusi pertama saat development dimulai:

```
Step 1:  mkdir -p app/backend app/frontend app/electron mobile
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:  Buat app/backend/main.go (Fiber app skeleton)
Step 5:  cd ../frontend && npm create vite@latest . -- --template react-ts
Step 6:  Install deps (tailwindcss v4, lucide-react, xterm, @xterm/xterm, zustand)
Step 7:  Copy template/src/* ke app/frontend/src/
Step 8:  Fix 5 bugs template (lihat section 3 di atas)
Step 9:  Setup Electron: npm install electron electron-builder --save-dev
```

---

## 6. Path Penting & Referensi

| Untuk | Lihat di |
|-------|----------|
| Arsitektur lengkap | `docs/ARCHITECTURE.md` |
| API spec | `docs/API.md` |
| Data models | `docs/DATA_MODELS.md` |
| UI component tree | `docs/UI_COMPONENTS.md` |
| Sprint plan detail | `docs/SPRINT_PLAN.md` |
| Template analysis + bugs | `docs/TEMPLATE_ANALYSIS.md` |
| Template source code | `template/src/components/` |
| Template AGENTS.md | `template/AGENTS.md` (desain system) |
| 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 ./...` |
| V1 project state | `v1/PROJECT_STATE.md` |

---

## 7. Aturan Penting

- **JANGAN** mengubah file di `v1/` — V1 FROZEN
- **JANGAN** mengubah `template/` — itu referensi, bukan source aktif
- Semua kode V2 baru di `app/` dan `mobile/`
- Saat reuse `v1/pkg/*`, pakai `go.mod replace` — jangan copy
- Pakai bahasa Indonesia untuk komunikasi dengan user (swanadiva)