swanadiva/HostKeeper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: migrate all planning docs from React to GoFiber + HTMX

Browse Source 
- New ARCHITECTURE_HTMX.md — comprehensive HTMX architecture doc
- ARCHITECTURE.md — updated to point to HTMX version
- UI_COMPONENTS.md — replaced React tree with HTMX partials
- SPRINT_PLAN.md — all sprint tasks updated for HTMX
- BUILD_SYSTEM.md — simplified (no Vite, no npm)
- TIMELINE.md — 3.5 week HTMX timeline
- PROGRESS.md — updated status + HTMX
- AGENTS.md — updated checkpoint with HTMX decision
This commit is contained in:
swanadiva
2026-07-07 12:15:19 +07:00
parent c215d68c81
commit a0c8483c0e
8 changed files with 1442 additions and 2500 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+130 -85
View File
@@ -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)