# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Node.js + Express + Prisma + Zod validation + Vitest + Docker project.

Stack: Node.js + Express, Prisma, Zod validation, Vitest, Docker.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type-check: `npx tsc --noEmit`
- Create and apply migration (dev): `npx prisma migrate dev --name <change>`
- Regenerate client: `npx prisma generate`
- Apply migrations (prod): `npx prisma migrate deploy`
- Unit tests: `npx vitest run`
- Local services: `docker compose up -d`

## Project structure

- `src/routes/` for routers, `src/services/` for business logic, `src/middleware/` for middleware.
- Keep route handlers thin: parse input, call a service, return a response.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Node.js + Express

- Express 5 forwards rejected promises from async handlers to the error middleware; do not wrap every handler in try/catch.
- Have one central error-handling middleware that logs the error and returns a consistent JSON error shape.
- Validate every request body, query and param before using it.
- Use `helmet`, a strict CORS allow-list and rate limiting on public endpoints.
- Read config from env vars once at startup in a typed config module; fail fast if a required var is missing.
- Return correct HTTP status codes (400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict).

## Prisma

- Change the database only through `schema.prisma` + `prisma migrate dev`. Never edit an applied migration.
- Reuse a single PrismaClient instance (cache it on `globalThis` in dev to survive hot reload).
- Use `select` / `include` to fetch only the fields you need.
- Wrap multi-step writes in `prisma.$transaction`.
- Run `npx prisma generate` after schema changes before type-checking.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Vitest

- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.

## Docker

- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.

## Reference docs

- [Express docs](https://expressjs.com)
- [Prisma docs](https://www.prisma.io/docs)
- [Zod docs](https://zod.dev)
- [Vitest docs](https://vitest.dev)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)