@raiyyan/brisk 0.1.0 → 0.2.0

package/AGENTS.md

@@ -16,16 +16,22 @@ Full documentation: https://github.com/MohammadRaiyyan/brisk#readme
 
 ## Starting a project
 
-- New app: install `@raiyyan/brisk` (and `typescript`, `@types/node`, `vitest` as dev dependencies), then run `npx brisk init`. It creates `src/env.ts`, `src/app.ts` (`export const app = defineApp(...)` with prefix `/api`, and `export type Api = typeof app`), `src/main.ts` (`await app.listen(env.PORT)`), `src/features/index.ts`, `.env.example` and a `tsconfig.json` that lets Node run `.ts` directly. It never overwrites existing files, adds `"type": "module"` and missing `dev`, `start`, `typecheck`, `test` and `brisk` scripts, then runs `brisk agents`.
-- `brisk init` asks about each option, or takes flags: `--db none|sqlite|postgres` (a `Database` provider and a unique-violation mapper to 409 `ALREADY_EXISTS`; postgres uses `pg` + Drizzle), `--auth` (HS256 bearer tokens, `authenticate` and `requireRole` middlewares), `--docker`, `--ci` (GitHub Actions), `--web` (CORS, rate limiting, static `public/`, pretty dev logs), `--pm`, `--yes`/`-y` (defaults, no questions), `--no-install`. It installs missing packages with the detected package manager after writing files.
-- Then: `cp .env.example .env`, `pnpm brisk g feature <name>`, `pnpm dev`.
+- brisk owns mechanisms (routing, validation, DI, lifecycle, errors, typed client, OpenAPI, test client, template rendering). Choices (database, auth scheme, lint and format tools, Docker, CI, folder layout, pagination shape) live in the project: in the starter it began from and in its own `templates/`. Follow the project's existing choices; do not look for them in brisk.
+- New app: install `@raiyyan/brisk`, then `npx brisk init [--starter <name>] [--pm pnpm|npm|yarn] [--no-install]`. Starters: `minimal` (default; in-memory feature template, no database) and `sqlite-auth` (`node:sqlite` with migrations at startup, scrypt passwords, HS256 bearer tokens, admin seeded from env, CORS, rate limit, static files, Dockerfile and compose). `--starter list` lists them.
+- `brisk init` copies the starter without overwriting any file, merges `type`, `engines`, scripts and dependencies into `package.json` (pinning brisk to the running version), installs, and runs `brisk agents`. There are no other init flags.
+- Both starters ship oxlint and oxfmt (`lint`, `format`, `format:check` scripts), `typecheck`, `test`, `dev`, and a deletable `notes` example feature.
+- `src/schemas.ts` in a starter holds `isoDate()`, `PageQuery` and `page(item)`. They are project code, not brisk exports.
+- Then: `cp .env.example .env`, `npx brisk g feature <name>`, `npm run dev`.
 - `npx brisk agents` adds or refreshes a brisk section (between `<!-- brisk:start -->` and `<!-- brisk:end -->`) in the project's `AGENTS.md` and makes `CLAUDE.md` import `@AGENTS.md` and `@node_modules/@raiyyan/brisk/AGENTS.md`. Run it again after upgrading brisk.
 
 ## Not in your way
 
 brisk owns only its own routes. Everything else is plain Express on a plain Node server, so any Express middleware or Node library works as it would without brisk. The escape hatches:
 
-- `configureExpress(expressApp)`: full Express access, before JSON parsing and before brisk's routes.
+- `use: [fromExpress(cors()), ...]` in `defineApp`: any Express middleware for every request, before brisk's routes (after `/health` and `/openapi.json`, so it never blocks them).
+- `mount: { "/path": handler }` in `defineApp`: Express handlers that are not brisk routes (static files, GraphQL, tRPC, webhooks, a legacy router, a SPA fallback). They answer only what brisk's routes did not.
+- `http.settings`: Express app settings (`{ "trust proxy": 1 }`, `{ "query parser": "extended" }`).
+- `fromExpress(handler)`: any Express middleware in one route's `use`, in order with brisk's middlewares.
 - `instance.express`: the Express app itself (for adapters; serverless uses `app.create()`).
 - `instance.server` and the `HttpServer` token: the Node server, for WebSockets and timeouts.
 - `ListenOptions.server`: bring your own server (HTTPS, tuned timeouts).
@@ -33,13 +39,14 @@ brisk owns only its own routes. Everything else is plain Express on a plain Node
 - `app.start()`: the same app without HTTP, for workers and schedulers.
 - `ctx.res`: write a raw response from any handler.
 
-## Project layout
+## Project layout and generators
 
 ```
 src/
   env.ts                       defineEnv(...)
   app.ts                       export const app = defineApp({...}); export type Api = typeof app
   main.ts                      await app.listen(env.PORT)
+  schemas.ts                   isoDate(), PageQuery, page(item)
   middlewares/<name>.ts        defineMiddleware(...)
   features/
     index.ts                   export const controllers = { users: usersController }  (keep the @brisk markers)
@@ -48,10 +55,15 @@ src/
       <name>.repository.ts     data access only
       <name>.service.ts        business rules, throws error classes
       <name>.controller.ts     defineController(...): HTTP only, delegates to the service
+templates/<kind>/              what `brisk g <kind> <name>` renders; owned by the project
 test/<name>.test.ts
 ```
 
-Generate a feature with `pnpm brisk g feature <name>`; it writes the four files (singular entity names: `products` gives `Product`, `CreateProductBody`) and a test, registers the controller as `products: productsController` at the `// @brisk:imports` and `// @brisk:controllers` markers in `src/features/index.ts`, and runs the project's formatter (oxfmt or Prettier) on the result. `pnpm brisk g middleware <name>` writes a middleware. `pnpm brisk help` lists commands.
+- Create new code with `npx brisk g <kind> <name>` (`feature`, `middleware`, or any folder in `templates/`), then edit it. When the project's conventions change, change the templates too.
+- `brisk g` renders `templates/<kind>/` into the project root. Tokens in paths and contents: `{{kebab}}` (`blog-posts`), `{{camel}}` (`blogPosts`), `{{pascal}}` (`BlogPosts`), `{{snake}}` (`blog_posts`), `{{entity}}` (`BlogPost`), `{{entityCamel}}` (`blogPost`).
+- A template file named `<target>.<marker>.insert` is inserted into the existing `<target>` before the line containing `@brisk:<marker>`: `// @brisk:imports` and `// @brisk:controllers` in `src/features/index.ts`, `// @brisk:migrations` in `sqlite-auth`'s `src/database/migrations.ts`. Never delete marker lines.
+- Everything is checked before anything is written: an unknown token, an existing file or a missing marker fails with nothing changed. Output is formatted with the project's oxfmt, prettier or biome when installed.
+- Keep `templates/` out of lint, format, typecheck and tests (the starters' configs do).
 
 ## Environment
 
@@ -102,38 +114,48 @@ export const usersController = defineController({ prefix: "/users", use: [authen
   - success status: 201 for POST, 200 otherwise; `res.status(code)` in the handler overrides the default, and the `status` option overrides both
   - writing to `res` yourself also works; brisk then sends nothing.
 - `setup` runs once per instance, when it is built (`listen`, `start`, `create`, `createTestClient`); `inject()` works there and in handlers. Configuration errors (a route left out of the returned object, an invalid `status`) are thrown then, not at `defineApp`.
-- Dates in a `response` schema: `z.date().transform((d) => d.toISOString()).pipe(z.iso.datetime())`, so the client type and OpenAPI say `string` (`date-time`).
+- Dates in a `response` schema: `z.date().transform((d) => d.toISOString()).pipe(z.iso.datetime())` (the starters' `isoDate()`), so the client type and OpenAPI say `string` (`date-time`).
+- Two routes with the same method and path (parameter names aside) fail when an instance is built.
+- `defineController({ prefix, use, providers })`: `providers` are created at startup with the app (a feature's WebSocket gateway, cache invalidator). They come before the app's providers, so the app's and tests' values for the same token win.
 
 ## Middlewares
 
-- A middleware may not return `req`, `res`, `requestId`, `params`, `query`, `body` or `headers` (compile error). Returning `log` replaces the request logger.
+`defineMiddleware(fn)` or `defineMiddleware({ params?, query?, security? }, fn)`. There is no name argument.
 
 ```ts
-export const authenticate = defineMiddleware(async ({ req }) => {
-  const user = await verify(req.get("authorization"));
+const bearer = { bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" } } satisfies SecuritySchemes;
+
+export const authenticate = defineMiddleware({ security: bearer }, async ({ req, log }) => {
+  const user = await inject(Sessions).verify(req.get("authorization"));
   if (!user) throw new UnauthorizedError("Invalid token", { challenge: "Bearer" });
-  return { user };
+  return { user, log: log.child({ userId: user.id }) };
 });
 
-export const requireRole = (role: Role) =>
-  defineMiddleware(async (ctx) => {
+export const requireProjectRole = (role: ProjectRole) =>
+  defineMiddleware({ params: z.object({ projectId: z.uuid() }), security: bearer }, async (ctx) => {
     const { user } = await authenticate.run(ctx);
-    if (user.role !== role) throw new ForbiddenError();
-    return { user };
+    return { projectRole: await inject(ProjectAccess).require(user.id, ctx.params.projectId, role) };
   });
 ```
 
-Return an object to add typed fields to the handler's `ctx`, return nothing for a pure check, throw an error class to stop the request. Each middleware runs at most once per request: another middleware or a handler can `await other.run(ctx)` to reuse its result. Sync or async both work.
+- Return an object to add typed fields to the handler's `ctx`, return nothing for a pure check, throw an error class to stop the request. Sync or async.
+- Each middleware runs at most once per request: another middleware or a handler can `await other.run(ctx)` to reuse its result.
+- A middleware may not return `req`, `res`, `requestId`, `params`, `query`, `body` or `headers` (compile error). Returning `log` replaces the request logger.
+- Order: controller `use`, group `use`, route `use`, then the route's validation. Authentication therefore rejects before input is validated.
+- `params` / `query` options: validated before the middleware runs (400 `VALIDATION_FAILED`, async refinements work) and typed on its ctx. Use them for per-resource authorization such as project membership.
+- `security`: OpenAPI security scheme objects. Every route behind the middleware gets `security` in OpenAPI and the document gets `components.securitySchemes`; routes without it stay public. `middleware.security` reads it back.
+- `fromExpress(handler)` runs Express middleware inside `use`, in order: `use: [authenticate, fromExpress(multer(...).single("file"))]` parses uploads only after authentication. Errors passed to `next` reach the app's error handler (`http-errors` `status`/`expose` honored, `errors.mappers` apply); if it ends the response, the route stops there.
+- App-wide middleware (CORS, helmet, rate limits, an audit log) goes in the app's `use`: `defineApp({ use: [fromExpress(cors({ origin })), audit] })`. A `defineMiddleware` there runs once per request, stops it by throwing, and adds its `security` to every OpenAPI operation, but its output is not typed on handler ctx: to type it, list it in the controller's `use` as well (it still runs once), or read it with `await audit.run(ctx)`.
 
 ## Dependency injection
 
 - A class with a no-argument constructor is its own token and a singleton per app: `readonly #repo = inject(UsersRepository)` in a field.
 - `defineToken<T>(name, factory?)` names anything else: config, clients, functions. Without a factory it must be provided.
-- `provide(token, value)` fixes a value: `defineApp({ providers: [provide(Clock, () => fixedDate)] })`, or `createTestClient(app, { providers: [...] })` to replace them in a test.
+- `provide(token, value)` fixes a value: `defineApp({ providers: [provide(Clock, () => fixedDate)] })`. Later entries win; the order is controllers' providers, the app's, then those passed to `createTestClient` / `listen` / `start` / `create`. Those last are added to the app's, not swapped in: a value for the same token wins, and every listed class is still created.
 - A class listed in `providers` is created at boot even if nothing injects it (WebSocket gateways, consumers, jobs) so its lifecycle hooks run.
 - `injectLazy(token)` returns `() => T` and creates on first call: for heavy clients or to break a circular dependency.
 - `inject()` works in class fields, token factories, controller setup, middlewares, handlers, lifecycle hooks, and timers or loops started from them. Cycles are reported as `A -> B -> A`.
-- `inject()` works for the whole request, including everything in `configureExpress` (GraphQL resolvers, tRPC procedures). It does not work in callbacks a library fires on its own outside a request (gRPC handlers, queue client callbacks, `ws` message listeners): resolve the dependency in a class field and use the field. Outside the app, use an instance's container: `instance.container.get(...)`. In unit tests with `new Container([...])`, call `container.get(...)`.
+- `inject()` works for the whole request, including the app's `use` and every `mount` (GraphQL resolvers, tRPC procedures). It does not work in callbacks a library fires on its own outside a request (gRPC handlers, queue client callbacks, `ws` message listeners): resolve the dependency in a class field and use the field. Outside the app, use an instance's container: `instance.container.get(...)`. In unit tests with `new Container([...])`, call `container.get(...)`.
 - `HttpServer` exists only once the instance listens: inject it in `onReady`, never in a field or `onInit` (that throws).
 - Unit tests without HTTP: `new Container([provide(Clock, fake)]).get(UsersService)`. `Logger` has a silent default there, so no logger provider is needed.
 
@@ -141,13 +163,15 @@ Return an object to add typed fields to the handler's `ctx`, return nothing for
 
 ```
 boot      providers' onInit (dependencies first) -> listen -> providers' onReady
-request   security headers -> request id -> configureExpress -> JSON body -> hooks.onRequest
-          -> controller/group/route middlewares -> Zod validation -> handler -> response -> hooks.onResponse
-          (any throw -> error handler -> hooks.onError)
-shutdown  SIGINT/SIGTERM -> stop accepting -> providers' onDrain (reverse)
+request   security headers -> request id -> /health, /openapi.json -> app use
+          -> brisk route: JSON body -> controller/group/route middlewares -> Zod validation -> handler -> response
+          -> 405 / OPTIONS -> mount -> 404
+          (any throw -> error handler -> hooks.onError; hooks.onResponse when the response closes)
+shutdown  SIGINT/SIGTERM -> /health answers 503 -> stop accepting -> providers' onDrain (reverse)
           -> in-flight requests finish with Connection: close (sockets still open after http.shutdownTimeoutMs are destroyed)
           -> providers' onShutdown (reverse) -> exit 0
 crash     unhandled rejection / uncaught exception -> logged fatal -> shutdown -> exit 1
+startup failure (a hook throws, port taken) -> logged fatal "startup failed" with provider and hook -> shutdown -> rethrown
 ```
 
 Implement `OnInit`, `OnReady`, `OnDrain`, `OnShutdown` on a provider class. `onDrain` is where long-lived work stops (close WebSockets and SSE, stop consumers and timers); `onShutdown` releases resources (database pools, clients). Hook failures are logged and shutdown continues. All hooks may be sync or async.
@@ -163,7 +187,8 @@ export const app = defineApp({
   logger: createLogger({ level: env.LOG_LEVEL, pretty: env.NODE_ENV === "development" }),
   openapi: { title: "Shop API", version: "1.0.0" },
   errors: { mappers: [uniqueViolation], exposeInternal: env.NODE_ENV === "development" },
-  configureExpress: (expressApp) => expressApp.use(cors({ origin: env.WEB_ORIGIN })),
+  use: [fromExpress(cors({ origin: env.WEB_ORIGIN }))],
+  mount: { "/static": express.static("public", { maxAge: "1h" }) },
 });
 export type Api = typeof app;
 
@@ -171,24 +196,28 @@ export type Api = typeof app;
 await app.listen(env.PORT);
 ```
 
-| Option             | Purpose                                                                                              |
-| ------------------ | ---------------------------------------------------------------------------------------------------- |
-| `prefix`           | Mount path for all controllers, such as `/api`                                                       |
-| `controllers`      | Controllers by name: `{ users: usersController }`; the names are the typed client's top level        |
-| `providers`        | `provide(token, value)` entries and classes to create at startup                                     |
-| `logger`           | A pino logger (`createLogger({ level, pretty })`); injectable as `Logger`                            |
-| `configureExpress` | `(expressApp) => void` with full Express access, before JSON parsing and before brisk routes         |
-| `hooks`            | `onRequest`, `onResponse`, `onError` only; startup and shutdown work goes in provider classes        |
-| `openapi`          | `{ title, version, description?, servers?, path? }`: serve the OpenAPI document                      |
-| `errors`           | `{ mappers, format, exposeInternal }`: translate library errors, change the error body, dev messages |
-| `http`             | `{ bodyLimit, trustProxy, securityHeaders, healthPath, shutdownTimeoutMs }`                          |
+| Option        | Purpose                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| `prefix`      | Mount path for all controllers, such as `/api`                                                         |
+| `controllers` | Controllers by name: `{ users: usersController }`; the names are the typed client's top level          |
+| `providers`   | `provide(token, value)` entries and classes to create at startup                                       |
+| `logger`      | A pino logger (`createLogger({ level, pretty })`); injectable as `Logger`                              |
+| `use`         | Middlewares for every request after `/health` and `/openapi.json`, before brisk's routes and mounts    |
+| `mount`       | `{ "/path": handler \| [handlers] }`: Express handlers that answer what brisk's routes did not         |
+| `hooks`       | `onResponse`, `onError` only; startup and shutdown work goes in provider classes                       |
+| `openapi`     | `{ title, version, description?, servers?, path? }`: serve the OpenAPI document                        |
+| `errors`      | `{ mappers, format, exposeInternal }`: translate library errors, change the error body, dev messages   |
+| `http`        | `{ bodyLimit, settings, securityHeaders, healthPath, shutdownTimeoutMs }`; health is 503 when draining |
 
-Name the `configureExpress` parameter `expressApp`: `app` would shadow the exported `app`.
+Mounts: paths are absolute (the `prefix` does not apply) and start with `/`; Express strips the path from `req.url`. brisk does not parse their bodies, so add a parser to the mount when it needs one (`[express.json(), handler]`). They get `getContext(req)`, `inject()`, the app's `use` and the error handler, and appear in the startup log as `MOUNT /path`. A mount never shadows a brisk route, so `mount: { "/": spaFallback }` is a fallback. brisk parses JSON only on its own routes.
+
+`http.settings` is applied with `app.set(name, value)` after brisk's defaults: `{ "trust proxy": 1 }` only behind a proxy you control, `{ "query parser": "extended" }` for nested query objects (the default is flat).
 
 - `app.listen(port, { host?, server?, manageProcess?, providers? })` builds a fresh instance, starts it and resolves with it. `app.start({ manageProcess?, providers? })` does the same without HTTP (workers). `app.create({ providers? })` returns an unstarted instance (serverless: `const instance = app.create(); await instance.init();`, then hand `instance.express` to the adapter).
-- Every call builds a new, independent instance; `providers` there replace the app's own.
+- Every call builds a new, independent instance; `providers` there are added after the app's own.
 - `app.manifest` and `app.openapi()` work on the definition, without starting anything.
 - The instance: `express`, `server`, `container`, `logger`, `manifest`, `openapi()`, `init()`, `shutdown()`.
+- `inject(ErrorTranslator)(error)` returns `{ status, code, message, details }` as a route would answer, `errors.mappers` applied and internal messages hidden: for GraphQL `maskError` or WebSocket close codes. Call it directly inside a request (resolvers, mounts), resolve it in a class field for library callbacks (`ws` message listeners), and use `instance.container.get(ErrorTranslator)` outside the app.
 - `manageProcess` (default `true`) installs signal and crash handling.
 
 ## Errors
@@ -240,6 +269,7 @@ Handled automatically:
 | Malformed JSON                                  | 400 `INVALID_JSON`                                                 |
 | Body over `http.bodyLimit`                      | 413 `PAYLOAD_TOO_LARGE`                                            |
 | Body sent to a `body` route that no parser read | 415 `UNSUPPORTED_MEDIA_TYPE`                                       |
+| Express middleware error with `status`+`expose` | that status; the message only when `expose` is true                |
 | Known path, wrong method                        | 405 with `Allow`; `OPTIONS` gets 204 with `Allow`                  |
 | Unknown path                                    | 404 `ROUTE_NOT_FOUND`                                              |
 | Result breaks its `response` schema             | 500 (a server bug)                                                 |
@@ -248,7 +278,9 @@ Handled automatically:
 ## Typed client
 
 - `createClient(app, { baseUrl })` in Node (the definition or an instance); in a browser `createClient<Api>(manifest, { baseUrl, headers?, fetch? })` from `@raiyyan/brisk/client`, with the manifest written by `brisk client --out web/src/api.manifest.ts` (run it again after changing routes). `Api` is `typeof app` (`export type Api = typeof app` in `src/app.ts`), imported with `import type`.
-- Calls: `await api.users.get({ params, query, body, headers })`. Inputs are typed by the route's schemas; every call accepts extra headers (such as `authorization`); a second argument is passed to `fetch` (`signal`).
+- Calls: `await api.users.get({ params, query, body, headers })`. Inputs are typed by the route's schemas; `params` and `query` also take the schema's output when a URL carries it (`z.stringbool()` takes `true`, `z.coerce.number()` takes `2`). Every call accepts extra headers (such as `authorization`); a second argument is passed to `fetch` (`signal`).
+- `FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer`/typed arrays and `ReadableStream` bodies are sent as they are (fetch sets the content type and multipart boundary); other bodies, strings included, are JSON.
+- `api.files.upload.raw(input, init?)` sends the same request and resolves to the raw `Response` whatever its status, with the client's headers applied and string bodies sent as they are: for downloads, uploads (`body: formData`) and non-JSON. Its body type is `RawBody` or the route's body.
 - A call resolves to the `response` schema's output, else the handler's return value after JSON (`Date` becomes `string`); a stream or bytes come back as the raw `Response`, nothing as `undefined`.
 - Non-2xx rejects with `ApiError` (`status`, `code`, `message`, `details`, `requestId`, `body`). Branch on `error.code`, not the message.
 
@@ -257,6 +289,8 @@ Handled automatically:
 - `defineApp({ openapi: { title, version, description?, servers?, path? } })` serves an OpenAPI 3.1 document at `/openapi.json` (`path: false` serves nothing). `app.openapi()` returns it; `brisk openapi --out openapi.json` writes it.
 - `operationId` is `controller.route`, tags are controller names; request schemas are documented as clients send them, `response` as clients receive it.
 - Transforms and `z.date()` are documented as "any": end response schemas in the type they produce (`.pipe(z.iso.datetime())`).
+- Routes behind a middleware with `security` list its schemes; the document lists them under `components.securitySchemes`.
+- `/openapi.json` and `/health` are answered before the app's `use`.
 
 ## Testing
 
@@ -273,10 +307,43 @@ it("validates the body", async () => {
 });
 ```
 
-`createTestClient(app, { providers? })` starts a fresh instance on a random port with the full lifecycle (`providers` replace the app's own) and returns `call` (the typed client: `await api.call.users.create({ body, headers })`, rejecting with `ApiError`), raw `get | post | put | patch | delete(path, { body, headers })`, `baseUrl`, `instance` (the running `AppInstance`: `api.instance.container.get(X)`) and `close()`. Use `call` for behavior and the raw methods for status codes, headers and malformed input. A raw string or `Uint8Array` body is sent as is. `res.body` is `unknown`: parse it with Zod or use `toMatchObject`. `readError(res)` returns the typed error object.
+`createTestClient(app, { providers? })` starts a fresh instance on a random port with the full lifecycle (`providers` are added after the app's own; a value for the same token wins) and returns `call` (the typed client: `await api.call.users.create({ body, headers })`, rejecting with `ApiError`), raw `get | post | put | patch | delete(path, { body, headers })`, `baseUrl`, `instance` (the running `AppInstance`: `api.instance.container.get(X)`) and `close()`. Use `call` for behavior and the raw methods for status codes, headers and malformed input. A raw string or `Uint8Array` body is sent as is. `res.body` is `unknown`: parse it with Zod or use `toMatchObject`. `readError(res)` returns the typed error object.
+
+`fetch`, and so the test client's raw methods, adds `Cache-Control: no-cache` to a request carrying `If-None-Match`, which disables 304. Test 304s with `node:http`, or send `cache-control: max-age=0`.
 
 ## Recipes
 
+Shared access rules: put the rules in one service and call it from every entry point (the middleware with declared `params` above, WebSocket gateways, GraphQL resolvers). Never re-implement them per transport.
+
+```ts
+export class ProjectAccess {
+  readonly #members = inject(MembersRepository);
+  async roleIn(userId: string, projectId: string): Promise<ProjectRole | undefined> {
+    return (await this.#members.find(projectId, userId))?.role;
+  }
+  /** 404 for a non-member (ids do not leak), 403 for too low a role. */
+  async require(userId: string, projectId: string, role: ProjectRole): Promise<ProjectRole> {
+    const actual = await this.roleIn(userId, projectId);
+    if (!actual) throw new NotFoundError("Project not found");
+    if (RANK[actual] < RANK[role]) throw new ForbiddenError(`Requires the ${role} role`);
+    return actual;
+  }
+}
+```
+
+A gateway resolves it in a class field (`readonly #access = inject(ProjectAccess)`), because `ws` callbacks run outside the app; a resolver calls `inject(ProjectAccess).require(...)`.
+
+Uploads: parse multipart on the route that takes it, after authentication. Clients send it with `.raw` and a `FormData` body:
+
+```ts
+const upload = fromExpress(multer({ dest: "uploads/", limits: { fileSize: 5_000_000 } }).single("file"));
+// in a controller with use: [authenticate]
+create: route.post("/:taskId/attachments", { use: [upload] }, ({ req, params }) => {
+  if (!req.file) throw new BadRequestError("Send the file in the `file` field");
+  return attachments.save(params.taskId, req.file);
+}),
+```
+
 WebSocket gateway (`ws`, works the same with Socket.IO):
 
 ```ts
@@ -294,27 +361,25 @@ export class ChatGateway implements OnReady, OnDrain {
 export const app = defineApp({ controllers, providers: [ChatGateway] });
 ```
 
-Plain Express (static files, SSE, uploads, webhooks, proxies) through `configureExpress`, which runs before JSON parsing:
+Plain Express (CORS, static files, SSE, webhooks, form bodies) through `use` and `mount`:
 
 ```ts
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => {
-    expressApp.use(cors({ origin: env.WEB_ORIGIN }));
-    expressApp.use("/static", express.static("public"));
-    expressApp.post("/webhooks/stripe", express.raw({ type: "application/json" }), stripeWebhook);
-    expressApp.post("/upload", multer().single("file"), upload);
-    expressApp.use(express.urlencoded({ extended: false }));
-    expressApp.get("/events", (req, res) => {
+  use: [fromExpress(cors({ origin: env.WEB_ORIGIN })), fromExpress(express.urlencoded({ extended: false }))],
+  mount: {
+    "/static": express.static("public"),
+    "/webhooks/stripe": [express.raw({ type: "application/json" }), stripeWebhook], // raw bytes for signatures
+    "/events": (req, res) => {
       res.writeHead(200, { "content-type": "text/event-stream" });
       res.write(`data: ${getContext(req).requestId}\n\n`);
-    });
+    },
   },
   http: { securityHeaders: { "content-security-policy": "default-src 'self'" } },
 });
 ```
 
-Requests there have a context (`getContext(req)`) and thrown errors use the app's error handler. A form body parsed there reaches a brisk route's `body` schema.
+Mounts have a context (`getContext(req)`) and thrown errors use the app's error handler. A form body parsed in `use` reaches a brisk route's `body` schema.
 
 Worker thread pool for CPU-heavy work:
 
@@ -350,30 +415,33 @@ Lazy loading: `injectLazy(HeavyClient)` defers creation; heavy code loads on dem
 
 Database clients: a class with `async onInit()` that connects and `onShutdown()` that disconnects. Translate driver errors once with `errors.mappers` (for example unique violation to `ConflictError`).
 
-GraphQL with Yoga. Resolvers call `inject()`:
+GraphQL with Yoga. Resolvers, the context factory and `maskError` call `inject()`. Mount it through a function (Yoga's own type is not an Express `RequestHandler`):
 
 ```ts
-const yoga = createYoga({
-  schema: createSchema({
-    typeDefs: "type Query { user(id: ID!): User }",
-    resolvers: { Query: { user: (_, { id }) => inject(UsersService).get(id) } },
-  }),
+export const yoga = createYoga<{ req: Request; res: Response }, { user: User | undefined }>({
+  schema, // resolvers: inject(ProjectAccess).require(user.id, args.id, "viewer"), then the service
+  context: async ({ req }) => ({ user: await inject(Sessions).verify(req.get("authorization")) }),
+  maskError: (error) => {
+    if (error instanceof GraphQLError && !error.originalError) return error; // syntax and validation errors
+    const cause = error instanceof GraphQLError ? error.originalError : error;
+    const { status, code, message } = inject(ErrorTranslator)(cause);
+    return new GraphQLError(message, { extensions: { code, status } });
+  },
 });
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => expressApp.use(yoga.graphqlEndpoint, yoga),
+  mount: { [yoga.graphqlEndpoint]: (req, res) => yoga(req, res) },
   http: { securityHeaders: { "content-security-policy": false } }, // GraphiQL needs scripts; or set a GraphiQL-compatible policy
 });
 ```
 
-GraphQL with Apollo Server. `configureExpress` runs before brisk's JSON parser, so the Apollo route adds `express.json()` itself:
+GraphQL with Apollo Server. brisk does not parse mount bodies, so the mount adds `express.json()`:
 
 ```ts
 await apollo.start();
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) =>
-    expressApp.use("/graphql", express.json(), expressMiddleware(apollo, { context })),
+  mount: { "/graphql": [express.json(), expressMiddleware(apollo, { context })] },
 });
 ```
 
@@ -388,7 +456,7 @@ const router = t.router({
 });
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => expressApp.use("/trpc", createExpressMiddleware({ router })),
+  mount: { "/trpc": createExpressMiddleware({ router }) },
 });
 ```
 
@@ -426,7 +494,7 @@ export const app = defineApp({ controllers, providers: [GrpcServer] });
 
 Socket.IO: `this.#io = new Server(inject(HttpServer))` in `onReady`, `await this.#io.close()` in `onDrain`, and list the class in `providers`.
 
-Microfrontends and serving frontends: serve static assets and remote entries with `express.static` in `configureExpress`. brisk's strict API headers block cross-origin asset loading, so relax them and allow the shell's origin:
+Microfrontends and serving frontends: serve static assets and remote entries with `express.static` in `mount`. brisk's strict API headers block cross-origin asset loading, so relax them and allow the shell's origin:
 
 ```ts
 export const app = defineApp({
@@ -438,10 +506,8 @@ export const app = defineApp({
       "x-frame-options": false, // only when the frontend is embedded in iframes
     },
   },
-  configureExpress: (expressApp) => {
-    expressApp.use(cors({ origin: env.SHELL_ORIGIN }));
-    expressApp.use("/remotes/checkout", express.static("dist/checkout"));
-  },
+  use: [fromExpress(cors({ origin: env.SHELL_ORIGIN }))],
+  mount: { "/remotes/checkout": express.static("dist/checkout") },
 });
 ```
 
@@ -451,7 +517,7 @@ Custom or HTTPS server: `await app.listen(443, { server: https.createServer(tlsO
 
 Serverless: `const instance = app.create(); await instance.init();`, then pass `instance.express` to the platform adapter.
 
-Cluster, PM2, Kubernetes: brisk keeps no per-process state; run one process per core. Behind a load balancer set `server.keepAliveTimeout` above the balancer's idle timeout (via `instance.server` on the instance `listen` resolves with, or your own server) to avoid 502s. Bind `host: "0.0.0.0"` in containers when needed.
+Cluster, PM2, Kubernetes: brisk keeps no per-process state; run one process per core. The app's own in-process state (event buses, uploads on local disk, in-memory rate limits) does not span instances: move it to shared services first. `/health` answers 503 once shutdown begins. Behind a load balancer set `server.keepAliveTimeout` above the balancer's idle timeout (via `instance.server` on the instance `listen` resolves with, or your own server) to avoid 502s. Bind `host: "0.0.0.0"` in containers when needed.
 
 ## Do and don't
 
@@ -460,8 +526,10 @@ Cluster, PM2, Kubernetes: brisk keeps no per-process state; run one process per
 - Do destructure what you need from `ctx` (`({ params, user, log }) => ...`) rather than copying the whole context.
 - Do keep services and repositories free of Express types; take plain values, return plain values.
 - Do give every route that takes input a schema, and a `response` schema for anything returning stored data.
-- Do add plain Express pieces through `configureExpress`; don't add routes to `instance.express` afterwards (they would land after the 404 handler).
-- Do use `provide()` in tests to swap dependencies; don't mutate singletons.
+- Do add app-wide middleware through the app's `use`, non-brisk handlers through `mount`, and per-route Express middleware through `fromExpress` in a route's `use`; don't add routes to `instance.express` afterwards (they would land after the 404 handler).
+- Do generate new features and middlewares with `brisk g`, and update `templates/` when conventions change; don't hand-copy a feature.
+- Do keep authorization rules in a service shared by middlewares, gateways and resolvers.
+- Do use `provide()` in tests to swap dependencies (test providers are added after the app's own); don't mutate singletons.
 - Do declare the app once (`export const app = defineApp(...)`) and import it everywhere; each `listen`, `start`, `create` or `createTestClient` builds its own instance. Don't write a `buildApp()` factory.
 - Do put long-lived connections behind `onDrain`, and resources behind `onShutdown`. Startup and shutdown work lives in provider classes; `defineApp({ hooks })` is per-request only.
 - Don't call `inject()` inside callbacks a library fires on its own (`ws` message listeners, gRPC handlers, queue clients); resolve the dependency in a class field.