AGENTS.md — instructions for coding agents working on KisAssistant

Read this before touching the code. Docs live in docs/ (English).

What this is

KisAssistant — private ChatGPT-like assistant. Bun backend (single process, serves API + static frontend), React 18 + Vite + Tailwind 3 + lucide-react frontend, SQLite persistence via Bun's native bun:sqlite driver.

Commands (run from repo root unless noted)

bun install — backend deps (almost none; @types/bun only)
bun run dev — backend with watch mode (auto-restart on edit), http://localhost:3000
bun run dev:frontend — Vite dev server with HMR + /api proxy, http://localhost:5173
bun run dev:all — both at once (two terminals also works)
bun run build:frontend / bun --cwd frontend build — typecheck + Vite build into public/ (wipes it first)
bun run typecheck / bun run typecheck:frontend — tsc --noEmit for each side
API smoke tests: boot on a non-3000 port with throwaway DATA_DIR, drive with curl/python (see docs/OPERATIONS.md). Port 3000 is the owner's dev server — never kill it, never bind it in tests.

Layout

src/index.ts          HTTP routes (Bun.serve). Auth gate: everything under /api/ except /api/auth/login and /api/share/:id
src/config.ts         env parsing (PORT, HOST, APP_PASSWORD=admin key, OLLAMA_HOST, DATA_DIR, rate limits)
src/db.ts             SQLite store: users, sessions, conversations, messages, shares (+ admin row bootstrap)
src/auth.ts           login(username,key), hashed Bearer sessions, sliding-window login rate limit
src/static.ts         static file server + SPA fallback (covers /share/:id)
src/drivers/          LLMDriver interface, OllamaDriver, ApiDriverBase, Mistral/DeepSeek/Anthropic/OpenAI, arcaic browser sub-drivers (arcaic-openai/gemini/qwen), DriverRegistry
frontend/src/         App.tsx (routing+state), lib/api.ts (fetch wrapper), components/
public/               BUILD OUTPUT (Vite). Never hand-edit; rebuild instead. Not committed (see .gitignore)
flake.nix/module.nix NixOS packaging + service module

Auth model (do not weaken)

No cookies. Bearer tokens in localStorage, stored sha256-hashed in SQLite.
admin logs in with APP_PASSWORD from .env. Users log in with admin-issued ka_… keys (also hashed). Comparisons are timing-safe.
Conversations/shares are per-account; always enforce conv.user_id === user.id. Admin has no cross-account read.
Never log, print, or commit secrets. .env, data/, *.db are gitignored.

Conventions

Language: TypeScript strict. UI text: English only.
Frontend styling: Tailwind only, emerald accent, rounded-2xl/3xl everywhere, dark: variants on every surface. Inter Variable font (self-hosted, no CDN).
Icons: lucide-react only. Never use native <select> — use the Picker component in frontend/src/components/ui.tsx (also Button, Modal, ConfirmDialog, ContextMenu, Avatar, CopyButton live there).
Backend responses: json() helper, { error } shape on failure, correct HTTP codes (400/401/403/404/409/429/502).
DB: synchronous bun:sqlite queries, prepared statements, PRAGMA journal_mode=WAL. Schema is created idempotently at boot — keep it that way (no migration framework).
Drivers: new LLM backends implement LLMDriver and register in DriverRegistry priority order. The arcaic browser driver is user-facing as "Arcaic-Technology" — never expose its scraping internals (no "puppeteer"/"crawler"/upstream-site names) in API responses, error strings, or UI labels.
Docs are in English. Update docs/ + README when adding routes, tables, or env vars.

NixOS

flake.nix builds the frontend offline via buildNpmPackage (needs frontend/package-lock.json committed). If npmDepsHash mismatches, take the hash from the error. Keep module.nix options backward compatible.

3.8 KiB Raw Blame History