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

9.5 KiB
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