@contractkit/plugin-typescript 0.34.1 → 0.36.0

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

@@ -0,0 +1,114 @@
+import type { ServerFramework } from './server-framework.js';
+
+/** Module the Koa flavour of ServerKit publishes its router and route middleware from. */
+const KOA_RUNTIME_MODULE = '@maroonedsoftware/koa';
+
+/**
+ * Symbols importable from {@link KOA_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.
+ */
+const KOA_RUNTIME_SYMBOLS = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature'] as const;
+
+/**
+ * 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 const KOA_SERVER_FRAMEWORK: ServerFramework = {
+    name: 'koa',
+
+    imports(uses) {
+        const symbols = KOA_RUNTIME_SYMBOLS.filter(uses);
+        return symbols.length > 0 ? [`import { ${symbols.join(', ')} } from '${KOA_RUNTIME_MODULE}';`] : [];
+    },
+
+    routerDeclaration(routerName) {
+        return `export const ${routerName} = ServerKitRouter();`;
+    },
+
+    pathParam(identifier) {
+        return `:${identifier}`;
+    },
+
+    handlerLocals: ['ctx'],
+
+    routeOpen(routerName, method, path, middlewares) {
+        const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
+        return `${routerName}.${method}('${path}'${middlewareStr} async ctx => {`;
+    },
+
+    routeClose() {
+        return ['});'];
+    },
+
+    middleware: {
+        policy(args) {
+            return `requirePolicy(${args})`;
+        },
+        bodyParser(tokensExpr) {
+            return `bodyParserMiddleware([${tokensExpr}])`;
+        },
+        signature(args) {
+            return `requireSignature(${args})`;
+        },
+    },
+
+    request: {
+        params: 'ctx.params',
+        query: 'ctx.query',
+        headers: 'ctx.headers',
+        // Not `ctx.request.body`: the ServerKit body parser drains the stream and writes its result
+        // here, and in Koa `ctx.body` is the *response* body.
+        parsedBody: 'ctx.parsedBody',
+        // Koa strips the parameters off `Content-Type` for this accessor already.
+        contentType: 'ctx.request.type',
+    },
+
+    resolveService(className) {
+        return `ctx.container.get(${className})`;
+    },
+
+    response: {
+        status(expr) {
+            return `ctx.status = ${expr};`;
+        },
+        header(name, valueExpr) {
+            return `ctx.set('${name}', ${valueExpr});`;
+        },
+        type(expr) {
+            return `ctx.type = ${expr};`;
+        },
+        send(bodyExpr) {
+            // A bodyless response needs no statement at all: Koa sends whatever `ctx.status` and the
+            // headers say once the handler resolves.
+            return bodyExpr === undefined ? [] : [`ctx.body = ${bodyExpr};`];
+        },
+        caseEnd() {
+            return ['break;'];
+        },
+    },
+
+    mcpRouter({ path }) {
+        return `import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '${KOA_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: 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
+        }
+    });
+}
+`;
+    },
+};

package/src/server-framework.ts

@@ -0,0 +1,129 @@
+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', 'fastify'] as const;
+
+/** One of {@link SERVER_FRAMEWORK_NAMES}. */
+export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
+
+/** The framework assumed when a config names none. */
+export const DEFAULT_SERVER_FRAMEWORK_NAME: ServerFrameworkName = 'koa';
+
+/**
+ * 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;
+
+    /**
+     * 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}. */
+    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 const SERVER_FRAMEWORKS: Readonly<Record<ServerFrameworkName, ServerFramework>> = {
+    koa: KOA_SERVER_FRAMEWORK,
+    fastify: FASTIFY_SERVER_FRAMEWORK,
+};
+
+/**
+ * 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 function resolveServerFramework(name: string | undefined): ServerFramework {
+    const resolved = name ?? DEFAULT_SERVER_FRAMEWORK_NAME;
+    const framework = (SERVER_FRAMEWORKS as Record<string, ServerFramework | undefined>)[resolved];
+    if (!framework) {
+        throw new Error(
+            `plugin-typescript: server.framework '${resolved}' is not supported — expected one of: ${SERVER_FRAMEWORK_NAMES.join(', ')}.`,
+        );
+    }
+    return framework;
+}

package/tests/codegen-mcp.test.ts

@@ -286,6 +286,18 @@ describe('generateMcpRouter', () => {
         expect(out).not.toContain('ctx.request.body');
     });
 
+        it('delegates the whole file to the framework adapter', () => {
+            const stub = { mcpRouter: ({ path }: { path: string }) => `// stub mount at ${path}` };
+            // Only `mcpRouter` is reachable from here, so the rest of the adapter is left off the stub.
+            const out = generateMcpRouter({ framework: stub as never });
+            expect(out).toBe('// stub mount at /mcp');
+        });
+
+        it('passes a configured path through to the adapter', () => {
+            const stub = { mcpRouter: ({ path }: { path: string }) => `// stub mount at ${path}` };
+            expect(generateMcpRouter({ path: '/tools', framework: stub as never })).toBe('// stub mount at /tools');
+        });
+
     it('defaults the mount path to /mcp', () => {
         expect(generateMcpRouter()).toContain("router.post('/mcp'");
     });

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

@@ -0,0 +1,184 @@
+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';
+
+/**
+ * A framework whose every string is unmistakable. Rendering a router through it and finding no Koa
+ * left in the output is what proves the seam is complete: a `ctx.` the generator still emits inline
+ * would survive this substitution, and a `toContain` test against the Koa output never notices,
+ * because the default adapter puts the very same string there.
+ */
+const STUB: ServerFramework = {
+    // The registry's key type admits only shipped frameworks; the adapter under test is a fake.
+    name: 'koa',
+    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: {
+        policy: args => `stubPolicy(${args})`,
+        bodyParser: tokens => `stubBody(${tokens})`,
+        signature: args => `stubSignature(${args})`,
+    },
+    request: {
+        params: 'rq.pathParams',
+        query: 'rq.searchParams',
+        headers: 'rq.headerBag',
+        parsedBody: 'rq.payload',
+        contentType: 'rq.mediaType',
+    },
+    resolveService: className => `rq.services.resolve(${className})`,
+    response: {
+        status: expr => `rs.setStatus(${expr});`,
+        header: (name, valueExpr) => `rs.putHeader('${name}', ${valueExpr});`,
+        type: expr => `rs.setMedia(${expr});`,
+        send: bodyExpr => (bodyExpr === undefined ? ['return rs.finish();'] : [`return rs.deliver(${bodyExpr});`]),
+        caseEnd: () => [],
+    },
+    mcpRouter: ({ path }) => `// stub mcp at ${path}\n`,
+};
+
+/** One op root touching every branch of the generator that can emit a framework string. */
+function everyBranchRoot() {
+    return opRoot([
+        opRoute(
+            '/payments/{paymentId}',
+            [
+            // Path params + query + headers + a single JSON body, with policy and signature middleware.
+            opOperation('post', {
+                request: opRequest('Payment'),
+                query: [opParam('limit', scalarType('int'))],
+                headers: [opParam('x-tenant', scalarType('string'))],
+                signature: 'stripe',
+                responses: [opResponse(201, 'Payment')],
+            }),
+            // Several request MIMEs with different shapes — the content-type switch.
+            opOperation('put', {
+                request: opMultiRequest([
+                    ['application/json', 'Payment'],
+                    ['multipart/form-data', 'Receipt'],
+                ]),
+                responses: [opResponse(200, 'Payment')],
+            }),
+            // No emitted body at all — the bodyless 204 path.
+            opOperation('delete', { responses: [] }),
+            // Several emitted statuses, one carrying response headers — the status switch.
+            opOperation('patch', {
+                responses: [
+                    opResponseMulti(200, [{ contentType: 'application/json', bodyType: 'Payment' }], {
+                        headers: [{ name: 'etag', optional: false, type: scalarType('string') }],
+                    }),
+                    opResponseMulti(202, [{ contentType: 'application/json', bodyType: refType('Payment') }], {
+                        headers: [{ name: 'retry-after', optional: true, type: scalarType('string') }],
+                    }),
+                ],
+            }),
+            ],
+            [opParam('paymentId', scalarType('uuid'))],
+        ),
+    ]);
+}
+
+describe('generateOp — framework seam', () => {
+    const output = generateOp(everyBranchRoot(), { framework: STUB });
+
+    it('leaves no Koa string anywhere in the output', () => {
+        expect(output).not.toMatch(/\bctx\b/);
+        expect(output).not.toContain('ServerKitRouter');
+        expect(output).not.toContain('@maroonedsoftware/koa');
+        expect(output).not.toContain('requirePolicy');
+        expect(output).not.toContain('bodyParserMiddleware');
+        expect(output).not.toContain('requireSignature');
+    });
+
+    it('renders the router shell through the adapter', () => {
+        expect(output).toContain('export const UsersRouter = StubRouter();');
+        expect(output).toContain("import { StubRouter } from '@stub/http';");
+        expect(output).toContain('}, END);');
+    });
+
+    it('renders the route line, its path params and its middleware through the adapter', () => {
+        expect(output).toContain("UsersRouter.route('post', '/payments/<paymentId>', [stubPolicy(), stubBody('json'), stubSignature('stripe')], async (rq, rs) => {");
+    });
+
+    it('reads params, query, headers and the body through the adapter', () => {
+        expect(output).toContain('rq.pathParams');
+        expect(output).toContain('rq.searchParams');
+        expect(output).toContain('rq.headerBag');
+        expect(output).toContain('rq.payload');
+        expect(output).toContain('switch (rq.mediaType) {');
+    });
+
+    it('resolves services through the adapter', () => {
+        expect(output).toContain('rq.services.resolve(UsersService)');
+    });
+
+    it('writes status, headers, content type and body through the adapter', () => {
+        expect(output).toContain('rs.setStatus(201);');
+        expect(output).toContain("rs.setMedia('application/json');");
+        expect(output).toContain('return rs.deliver(result);');
+        expect(output).toContain('rs.putHeader(\'etag\', String(result.headers["etag"]));');
+        expect(output).toContain('if (result.headers["retryAfter"] !== undefined) rs.putHeader(\'retry-after\', String(result.headers["retryAfter"]));');
+    });
+
+    it('gives a bodyless response the adapter\'s terminal statement', () => {
+        // Koa needs none, so the generator only emits one because the adapter asked for it.
+        expect(output).toContain('rs.setStatus(204);');
+        expect(output).toContain('return rs.finish();');
+    });
+
+    it('omits the status-case terminator when the adapter has none', () => {
+        expect(output).toContain('rs.setStatus(result.status);');
+        // Scoped to the status switch: the multi-MIME request dispatch is the generator's own control
+        // flow and keeps its `break;` whatever the framework is.
+        const statusSwitch = output.slice(output.indexOf('switch (result.status) {'));
+        expect(statusSwitch).toContain('case 202:');
+        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([
@@ -567,6 +612,35 @@ describe('generateOperation', () => {
             expect(output).toContain('z.object({');
         });
 
+        it('renders an inline array header through renderInputType, without the query coercion', () => {
+            // The comma-splitting preprocess belongs to query strings only. Headers and params share
+            // the same inline-param renderer, so the block has to be told which one it is rendering.
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        headers: [opParam('x-tags', arrayType(scalarType('string')))],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('ctx.headers');
+            expect(output).not.toContain('z.preprocess');
+            expect(output).not.toContain("v.split(',')");
+        });
+
+        it('declares headers as a whole object rather than destructuring it', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        headers: [opParam('authorization', scalarType('string'))],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('const headers = await parseAndValidate(');
+            expect(output).not.toContain('const { authorization }');
+        });
+
         it('generates parseAndValidate import when operation has headers', () => {
             const root = opRoot([
                 opRoute('/users', [