swanadiva/HostKeeper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
86620b034f355d3ddee39823e537e3a9da9dd0ea
HostKeeper/AGENTS.md
T
swanadiva a0c8483c0e docs: migrate all planning docs from React to GoFiber + HTMX 
- 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
2026-07-07 12:15:19 +07:00

206 lines
9.5 KiB
Markdown
Raw Blame History

# 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 (documentation updated, 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 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
├── 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 — Pre-Development
### ✅ 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)
```
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: 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
```
---
## 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` |
| 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)
Reference in New Issue View Git Blame Copy Permalink