From fe4b1b02d1fc446bf0913eff36eb6573fc4a0306 Mon Sep 17 00:00:00 2001 From: Benjamin Toby Date: Thu, 15 Oct 2026 21:09:27 +0100 Subject: [PATCH] Remove unused dependencies and dead code, refresh AGENTS.md - Drop unused email module and media text extraction path - Remove 12 unused dependencies - Remove unused imports in server.ts - Add typecheck and test scripts - Rewrite AGENTS.md to describe this project Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 99 +++----- bun.lock | 226 +----------------- package.json | 18 +- .../db/users/media/upload-and-record-media.ts | 14 -- src/pages/api/admin/upload-media.ts | 2 - src/server.ts | 4 - 6 files changed, 38 insertions(+), 325 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dcacb70..0aacf02 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,15 +1,14 @@ # Agent Instructions -Read `WORKSPACE_MEMORY.md` before making structural changes to page code. +WireGuard UI — a self-hosted web admin for WireGuard hosts and clients. The app runs **as root** and executes system commands (`wg`, `ip`, `iptables`, `wg-quick`, firewall managers). Treat every API route and every value that reaches a shell or a WireGuard config as security-sensitive. ## Stack - **Runtime:** Bun — not Node. Use `bun` commands, never `npm`/`npx`. - **Framework:** `@moduletrace/bunext` — not Next.js. Routing is filesystem-based under `src/pages/`, served by `Bun.serve` in `src/server.ts`. -- **Database:** `@moduletrace/bun-sqlite` — MariaDB database. Schema in `db/schema.ts`, generated types in `db/types/db.ts`. Config in `bun-sqlite.config.ts` (DB name `rpe.db` in `./db`). -- **UI:** Tailwind CSS v4 + local `twui` components (`src/components/twui`) + shadcn/ui (`src/components/ui`). shadcn/ui configured via `components.json` (style: `radix-vega`), CSS entry at `src/components/twui/base.css` (imported by `src/styles/globals.css`). Uses `@shadcnblocks` registry for extra blocks (`src/components/shadcnblocks`). +- **Database:** `@moduletrace/bun-sqlite` — SQLite. Schema in `db/schema.ts`, generated types in `db/types/db.ts`. Config in `bun-sqlite.config.ts` (DB name `wgui` in `./db`). Import its types from `@moduletrace/bun-sqlite/types` (not `/dist/types`). +- **UI:** Tailwind CSS v4 + local `twui` components (`src/components/twui`). Global styles in `src/styles/main.css`. - **Icons:** `lucide-react`. -- **Validation:** `zod` v4 (`zod@4.1.12`). ## MCP Tool Usage Guidelines @@ -27,48 +26,35 @@ When building, refactoring, styling, or auditing UI components and layouts, acti ## Entrypoint -`src/server.ts` — runs `bunextInit()`, initializes a persistent **Piper TTS daemon** (global `PIPER_MANAGER`), starts `Bun.serve` with WebSocket upgrade on `/ws`, then starts cron. +`src/server.ts` — runs `bunextInit()`, starts `Bun.serve` on `0.0.0.0` (port from `SiteData.ServerPort`), serves `/media/*` via `handleMediaServer`, then runs `syncWireguardHosts()` to bring host tunnels in line with the DB. + +On-disk state: WireGuard keys/configs/iptables scripts live under `/var/lib/wgui` (`grabDirNames()` in `src/utils/grab-dir-names.ts`); uploaded media under `DATA_DIR` (default `./.data`). ## Commands -| Purpose | Command | -| -------------------------- | --------------------------------------------------------- | -| Dev server | `bun run dev` (runs `bun src/server.ts`) | -| Production | `bun run start` (`NODE_ENV=production bun src/server.ts`) | -| Type-check only | `bunx tsc --noEmit` | -| DB schema (tables) | `bun run db:schema` | -| DB schema (+vectors) | `bun run db:schema:vector` | -| DB admin UI | `bun run db:admin` | -| DB backup | `bun run db:backup` | -| Port SQLite → MariaDB | `bun run db:port-sqlite` | -| Install (private registry) | `bun install` (uses registry in `bunfig.toml`) | +| Purpose | Command | +| --------------- | ------------------------------------------------------- | +| Dev server | `bun run dev` (runs `sudo bun src/server.ts`) | +| Production | `bun run start` | +| Build | `bun run build` | +| Type-check | `bun run typecheck` (`bunx tsc --noEmit`) | +| Tests | `bun run test` (`bun test`) | +| DB schema | `bun run db:schema` | +| DB admin UI | `bun run db:admin` | -No linter or formatter configured. Type-check is the primary verification step. 33 project-level `.test.ts`/`.test.tsx` files exist but no test runner script is configured — run individual tests with `bun test `. +No linter or formatter configured. Type-check and `bun test` are the verification steps. ## Architecture -### Root Component & Context - -`src/pages/__root.tsx` — sets up: - -- Layout selection (admin/auth/public) -- WebSocket connection via `useWebSocket` + `useWebSocketEventHandler` -- `AppContext` (React context) providing `AppContextType` globally — includes user data, WebSocket, and `sendWebsocketData` -- Server-navigated URL push via `server:navigate-to-url` WebSocket event +- `src/pages/__root.tsx` — picks the layout (`src/layouts/main` or `src/layouts/admin`, or `LoginShell` for auth pages) and provides `AppContext`. +- **Pages:** `/` + `about`, `privacy`, `terms`; `/auth/{login,logout,signup}`; `/admin` (dashboard), `/admin/setup`, `/admin/settings`, `/admin/clients`, `/admin/hosts/*` (add/edit hosts, `[host_id]/clients/*` add/edit/view clients). +- **API:** `src/pages/api/admin/*` (host/client setup, network info, firewall status, service restart/update, media), generic CRUD at `src/pages/api/admin/crud/[[...paths]].ts` with per-table handlers in `crud/(tables)//{get,post,put,del}.ts`, plus `api/auth/login.ts` and `api/create-first-user.ts`. +- **Every `/api/admin/*` route must authenticate** — nothing guards the prefix globally. Use `adminApiGuard({ req })` (`src/functions/backend/auth/admin-api-guard.ts`) or `userAuth` + `checkUserAccess`. +- **Shell safety:** never interpolate request/DB values into `execSync` strings. Use `execFileSync` with an args array or `node:fs` APIs, and validate values before they reach a WireGuard config (newlines there can inject `PostUp` commands). Validators live in `src/utils/` (`validate-ipv4`, `validate-ipv4-cidr`, `validate-allowed-ips`, `validate-endpoint-host`, `validate-interface-name`). ## Path Alias -`@/*` resolves from repo root. Import like `@/src/components/ui/button`, `@/db/types/db`, `@/external/cloudflare/r2`. - -## Admin Route Hierarchy - -Two tiers of admin pages: - -- **`/admin/*`** — Resident-facing features: access booking (`/admin/access`), payments (`/admin/payments/*`), chat (`/admin/chat/*`), dependants (`/admin/dependants`), notifications (`/admin/notification`), events (`/admin/events`), settings/profile, support/complaints. Additional sections: `association/`, `devops/`, `management/`, `workers/` -- **`/admin/admin/*`** — Admin-only features: user management (`/admin/admin/users/*`), payment schemes, payment management, documents/constitution, chat group management. Requires `admin` or `exco` role. -- **`/admin/security/*`** — Security features: gate control, guest access monitoring, dependant verification. Requires `security`, `exco`, `manager`, or `aco` role. - -Admin sidebar navigation data in `src/layouts/admin/(data)/`. ElevenLabs voice agent widget integrated into admin layout (`src/layouts/admin/(partials)/eleven-labs-widget.tsx`). +`@/*` resolves from repo root. Import like `@/src/components/general/admin-card`, `@/db/types/db`. ## Page Directory Rules @@ -89,45 +75,24 @@ Server functions use `index.server.ts` alongside `index.tsx` (e.g. `single-docum ## Shared Code Organization -- **`src/hooks/`** — Shared React hooks: `use-admin-crud-get`, `use-all-users-list-init`, `use-annual-dues-status`, `useAppContext`, `use-fetch-get`, `use-form-init`, `useLocalUser`, `use-mobile`, `use-payments-query`, `use-users-get` -- **`src/functions/`** — Shared functions split by target: - - `src/functions/backend/` — Server-only: DB queries (`grab-users` in `backend/db/`), email client, RAG ingest, media upload, embed/face ingest - - `src/functions/frontend/` — Client-safe: CRUD handlers, fetch handlers, Paystack script loader, URL parser - - `src/functions/general/` — Platform-agnostic: join builders in `general/joins/` (users, payments, guests, messages, chat groups) -- **`src/utils/`** — Utility modules: auth, cookies, crypto, CSRF, hashing, contact classification, RAG text chunking, user type parsing. Most have corresponding `.test.ts` files (auth, cookies, crypto, CSRF, hashing, contact classification, user type parsing). -- **`src/dict/`** — Dictionaries/constants: user types, access codes, gates, LLM providers/models, TTS voices, WebSocket rooms, messaging types, localStorage keys -- **`src/data/`** — Static data: `app-data.ts` (app constants — cookie names, limits, default models, Paystack endpoint), location data, super admin users, role documentation -- **`src/types/`** — Type definitions (~1,350 lines total across 4 files): `index.ts` (1,037 lines), `sql-joins.ts`, `paystack.ts`, `search-api.ts` -- **`src/lib/`** — `utils.ts` exports `cn()` (clsx + tailwind-merge), used by shadcn/ui components -- **`src/scripts/`** — Seed scripts for location and resident data - -## Component Systems - -| Directory | Description | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `src/components/twui/` | Local design system — publishable package with its own `package.json`. Contains elements, composites, editors (TinyMCE), form components, MDX support, hooks, layout, SVGs, and utilities | -| `src/components/general/` | Shared page components: AI chat, date-picker, logo, Paystack widgets, status-tag, user-avatar, face-search-card, guarantor-preview-modal, guarantor-info-row, etc. (search-select lives in `src/components/twui/form/SearchSelect.tsx`) | -| `src/components/pages/` | Public page components: `about/`, `constitution/`, `homepage/` | -| `src/components/shadcnblocks/` | Components from shadcnblocks.com registry (logo) | +- **`src/functions/backend/`** — Server-only: `auth/`, `db/`, `firewall/` (firewalld/ufw rules, status), `media/`, `setup/` (host/client setup, iptables script builder, network detection). +- **`src/functions/frontend/`** — Client-safe: CRUD/fetch handlers, media upload/delete, client rule label formatting. +- **`src/functions/server/`** — Request-level server handlers (media server). +- **`src/hooks/`** — `use-admin-crud-get`, `use-client-rules-map`, `use-fetch-get`, `use-form-init`, `use-users-get`. +- **`src/utils/`** — Cookies, crypto, dir names, IP/CIDR/port/interface validators, WireGuard interface naming. Most have `.test.ts` files. +- **`src/dict/`**, **`src/data/`** — Constants (`app-data.ts`, `site-data.ts`), user types, client rules, links. +- **`src/scripts/`** — Shell scripts: `install-wg-ui.sh`, `setup-wireguard.sh`, `wg-quick-manage.sh`. +- **`src/components/general/`** — Shared app components (admin cards/buttons, clients table, host IP field, login shell, user form). ## Conventions - Prefer one function/component per file over monolithic files with multiple exports. -- **Modularization is non-negotiable: prioritize modularization over monolithic functions/components.** Repeated UI blocks must be extracted into their own reusable components driven by props (e.g. an info row component taking `{ icon, text }`), never repeated inline markup. - **Every rendered array must have a separate component for each array item.** Always extract the item JSX into its own component and render it via `items.map((item) => )` — never inline the item's JSX inside the map callback. - Always use object parameters (`{ foo, bar }`) instead of comma-separated positional parameters. - Prefer existing patterns over new abstractions. -- `.env` is gitignored but exists locally with secrets. Do not commit it. -- `secrets/` directory is also gitignored. -- `external/` binary directories (`**/models`, `**/bin`, `**/x-86`, `**/arm-64`) are gitignored. -- The `bunext.config.ts` excludes `onnxruntime-node` and `@xenova/transformers` from SSR/page compilation (native modules that must stay server-side). -- `tsconfig.json` excludes `src/components/twui/mdx`, `src/components/twui/elements/RemoteCodeBlock.tsx`, and `src/components/twui/mdx/markdown/MarkdownEditorPreviewComponent.tsx` from type-checking. - -## Conventions - -- Prefer one function/component per file over monolithic files with multiple exports. - **Modularization is non-negotiable: prioritize modularization over monolithic functions/components.** Repeated UI blocks must be extracted into their own reusable components driven by props (e.g. an info row component taking `{ icon, text }`), never repeated inline markup. - **UNCHANGEABLE RULE — twui components always win over raw JSX elements.** ALWAYS use twui components (`H1`–`H5`, `P`, `Span`, `List`, `Img`, `Row`, `Stack`, `Container`, `Section`, `Border`, `Card`, `Button`, `Tag`, `Link`, etc.) before basic JSX elements (`

`–`

`, `

`, ``, `