chore: update .gitignore, add docs site, plan docs

2026-05-23 04:16:13 +07:00
parent 92051d5fb4
commit 64e29609b3
17 changed files with 1568 additions and 3 deletions
@@ -0,0 +1,349 @@
+# init-deep: AGENTS.md Generation Plan
+
+**Generated:** 2026-05-22
+**Branch:** `main` (`92051d5`)
+
+## Overview
+
+Generate hierarchical AGENTS.md files for the NexusGuard SD-WAN Suite monorepo.
+Scored 4 locations for AGENTS.md: root + 3 submodules.
+
+## Scoring Results
+
+| Location | Score | Reason | Action |
+|----------|-------|--------|--------|
+| `.` (root) | — | Always create root | CREATE |
+| `apps/server-core/` | 3+2+2+1=8+ | 54 files (3x), 9 subdirs (2x), go.mod (2x), Dockerfile (1x) | CREATE |
+| `apps/dashboard-ui/` | 3+2+2+1=8+ | 54 files (3x), 8 subdirs (2x), package.json (2x), tsconfig (1x) | CREATE |
+| `apps/device-agent/` | 3+0+2+0=5+ | 21 files (3x), 5 subdirs (0x), go.mod (2x) | CREATE (≥15) |
+| `apps/server-core/api/` | 0 | 17 files (<20) | SKIP (parent covers) |
+| `apps/dashboard-ui/views/` | 0 | 7 files (<20) | SKIP (parent covers) |
+| `apps/dashboard-ui/api/` | 0 | 7 files (<20) | SKIP (parent covers) |
+
+## Files to Create/Update
+
+No existing AGENTS.md files found. All 4 are new files (`Write`).
+
+---
+
+## File 1: `./AGENTS.md` (Root — 122 lines)
+
+```markdown
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-05-22
+**Commit:** `92051d5`
+**Branch:** `main`
+
+## OVERVIEW
+NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunneling, centralized IPAM, and real-time nftables network isolation. Monorepo with 3 git submodules: Go backend (Gin), Vue 3 dashboard, Go device agent.
+
+## STRUCTURE
+```
+./
+├── apps/
+│   ├── server-core/    # Go/Gin API backend (submodule)
+│   ├── dashboard-ui/   # Vue 3 + Vite frontend (submodule)
+│   └── device-agent/   # Go stealth daemon (submodule)
+├── docker-compose.yml  # Production orchestration
+├── docker-compose.dev.yml  # Dev (air hot-reload)
+├── Makefile            # up/down/dev/migrate/reset-db
+├── setup.sh            # First-run: generate .env + random keys
+├── .env.example        # DB/JWT/SALT/VITE config template
+├── .gitmodules         # 3 submodules → git.datadunia.com
+└── .opencode/          # IDE agent config (tooling, not project code)
+```
+
+**CRITICAL**: `apps/*` are **git submodules** — clone with `--recurse-submodules`.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| API handlers | `apps/server-core/api/` | 17 files: auth, devices, peers, rules, share, provisioning, servers, wg |
+| Backend core | `apps/server-core/internal/` | auth, config, firewall, heartbeat, ipam, models, wgmanager |
+| Dev migration | `apps/server-core/main_dev.go` | GORM AutoMigrate (build tag `dev`) |
+| Firewall rules | `apps/server-core/internal/firewall/` | nftables Linux rules |
+| Dashboard views | `apps/dashboard-ui/src/views/` | Vue SFC pages |
+| Dashboard API client | `apps/dashboard-ui/src/api/` | Axios API modules |
+| Dashboard stores | `apps/dashboard-ui/src/stores/` | Pinia state stores |
+| Agent client | `apps/device-agent/internal/client/` | Provisioning + heartbeat |
+| Agent tunnel | `apps/device-agent/internal/tunnel/` | Memory-injected WireGuard |
+| Shared crypto | `apps/*/shared/crypto/encryptor.go` | AES-256-GCM (duplicated identical) |
+| CI workflows | `apps/*/.gitea/workflows/build.yml` | Gitea Actions per submodule |
+| Build config | `apps/dashboard-ui/vite.config.ts` | Vite 8 + Vue + TailwindCSS v4 |
+| Source of truth | `apps/server-core/docs/` | API_SPEC, KEY_ROTATION, PEER_DISCOVERY |
+| Plan guardrails | `.sisyphus/plans/` | Anti-patterns, "Must NOT do" rules |
+
+## CODE MAP
+| Symbol | Type | Location | Role |
+|--------|------|----------|------|
+| `main()` (server-core) | func | `apps/server-core/main.go` | Entry: CLI flags + Gin init |
+| `main()` (device-agent) | func | `apps/device-agent/main.go` | Entry: agent daemon lifecycle |
+| `config.Load()` | func | `apps/server-core/internal/config/` | Env-based config loader |
+| `auth.Init()` | func | `apps/server-core/internal/auth/` | JWT sign/verify init |
+| `firewall.InitNetwork()` | func | `apps/server-core/internal/firewall/` | nftables table/set creation |
+| `ipam.AllocateIP()` | func | `apps/server-core/internal/ipam/` | IP pool allocation from CIDR |
+| `wgmanager.SetConfig()` | func | `apps/server-core/internal/wgmanager/` | WireGuard config push |
+| `models.AutoMigrate()` | func | `apps/server-core/internal/models/` | GORM schema migration |
+| `encrypt()` / `decrypt()` | func | `apps/*/shared/crypto/encryptor.go` | AES-256-GCM (identical) |
+
+## CONVENTIONS
+- **Go**: Standard layout (`main.go` in root, `internal/`, `api/`)
+- **Vue 3**: Composition API + `<script setup lang="ts">` throughout
+- **State management**: Pinia stores in `src/stores/`
+- **API client**: Axios-based services in `src/api/` + base `src/services/`
+- **Styling**: TailwindCSS v4 (no PostCSS — `@tailwindcss/vite` plugin)
+- **DB**: GORM ORM, PostgreSQL, AutoMigrate in dev / `-migrate-prod` in prod
+- **Naming**: `UPPER_SNAKE_CASE` env vars, `camelCase` Go vars, `PascalCase` exported Go
+- **Auth**: JWT, admin-only enforced by middleware pattern
+- **Build tags**: `//go:build dev` for AutoMigrate
+- **Capabilities**: Server containers need `NET_ADMIN` + `NET_RAW`
+- **Ports**: API 8080, Dashboard 80 (Nginx), Postgres 5432, Redis 6379
+
+## ANTI-PATTERNS (THIS PROJECT)
+- **NEVER** `nft flush table` — only atomic add/remove
+- **NEVER** log plaintext or encryption keys
+- **NEVER** reopen completed phases/commits — fix forward only
+- **NEVER** rebuild `shared/crypto/encryptor.go` — copy identical file
+- **NEVER** commit build artifacts (binaries, `dist/`)
+- **NEVER** force push
+- **NEVER** create cross-phase workarounds
+
+## UNIQUE STYLES
+- **Zero-Attack Surface**: `/auth/register` locked; admin via `-create-admin` CLI only
+- **Stealth Agent**: No `/etc/wireguard/` — config in memory only
+- **Duplicate crypto**: `encryptor.go` copy-pasted in server-core + device-agent (known debt, do not deduplicate)
+- **nftables default Accept**: Contradicts Zero-Trust "Default DROP" — intentional gap
+
+## COMMANDS
+```bash
+make up              # Start all services
+make down            # Stop all services
+make dev             # Start with hot-reload (air)
+make logs            # Tail all logs
+make migrate         # Run DB migration (requires local Go)
+make reset-db        # Nuke PG volume + recreate + migrate
+
+cd apps/server-core && go run -tags dev .
+cd apps/dashboard-ui && npm run dev
+cd apps/device-agent && go run .
+
+go run -tags dev ./apps/server-core -create-admin -user admin -pass "..."
+```
+
+## NOTES
+- Submodules → private Gitea (`git.datadunia.com`); CI via Gitea Actions per submodule
+- Go versions diverge: server-core `1.25.7`, device-agent `1.25.1`
+- No root linter configs (`.golangci.yml`, `.eslintrc`, `.editorconfig`)
+- Shell scripts use deprecated `docker-compose` v1, Makefile uses `docker compose` v2
+- Root has stale artifacts: `connect_remote.txt`, `temp_section*.txt`
+- `package.json` name is `"temp-ui"` (stale scaffold remnant)
+```
+
+---
+
+## File 2: `apps/server-core/AGENTS.md` (Server Core — 70 lines)
+
+```markdown
+# SERVER CORE — Go/Gin Backend
+
+## OVERVIEW
+Central API and VPN Hub managing database state, JWT token distribution, and Linux nftables firewall isolation. Module: `git.datadunia.com/nexusguard/nexus-server-core`.
+
+## STRUCTURE
+```
+apps/server-core/
+├── main.go            # Entry: CLI flags, Gin init, DB connect
+├── main_dev.go        # Dev build: AutoMigrate on boot
+├── main_prod.go       # Prod build: no-op migration
+├── api/               # 17 HTTP handler files (auth, devices, peers, rules...)
+├── internal/
+│   ├── auth/          # JWT init/signing (auth.Init)
+│   ├── config/        # Env-based config loader
+│   ├── firewall/      # nftables rule management (Linux only)
+│   ├── heartbeat/     # Redis heartbeat TTL check
+│   ├── ipam/          # IP pool allocation from CIDR
+│   ├── models/        # GORM models + AutoMigrate
+│   └── wgmanager/     # WireGuard config push to kernel
+├── shared/crypto/     # AES-256-GCM (identical copy in device-agent)
+├── migrations/        # SQL migration files
+└── docs/              # API_SPEC, KEY_ROTATION, PEER_DISCOVERY
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Auth endpoints | `api/auth.go` | Login, admin creation |
+| Device CRUD | `api/devices.go` | Device lifecycle |
+| Peer management | `api/peers.go` | Peer CRUD + 500 fix |
+| Firewall rules API | `api/rules.go` | nftables rule CRUD |
+| Provisioning | `api/provisioning.go` | Registration token flow |
+| Tests | `api/*_test.go` | auth_test, devices_test, rules_test, etc. |
+| Config loading | `internal/config/config.go` | Env var parsing |
+| nftables engine | `internal/firewall/nftables_linux.go` | InitNetwork, AddRule, RemoveRule |
+
+## CONVENTIONS
+- **Stack**: Go 1.25.7, Gin 1.12, GORM 1.31 (PostgreSQL), JWT v5, go-redis 9.x, google/nftables 0.3, wgctrl
+- **DB**: GORM AutoMigrate in dev (`-tags dev`); `-migrate-prod` for production
+- **Auth**: JWT middleware in `api/` — repeated admin-only checks (not centralized)
+- **API style**: Gin `c.JSON` responses, status codes, error message strings
+- **nftables**: Default Accept policy (`nftables_linux.go:35`) — known doc gap
+
+## ANTI-PATTERNS (THIS PROJECT)
+- **NEVER** `nft flush table` — destroys all peer isolation
+- **NEVER** log plaintext or encryption keys
+- **Admin-only authorization** is copy-pasted across 7+ handler files — refactoring opportunity
+
+## COMMANDS
+```bash
+go run -tags dev .                          # Dev server
+go run -tags dev . -migrate-prod            # Run migration manually
+go run -tags dev . -create-admin -user admin -pass "..."
+go test ./... -tags dev -cover              # Run all tests
+```
+
+## NOTES
+- API runs on port 8080 (configurable via `PORT`/`API_PORT`)
+- Docker needs `NET_ADMIN` + `NET_RAW` capabilities
+- Tests exist for auth, devices, provisioning, rules, share
+```
+
+---
+
+## File 3: `apps/dashboard-ui/AGENTS.md` (Dashboard UI — 60 lines)
+
+```markdown
+# DASHBOARD UI — Vue 3 Frontend
+
+## OVERVIEW
+Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules. Futuristic glassmorphism design with Vue 3 + Vite + TailwindCSS v4.
+
+## STRUCTURE
+```
+apps/dashboard-ui/
+├── src/
+│   ├── main.ts           # Vue app bootstrap (Pinia + Router)
+│   ├── App.vue           # Root component
+│   ├── api/              # Axios API client modules (7 files)
+│   ├── views/            # Page components (7 SFCs)
+│   ├── components/       # Shared UI components (4 files)
+│   ├── stores/           # Pinia stores (2 files)
+│   ├── assets/           # CSS (main.css)
+│   ├── router/           # Vue Router config
+│   └── services/         # Base Axios HTTP service
+├── public/               # Static assets
+├── index.html            # HTML shell
+├── vite.config.ts        # Vite 8 config (+Vue +TailwindCSS)
+├── tsconfig.app.json     # Strict TS, noUnusedLocals, noUnusedParameters
+└── nginx.conf            # SPA nginx fallback
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| API integration | `src/api/` | 7 modules matching backend routes |
+| Page views | `src/views/` | Nodes, Devices, Firewall, Settings, etc. |
+| State management | `src/stores/` | Pinia stores |
+| Shared components | `src/components/` | Reusable UI elements |
+| Routing | `src/router/index.ts` | Vue Router config |
+| Base HTTP | `src/services/` | Axios instance with interceptors |
+
+## CONVENTIONS
+- **Stack**: Vue 3.5, Vite 8, TypeScript 6.0, TailwindCSS 4.3, Pinia 2.3, VueUse 14.3, Axios 1.16, HeadlessUI 1.7, Iconify 5.0
+- **Style**: Composition API, `<script setup lang="ts">`, glassmorphism design
+- **Build**: `vue-tsc -b && vite build` (type-check before build)
+- **Dev**: `vite` (Vite 8 dev server, no explicit port)
+- **TS**: Strict mode, ES2020, noUnusedLocals, noUnusedParameters
+- **API base**: `VITE_API_BASE_URL` env var (baked at build time)
+
+## ANTI-PATTERNS (THIS PROJECT)
+- `package.json` name is `"temp-ui"` — stale scaffold remnant — rename
+- No ESLint/Prettier configs exist
+- `index.html` `<title>` still says "temp-ui"
+
+## COMMANDS
+```bash
+npm run dev       # Vite dev server
+npm run build     # vue-tsc + vite build
+npm run build     # Build output → dist/ for Nginx
+```
+
+## NOTES
+- Port 80 in Docker (Nginx), no explicit dev server port
+- VITE_API_BASE_URL injected via Docker ARG at build time
+- No `package-lock.json` committed? Verify — `npm ci` not `npm install`
+```
+
+---
+
+## File 4: `apps/device-agent/AGENTS.md` (Device Agent — 50 lines)
+
+```markdown
+# DEVICE AGENT — Go Stealth Daemon
+
+## OVERVIEW
+Stealth background daemon for Linux client machines. Establishes memory-injected WireGuard tunnels — no `/etc/wireguard/` config files ever written to disk.
+
+## STRUCTURE
+```
+apps/device-agent/
+├── main.go                    # Entry: env parsing, identity, provisioning, tunnel, heartbeat
+├── internal/
+│   ├── client/                # Provisioning (register + key exchange) + heartbeat
+│   ├── identity/              # HWID detection (machine identity binding)
+│   └── tunnel/                # Fileless WireGuard tunnel injection
+├── shared/crypto/             # AES-256-GCM (identical copy in server-core)
+└── scripts/
+    ├── install_agent.sh       # Systemd service installer
+    └── sys-bridge.service     # Systemd unit file
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Provisioning flow | `internal/client/` | Registration, key exchange with server |
+| HW identity | `internal/identity/` | Hardware ID detection |
+| Tunnel injection | `internal/tunnel/` | Memory-only WireGuard config |
+| Install script | `scripts/install_agent.sh` | One-command agent deployment |
+
+## CONVENTIONS
+- **Stack**: Go 1.25.1, wireguard, crypto, net, sys (minimal deps)
+- **Design**: Stealth — no disk writes for WG config; tunnel lives in process memory
+- **Lifecycle**: HWID → Provision → Tunnel → Heartbeat loop
+- **Env vars**: `SERVER_URL`, `REG_TOKEN`
+- **Cross-compile**: CI builds for linux/amd64, arm64, arm
+
+## ANTI-PATTERNS (THIS PROJECT)
+- **NEVER** write WireGuard config to `/etc/wireguard/` — stealth invariant
+- **NEVER** log encryption keys or registration tokens
+- `shared/crypto/` is duplicated from server-core (do not rewrite separately)
+
+## COMMANDS
+```bash
+go run .                                       # Run (needs SERVER_URL + REG_TOKEN)
+go build -o device-agent .                     # Build binary
+CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o device-agent-linux-arm64 .
+```
+
+## NOTES
+- Cross-compiled in CI for 3 architectures (amd64, arm64, arm)
+- Go version `1.25.1` — slightly behind server-core's `1.25.7`
+- Install via `sudo ./install_agent.sh --server-url ... --token ...`
+```
+
+---
+
+## Execution Steps
+
+1. **[DONE]** **Write** `./AGENTS.md` (root) — 109 lines, full treatment
+2. **[DONE]** **Write** `apps/server-core/AGENTS.md` — 61 lines, domain-specific
+3. **[DONE]** **Write** `apps/dashboard-ui/AGENTS.md` — 58 lines, domain-specific
+4. **[DONE]** **Write** `apps/device-agent/AGENTS.md` — 50 lines, domain-specific
+5. **[DONE]** **Verify**: no duplicate content between parent and children
+
+## Quality Gates
+- [x] Root AGENTS.md: 50-150 lines ✅ (109)
+- [x] Subdir AGENTS.md: 30-80 lines each ✅ (61/58/50)
+- [x] No generic advice in any file
+- [x] No parent duplicates repeated in children
+- [x] Telegraphic style throughout