diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9db6421 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,161 @@ +# 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/ +│ └── v2/ ← 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/v2/`: + - `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/v2/ARCHITECTURE.md` | +| API spec | `docs/v2/API.md` | +| Data models | `docs/v2/DATA_MODELS.md` | +| UI component tree | `docs/v2/UI_COMPONENTS.md` | +| Sprint plan detail | `docs/v2/SPRINT_PLAN.md` | +| Template analysis + bugs | `docs/v2/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) diff --git a/docs/plans/2024-06-22-hostkeeper-design.md b/v1/docs/plans/2024-06-22-hostkeeper-design.md similarity index 100% rename from docs/plans/2024-06-22-hostkeeper-design.md rename to v1/docs/plans/2024-06-22-hostkeeper-design.md diff --git a/docs/plans/2024-06-22-hostkeeper-implementation.md b/v1/docs/plans/2024-06-22-hostkeeper-implementation.md similarity index 100% rename from docs/plans/2024-06-22-hostkeeper-implementation.md rename to v1/docs/plans/2024-06-22-hostkeeper-implementation.md