@contractkit/plugin-typescript 0.34.1 → 0.35.0

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

@@ -0,0 +1,7 @@
+import type { ServerFramework } from './server-framework.js';
+/**
+ * ServerKit on Koa: the router is a `@koa/router` instance, handlers take a single `ctx`, and a
+ * response is written by assigning to `ctx.status` / `ctx.type` / `ctx.body` rather than returned.
+ */
+export declare const KOA_SERVER_FRAMEWORK: ServerFramework;
+//# sourceMappingURL=server-framework-koa.d.ts.map

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

@@ -0,0 +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"}

package/dist/server-framework.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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"];
+/** One of {@link SERVER_FRAMEWORK_NAMES}. */
+export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
+/** The framework assumed when a config names none. */
+export declare const DEFAULT_SERVER_FRAMEWORK_NAME: ServerFrameworkName;
+/**
+ * Every framework-specific string the router and MCP router generators emit.
+ *
+ * Granularity is one statement (or one fragment) per method, so the shared codegen keeps ownership
+ * of control flow — which branches exist, what order they run in, and which values reach them — and
+ * an adapter only decides how a given step is spelled. Anything an adapter cannot express as a
+ * statement, such as ending a response, is returned as a list of lines so it can also be empty.
+ */
+export interface ServerFramework {
+    readonly name: ServerFrameworkName;
+    /**
+     * Import lines for the framework runtime, already filtered down to what the generated body uses.
+     *
+     * The adapter applies `uses` itself rather than declaring a symbol list, because a framework may
+     * need more than one import line, and because only names the adapter chooses ever go through the
+     * word-boundary probe — a handler-local identifier can never be mistaken for an import.
+     */
+    imports(uses: (symbol: string) => boolean): string[];
+    /** The module-level router value every handler attaches to. */
+    routerDeclaration(routerName: string): string;
+    /** Placeholder syntax for one path parameter, given a name already mapped to a valid identifier. */
+    pathParam(identifier: string): 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}. */
+    routeClose(): string[];
+    /** Route middleware factory calls, rendered as expressions for {@link routeOpen}. */
+    readonly middleware: {
+        policy(args: string): string;
+        bodyParser(tokensExpr: string): string;
+        signature(args: string): string;
+    };
+    /** Expressions a handler reads the request through. */
+    readonly request: {
+        params: string;
+        query: string;
+        headers: string;
+        /** The body already parsed by the body-parser middleware. */
+        parsedBody: string;
+        /**
+         * The request's media type with any parameters stripped. It is matched against declared MIME
+         * literals, so an adapter whose framework exposes only the raw header must normalise it here
+         * — a `; charset=utf-8` left on the end matches nothing.
+         */
+        contentType: string;
+    };
+    /** Expression resolving a service class out of the request-scoped DI container. */
+    resolveService(className: string): string;
+    /** Statements a handler writes the response with. */
+    readonly response: {
+        status(expr: string): string;
+        /**
+         * One statement setting a response header. It is emitted bare or behind an `if` guard for an
+         * optional header, so it must stay a single statement.
+         */
+        header(name: string, valueExpr: string): string;
+        type(expr: string): string;
+        /**
+         * The terminal write for a response, or for one without a body when `bodyExpr` is undefined.
+         * A framework that ends a response by returning needs a statement in both cases; Koa, which
+         * ends it by assignment, emits nothing for a bodyless one.
+         */
+        send(bodyExpr: string | undefined): string[];
+        /** What closes one `case` of the multi-status switch, after that status has been written. */
+        caseEnd(): string[];
+    };
+    /** The whole `mcp.router.ts` file, which is boilerplate rather than a per-operation render. */
+    mcpRouter(options: {
+        path: string;
+    }): string;
+}
+/**
+ * Every supported framework, keyed by name. The annotation is what ties this to
+ * {@link SERVER_FRAMEWORK_NAMES}: adding a name without an adapter is a compile error.
+ */
+export declare const SERVER_FRAMEWORKS: Readonly<Record<ServerFrameworkName, ServerFramework>>;
+/**
+ * Resolve a configured framework name to its adapter.
+ *
+ * @param name The `server.framework` value, or undefined for {@link DEFAULT_SERVER_FRAMEWORK_NAME}.
+ * @throws When `name` is not a supported framework. Config arrives as JSON, so this is a runtime
+ *   check and not something the `ServerFrameworkName` type can enforce on its own.
+ */
+export declare function resolveServerFramework(name: string | undefined): ServerFramework;
+//# sourceMappingURL=server-framework.d.ts.map

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

@@ -0,0 +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"}

package/llms.txt

@@ -56,7 +56,7 @@ Path templates accept `{filename}`, `{dir}`, `{area}`, and — in `sdk.output.sd
 
 | Key | Emits |
 | --- | --- |
-| `server` | Koa routers from `operation` declarations, plus the type or Zod files they import |
+| `server` | Server routers from `operation` declarations, plus the type or Zod files they import. `framework` selects the HTTP framework; only `koa` today |
 | `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,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {

package/src/codegen-mcp.ts

@@ -5,6 +5,8 @@ import { inferService, deriveModulePath, buildArgs, deriveBaseName } from './cod
 import { quoteKey, escapeSingleQuoted, sourceLink } from './ts-render.js';
 import { DECIMAL_IMPORT, DECIMAL_PRELUDE_LINES } from './decimal-runtime.js';
 import { basename, dirname, relative } from 'node:path';
+import type { ServerFramework } from './server-framework.js';
+import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
 
 // ─── Options ────────────────────────────────────────────────────────────────
 
@@ -498,29 +500,13 @@ export function generateMcpAggregator(entries: McpAggregatorEntry[]): string {
     return lines.join('\n') + '\n';
 }
 
-/** Generate the optional `mcp.router.ts` — the standard ServerKit route wiring for the dispatcher. */
-export function generateMcpRouter(options: { path?: string } = {}): string {
-    const path = options.path ?? '/mcp';
-    return `import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '@maroonedsoftware/koa';
-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: ReturnType<typeof ServerKitRouter>): void {
-    router.post('${path}', bodyParserMiddleware(['json']), requireSignature('mcp', { policy: MCP_AUTH_POLICY }), async (ctx) => {
-        const dispatcher = ctx.container.get(McpDispatcher);
-        const context = createMcpRequestContext({ requestId: ctx.requestId, logger: ctx.logger });
-        if (dispatcher.sessionMode === 'stateful') {
-            ctx.respond = false;
-            await dispatcher.dispatchStateful(
-                { req: ctx.req, res: ctx.res, body: ctx.parsedBody, sessionId: ctx.get('mcp-session-id') },
-                context,
-            );
-        } else {
-            const response = await dispatcher.dispatch(JSON.parse(String(ctx.rawBody)), context);
-            if (response) ctx.body = response;
-            else ctx.status = 202; // a notification — nothing to return
-        }
-    });
-}
-`;
+/**
+ * Generate the optional `mcp.router.ts` — the standard ServerKit route wiring for the dispatcher.
+ *
+ * The whole file is framework-specific boilerplate rather than a per-operation render, so the
+ * adapter owns the template. Defaults to Koa, matching the router generator.
+ */
+export function generateMcpRouter(options: { path?: string; framework?: ServerFramework } = {}): string {
+    const framework = options.framework ?? KOA_SERVER_FRAMEWORK;
+    return framework.mcpRouter({ path: options.path ?? '/mcp' });
 }

package/src/codegen-operation.ts

@@ -21,10 +21,19 @@ import {
 import { renderOutputTsType, quoteKey, headerNameToProperty, escapeJsDocLines, escapeSingleQuoted, sourceLink } from './ts-render.js';
 import { DECIMAL_IMPORT, DECIMAL_PRELUDE_LINES } from './decimal-runtime.js';
 import { basename, dirname, relative } from 'path';
+import type { ServerFramework } from './server-framework.js';
+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';
 
 // ─── Content-type helpers ──────────────────────────────────────────────────
 
-/** Map a request MIME type to the koa-bodyparser parser token used in middleware. */
+/**
+ * Map a request MIME type to the ServerKit parser token used in middleware. The tokens are the keys
+ * of the parser map in `@maroonedsoftware/servercore`, so they are the same whichever HTTP framework
+ * the router targets.
+ */
 function bodyParserToken(contentType: string): string {
     switch (classifyContentType(contentType)) {
         case 'urlencoded':
@@ -34,9 +43,8 @@ function bodyParserToken(contentType: string): string {
         case 'text':
             return 'text';
         case 'binary':
-            // koa-bodyparser has no native binary token; fall back to text so the body is
-            // still readable as a string. Services handling binary uploads should switch to
-            // multipart/form-data.
+            // There is no native binary token; fall back to text so the body is still readable as a
+            // string. Services handling binary uploads should switch to multipart/form-data.
             return 'text';
         default:
             return 'json';
@@ -125,7 +133,7 @@ export function bodyTypesStructurallyEqual(a: ContractTypeNode, b: ContractTypeN
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
-/** Options controlling how {@link generateOp} renders a Koa router module. */
+/** Options controlling how {@link generateOp} renders a server router module. */
 export interface OpCodegenOptions {
     servicePathTemplate?: string;
     typeImportPathTemplate?: string;
@@ -143,8 +151,8 @@ export interface OpCodegenOptions {
      */
     includeInternal?: boolean;
     /**
-     * Re-parse the service result through its declared response schema before writing `ctx.body`,
-     * and write the parsed value. Requires the type file to hold Zod schemas (`server.zod`) —
+     * Re-parse the service result through its declared response schema before writing the response
+     * body, and write the parsed value. Requires the type file to hold Zod schemas (`server.zod`) —
      * plain interfaces are types, with no runtime schema value to validate against. Default false.
      */
     validateResponses?: boolean;
@@ -154,10 +162,18 @@ export interface OpCodegenOptions {
      * post-transform shape, which the schema itself cannot re-parse.
      */
     modelsWithTransform?: Set<string>;
+    /**
+     * Which HTTP framework the emitted router targets. Every framework-specific string in the output
+     * comes from here. Defaults to Koa, the only framework shipped today.
+     */
+    framework?: ServerFramework;
 }
 
+/** {@link OpCodegenOptions} after {@link generateOp} has filled in the framework default. */
+type ResolvedOpCodegenOptions = OpCodegenOptions & { framework: ServerFramework };
+
 /**
- * Generate a Koa router module for every operation in `root`, including the imports, type
+ * Generate a server router module for every operation in `root`, including the imports, type
  * aliases, and handler list.
  *
  * Imports are derived from the generated body — each candidate symbol is emitted only if it
@@ -166,6 +182,10 @@ export interface OpCodegenOptions {
  * trips `noUnusedLocals` and lint downstream.
  */
 export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): string {
+    // Resolved once here rather than defaulted at each use, so every helper below reads a framework
+    // that is definitely present and no branch can quietly fall back to a different one.
+    const resolved: ResolvedOpCodegenOptions = { ...options, framework: options.framework ?? KOA_SERVER_FRAMEWORK };
+    const framework = resolved.framework;
     // Collect all referenced types across all routes
     const types = collectTypes(root, options.modelsWithInput, options.modelsWithOutput);
     const services = collectServices(root);
@@ -177,14 +197,14 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
     lines.push('/**');
     lines.push(` * generated from ${sourceLink(basename(root.file), options.outPath, root.file)}`);
     lines.push('*/');
-    lines.push(`export const ${routerName} = ServerKitRouter();`);
+    lines.push(framework.routerDeclaration(routerName));
     lines.push('');
 
     const includeInternal = options.includeInternal ?? true;
     for (const route of root.routes) {
         for (const op of route.operations) {
             if (!includeInternal && resolveModifiers(route, op).includes('internal')) continue;
-            lines.push(...generateHandler(route, op, root, options));
+            lines.push(...generateHandler(route, op, root, resolved));
             lines.push('');
         }
     }
@@ -231,10 +251,7 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
 
     const body: string[] = [];
 
-    const koaImports = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature'].filter(uses);
-    if (koaImports.length > 0) {
-        body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
-    }
+    body.push(...framework.imports(uses));
 
     // Services and model names come from the AST, which over-approximates two ways: a model with an
     // Input/Output variant contributes its base name even when only the variant is ever annotated,
@@ -280,11 +297,12 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
 
 // ─── Handler generation ────────────────────────────────────────────────────
 
-function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNode, options: OpCodegenOptions): string[] {
+function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNode, options: ResolvedOpCodegenOptions): string[] {
     const lines: string[] = [];
     const file = root.file;
     const outPath = options.outPath;
     const modelsWithInput = options.modelsWithInput;
+    const framework = options.framework;
 
     lines.push('/**');
 
@@ -310,10 +328,10 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     lines.push('*/');
 
     const method = op.method;
-    // `:name` from `{name}`, mapped to a valid identifier. Unlike a query parameter or a header,
-    // a path placeholder's name never reaches the wire — Koa matches by position — so renaming it
-    // is free, and it is what lets `ctx.params` be destructured at all.
-    const path = route.path.replace(PATH_PARAM_RE_G, (_m, name: string) => `:${toIdentifier(name)}`);
+    // The framework's placeholder syntax, from `{name}`, mapped to a valid identifier. Unlike a query
+    // parameter or a header, a path placeholder's name never reaches the wire — the framework matches
+    // by position — so renaming it is free, and it is what lets the params object be destructured.
+    const path = route.path.replace(PATH_PARAM_RE_G, (_m, name: string) => framework.pathParam(toIdentifier(name)));
     const bodies = op.request?.bodies ?? [];
     const hasBody = bodies.length > 0;
     const isSingleMultipart = bodies.length === 1 && bodies[0]!.contentType === 'multipart/form-data';
@@ -328,39 +346,37 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
                 : policy === false
                   ? '{ policy: false }'
                   : `{ policy: '${policy}' }`;
-        middlewares.push(`requirePolicy(${args})`);
+        middlewares.push(framework.middleware.policy(args));
     }
     if (hasBody) {
         const parserTokens = Array.from(new Set(bodies.map(b => bodyParserToken(b.contentType))));
         const tokensExpr = parserTokens.map(t => `'${t}'`).join(', ');
-        middlewares.push(`bodyParserMiddleware([${tokensExpr}])`);
+        middlewares.push(framework.middleware.bodyParser(tokensExpr));
     }
     if (op.signature) {
         const sigArgs = op.signaturePolicy
             ? `'${escapeSingleQuoted(op.signature)}', { policy: '${escapeSingleQuoted(op.signaturePolicy)}' }`
             : `'${escapeSingleQuoted(op.signature)}'`;
-        middlewares.push(`requireSignature(${sigArgs})`);
+        middlewares.push(framework.middleware.signature(sigArgs));
     }
-    const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
-
-    lines.push(`${deriveRouterName(file)}.${method}('${path}'${middlewareStr} async ctx => {`);
+    lines.push(framework.routeOpen(deriveRouterName(file), method, path, middlewares));
 
     // Params / query / headers validation (request-side — use Input variants)
-    lines.push(...generateParamValidation(route.params, 'ctx.params', 'params', route.paramsMode ?? 'strict', '', modelsWithInput));
-    lines.push(...generateParamValidation(op.query, 'ctx.query', 'query', op.queryMode ?? 'strict', '', modelsWithInput));
-    lines.push(...generateParamValidation(op.headers, 'ctx.headers', 'headers', op.headersMode ?? 'strip', '', modelsWithInput));
+    lines.push(...generateParamValidation(route.params, 'params', framework.request.params, route.paramsMode ?? 'strict', '', modelsWithInput));
+    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));
 
     // Body validation (request-side — use Input variants)
     if (hasBody && op.request) {
         if (isSingleMultipart) {
-            lines.push(`    const multipartBody = ctx.parsedBody as MultipartBody;`);
+            lines.push(`    const multipartBody = ${framework.request.parsedBody} as MultipartBody;`);
             lines.push('');
         } else if (bodies.length === 1) {
-            lines.push(`    const body = await parseAndValidate(ctx.parsedBody, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
+            lines.push(`    const body = await parseAndValidate(${framework.request.parsedBody}, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
             lines.push('');
         } else if (bodies.every(b => bodyTypesStructurallyEqual(b.bodyType, bodies[0]!.bodyType))) {
             // All declared MIMEs share the same body shape — single validation suffices
-            lines.push(`    const body = await parseAndValidate(ctx.parsedBody, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
+            lines.push(`    const body = await parseAndValidate(${framework.request.parsedBody}, ${renderInputType(bodies[0]!.bodyType, modelsWithInput)});`);
             lines.push('');
         } else {
             // Different body types per MIME — dispatch on Content-Type
@@ -370,13 +386,13 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
                 )
                 .join(' | ');
             lines.push(`    let body!: ${annotation};`);
-            lines.push(`    switch (ctx.request.type) {`);
+            lines.push(`    switch (${framework.request.contentType}) {`);
             for (const b of bodies) {
                 lines.push(`        case '${b.contentType}':`);
                 if (b.contentType === 'multipart/form-data') {
-                    lines.push(`            body = ctx.parsedBody as MultipartBody;`);
+                    lines.push(`            body = ${framework.request.parsedBody} as MultipartBody;`);
                 } else {
-                    lines.push(`            body = await parseAndValidate(ctx.parsedBody, ${renderInputType(b.bodyType, modelsWithInput)});`);
+                    lines.push(`            body = await parseAndValidate(${framework.request.parsedBody}, ${renderInputType(b.bodyType, modelsWithInput)});`);
                 }
                 lines.push(`            break;`);
             }
@@ -397,25 +413,26 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
         lines.push(...generateSingleStatusResult(emitted[0], op, serviceParts.className, call, options));
     }
 
-    lines.push(`});`);
+    lines.push(...framework.routeClose());
 
     return lines;
 }
 
 /**
  * The service produces exactly one status (or none): the result is the body itself, or
- * `{ body, headers }` when the status declares headers, and `ctx.status` is a constant.
+ * `{ body, headers }` when the status declares headers, and the status code is a constant.
  *
  * A status declaring several mimes also gains a `contentType` the service picks, which is the
- * only thing here that can turn `ctx.type` from a literal into an expression.
+ * only thing here that can turn the response content type from a literal into an expression.
  */
 function generateSingleStatusResult(
     resp: OpResponseNode | undefined,
     op: OpOperationNode,
     className: string,
     call: string,
-    options: OpCodegenOptions,
+    options: ResolvedOpCodegenOptions,
 ): string[] {
+    const framework = options.framework;
     const lines: string[] = [];
     const bodies = resp ? resp.bodies : [];
     const respHeaders = resp?.headers ?? [];
@@ -428,7 +445,7 @@ function generateSingleStatusResult(
         const { annotation, prelude } = formatTypeAnnotation(bodies[0]!.bodyType, options.modelsWithOutput);
         if (prelude) lines.push(`    ${prelude}`);
         bodySchema = responseBodySchema(bodies[0]!.bodyType, options, prelude ? 'resultType' : undefined);
-        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const service = ${framework.resolveService(className)};`);
         if (hasRespHeaders) {
             lines.push(`    const result: { body: ${annotation}; headers: ${headersAnnotation} } = ${call};`);
         } else {
@@ -439,10 +456,10 @@ function generateSingleStatusResult(
         const { members, preludes } = rendered;
         bodySchema = rendered.bodySchema;
         for (const prelude of preludes) lines.push(`    ${prelude}`);
-        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const service = ${framework.resolveService(className)};`);
         lines.push(`    const result: ${members.join(' | ')} = ${call};`);
     } else {
-        lines.push(`    const service = ctx.container.get(${className});`);
+        lines.push(`    const service = ${framework.resolveService(className)};`);
         if (hasRespHeaders) {
             lines.push(`    const result: { headers: ${headersAnnotation} } = ${call};`);
         } else {
@@ -456,15 +473,18 @@ function generateSingleStatusResult(
     // also what aligns the three generators: `observableResponses` excludes a bare `400:` too, so
     // the SDK already types such a method `Promise<void>` and `thrownResponses` puts the 400 in
     // `@throws`. A bodyless 204 success is exactly what `Promise<void>` means.
-    lines.push(`    ctx.status = ${resp?.statusCode ?? 204};`);
-    lines.push(...headerSetLines(respHeaders, '    '));
+    lines.push(`    ${framework.response.status(String(resp?.statusCode ?? 204))}`);
+    lines.push(...headerSetLines(respHeaders, '    ', framework));
 
     if (bodies.length === 1) {
-        lines.push(`    ctx.type = '${bodies[0]!.contentType}';`);
-        lines.push(`    ctx.body = ${responseBodyExpr(hasRespHeaders ? 'result.body' : 'result', bodySchema)};`);
+        lines.push(`    ${framework.response.type(`'${bodies[0]!.contentType}'`)}`);
+        lines.push(...indent(framework.response.send(responseBodyExpr(hasRespHeaders ? 'result.body' : 'result', bodySchema)), '    '));
     } else if (bodies.length > 1) {
-        lines.push(`    ctx.type = result.contentType;`);
-        lines.push(`    ctx.body = ${responseBodyExpr('result.body', bodySchema)};`);
+        lines.push(`    ${framework.response.type('result.contentType')}`);
+        lines.push(...indent(framework.response.send(responseBodyExpr('result.body', bodySchema)), '    '));
+    } else {
+        // Nothing to write, but a framework that ends a response by returning still needs a statement.
+        lines.push(...indent(framework.response.send(undefined), '    '));
     }
 
     return lines;
@@ -475,7 +495,8 @@ function generateSingleStatusResult(
  * `status`, and the handler switches on it so each status writes only its own headers, mime
  * and body.
  */
-function generateMultiStatusResult(emitted: OpResponseNode[], className: string, call: string, options: OpCodegenOptions): string[] {
+function generateMultiStatusResult(emitted: OpResponseNode[], className: string, call: string, options: ResolvedOpCodegenOptions): string[] {
+    const framework = options.framework;
     const lines: string[] = [];
     const members: string[] = [];
     const preludes: string[] = [];
@@ -490,21 +511,23 @@ function generateMultiStatusResult(emitted: OpResponseNode[], className: string,
     }
 
     for (const prelude of preludes) lines.push(`    ${prelude}`);
-    lines.push(`    const service = ctx.container.get(${className});`);
+    lines.push(`    const service = ${framework.resolveService(className)};`);
     lines.push(`    const result:`);
     for (const member of members) lines.push(`        | ${member}`);
     lines.push(`        = ${call};`);
     lines.push('');
-    lines.push(`    ctx.status = result.status;`);
+    lines.push(`    ${framework.response.status('result.status')}`);
     lines.push(`    switch (result.status) {`);
     for (const resp of emitted) {
         lines.push(`        case ${resp.statusCode}:`);
-        lines.push(...headerSetLines(resp.headers ?? [], '            '));
+        lines.push(...headerSetLines(resp.headers ?? [], '            ', framework));
         if (resp.bodies.length > 0) {
-            lines.push(`            ctx.type = result.contentType;`);
-            lines.push(`            ctx.body = ${responseBodyExpr('result.body', bodySchemas.get(resp.statusCode))};`);
+            lines.push(`            ${framework.response.type('result.contentType')}`);
+            lines.push(...indent(framework.response.send(responseBodyExpr('result.body', bodySchemas.get(resp.statusCode))), '            '));
+        } else {
+            lines.push(...indent(framework.response.send(undefined), '            '));
         }
-        lines.push(`            break;`);
+        lines.push(...indent(framework.response.caseEnd(), '            '));
     }
     lines.push(`    }`);
 
@@ -565,16 +588,20 @@ function renderHeadersAnnotation(headers: OpResponseHeaderNode[], modelsWithOutp
     return `{ ${fields.join('; ')} }`;
 }
 
-/** `ctx.set(...)` calls for a status's declared response headers, guarding the optional ones. */
-function headerSetLines(headers: OpResponseHeaderNode[], indent: string): string[] {
+/** Response-header writes for a status's declared headers, guarding the optional ones. */
+function headerSetLines(headers: OpResponseHeaderNode[], pad: string, framework: ServerFramework): string[] {
     return headers.map(h => {
         const accessor = `result.headers[${JSON.stringify(headerNameToProperty(h.name))}]`;
-        return h.optional
-            ? `${indent}if (${accessor} !== undefined) ctx.set('${h.name}', String(${accessor}));`
-            : `${indent}ctx.set('${h.name}', String(${accessor}));`;
+        const write = framework.response.header(h.name, `String(${accessor})`);
+        return h.optional ? `${pad}if (${accessor} !== undefined) ${write}` : `${pad}${write}`;
     });
 }
 
+/** Prefix each of a framework's statements with the handler indentation the caller is writing at. */
+function indent(lines: string[], pad: string): string[] {
+    return lines.map(line => `${pad}${line}`);
+}
+
 // ─── Inference helpers ─────────────────────────────────────────────────────
 
 /**
@@ -778,7 +805,7 @@ function responseBodySchema(bodyType: ContractTypeNode, options: OpCodegenOption
 }
 
 /**
- * The `ctx.body = ...` right-hand side for a response body: the raw result expression, or a
+ * The right-hand side of a response body write: the raw result expression, or a
  * `parseAndValidate` of it. The `500` is deliberate — a service returning a shape its own contract
  * rejects is a server fault, not a client one, and `@maroonedsoftware/zod` routes the field-level
  * detail to `internalDetails` (log-only) rather than the response body at 5xx.
@@ -789,37 +816,35 @@ function responseBodyExpr(value: string, schema: string | undefined): string {
 
 function generateParamValidation(
     source: ParamSource | undefined,
-    ctxExpr: string,
-    varName: string,
+    kind: ParamKind,
+    sourceExpr: string,
     mode: ObjectMode,
     suffix = '',
     modelsWithInput?: Set<string>,
 ): string[] {
     if (!source) return [];
     const lines: string[] = [];
-    const isQuery = ctxExpr === 'ctx.query';
+    const isQuery = kind === 'query';
+    // Path params are destructured and spread into the service call; query and headers pass as
+    // whole objects. The variable the block declares is named after the kind either way.
+    const isPathParams = kind === 'params';
     if (source.kind === 'ref') {
         // Type reference — apply mode as a method call on the schema
         const typeName = modelsWithInput?.has(source.name) ? `${source.name}Input` : source.name;
-        lines.push(`    const ${varName} = await parseAndValidate(${ctxExpr}, ${typeName}.${mode}());`);
+        lines.push(`    const ${kind} = await parseAndValidate(${sourceExpr}, ${typeName}.${mode}());`);
         lines.push('');
     } else if (source.kind === 'params') {
         // Inline param declarations — wrap with the appropriate z.*Object constructor
         if (source.nodes.length > 0) {
-            // Destructure only for params (spread individually in service call);
-            // query/headers are passed as whole objects.
-            // Path params are destructured and spread into the service call; query and headers pass
-            // as whole objects.
-            const isPathParams = ctxExpr === 'ctx.params';
             const bind = (name: string) => (isPathParams ? toIdentifier(name) : name);
-            const lhs = varName === 'params' ? `{ ${source.nodes.map(p => bind(p.name)).join(', ')} }` : varName;
+            const lhs = isPathParams ? `{ ${source.nodes.map(p => bind(p.name)).join(', ')} }` : kind;
             lines.push(`    const ${lhs} = await parseAndValidate(`);
-            lines.push(`        ${ctxExpr},`);
+            lines.push(`        ${sourceExpr},`);
             lines.push(`        ${modeToWrapper(mode)}({`);
             for (const param of source.nodes) {
                 // For path params the key must match the name in the route pattern above, which
-                // is what `ctx.params` is keyed by. For query and headers it is the wire name,
-                // quoted when that is not an identifier — those the client actually sends.
+                // is what the framework keys its params object by. For query and headers it is the
+                // wire name, quoted when that is not an identifier — those the client actually sends.
                 const bound = bind(param.name);
                 const key = isValidIdentifier(bound) ? bound : `'${bound}'`;
                 // Delegating to renderQueryType rather than hand-rolling the array preprocess here:
@@ -837,7 +862,7 @@ function generateParamValidation(
         // ContractTypeNode — use query-aware rendering for query params (coerces single string → array),
         // otherwise use Input variant rendering; apply mode as a method call
         const schema = isQuery ? renderQueryType(source.node, modelsWithInput) : renderInputType(source.node, modelsWithInput);
-        lines.push(`    const ${varName} = await parseAndValidate(${ctxExpr}, (${schema}).${mode}());`);
+        lines.push(`    const ${kind} = await parseAndValidate(${sourceExpr}, (${schema}).${mode}());`);
         lines.push('');
     }
     return lines;