@contractkit/plugin-typescript 0.35.0 → 0.36.0

package/dist/server-framework-fastify.d.ts

@@ -0,0 +1,8 @@
+import type { ServerFramework } from './server-framework.js';
+/**
+ * ServerKit on Fastify: `ServerKitRouter()` collects routes the way a Koa app reads and mounts them
+ * as a Fastify plugin, handlers take `(request, reply)` where the request *is* the ServerKit
+ * context, and a response is sent by returning `reply.send(...)` rather than by assignment.
+ */
+export declare const FASTIFY_SERVER_FRAMEWORK: ServerFramework;
+//# sourceMappingURL=server-framework-fastify.d.ts.map

package/dist/server-framework-fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-framework-fastify.d.ts","sourceRoot":"","sources":["../src/server-framework-fastify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAc7D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,eA4GtC,CAAC"}

package/dist/server-framework-koa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-framework-koa.d.ts","sourceRoot":"","sources":["../src/server-framework-koa.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAW7D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAgGlC,CAAC"}
+{"version":3,"file":"server-framework-koa.d.ts","sourceRoot":"","sources":["../src/server-framework-koa.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAW7D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAkGlC,CAAC"}

package/dist/server-framework.d.ts

@@ -2,7 +2,7 @@
  * HTTP frameworks the server sub-generator can target. Adding a name here without adding an adapter
  * to {@link SERVER_FRAMEWORKS} fails to compile, which is the point of keeping the two in step.
  */
-export declare const SERVER_FRAMEWORK_NAMES: readonly ["koa"];
+export declare const SERVER_FRAMEWORK_NAMES: readonly ["koa", "fastify"];
 /** One of {@link SERVER_FRAMEWORK_NAMES}. */
 export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
 /** The framework assumed when a config names none. */
@@ -29,6 +29,13 @@ export interface ServerFramework {
     routerDeclaration(routerName: string): string;
     /** Placeholder syntax for one path parameter, given a name already mapped to a valid identifier. */
     pathParam(identifier: string): string;
+    /**
+     * Identifiers the handler signature itself binds — `ctx`, or `request` and `reply`. A path
+     * parameter is destructured into the handler body, so one declared with the same name would
+     * shadow the handler's own parameter: a redeclaration under `tsc`, and a temporal-dead-zone
+     * `ReferenceError` at runtime. Codegen renames the local binding to avoid these.
+     */
+    readonly handlerLocals: readonly string[];
     /** Opening line of a handler, including its middleware and the handler function's parameters. */
     routeOpen(routerName: string, method: string, path: string, middlewares: readonly string[]): string;
     /** Lines that close a handler opened by {@link routeOpen}. */

package/dist/server-framework.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-framework.d.ts","sourceRoot":"","sources":["../src/server-framework.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,sBAAsB,kBAAmB,CAAC;AAEvD,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,sDAAsD;AACtD,eAAO,MAAM,6BAA6B,EAAE,mBAA2B,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,EAAE,CAAC;IAErD,+DAA+D;IAC/D,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAE9C,oGAAoG;IACpG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtC,iGAAiG;IACjG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IAEpG,8DAA8D;IAC9D,UAAU,IAAI,MAAM,EAAE,CAAC;IAEvB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE;QACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;QACvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;KACnC,CAAC;IAEF,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,6DAA6D;QAC7D,UAAU,EAAE,MAAM,CAAC;QACnB;;;;WAIG;QACH,WAAW,EAAE,MAAM,CAAC;KACvB,CAAC;IAEF,mFAAmF;IACnF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE;QACf,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B;;;WAGG;QACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC3B;;;;WAIG;QACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAAC;QAC7C,6FAA6F;QAC7F,OAAO,IAAI,MAAM,EAAE,CAAC;KACvB,CAAC;IAEF,+FAA+F;IAC/F,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAEpF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAShF"}
+{"version":3,"file":"server-framework.d.ts","sourceRoot":"","sources":["../src/server-framework.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,sBAAsB,6BAA8B,CAAC;AAElE,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,sDAAsD;AACtD,eAAO,MAAM,6BAA6B,EAAE,mBAA2B,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,EAAE,CAAC;IAErD,+DAA+D;IAC/D,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAE9C,oGAAoG;IACpG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C,iGAAiG;IACjG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IAEpG,8DAA8D;IAC9D,UAAU,IAAI,MAAM,EAAE,CAAC;IAEvB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE;QACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;QACvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;KACnC,CAAC;IAEF,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,6DAA6D;QAC7D,UAAU,EAAE,MAAM,CAAC;QACnB;;;;WAIG;QACH,WAAW,EAAE,MAAM,CAAC;KACvB,CAAC;IAEF,mFAAmF;IACnF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE;QACf,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B;;;WAGG;QACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC3B;;;;WAIG;QACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAAC;QAC7C,6FAA6F;QAC7F,OAAO,IAAI,MAAM,EAAE,CAAC;KACvB,CAAC;IAEF,+FAA+F;IAC/F,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAGpF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAShF"}

package/llms.txt

@@ -56,7 +56,7 @@ Path templates accept `{filename}`, `{dir}`, `{area}`, and — in `sdk.output.sd
 
 | Key | Emits |
 | --- | --- |
-| `server` | Server routers from `operation` declarations, plus the type or Zod files they import. `framework` selects the HTTP framework; only `koa` today |
+| `server` | Server routers from `operation` declarations, plus the type or Zod files they import. `framework` selects the HTTP framework: `koa` or `fastify` |
 | `sdk` | The SDK class, per-area operation clients, and their types |
 | `zod` | Standalone Zod schemas, independent of `server` and `sdk` |
 | `types` | Standalone plain TypeScript types, independent of `server` and `sdk` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.35.0",
-  "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
+  "version": "0.36.0",
+  "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa or Fastify routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {
     "name": "Marooned Software",

package/src/codegen-operation.ts

@@ -27,6 +27,34 @@ import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
 /** Which request-side object a validation block reads from. Names the variable the block declares. */
 export type ParamKind = 'params' | 'query' | 'headers';
 
+/**
+ * Identifiers the generated handler body binds for itself. A path parameter destructured under one
+ * of these names would redeclare it, so those bindings are renamed the same way a collision with a
+ * handler parameter is.
+ */
+const GENERATOR_HANDLER_LOCALS = ['service', 'result', 'body', 'multipartBody', 'params', 'query', 'headers'] as const;
+
+/**
+ * Local identifier for each inline path parameter, keyed by its declared name.
+ *
+ * The declared name is what the framework keys its params object by, so it stays the schema key and
+ * the route placeholder; only the local binding moves, and a `_` is appended until it collides with
+ * neither a reserved identifier nor another parameter's binding. Path parameters are spread
+ * positionally into the service call, so a rename is invisible to the service.
+ */
+function bindPathParams(nodes: readonly { name: string }[], handlerLocals: readonly string[]): Map<string, string> {
+    const reserved = new Set<string>([...handlerLocals, ...GENERATOR_HANDLER_LOCALS]);
+    const taken = new Set<string>();
+    const bindings = new Map<string, string>();
+    for (const node of nodes) {
+        let local = toIdentifier(node.name);
+        while (reserved.has(local) || taken.has(local)) local += '_';
+        taken.add(local);
+        bindings.set(node.name, local);
+    }
+    return bindings;
+}
+
 // ─── Content-type helpers ──────────────────────────────────────────────────
 
 /**
@@ -362,7 +390,10 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     lines.push(framework.routeOpen(deriveRouterName(file), method, path, middlewares));
 
     // Params / query / headers validation (request-side — use Input variants)
-    lines.push(...generateParamValidation(route.params, 'params', framework.request.params, route.paramsMode ?? 'strict', '', modelsWithInput));
+    const pathBindings =
+        route.params?.kind === 'params' ? bindPathParams(route.params.nodes, framework.handlerLocals) : undefined;
+
+    lines.push(...generateParamValidation(route.params, 'params', framework.request.params, route.paramsMode ?? 'strict', '', modelsWithInput, pathBindings));
     lines.push(...generateParamValidation(op.query, 'query', framework.request.query, op.queryMode ?? 'strict', '', modelsWithInput));
     lines.push(...generateParamValidation(op.headers, 'headers', framework.request.headers, op.headersMode ?? 'strip', '', modelsWithInput));
 
@@ -405,7 +436,7 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     // responsible for producing; the rest are documentation, or the thrown-error path.
     const emitted = emittedResponses(op);
     const serviceParts = inferService(op, route, file);
-    const call = `await service.${serviceParts.methodName}(${buildArgs(route, op)})`;
+    const call = `await service.${serviceParts.methodName}(${buildArgs(route, op, pathBindings)})`;
 
     if (emitted.length > 1) {
         lines.push(...generateMultiStatusResult(emitted, serviceParts.className, call, options));
@@ -654,12 +685,14 @@ function inferMethodName(method: string, path: string): string {
  *
  * @returns The rendered argument list, or an empty string when the method takes no arguments.
  */
-export function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
+export function buildArgs(route: OpRouteNode, op: OpOperationNode, bindings?: Map<string, string>): string {
     const args: string[] = [];
     // Path params: spread individually (inline) or pass 'params' object (type-ref/ContractTypeNode)
     if (route.params) {
         if (route.params.kind === 'params') {
-            args.push(...route.params.nodes.map(p => toIdentifier(p.name)));
+            // `bindings` carries any rename the handler needed; the MCP generator passes none, since
+            // its handlers bind different locals than a router's.
+            args.push(...route.params.nodes.map(p => bindings?.get(p.name) ?? toIdentifier(p.name)));
         } else {
             args.push('params');
         }
@@ -821,6 +854,7 @@ function generateParamValidation(
     mode: ObjectMode,
     suffix = '',
     modelsWithInput?: Set<string>,
+    bindings?: Map<string, string>,
 ): string[] {
     if (!source) return [];
     const lines: string[] = [];
@@ -837,7 +871,17 @@ function generateParamValidation(
         // Inline param declarations — wrap with the appropriate z.*Object constructor
         if (source.nodes.length > 0) {
             const bind = (name: string) => (isPathParams ? toIdentifier(name) : name);
-            const lhs = isPathParams ? `{ ${source.nodes.map(p => bind(p.name)).join(', ')} }` : kind;
+            // A path param whose binding was renamed is destructured under an alias, so the key the
+            // framework supplies stays the declared one while the local is collision-free.
+            const lhs = isPathParams
+                ? `{ ${source.nodes
+                      .map(p => {
+                          const wire = bind(p.name);
+                          const local = bindings?.get(p.name) ?? wire;
+                          return wire === local ? wire : `${wire}: ${local}`;
+                      })
+                      .join(', ')} }`
+                : kind;
             lines.push(`    const ${lhs} = await parseAndValidate(`);
             lines.push(`        ${sourceExpr},`);
             lines.push(`        ${modeToWrapper(mode)}({`);

package/src/index.ts

@@ -55,6 +55,7 @@ export {
     type ServerFrameworkName,
 } from './server-framework.js';
 export { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
+export { FASTIFY_SERVER_FRAMEWORK } from './server-framework-fastify.js';
 
 /** Taint set for the SDK's bigint response reviver. */
 const BIGINT_SCALARS: ReadonlySet<ScalarTypeNode['name']> = new Set(['bigint']);

package/src/server-framework-fastify.ts

@@ -0,0 +1,128 @@
+import type { ServerFramework } from './server-framework.js';
+
+/** Module the Fastify flavour of ServerKit publishes its router and route middleware from. */
+const FASTIFY_RUNTIME_MODULE = '@maroonedsoftware/fastify';
+
+/**
+ * Symbols importable from {@link FASTIFY_RUNTIME_MODULE}. Every one is a name the adapter itself
+ * emits, so none can collide with a service class or router name derived from a contract.
+ *
+ * `requestMediaType` is here because Fastify has no accessor that strips the parameters off
+ * `Content-Type`, and it is only referenced when an operation declares several request MIME types.
+ */
+const FASTIFY_RUNTIME_SYMBOLS = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature', 'requestMediaType'] as const;
+
+/**
+ * ServerKit on Fastify: `ServerKitRouter()` collects routes the way a Koa app reads and mounts them
+ * as a Fastify plugin, handlers take `(request, reply)` where the request *is* the ServerKit
+ * context, and a response is sent by returning `reply.send(...)` rather than by assignment.
+ */
+export const FASTIFY_SERVER_FRAMEWORK: ServerFramework = {
+    name: 'fastify',
+
+    imports(uses) {
+        const symbols = FASTIFY_RUNTIME_SYMBOLS.filter(uses);
+        return symbols.length > 0 ? [`import { ${symbols.join(', ')} } from '${FASTIFY_RUNTIME_MODULE}';`] : [];
+    },
+
+    routerDeclaration(routerName) {
+        return `export const ${routerName} = ServerKitRouter();`;
+    },
+
+    pathParam(identifier) {
+        return `:${identifier}`;
+    },
+
+    handlerLocals: ['request', 'reply'],
+
+    routeOpen(routerName, method, path, middlewares) {
+        const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
+        return `${routerName}.${method}('${path}'${middlewareStr} async (request, reply) => {`;
+    },
+
+    routeClose() {
+        return ['});'];
+    },
+
+    middleware: {
+        policy(args) {
+            return `requirePolicy(${args})`;
+        },
+        bodyParser(tokensExpr) {
+            return `bodyParserMiddleware([${tokensExpr}])`;
+        },
+        signature(args) {
+            return `requireSignature(${args})`;
+        },
+    },
+
+    request: {
+        params: 'request.params',
+        query: 'request.query',
+        headers: 'request.headers',
+        // ServerKit parses lazily per route, so Fastify's own `request.body` is never populated.
+        parsedBody: 'request.parsedBody',
+        // A call, not a property: the raw header carries `; charset=utf-8`, which would match none of
+        // the declared MIME literals the generated switch compares against.
+        contentType: 'requestMediaType(request)',
+    },
+
+    resolveService(className) {
+        return `request.container.get(${className})`;
+    },
+
+    response: {
+        status(expr) {
+            return `reply.status(${expr});`;
+        },
+        header(name, valueExpr) {
+            return `reply.header('${name}', ${valueExpr});`;
+        },
+        type(expr) {
+            return `reply.type(${expr});`;
+        },
+        send(bodyExpr) {
+            // Unlike Koa, a bodyless response still needs a statement: a handler that neither returns
+            // a body nor calls `send` leaves the request hanging.
+            return bodyExpr === undefined ? ['return reply.send();'] : [`return reply.send(${bodyExpr});`];
+        },
+        caseEnd() {
+            // Every status case has already returned, so a `break` here would be unreachable code.
+            return [];
+        },
+    },
+
+    mcpRouter({ path }) {
+        return `import { type ServerKitRouterType, bodyParserMiddleware, requireSignature, requestHeader } from '${FASTIFY_RUNTIME_MODULE}';
+import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';
+
+/** Mount the MCP endpoint onto a ServerKit router. Bind \`registerMcpTools\` to the \`McpToolHandlerMap\` token. */
+export function mountMcp(router: ServerKitRouterType): void {
+    router.post('${path}', bodyParserMiddleware(['json']), requireSignature('mcp', { policy: MCP_AUTH_POLICY }), async (request, reply) => {
+        const dispatcher = request.container.get(McpDispatcher);
+        const context = createMcpRequestContext({ requestId: request.requestId, logger: request.logger });
+        if (dispatcher.sessionMode === 'stateful') {
+            // Fastify's equivalent of Koa's \`ctx.respond = false\`: the dispatcher writes the raw
+            // response itself, and the request scope is disposed on the raw socket close instead.
+            reply.hijack();
+            await dispatcher.dispatchStateful(
+                {
+                    req: request.raw,
+                    res: reply.raw,
+                    body: request.parsedBody,
+                    // \`requestHeader\` returns '' for an absent header; the session id is optional.
+                    sessionId: requestHeader(request, 'mcp-session-id') || undefined,
+                },
+                context,
+            );
+            return;
+        }
+        const response = await dispatcher.dispatch(JSON.parse(String(request.rawBody)), context);
+        if (response) return reply.send(response);
+        reply.status(202); // a notification — nothing to return
+        return reply.send();
+    });
+}
+`;
+    },
+};

package/src/server-framework-koa.ts

@@ -29,6 +29,8 @@ export const KOA_SERVER_FRAMEWORK: ServerFramework = {
         return `:${identifier}`;
     },
 
+    handlerLocals: ['ctx'],
+
     routeOpen(routerName, method, path, middlewares) {
         const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
         return `${routerName}.${method}('${path}'${middlewareStr} async ctx => {`;

package/src/server-framework.ts

@@ -1,10 +1,11 @@
 import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
+import { FASTIFY_SERVER_FRAMEWORK } from './server-framework-fastify.js';
 
 /**
  * HTTP frameworks the server sub-generator can target. Adding a name here without adding an adapter
  * to {@link SERVER_FRAMEWORKS} fails to compile, which is the point of keeping the two in step.
  */
-export const SERVER_FRAMEWORK_NAMES = ['koa'] as const;
+export const SERVER_FRAMEWORK_NAMES = ['koa', 'fastify'] as const;
 
 /** One of {@link SERVER_FRAMEWORK_NAMES}. */
 export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
@@ -38,6 +39,14 @@ export interface ServerFramework {
     /** Placeholder syntax for one path parameter, given a name already mapped to a valid identifier. */
     pathParam(identifier: string): string;
 
+    /**
+     * Identifiers the handler signature itself binds — `ctx`, or `request` and `reply`. A path
+     * parameter is destructured into the handler body, so one declared with the same name would
+     * shadow the handler's own parameter: a redeclaration under `tsc`, and a temporal-dead-zone
+     * `ReferenceError` at runtime. Codegen renames the local binding to avoid these.
+     */
+    readonly handlerLocals: readonly string[];
+
     /** Opening line of a handler, including its middleware and the handler function's parameters. */
     routeOpen(routerName: string, method: string, path: string, middlewares: readonly string[]): string;
 
@@ -98,6 +107,7 @@ export interface ServerFramework {
  */
 export const SERVER_FRAMEWORKS: Readonly<Record<ServerFrameworkName, ServerFramework>> = {
     koa: KOA_SERVER_FRAMEWORK,
+    fastify: FASTIFY_SERVER_FRAMEWORK,
 };
 
 /**

package/tests/codegen-operation-framework.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { generateOp } from '../src/codegen-operation.js';
 import type { ServerFramework } from '../src/server-framework.js';
+import { FASTIFY_SERVER_FRAMEWORK } from '../src/server-framework-fastify.js';
 import { scalarType, refType, opParam, opRequest, opMultiRequest, opResponse, opResponseMulti, opOperation, opRoute, opRoot } from './helpers.js';
 
 /**
@@ -15,6 +16,7 @@ const STUB: ServerFramework = {
     imports: uses => (uses('StubRouter') ? ["import { StubRouter } from '@stub/http';"] : []),
     routerDeclaration: routerName => `export const ${routerName} = StubRouter();`,
     pathParam: identifier => `<${identifier}>`,
+    handlerLocals: ['rq', 'rs'],
     routeOpen: (routerName, method, path, middlewares) => `${routerName}.route('${method}', '${path}', [${middlewares.join(', ')}], async (rq, rs) => {`,
     routeClose: () => ['}, END);'],
     middleware: {
@@ -138,3 +140,45 @@ describe('generateOp — framework seam', () => {
         expect(statusSwitch).not.toContain('break;');
     });
 });
+
+describe('generateOp — Fastify', () => {
+    const output = generateOp(everyBranchRoot(), { framework: FASTIFY_SERVER_FRAMEWORK });
+
+    it('opens each handler with the Fastify signature', () => {
+        expect(output).toContain("UsersRouter.post('/payments/:paymentId', requirePolicy(), bodyParserMiddleware(['json']), requireSignature('stripe'), async (request, reply) => {");
+        expect(output).not.toMatch(/\bctx\b/);
+    });
+
+    it('imports the runtime helper only because the multi-MIME switch uses it', () => {
+        expect(output).toContain(
+            "import { ServerKitRouter, bodyParserMiddleware, requirePolicy, requireSignature, requestMediaType } from '@maroonedsoftware/fastify';",
+        );
+        expect(output).toContain('switch (requestMediaType(request)) {');
+    });
+
+    it('reads the request through the request object', () => {
+        expect(output).toContain('request.params');
+        expect(output).toContain('request.query');
+        expect(output).toContain('request.headers');
+        expect(output).toContain('await parseAndValidate(request.parsedBody,');
+        expect(output).toContain('request.container.get(UsersService)');
+    });
+
+    it('writes the response through reply, returning the send', () => {
+        expect(output).toContain('reply.status(201);');
+        expect(output).toContain("reply.type('application/json');");
+        expect(output).toContain('return reply.send(result.body);');
+        expect(output).toContain('reply.header(\'etag\', String(result.headers["etag"]));');
+    });
+
+    it('sends explicitly for a bodyless response, where Koa writes nothing', () => {
+        expect(output).toContain('reply.status(204);');
+        expect(output).toContain('return reply.send();');
+    });
+
+    it('leaves no break in the status switch, since every case returns', () => {
+        const statusSwitch = output.slice(output.indexOf('switch (result.status) {'));
+        expect(statusSwitch).toContain('case 202:');
+        expect(statusSwitch).not.toContain('break;');
+    });
+});

package/tests/codegen-operation.test.ts

@@ -394,6 +394,51 @@ describe('generateOperation', () => {
 
     // ─── Query validation ────────────────────────────────────────
 
+    describe('path params that would shadow a handler local', () => {
+        it('renames the binding but keeps the placeholder and the schema key', () => {
+            // `ctx` is the Koa handler's own parameter. Destructuring one under that name redeclares
+            // it: a tsc error, and a temporal-dead-zone ReferenceError at runtime.
+            const root = opRoot([opRoute('/threads/{ctx}', [opOperation('get')], [opParam('ctx', scalarType('uuid'))])]);
+            const output = generateOp(root);
+            expect(output).toContain("get('/threads/:ctx'");
+            expect(output).toContain('ctx: z.uuid()');
+            expect(output).toContain('const { ctx: ctx_ } = await parseAndValidate(');
+            expect(output).not.toContain('const { ctx } =');
+        });
+
+        it('passes the renamed identifier to the service', () => {
+            const root = opRoot([opRoute('/threads/{ctx}', [opOperation('get')], [opParam('ctx', scalarType('uuid'))])]);
+            expect(generateOp(root)).toContain('await service.getById(ctx_)');
+        });
+
+        it('renames a param that would shadow one of the generator\'s own locals', () => {
+            // `body` is the variable the request-body block declares.
+            const root = opRoot([
+                opRoute('/posts/{body}', [opOperation('post', { request: opRequest('CreatePost') })], [opParam('body', scalarType('uuid'))]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('const { body: body_ } = await parseAndValidate(');
+            expect(output).toContain('const body = await parseAndValidate(');
+            expect(output).toContain('await service.create(body_, body)');
+        });
+
+        it('leaves a param alone when nothing collides', () => {
+            const root = opRoot([opRoute('/users/{userId}', [opOperation('get')], [opParam('userId', scalarType('uuid'))])]);
+            const output = generateOp(root);
+            expect(output).toContain('const { userId } = await parseAndValidate(');
+            expect(output).toContain('await service.getById(userId)');
+        });
+
+        it('keeps two params distinct when a rename would collapse them onto one name', () => {
+            const root = opRoot([
+                opRoute('/x/{ctx}/{ctx_}', [opOperation('get')], [opParam('ctx', scalarType('uuid')), opParam('ctx_', scalarType('uuid'))]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('const { ctx: ctx_, ctx_: ctx__ } = await parseAndValidate(');
+            expect(output).toContain('await service.getById(ctx_, ctx__)');
+        });
+    });
+
     describe('query validation', () => {
         it('generates query validation block', () => {
             const root = opRoot([

package/tests/server-framework-fastify.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { FASTIFY_SERVER_FRAMEWORK as fastify } from '../src/server-framework-fastify.js';
+
+/**
+ * Pinned method by method, the way the Koa adapter is. These strings are the contract with
+ * `@maroonedsoftware/fastify`, so a change to any of them should fail here, naming the piece,
+ * rather than only as a snapshot diff in another package.
+ */
+describe('FASTIFY_SERVER_FRAMEWORK', () => {
+    it('is named fastify', () => {
+        expect(fastify.name).toBe('fastify');
+    });
+
+    describe('imports', () => {
+        it('emits one line naming every symbol the body uses', () => {
+            expect(fastify.imports(() => true)).toEqual([
+                "import { ServerKitRouter, bodyParserMiddleware, requirePolicy, requireSignature, requestMediaType } from '@maroonedsoftware/fastify';",
+            ]);
+        });
+
+        it('narrows to the symbols the body actually references', () => {
+            expect(fastify.imports(s => s === 'requestMediaType')).toEqual(["import { requestMediaType } from '@maroonedsoftware/fastify';"]);
+        });
+
+        it('emits nothing when the body references none of them', () => {
+            expect(fastify.imports(() => false)).toEqual([]);
+        });
+    });
+
+    it('declares the router', () => {
+        expect(fastify.routerDeclaration('UsersRouter')).toBe('export const UsersRouter = ServerKitRouter();');
+    });
+
+    it('renders a path parameter with a colon', () => {
+        expect(fastify.pathParam('userId')).toBe(':userId');
+    });
+
+    it('reserves the two identifiers its handler signature binds', () => {
+        expect(fastify.handlerLocals).toEqual(['request', 'reply']);
+    });
+
+    describe('routeOpen', () => {
+        it('omits the middleware list when there is none', () => {
+            expect(fastify.routeOpen('UsersRouter', 'get', '/users', [])).toBe("UsersRouter.get('/users', async (request, reply) => {");
+        });
+
+        it('places the middleware between the path and the handler', () => {
+            expect(fastify.routeOpen('UsersRouter', 'post', '/users', ['requirePolicy()', "bodyParserMiddleware(['json'])"])).toBe(
+                "UsersRouter.post('/users', requirePolicy(), bodyParserMiddleware(['json']), async (request, reply) => {",
+            );
+        });
+    });
+
+    it('closes a route', () => {
+        expect(fastify.routeClose()).toEqual(['});']);
+    });
+
+    it('renders the route middleware factories, which take the same arguments as Koa\'s', () => {
+        expect(fastify.middleware.policy('')).toBe('requirePolicy()');
+        expect(fastify.middleware.policy("{ policy: 'admin' }")).toBe("requirePolicy({ policy: 'admin' })");
+        expect(fastify.middleware.bodyParser("'json', 'multipart'")).toBe("bodyParserMiddleware(['json', 'multipart'])");
+        expect(fastify.middleware.signature("'slack'")).toBe("requireSignature('slack')");
+    });
+
+    it('reads the request off the request object, which is the context', () => {
+        expect(fastify.request).toEqual({
+            params: 'request.params',
+            query: 'request.query',
+            headers: 'request.headers',
+            parsedBody: 'request.parsedBody',
+            // A call rather than a property: the raw header carries `; charset=…`, which matches no
+            // declared MIME literal.
+            contentType: 'requestMediaType(request)',
+        });
+    });
+
+    it('resolves a service from the request container', () => {
+        expect(fastify.resolveService('PaymentService')).toBe('request.container.get(PaymentService)');
+    });
+
+    describe('response', () => {
+        it('sets the status through reply', () => {
+            expect(fastify.response.status('200')).toBe('reply.status(200);');
+            expect(fastify.response.status('result.status')).toBe('reply.status(result.status);');
+        });
+
+        it('sets a header as a single statement, so the optional guard can wrap it', () => {
+            expect(fastify.response.header('x-request-id', 'String(result.headers["xRequestId"])')).toBe(
+                'reply.header(\'x-request-id\', String(result.headers["xRequestId"]));',
+            );
+        });
+
+        it('sets the content type', () => {
+            expect(fastify.response.type("'application/json'")).toBe("reply.type('application/json');");
+            expect(fastify.response.type('result.contentType')).toBe('reply.type(result.contentType);');
+        });
+
+        it('returns the send, including for a response with no body', () => {
+            expect(fastify.response.send('result')).toEqual(['return reply.send(result);']);
+            // Unlike Koa: a handler that neither returns a body nor calls send leaves the request hanging.
+            expect(fastify.response.send(undefined)).toEqual(['return reply.send();']);
+        });
+
+        it('closes a status case with nothing, since the case already returned', () => {
+            expect(fastify.response.caseEnd()).toEqual([]);
+        });
+    });
+
+    describe('mcpRouter', () => {
+        const out = fastify.mcpRouter({ path: '/mcp' });
+
+        it('mounts the dispatcher at the given path', () => {
+            expect(fastify.mcpRouter({ path: '/tools' })).toContain("router.post('/tools',");
+            expect(out).toContain("from '@maroonedsoftware/fastify'");
+            expect(out).toContain('const dispatcher = request.container.get(McpDispatcher);');
+        });
+
+        it('names the exported router type rather than inferring it', () => {
+            expect(out).toContain('export function mountMcp(router: ServerKitRouterType): void {');
+            // And therefore never imports the factory value, which `noUnusedLocals` would reject.
+            expect(out).toContain("import { type ServerKitRouterType, bodyParserMiddleware, requireSignature, requestHeader } from '@maroonedsoftware/fastify';");
+        });
+
+        it('hijacks the reply for a stateful session, which is Fastify\'s ctx.respond = false', () => {
+            expect(out).toContain('reply.hijack();');
+            expect(out).toContain('req: request.raw,');
+            expect(out).toContain('res: reply.raw,');
+        });
+
+        it('reads the parsed body, not Fastify\'s own request.body', () => {
+            expect(out).toContain('body: request.parsedBody,');
+            expect(out).not.toContain('request.body,');
+        });
+
+        it('passes undefined rather than the empty string for an absent session id', () => {
+            expect(out).toContain("sessionId: requestHeader(request, 'mcp-session-id') || undefined,");
+        });
+
+        it('answers a notification with a bodyless 202', () => {
+            expect(out).toContain('reply.status(202);');
+            expect(out).toContain('return reply.send();');
+        });
+
+        it('escapes the backticks in its own doc comment rather than closing the template', () => {
+            expect(out).toContain('Bind `registerMcpTools` to the `McpToolHandlerMap` token.');
+        });
+    });
+});

package/tests/server-framework.test.ts

@@ -9,6 +9,7 @@ describe('resolveServerFramework', () => {
 
     it('resolves a supported name', () => {
         expect(resolveServerFramework('koa').name).toBe('koa');
+        expect(resolveServerFramework('fastify').name).toBe('fastify');
     });
 
     it('rejects an unsupported name, naming what is supported', () => {