chassis AGENTS.md

Agent guide

Instructions for AI coding agents (Claude Code, Cursor, Copilot, Codex, …) working in a Chassis project. Follow these conventions and the code you produce will match what a human maintainer would write — that's the whole point of this file.

Golden rule: finish every change by running npm run verify and only stop when it passes. It runs typecheck + lint + tests — the same gate CI uses. Green means done; anything else means keep going.

The 60-second mental model

• Endpoints are controller methods. A controller is a class extending Routable; each method is decorated with @route(method, path).
• Exported controllers auto-mount. Everything exported from src/controllers/index.ts is registered at boot. There are no router files to edit.
• Responses go through req.resHandler — ok, created, notFound, validation, … Never call res.status().json() directly.
• Errors are thrown, not handled. throw new AppError(ERROR_CODES.X, msg) from anywhere; a central handler maps it. Do not write try/catch in controllers — Express 5 forwards rejected promises for you.
• Config is one validated file. src/config is the only place that reads process.env.

Do this

• Add an endpoint: run npm run gen <Name> to scaffold a controller + test, then edit the generated methods. It's DB-aware — it wires the controller to the installed ORM (Drizzle or Mongoose) and, for Drizzle, appends a table to src/db/<engine>/schema.ts. (Or copy an existing *.controller.ts and export it from src/controllers/index.ts.)
• Protect or charge for a route with @protectedRoute(...) (auth) or @paidRoute(method, path, price) (x402 payments). Both answer 501 until their module is configured — never silently open or free.
• Validate input with validate({ body|query|params: zodSchema }) in the route's middleware array. Define the schema next to the controller or in src/schemas.
• Return via req.resHandler and match the semantic helper to the outcome (created for 201, noContent for 204, notFound, conflict, …). See docs/reference/core-api.md for the full list.
• Signal errors by throwing AppError with the right ERROR_CODES entry. Add new domain codes to src/core/errors.ts rather than inventing ad-hoc status numbers.
• Add a config value by extending the zod schema in src/config, exposing it on the config object, and documenting it in .env.example.
• Keep controllers thin. Push real logic into src/services/* and data access into src/models/*. Controllers translate HTTP ↔ domain.