swanadiva/HostKeeper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
HostKeeper/AGENTS.md
T
swanadiva 8357d9d76e fix: UI overhaul — align all HTMX views with Lumina Design System (46 fixes) 
- All 7 pages rewritten: Dashboard, Terminal, Snippets, Keychain, SFTP, Settings, Brief
- Apply consistent Lumina glassmorphic theme (rounded-2xl, shadows, borders, tracking)
- Fix SVG icons not rendering — return template.HTML instead of string
- Fix Alpine x-data scoping: terminal tabs, SFTP modals, snippet tag buttons
- Fix dashboard search sending literal ?q=...
- Rebuild CSS with all new Tailwind classes (62KB)
- Add .air.toml with hot-reload config, docs/PERBAIKANUI.md checklist
- Remove unused backup partials
2026-07-07 14:55:42 +07:00

11 KiB
Raw Permalink 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: UI Fix — memperbaiki 107 visual issue dari docs/PERBAIKANUI.md

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/                             ← 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
│   └── PERBAIKANUI.md               UI fix checklist (107 task)
├── 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 — Sprint 0—6 Complete

✅ 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)
  • Sprint 0: GoFiber v2 server + HTMX + Alpine.js + TailwindCSS v4 + custom CSS + layout + nav + health endpoint
  • Sprint 1: Host model (8 mock hosts), dashboard CRUD, search/filter HTMX, grid/list Alpine toggle, add host modal (Alpine events), delete host (hx-delete), transfers panel
  • Sprint 2: Snippets + Keychain CRUD, clipboard.js, utils.js
  • Sprint 3: Settings + Brief, tabs, toggles, danger zone
  • Sprint 4: SFTP Dual-Pane, breadcrumb, file icons by type, create/delete
  • Sprint 5: Terminal + xterm.js + WebSocket mock shell, tab management
  • Sprint 6: JSON file persistence (store package), go.mod replace directive for V1 crypto+knownhosts, model SSH fields, real SSH client for terminal (falls back to mock), dynamic host list from server

🐛 UI Fix Checklist — Lihat docs/PERBAIKANUI.md

  • 107 task teridentifikasi dari audit visual vs template React
  • Acuan utama: 7 file di template/src/components/
  • Setiap task dihapus dari checklist setelah selesai
  • Urutan: Dashboard (P0) → Terminal (P0) → Snippets (P0) → Keychain/SFTP/Settings/Brief (P1)

5. Struktur Folder V2 (Aktual)

app/backend/
├── main.go                    ← Fiber app entry
├── go.mod                     ← module git.tukangketik.id/swanadiva/hostkeeper/v2
├── internal/
│   ├── handler/               ← HTTP handlers (render HTML)
│   │   ├── dashboard.go
│   │   ├── snippets.go
│   │   ├── keychain.go
│   │   ├── terminal.go
│   │   ├── sftp.go
│   │   ├── settings.go
│   │   ├── brief.go
│   │   └── health.go
│   ├── model/                 ← Go structs (Host, Snippet, Key, dll)
│   │   ├── host.go
│   │   ├── snippet.go
│   │   └── keychain.go
│   ├── store/                 ← JSON file persistence (store package)
│   │   ├── store.go
│   │   ├── host.go
│   │   ├── snippet.go
│   │   ├── key.go
│   │   ├── settings.go
│   │   └── devices.go
│   ├── sshconn/               ← Real SSH client for terminal
│   │   └── client.go
│   ├── template/              ← Template helper funcs
│   └── middleware/             ← View data injection
├── static/
│   ├── css/                   ← output.css + custom.css
│   ├── js/                    ← htmx.min.js, alpine.min.js, utils.js, clipboard.js, terminal.js
│   └── xterm/                 ← xterm.js lib
└── views/                     ← Semua template flat (tidak ada subfolder partials/)
    ├── nav.html
    ├── index.html
    ├── host_list.html
    ├── host_modal.html
    ├── snippets.html
    ├── snippet_grid.html
    ├── snippet_modal.html
    ├── keychain.html
    ├── key_grid.html
    ├── key_modal.html
    ├── terminal.html
    ├── sftp.html
    ├── settings.html
    └── brief.html

6. Yang Harus Dilakukan Selanjutnya (UI Fix)

  1. Baca docs/PERBAIKANUI.md — 107 task teridentifikasi
  2. Urutan: Dashboard (P0) → Terminal (P0) → Snippets (P0) → Keychain (P1) → SFTP (P1) → Settings (P1) → Brief (P1) → Global (P1)
  3. Setiap selesai satu task, hapus dari checklist docs/PERBAIKANUI.md
  4. Verify: cd app/backend && go build && ./backend lalu buka http://localhost:1947

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
UI fix checklist docs/PERBAIKANUI.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