AGENTS.md

Guidance for AI agents and contributors working in this repo. Read README.md for commands and layout.

Project priorities (do not erode)

Simplicity — prefer the smallest, most readable solution.
Few dependencies — runtime deps stay minimal (today ejs, lucide-static, @larvit/log — the last itself zero-dependency, for structured/OTLP logging). Prefer the Node standard library; justify any new dependency; do not add frameworks. The app is stateless — no database. Auth/identity/OAuth are Ory sidecar services (Kratos/Keto/Hydra, backed by Postgres), reached over their REST APIs with built-in fetch — no SDK dependency. New capabilities ship as plugin folders under plugins/ that fetch their data from upstream services, not as core code. See README.md for the architecture.
Strict TypeScript — tsconfig.json is strict (incl. noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax). Keep it that way.
Environment-agnostic — the app never asks which environment it runs in; there is no NODE_ENV (or equivalent) branching. Every behaviour is an explicit config toggle (e.g. CACHE_TEMPLATES, REQUIRE_SECURE_SECRETS, a future "disable email"), read once in src/config.ts. Compose files set the toggles per deployment.
Semantic, accessible DOM — markup is a first-class concern. Use the right element for the job (landmarks, one <h1> per page + sane heading order, lists, <table> with row/column headers, <fieldset>/<legend>, <button> vs <a>); add ARIA only to fill real gaps (aria-current, aria-sort, labels). Classes/ids name meaning, not looks. Prefer native semantics over div + ARIA. New views and partials keep this bar.
Full, parallel E2E — every user-facing flow (each page, form, guard, plugin route) has a Playwright E2E test, and a new surface ships with its E2E in the same change. Tests stay independent and side-effect-free so the suite runs fullyParallel — keep it that way as it grows (never serialise on shared state); parallelism is what keeps it fast. E2E runs in Docker against the live stack — see README.md.

Deliberate architectural deviations (don't re-flag)

Intentional, reasoned choices — an architecture review should honor them, not re-raise them. Revisit only if the stated reason stops holding.

src/ is grouped by concern, not flat — http/ (request pipeline), auth/ (session-JWT hot path, guards, and the Ory REST clients), admin/ (built-in screens), plugin-host/ (discovery/router/hooks/view-resolver + the plugin-api.ts author barrel), and ui/ (design-system view-models + menu/chrome); server.ts/config.ts/logger.ts and the topology-guard *.test.ts stay at the root. Tests are co-located (foo.test.ts beside foo.ts). Add a new module to the folder that owns its concern rather than to the root; don't reintroduce a flat tree.
ctx.chrome is lazily memoized — do not make it unconditional or move it into the base request context. It protects the I/O-free hot path on the public, bot-hit landing (/). (Declined twice.)
Email is delegated to Kratos (it renders + sends recovery/verification mail); web never touches SMTP. Customization is Kratos' built-in courier.template_override_path, not app code — keeping web stateless and dependency-light (see Email).

Docker only — no host tooling

Everything (install, typecheck, test, run, build, deploy) goes through Docker / Docker Compose. Never run node, npm, or tsc on the host.

docker compose up                                       # dev server, live reload
docker compose run --rm --no-deps web npm run typecheck  # strict type check (--no-deps: skip Ory)
docker compose run --rm --no-deps web npm test           # tests
docker compose -f compose.yml up --build -d              # production

README structure (keep it this way)

README.md serves two readers, in this order — preserve it when editing:

First-time reader (top). A one/two-sentence tagline, then a Quick start that gets the stack up (docker compose up, sign in) and a minimal plugin live. Nothing comes before Quick start — no philosophy, no rationale. Keep its commands copy-pasteable and the example plugin as small as possible; deeper detail lives in its own section, linked.
Returning developer (rest). A Contents ToC immediately after Quick start, then sections ordered most-used/overview first → least-used/in-depth last: Overview → Architecture → Building plugins → menu/blocks/interactivity → Configuration → Auth → Email → Testing → Production → Observability → the JWT-rotation runbook → the Project-layout file map → Extending. Niche ops runbooks and the file-map reference stay near the end.

When editing: put content in the section it belongs to (don't prepend rationale above Quick start); keep the ToC in sync when you add/rename/remove an H2/H3; and state each fact in one home, linking to it rather than restating (credentials, env vars, rotation steps).

Rules

Node 24 runs .ts directly (type stripping). Keep all TypeScript erasable (erasableSyntaxOnly is on): no enum, namespace, parameter properties, or decorators. Import local modules with their .ts extension.
No .mjs. Write modules as .ts (Prio 1) — even standalone scripts run in bare node:24 containers (the e2e mock servers, examples/shifts-upstream/server.ts): Node strips types and detects ESM from syntax, no package.json needed. If a file genuinely must be plain JavaScript, use .js (Prio 2); "type": "module" is already set in both package.jsons, so .js is ESM.
No build step and no compiled artifacts — do not add a bundler or tsc emit.
Before finishing a change, run the typecheck and tests above; both must pass.
Tests use the built-in node --test runner — no test framework dependency.
English everywhere. Keep code comments short and information-dense.
Pin all dependencies and Docker images to exact, human-readable semantic versions — never ranges (^, ~) and never digests/hashes. npm deps are kept exact by .npmrc (save-exact=true) + npm ci; the base image by tag (e.g. node:24.16.0-alpine3.24).
Run the stability reviewer agent after every implementation of something that can be like a PR. That includes any change pushed directly to master. Skip this if the changes are purely documentation and/or comments.

6.6 KiB Raw Blame History