ddd-ts-kit 0.12.0 → 0.14.0

package/templates/controller/controller.none.ts.tpl

@@ -23,7 +23,7 @@ const anyObject = customSchema<Record<string, unknown>>(
 const body = anyObject;
 
 {{/if}}
-{{#if route.returnsId}}
+{{#if route.ownAccepted}}
 const accepted = customSchema<{ readonly id: string }>(
   (input) =>
     typeof input === 'object' && input !== null && 'id' in input && typeof input.id === 'string'
@@ -50,7 +50,7 @@ const answer = anyObject;
   body,
   {{/if}}
   {{#if route.returnsId}}
-  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: accepted },
+  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: {{route.acceptedBody}} },
   {{/if}}
   {{#if route.returnsNothing}}
   response: { status: {{route.status}}, description: 'Done.' },

package/templates/controller/controller.search.ts.tpl

@@ -1,6 +1,9 @@
 {{#if validation.zod}}
 import { z } from 'zod';
 {{/if}}
+{{#if validation.typebox}}
+import Type from 'typebox';
+{{/if}}
 import {
   Controller,
   pageQuerySchema,
@@ -23,6 +26,9 @@ import { zodSchema } from '@ddd-ts-kit/validation/zod';
 {{#if validation.classValidator}}
 import { classSchema } from '@ddd-ts-kit/validation/class-validator';
 {{/if}}
+{{#if validation.typebox}}
+import { typeboxSchema } from '@ddd-ts-kit/validation/typebox';
+{{/if}}
 {{route.imports}}
 
 // TODO(domain): list here the fields of {{name.pascal}}Sort a client may sort by, and bound the size of a page.
@@ -40,6 +46,14 @@ const line = zodSchema(
 {{#if validation.classValidator}}
 const line = classSchema({{name.pascal}}Line);
 {{/if}}
+{{#if validation.typebox}}
+const line = typeboxSchema(
+  Type.Object({
+    id: Type.String(),
+    // TODO(domain): declare the fields of {{name.pascal}}Item that are part of the public contract.
+  }),
+);
+{{/if}}
 {{#if search.customSchema}}
 interface {{name.pascal}}Line {
   readonly id: string;

package/templates/controller/controller.standard-schema.ts.tpl

@@ -26,7 +26,7 @@ const anyObject: StandardSchemaV1<unknown, Record<string, unknown>> = {
 const body = standardSchema(anyObject, { type: 'object' });
 
 {{/if}}
-{{#if route.returnsId}}
+{{#if route.ownAccepted}}
 const acceptedShape: StandardSchemaV1<unknown, { readonly id: string }> = {
   '~standard': {
     version: 1,
@@ -62,7 +62,7 @@ const answer = standardSchema(anyObject, { type: 'object' });
   body,
   {{/if}}
   {{#if route.returnsId}}
-  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: accepted },
+  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: {{route.acceptedBody}} },
   {{/if}}
   {{#if route.returnsNothing}}
   response: { status: {{route.status}}, description: 'Done.' },

package/templates/controller/controller.typebox.ts.tpl

@@ -0,0 +1,98 @@
+{{#if route.declaresSchema}}
+import Type from 'typebox';
+{{/if}}
+import { {{route.httpImports}} } from '@ddd-ts-kit/http';
+import type { {{route.busType}} } from '@ddd-ts-kit/kernel';
+{{#if route.usesInfer}}
+import type { Infer } from '@ddd-ts-kit/validation';
+{{/if}}
+{{#if route.declaresSchema}}
+import { typeboxSchema } from '@ddd-ts-kit/validation/typebox';
+{{/if}}
+{{route.imports}}
+
+{{#if route.hasParams}}
+const params = typeboxSchema(Type.Object({ {{route.typeboxParams}} }));
+
+{{/if}}
+{{#if route.hasBody}}
+const body = typeboxSchema(
+  Type.Object({
+    // TODO(domain): declare the fields the client sends for "{{name.words}}", with shape constraints only (types, formats, lengths); business rules stay in the domain.
+  }),
+);
+
+{{/if}}
+{{#if route.ownAccepted}}
+const accepted = typeboxSchema(Type.Object({ id: Type.String() }));
+
+{{/if}}
+{{#if route.isQuery}}
+const answer = typeboxSchema(
+  Type.Object({
+    // TODO(domain): declare the fields of {{name.pascal}}Result that are part of the public contract.
+  }),
+);
+
+{{/if}}
+@Controller({
+  {{route.access}}
+  method: '{{route.method}}',
+  path: '{{route.groupPath}}',
+  summary: '{{name.title}}',
+  {{#if route.hasTypedParams}}
+  params,
+  {{/if}}
+  {{#if route.hasBody}}
+  body,
+  {{/if}}
+  {{#if route.returnsId}}
+  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: {{route.acceptedBody}} },
+  {{/if}}
+  {{#if route.returnsNothing}}
+  response: { status: {{route.status}}, description: 'Done.' },
+  {{/if}}
+  {{#if route.isQuery}}
+  response: { status: {{route.status}}, description: 'The answer.', body: answer },
+  {{/if}}
+  // TODO(domain): list the codes of the refusals "{{name.words}}" can raise, as their factories set them, so that they appear in the contract with their status (`errors/known-code`).
+  errors: [],
+})
+export class {{name.pascal}}Controller {
+  constructor({{route.constructorParams}}) {}
+
+  {{#if route.isQuery}}
+  async handle({{route.requestParam}}): Promise<{{route.answerType}}> {
+    {{#unless route.mapper}}
+    // TODO(domain): build the query from `request` (params, query string); the actor is already there.
+    {{/unless}}
+    {{#if route.serializer}}
+    return this.serializer.serialize(await this.{{route.bus}}.execute({{route.message}}));
+    {{/if}}
+    {{#unless route.serializer}}
+    // TODO(domain): map the answer of the query to the public fields.
+    await this.{{route.bus}}.execute({{route.message}});
+
+    return {};
+    {{/unless}}
+  }
+  {{/if}}
+  {{#if route.returnsId}}
+  async handle({{route.requestParam}}): Promise<{{route.acceptedType}}> {
+    {{#unless route.mapper}}
+    // TODO(domain): build the command from `request` (body, params); the actor is already there.
+    {{/unless}}
+    const id = await this.{{route.bus}}.execute({{route.message}});
+
+    return { id };
+  }
+  {{/if}}
+  {{#if route.returnsNothing}}
+  async handle({{route.requestParam}}): Promise<void> {
+    {{#unless route.mapper}}
+    // TODO(domain): build the command from `request` (body, params); the actor is already there.
+    {{/unless}}
+    await this.{{route.bus}}.execute({{route.message}});
+  }
+  {{/if}}
+}

package/templates/controller/controller.zod.ts.tpl

@@ -23,7 +23,7 @@ const body = zodSchema(
 );
 
 {{/if}}
-{{#if route.returnsId}}
+{{#if route.ownAccepted}}
 const accepted = zodSchema(z.object({ id: z.string() }), { io: 'output' });
 
 {{/if}}
@@ -48,7 +48,7 @@ const answer = zodSchema(
   body,
   {{/if}}
   {{#if route.returnsId}}
-  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: accepted },
+  response: { status: {{route.status}}, description: 'Done; the body carries the identifier.', body: {{route.acceptedBody}} },
   {{/if}}
   {{#if route.returnsNothing}}
   response: { status: {{route.status}}, description: 'Done.' },

package/templates/docs/openapi.json.tpl

@@ -262,6 +262,21 @@
               "FORBIDDEN"
             ]
           },
+{{#if presentation.negotiated}}
+          "406": {
+            "description": "Not Acceptable. Error codes: NOT_ACCEPTABLE.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            },
+            "x-error-codes": [
+              "NOT_ACCEPTABLE"
+            ]
+          },
+{{/if}}
           "422": {
             "description": "Unprocessable Content. Error codes: VALIDATION_FAILED.",
             "content": {

package/templates/init/CLAUDE.md.tpl

@@ -8,7 +8,7 @@ A ddd-ts-kit project: one bounded context per directory of `{{config.contextsDir
 - `npx ddd-ts-kit check --changed-since <ref>`: the architecture rules on what changed; `npx ddd-ts-kit explain <rule-id>` gives the reason and an example.
 - `npx ddd-ts-kit list --json`: the map of the contexts. `npx ddd-ts-kit describe <context> --json`: one context as data (use cases, routes, events, ports, dependencies).
 - `npx ddd-ts-kit status`: the next step of the plan, the slices by status, the markers left per context. `npx ddd-ts-kit todo [<context>]`: each remaining `TODO(domain)` and `it.todo` as `file:line`.
-- `npx ddd-ts-kit docs`: regenerates the context map and the generated sections of each `CONTEXT.md`; `npm run docs:generate` the OpenAPI contract and the event catalog.
+- `npx ddd-ts-kit docs`: regenerates the context map and the generated sections of each `CONTEXT.md`; `npm run docs:generate` the OpenAPI contract, the forms and the event catalog.
 
 ## Read less
 
@@ -29,7 +29,7 @@ Never edit `<context>.declarations.ts`: `generate`, `docs` and `npm run dev` rew
 {{#if assembly.discovery}}
 Never edit `<context>.dependencies.ts`: `generate`, `docs` and `npm run dev` rewrite it from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
 {{/if}}
-Never edit the contracts under `openapi/` (`openapi/openapi.yaml`, one file per document when `openapi.documents` splits it), `docs/integration/asyncapi.yaml`, `docs/integration/event-catalog.md`, `{{config.platformDir}}/http/openapi-documents.ts`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run docs:generate`, `npx ddd-ts-kit docs` and `npx ddd-ts-kit depcruise-config --write`. `stored-events.lock.json` is written by `npx ddd-ts-kit docs --stored-events` once the shape of a version is final (`docs --check` fails while one is unrecorded), never by hand: a stored shape changes only by a new version with its upcaster (`event-sourcing/upcaster-required`).
+Never edit the contracts under `openapi/` (`openapi/openapi.yaml`, one file per document when `openapi.documents` splits it, the forms of `openapi/forms/`), `docs/integration/asyncapi.yaml`, `docs/integration/event-catalog.md`, `{{config.platformDir}}/http/openapi-documents.ts`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run docs:generate`, `npx ddd-ts-kit docs` and `npx ddd-ts-kit depcruise-config --write`. `stored-events.lock.json` is written by `npx ddd-ts-kit docs --stored-events` once the shape of a version is final (`docs --check` fails while one is unrecorded), never by hand: a stored shape changes only by a new version with its upcaster (`event-sourcing/upcaster-required`).
 {{#if sdk.on}}
 {{sdk.instruction}}
 {{/if}}

package/templates/init/platform/auth/http-boundary.ts.tpl

@@ -45,9 +45,12 @@ import { multipartUploads } from '@ddd-ts-kit/http/uploads';
 {{/if}}
 import { tracedRoutes } from '@ddd-ts-kit/tracing';
 import { principalOf } from '{{alias.platform}}/auth/principal-of{{alias.ext}}';
+{{#if presentation.any}}
+import type { Presentation } from '{{alias.platform}}/http/presentation-of{{alias.ext}}';
+{{/if}}
 
 /** What the HTTP adapter needs at the edge of the application: spread into its mount options, for every route. */
-export interface HttpBoundary {
+export interface HttpBoundary{{#if presentation.any}} extends Presentation{{/if}} {
   readonly resolvePrincipal: (raw: unknown) => Promise<Session>;
   /** Every handler runs inside it, with the correlation id, the actor and the session of its request. */
   readonly executionScope: ExecutionScope;
@@ -92,21 +95,29 @@ interface Edge {
   /** Where a request answered 5xx is reported, unless a bus already reported its failure. */
   readonly errors: ErrorReporter;
 {{/if}}
+{{#if presentation.any}}
+  readonly presentation: Presentation;
+{{/if}}
 }
 
 /** A request is authenticated once, then handled inside the execution scope, so infrastructure sees who acts and under which correlation. */
 {{#if errors.none}}
-{{#unless audit.on}}
+{{#unless presentation.widensEdge}}
 export function httpBoundary({ authenticator, executionScope, errorMapper, clock, logger }: Edge): HttpBoundary {
 {{/unless}}
-{{#if audit.on}}
+{{#if presentation.widensEdge}}
 export function httpBoundary({
   authenticator,
   executionScope,
   errorMapper,
   clock,
   logger,
+{{#if audit.on}}
   refusals,
+{{/if}}
+{{#if presentation.any}}
+  presentation,
+{{/if}}
 }: Edge): HttpBoundary {
 {{/if}}
 {{/if}}
@@ -121,11 +132,17 @@ export function httpBoundary({
   refusals,
 {{/if}}
   errors,
+{{#if presentation.any}}
+  presentation,
+{{/if}}
 }: Edge): HttpBoundary {
   const report = reportHttpErrors(errors);
 
 {{/if}}
   return {
+{{#if presentation.any}}
+    ...presentation,
+{{/if}}
     resolvePrincipal: principalOf(authenticator),
     executionScope,
     errorMapper,

package/templates/init/platform/compose-application.manual.ts.tpl

@@ -26,6 +26,12 @@ import { auditModule } from '{{alias.platform}}/audit/audit.module{{alias.ext}}'
 {{#if http.any}}
 import { httpBoundary, type HttpBoundary } from '{{alias.platform}}/auth/http-boundary{{alias.ext}}';
 {{/if}}
+{{#if presentation.any}}
+import { presentationOf } from '{{alias.platform}}/http/presentation-of{{alias.ext}}';
+{{/if}}
+{{#if presentation.forms}}
+import { withForms } from '{{alias.platform}}/http/with-forms{{alias.ext}}';
+{{/if}}
 {{#if authz.rebac}}
 import { relateSystemActors } from '{{alias.platform}}/auth/relate-system-actors{{alias.ext}}';
 {{/if}}
@@ -123,10 +129,19 @@ export function composeApplication(
 {{/unless}}
 
   platform.protection.declare(contexts.flatMap((context) => context.useCases));
+{{#if presentation.any}}
+  // What the server answers in and which fields each caller sees: the forms and the contract are given the same.
+  const presentation = presentationOf(platform.access, clock);
+{{/if}}
 
   return {
 {{#if http.any}}
+{{#if presentation.forms}}
+    routes: withForms(defineRoutes(...contexts.map((context) => context.routes)), presentation),
+{{/if}}
+{{#unless presentation.forms}}
     routes: defineRoutes(...contexts.map((context) => context.routes)),
+{{/unless}}
     boundary: httpBoundary({
       authenticator: options.authenticator,
       executionScope: platform.scope,
@@ -138,6 +153,9 @@ export function composeApplication(
 {{/if}}
 {{#if errors.sentry}}
       errors: platform.errors,
+{{/if}}
+{{#if presentation.any}}
+      presentation,
 {{/if}}
     }),
 {{/if}}

package/templates/init/platform/compose-application.tsyringe.ts.tpl

@@ -1,6 +1,11 @@
 import { installAspectRuntime } from '@ddd-ts-kit/aspects';
 {{#if http.any}}
+{{#if presentation.any}}
+import { Access, Authenticator } from '@ddd-ts-kit/auth';
+{{/if}}
+{{#unless presentation.any}}
 import { Authenticator } from '@ddd-ts-kit/auth';
+{{/unless}}
 {{/if}}
 import {
 {{#if routes.declaredControllers}}
@@ -94,6 +99,12 @@ import { securitySchemes } from '{{alias.platform}}/auth/security-schemes{{alias
 {{#if http.any}}
 import { httpBoundary, type HttpBoundary } from '{{alias.platform}}/auth/http-boundary{{alias.ext}}';
 {{/if}}
+{{#if presentation.any}}
+import { presentationOf } from '{{alias.platform}}/http/presentation-of{{alias.ext}}';
+{{/if}}
+{{#if presentation.forms}}
+import { withForms } from '{{alias.platform}}/http/with-forms{{alias.ext}}';
+{{/if}}
 {{#if authz.rebac}}
 import { relateSystemActors } from '{{alias.platform}}/auth/relate-system-actors{{alias.ext}}';
 {{/if}}
@@ -271,10 +282,19 @@ function kernel(foundations: Foundations, persistence: Persistence, options: App
 
 function running(container: Container, options: ApplicationOptions, contexts: ContextSelection): Application {
   const logger = container.resolve(Logger);
+{{#if presentation.any}}
+  // What the server answers in and which fields each caller sees: the forms and the contract are given the same.
+  const presentation = presentationOf(container.resolve(Access), container.resolve(Clock));
+{{/if}}
 
   return {
 {{#if http.any}}
+{{#if presentation.forms}}
+    routes: withForms(routesOf(container, contexts), presentation),
+{{/if}}
+{{#unless presentation.forms}}
     routes: routesOf(container, contexts),
+{{/unless}}
     boundary: httpBoundary({
       authenticator: container.resolve(Authenticator),
       executionScope: container.resolve(ExecutionScope),
@@ -289,6 +309,9 @@ function running(container: Container, options: ApplicationOptions, contexts: Co
 {{/if}}
 {{#if errors.sentry}}
       errors: container.resolve(ErrorReporter),
+{{/if}}
+{{#if presentation.any}}
+      presentation,
 {{/if}}
     }),
 {{/if}}

package/templates/init/platform/http/presentation-of.ts.tpl

@@ -0,0 +1,27 @@
+import type { Access } from '@ddd-ts-kit/auth';
+{{#if presentation.negotiated}}
+import { Representations, fieldDeciderOf, type FieldDecider } from '@ddd-ts-kit/http';
+{{/if}}
+{{#unless presentation.negotiated}}
+import { fieldDeciderOf, type FieldDecider } from '@ddd-ts-kit/http';
+{{/unless}}
+import type { Clock } from '@ddd-ts-kit/kernel';
+
+/** How the answers of the application are presented, the same for the server, the forms and the contract. */
+export interface Presentation {
+{{#if presentation.negotiated}}
+  /** JSON, XML and CSV: each request is answered in the one its `Accept` header prefers among those its route declares in `produces`. */
+  readonly representations: Representations;
+{{/if}}
+  /** Decides the fields a schema reserves to some callers (`withFieldAccess`), through the policies and the authorizer of the application. */
+  readonly fieldAccess: FieldDecider;
+}
+
+export function presentationOf(access: Access, clock: Clock): Presentation {
+  return {
+{{#if presentation.negotiated}}
+    representations: Representations.standard(),
+{{/if}}
+    fieldAccess: fieldDeciderOf({ access, clock }),
+  };
+}

package/templates/init/platform/http/start-http-server.express.ts.tpl

@@ -34,7 +34,7 @@ export async function startHttpServer(served: Served, config: AppConfig): Promis
 {{/if}}
   app.use(express.json());
 {{#if docs.any}}
-  mountExpress(app, withDocumentation(served.routes, config), served.boundary);
+  mountExpress(app, withDocumentation(served.routes, config, served.boundary), served.boundary);
 {{/if}}
 {{#unless docs.any}}
   mountExpress(app, served.routes, served.boundary);

package/templates/init/platform/http/start-http-server.fastify.ts.tpl

@@ -29,7 +29,7 @@ export async function startHttpServer(served: Served, config: AppConfig): Promis
   mountFastify(app, served.fileRoutes, served.boundary);
 {{/if}}
 {{#if docs.any}}
-  mountFastify(app, withDocumentation(served.routes, config), served.boundary);
+  mountFastify(app, withDocumentation(served.routes, config, served.boundary), served.boundary);
 {{/if}}
 {{#unless docs.any}}
   mountFastify(app, served.routes, served.boundary);

package/templates/init/platform/http/start-http-server.hono.ts.tpl

@@ -0,0 +1,84 @@
+import type { AddressInfo } from 'node:net';
+import { serve, type ServerType } from '@hono/node-server';
+{{#if cache.rateLimit}}
+import { getConnInfo } from '@hono/node-server/conninfo';
+{{/if}}
+import { Hono } from 'hono';
+import { mountHono } from '@ddd-ts-kit/http/hono';
+import type { Application } from '{{alias.platform}}/compose-application{{alias.ext}}';
+import type { AppConfig } from '{{alias.platform}}/config/app-config{{alias.ext}}';
+{{#if cache.rateLimit}}
+import { refusalFor } from '{{alias.platform}}/http/refusal-for{{alias.ext}}';
+{{/if}}
+{{#if docs.any}}
+import { withDocumentation } from '{{alias.platform}}/http/with-documentation{{alias.ext}}';
+{{/if}}
+
+export interface HttpServer {
+  /** The port really bound: differs from the configured one when that was 0. */
+  readonly port: number;
+
+  close(): Promise<void>;
+}
+
+/** What the server needs of the application: its routes and what stands at its edge. */
+type Served = Pick<Application, 'routes' | 'boundary'{{#if cache.rateLimit}} | 'rateLimiter' | 'ready'{{/if}}>;
+
+export async function startHttpServer(served: Served, config: AppConfig): Promise<HttpServer> {
+  const app = new Hono();
+
+{{#if cache.rateLimit}}
+  guardTheDoor(app, served, config);
+{{/if}}
+{{#if docs.any}}
+  mountHono(app, withDocumentation(served.routes, config, served.boundary), served.boundary);
+{{/if}}
+{{#unless docs.any}}
+  mountHono(app, served.routes, served.boundary);
+{{/unless}}
+
+  const server = await listen(app, config.port);
+
+  return { port: boundPort(server), close: () => close(server) };
+}
+{{#if cache.rateLimit}}
+
+/** The readiness probe, then the limiter, before any route. */
+function guardTheDoor(app: Hono, served: Served, config: AppConfig): void {
+  app.get('/health/ready', async (context) => {
+    const ready = await served.ready();
+
+    return context.json({ status: ready ? 'up' : 'down' }, ready ? 200 : 503);
+  });
+
+  app.use(async (context, next) => {
+    const refusal = await refusalFor(served.rateLimiter, config.rateLimit, getConnInfo(context).remote.address);
+
+    if (refusal === undefined) {
+      await next();
+
+      return undefined;
+    }
+
+    return new Response(JSON.stringify(refusal.problem), { status: refusal.problem.status, headers: refusal.headers });
+  });
+}
+{{/if}}
+
+function listen(app: Hono, port: number): Promise<ServerType> {
+  return new Promise<ServerType>((resolve) => {
+    const server = serve({ fetch: app.fetch, port }, () => resolve(server));
+  });
+}
+
+function boundPort(server: ServerType): number {
+  const address: AddressInfo | string | null = server.address();
+
+  return typeof address === 'object' && address !== null ? address.port : 0;
+}
+
+function close(server: ServerType): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    server.close((error) => (error === undefined ? resolve() : reject(error)));
+  });
+}

package/templates/init/platform/http/start-http-server.nest.ts.tpl

@@ -38,7 +38,7 @@ interface Outgoing {
 export async function startHttpServer(served: Served, config: AppConfig): Promise<HttpServer> {
 {{#if files.http}}
 {{#if docs.any}}
-  const routes = [...withDocumentation(served.routes, config), ...served.fileRoutes];
+  const routes = [...withDocumentation(served.routes, config, served.boundary), ...served.fileRoutes];
 {{/if}}
 {{#unless docs.any}}
   const routes = [...served.routes, ...served.fileRoutes];
@@ -47,7 +47,7 @@ export async function startHttpServer(served: Served, config: AppConfig): Promis
 {{/if}}
 {{#unless files.http}}
 {{#if docs.any}}
-  const app = await NestFactory.create(createAppModule(withDocumentation(served.routes, config), served.boundary), {
+  const app = await NestFactory.create(createAppModule(withDocumentation(served.routes, config, served.boundary), served.boundary), {
     logger: ['error', 'warn'],
   });
 {{/if}}

package/templates/init/platform/http/with-documentation.ts.tpl

@@ -1,12 +1,20 @@
-import type { Route } from '@ddd-ts-kit/http';
+import type { ExecuteOptions, Route } from '@ddd-ts-kit/http';
 import { openApiDocumentsRoutes } from '@ddd-ts-kit/http/docs';
 import { generateOpenApi, routesByDocument } from '@ddd-ts-kit/http/openapi';
 import { securitySchemes } from '{{alias.platform}}/auth/security-schemes{{alias.ext}}';
 import type { AppConfig } from '{{alias.platform}}/config/app-config{{alias.ext}}';
 import { OPENAPI_DOCUMENTS } from '{{alias.platform}}/http/openapi-documents{{alias.ext}}';
 
-/** Adds the contract and its interactive page next to the routes, one per document of a split contract, unless documentation is switched off (API_DOCS, off in production by default). */
-export function withDocumentation(routes: readonly Route[], config: AppConfig): readonly Route[] {
+/**
+ * Adds the contract and its interactive page next to the routes, one per document of a split
+ * contract, unless documentation is switched off (API_DOCS, off in production by default). The
+ * contract is written with the error mapper and the representations the routes are mounted with.
+ */
+export function withDocumentation(
+  routes: readonly Route[],
+  config: AppConfig,
+  boundary: Pick<ExecuteOptions, 'errorMapper' | 'representations'>,
+): readonly Route[] {
   if (!config.docsEnabled) {
     return routes;
   }
@@ -17,6 +25,8 @@ export function withDocumentation(routes: readonly Route[], config: AppConfig):
       info: { title: title ?? config.serviceName, version: config.serviceVersion },
       routes: selected,
       securitySchemes,
+      ...(boundary.errorMapper === undefined ? {} : { errorMapper: boundary.errorMapper }),
+      ...(boundary.representations === undefined ? {} : { representations: boundary.representations }),
     }),
   }));
 

package/templates/init/platform/http/with-forms.ts.tpl

@@ -0,0 +1,7 @@
+import { defineRoutes, formRoutes, type Route } from '@ddd-ts-kit/http';
+import type { Presentation } from '{{alias.platform}}/http/presentation-of{{alias.ext}}';
+
+/** The routes, and the form of each one that declares `form`, at `GET /forms/<operationId>`, for the caller who asks. */
+export function withForms(routes: readonly Route[], { fieldAccess }: Presentation): readonly Route[] {
+  return defineRoutes(routes, formRoutes(routes, { fieldAccess }));
+}

package/templates/init/rules/application.md.tpl

@@ -30,7 +30,7 @@ paths:
 {{#if files.any}}
 - A file arrives in the command as a `FileUpload` of its area, which the bus stages before the transaction under a key of `FileKeys` (never a name or a path from the user) and scans; the handler records `upload.file`, its `StoredFile`, on the aggregate and calls `FileStaging.promoteOnCommit`, which moves it to its key with the commit. A direct upload is confirmed from the `PendingUpload` the aggregate kept, never from a key the client sends. The ports are named here, never a connector (`files/port-not-connector`); `npx ddd-ts-kit generate file-upload` writes the slice.
 {{/if}}
-- A query never saves, deletes or publishes (`application/command-query-separation`); it hands the access scope of the actor to its read port and never filters after loading.
+- A query never saves, deletes or publishes (`application/command-query-separation`); it hands the access scope of the actor to its read port and never filters after loading, and answers every field its read model holds: a field reserved to some callers is marked on the response schema with `withFieldAccess` of `@ddd-ts-kit/http`, never removed by a test on the roles of the actor (`authz/fields-by-schema`).
 - A read that takes criteria, a scope or a page is a search, never a list (`naming/search-not-list`): `Search<Things>Query` in `queries/search-<things>/` (`generate query ... --search`), `search...` on the port, its adapters and its fakes; one element or none stays `findById` or `findBy...`.
 {{#if literals.named}}
 - A permission, a role or a status is read from its declaration, `billingPermissions['invoice.issue']`, `InvoiceStatus.Issued`, never written as a string (`language/declared-vocabulary`); a number has a name (`clean/no-magic-number`).

package/templates/init/rules/presentation.md.tpl

@@ -27,8 +27,11 @@ paths:
 {{#if refusals.classes}}
 - Every route says who may call it (its group or its guards for a controller, `security` for a function) and the `DomainError` codes it can answer in `errors`; the mapping from code to status lives in one place, the error mapper.
 {{/if}}
-- No role or ownership test in a controller or a route (`authz/in-application`): a guard of the group asks for a role at the edge, the bus asks for the permission, a policy decides on loaded state.
+- No role or ownership test in a controller or a route (`authz/in-application`): a guard of the group asks for a role at the edge, the bus asks for the permission, a policy decides on loaded state. A field reserved to some callers is marked on its schema, `withFieldAccess(schema, { field: { read, write } })`, never by an `if` on a role (`authz/fields-by-schema`).{{#if presentation.negotiated}} Other media types are `produces` and `consumes` of the declaration (`generate representation`), from the same schema. A streamed export is `everyPage` over the search query of one page, sent through the bus page by page, never a query handler that answers a lazy list.{{/if}}{{#if presentation.forms}} A form is `defineForm` hints next to the body (`generate form`): shape and presentation, never a business rule; it `requires` the permission of its use case, asked as its `@Requires` asks it.{{/if}}
 - Request and response types are presentation types, one class or schema per file next to the controller (`*.body.ts`, `*.params.ts`, `*.answer.ts`...; `*.dto.ts` for function routes and under `shared/`): never an aggregate, never a row.
+{{#if schemas.shared}}
+- A shape several routes use is declared once, in `presentation/http/shared/<name>.schema.ts` (`npx ddd-ts-kit generate schema <context> <Name>`), or in `presentation/` of the shared kernel when several contexts answer with it (`generate schema shared-kernel <Name>`), and shared: the contract documents it once and every route refers to it. A route takes the part it needs from it (pick, omit, partial, extend) instead of copying it, and answers an identifier with `acceptedSchema` of `@ddd-ts-kit/http` (`schema/no-duplicate-shape`). Only presentation layers import a schema (`schema/presentation-only`).
+{{/if}}
 - A read declares how caches may keep its answer in `cache` (its controller, its route group, or the spec of a function route): `private` for what a caller reads again, with `etag`; `public` only for what is the same for everybody, with `tags` naming the resources it shows. A route that knows its caller is `no-store` unless it says otherwise, and a `public` answer of such a route is refused unless `vary` names who calls (`Authorization`, `Cookie`) or the header its tenant is read from (`presentation/shared-cache-varies`, then the mount): never cache a decision of authorization across actors. A group policy reaches the reads of the group only. A write that must not overwrite a newer version declares `ifMatch` and hands `context.expectedVersion` to its command; the handler calls `expectVersion` (412). A change purges the answers it makes stale from a `before-commit` handler of its domain event, `CacheInvalidation.invalidate([cacheTag(...)])` (`platform.cacheInvalidation` on a platform wired by hand): the purge then runs after the commit, through the outbox. Every event that changes what a kept answer shows, its version included, purges it, not only the one the route is about.
 - Never put the message of an unexpected failure in a response or a log.
 - Files: the canonical tree of `presentation/http/` (`naming/suffix`, `tree/closed`): a folder per controller, `*.routes.ts` for the groups, `guards/`, `shared/`; function routes stay flat (`*.route.ts`, `*.dto.ts`).