diff --git a/AGENTS.md b/AGENTS.md index c7a4160..38ca7d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ > **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) +> **Current Phase**: Pre-development (documentation updated, scaffolding not yet started) --- @@ -20,12 +20,24 @@ hostkeeper/ (root — bersih untuk V2) │ ├── go.mod module git.tukangketik.id/swanadiva/hostkeeper │ ├── Makefile │ └── PROJECT_STATE.md V1 full project state -├── app/ ← (BELUM DIBUAT) V2 backend + frontend + electron +├── app/ ← (BELUM DIBUAT) V2 backend GoFiber + views + static ├── 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) +├── 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) @@ -46,115 +58,148 @@ Git branches: --- -## 3. V2 Status — Pre-Development +## 3. V2 Architecture — HTMX (Keputusan Penting) -### ✅ 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/` +**Hostkeeper V2 menggunakan GoFiber + HTMX, BUKAN React.** -### ❌ 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) +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 ``` -┌─────────────────────────────────────────────────────┐ -│ 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)│ │ -│ │ └─────────┘ │ │ -│ └──────────────────────────────────────────────┘ │ +┌───────────────────────────────────────────────────┐ +│ 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) │ │ +│ │ └─────────┘ │ │ +│ └──────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ ``` -**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` +| 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 | --- -## 5. Yang Harus Dilakukan Selanjutnya (First Actions) +## 4. V2 Status — Pre-Development -Urutan eksekusi pertama saat development dimulai: +### ✅ 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) + +### ❌ Belum Dimulai +- `app/backend/` — GoFiber v2 server + handler + views + +### 🐛 Bug Template (dari template/src/ — catatan saat implementasi) +1. **P0**: Missing CSS keyframes (fade-in, scale-up, slide-in) → tambah di `custom.css` +2. **P1**: `w-4.5 h-4.5` → ganti `w-5 h-5` +3. **P2**: Tidak ada Error Boundary → not applicable (HTML template) +4. **P2**: `as any` casts → not applicable (Go typed) +5. **P3**: Auto-focus loss → handle via JS `focus()` di Alpine + +--- + +## 5. Struktur Folder V2 (Target) ``` -Step 1: mkdir -p app/backend app/frontend app/electron mobile +app/backend/ +├── main.go ← Fiber app entry +├── go.mod ← module git.tukangketik.id/swanadiva/hostkeeper/v2 +├── internal/ +│ ├── handler/ ← HTTP handlers (render HTML) +│ │ ├── dashboard.go +│ │ ├── terminal.go +│ │ ├── sftp.go +│ │ ├── snippets.go +│ │ ├── keychain.go +│ │ ├── settings.go +│ │ ├── brief.go +│ │ └── health.go +│ ├── model/ ← Go structs (Host, Snippet, Key, dll) +│ ├── template/ ← Template helper funcs +│ └── middleware/ ← View data injection +├── static/ +│ ├── css/ ← output.css + custom.css +│ ├── js/ ← htmx.min.js, alpine.min.js, utils.js, terminal.js +│ └── xterm/ ← xterm.js lib +└── views/ + ├── layout.html + ├── index.html + └── partials/ ← ~17 partial HTML files +``` + +--- + +## 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: 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 +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 ``` --- -## 6. Path Penting & Referensi +## 7. Path Penting & Referensi | Untuk | Lihat di | |-------|----------| -| Arsitektur lengkap | `docs/ARCHITECTURE.md` | +| Arsitektur HTMX lengkap | `docs/ARCHITECTURE_HTMX.md` | | API spec | `docs/API.md` | -| Data models | `docs/DATA_MODELS.md` | -| UI component tree | `docs/UI_COMPONENTS.md` | +| Data models (Go struct) | `docs/DATA_MODELS.md` | +| HTMX 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) | +| 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 ./...` | -| V1 project state | `v1/PROJECT_STATE.md` | --- -## 7. Aturan Penting +## 8. 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/` +- **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) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6d2c3d5..38a6607 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,42 +1,26 @@ # Hostkeeper V2 — Architecture -> **Status**: V2 Planning Complete -> **Last Updated**: 2026-06-29 +> **Status**: Migrasi React → HTMX +> **Last Updated**: 2026-07-07 +> **Dokumen arsitektur baru**: [ARCHITECTURE_HTMX.md](ARCHITECTURE_HTMX.md) > **V1 (existing)**: CLI/TUI SSH/SFTP manager — frozen, no changes. --- -## 1. System Overview +## ⚠️ Keputusan Arsitektur -Hostkeeper V2 is a Termius-like cross-platform SSH/SFTP management GUI. The architecture follows a **Go backend + Web UI + Electron/WebView** pattern — the same approach used by Termius, VS Code, Discord, Slack, and Figma. +Hostkeeper V2 menggunakan **GoFiber + HTMX**, **bukan React/SPA**. -``` -┌──────────────────────────────────────────────────────┐ -│ ELECTRON / WEBVIEW │ -│ Native window, menu bar, tray icon, auto-updater │ -│ │ -│ ┌─────────────────────────────────────────────────┐ │ -│ │ WEB UI (React + TypeScript) │ │ -│ │ Host List │ Terminal │ SFTP │ Keys │ Settings │ │ -│ │ ┌───────────────────────────────────────────┐ │ │ -│ │ │ xterm.js (terminal) │ │ │ -│ │ └───────────────────────────────────────────┘ │ │ -│ └─────────────────────────────────────────────────┘ │ -│ │ HTTP + WebSocket │ -│ ┌─────────────────────────────────────────────────┐ │ -│ │ GO BACKEND (GoFiber v2) │ │ -│ │ REST API │ WebSocket │ SSH │ SFTP │ │ -│ │ ┌───────────────────────────────────────────┐ │ │ -│ │ │ pkg/ssh │ pkg/sftp │ pkg/crypto │ ... │ │ │ -│ │ └───────────────────────────────────────────┘ │ │ -│ └─────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────┘ - │ Distributed as: - ├── .dmg (macOS) - ├── .exe (Windows) - ├── .AppImage (Linux) - └── .aab / .ipa (Android / iOS) -``` +Keputusan ini diambil karena: +1. Developer lebih nyaman dengan Go daripada JavaScript +2. ~90% kode adalah Go + HTML template +3. Hanya ~410 baris JS yang diperlukan (xterm.js, clipboard, toggle) +4. Build lebih sederhana — tanpa Vite, npm, TypeScript +5. Bisa berjalan di browser biasa tanpa Electron + +**Dokumen arsitektur lengkap ada di** [`ARCHITECTURE_HTMX.md`](ARCHITECTURE_HTMX.md). + +--- ### Communication Flow diff --git a/docs/ARCHITECTURE_HTMX.md b/docs/ARCHITECTURE_HTMX.md new file mode 100644 index 0000000..ed8c721 --- /dev/null +++ b/docs/ARCHITECTURE_HTMX.md @@ -0,0 +1,385 @@ +# Hostkeeper V2 — Architecture (HTMX) + +> **Status**: Approved — Menggantikan arsitektur React sebelumnya +> **Last Updated**: 2026-07-07 +> **Keputusan**: React → GoFiber + HTMX + Alpine.js + minimal JS + +--- + +## 1. Arsitektur Baru + +Hostkeeper V2 menggunakan arsitektur **server-rendered HTML** dengan interaktivitas via HTMX, bukan SPA React. + +``` +┌────────────────────────────────────────────────────┐ +│ Browser / Electron WebView │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ HTMX (14kb) + Alpine.js (15kb) + xterm.js │ │ +│ │ │ │ +│ │ ● HTMX: semua interaksi (search, filter, │ │ +│ │ modal, form, navigasi) │ │ +│ │ ● Alpine.js: client state (toast, toggle, │ │ +│ │ passphrase reveal, tab) │ │ +│ │ ● xterm.js: terminal emulator (hanya │ │ +│ │ halaman terminal) │ │ +│ │ ● Vanilla JS: clipboard, toggle switch, │ │ +│ │ strength calc │ │ +│ └────────────────┬─────────────────────────────┘ │ +│ │ hx-get/hx-post/hx-ws │ +│ ┌────────────────▼─────────────────────────────┐ │ +│ │ GoFiber v2 Backend (localhost:1947) │ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────────────┐ │ │ +│ │ │ HTML handlers │ │ WebSocket /xterm.js │ │ │ +│ │ │ (Fiber + html│ │ (SSH I/O via WS) │ │ │ +│ │ │ template) │ └──────────────────────┘ │ │ +│ │ └──────┬───────┘ │ │ +│ │ │ go.mod replace │ │ +│ │ ┌────▼────┐ │ │ +│ │ │ v1/pkg/ │ ssh, crypto, storage, config │ │ +│ │ └─────────┘ │ │ +│ └───────────────────────────────────────────────┘ │ +└──────────────────────────────────────────────────────┘ +``` + +### Alur Request + +``` +1. User klik tombol "Filter Active" + │ hx-get="/hosts?filter=active" + │ hx-target="#host-list" + ▼ +2. GoFiber handler: + func (h *Handler) ListHosts(c fiber.Ctx) error { + hosts := h.store.Filter("active") + return c.Render("partials/host_list", fiber.Map{ + "Hosts": hosts, + }) + } + ▼ +3. Server return HTML partial +