@contractkit/plugin-typescript 0.33.2 → 0.34.0

package/src/index.ts

@@ -8,6 +8,7 @@ import type {
     ContractRootNode,
     OpRootNode,
     ModelNode,
+    ScalarTypeNode,
     IncrementalManifest,
     IncrementalUnit,
     IncrementalOutputFile,
@@ -21,7 +22,7 @@ import {
     collectTransitiveModelRefs,
     collectTypeRefs,
     computeModelsWithCaseTransform,
-    computeModelsWithDecimal,
+    computeModelsWithScalar,
 } from '@contractkit/core';
 import {
     generateSdk,
@@ -43,9 +44,14 @@ import {
     type SdkScaffoldDeps,
 } from './codegen-sdk.js';
 import { generatePlainTypes } from './codegen-plain-types.js';
+import { DEFAULT_REVIVABLE_SCALARS } from './codegen-revive.js';
+
+/** Taint set for the SDK's bigint response reviver. */
+const BIGINT_SCALARS: ReadonlySet<ScalarTypeNode['name']> = new Set(['bigint']);
 import { generateMcpFile, generateMcpAggregator, generateMcpRouter, hasMcpOperations, deriveMcpRegisterFnName } from './codegen-mcp.js';
 import {
     TEMPLATE_VAR_RE,
+    TEMPLATE_VAR_RE_G,
     resolveTemplate,
     commonDir,
     computeOpOutPath,
@@ -167,7 +173,12 @@ export interface TypescriptPluginConfig {
 // ─── Caching constants ─────────────────────────────────────────────────────
 
 /** Bumped when the codegen output shape changes in a way that should bust every per-file fingerprint. */
-export const TYPESCRIPT_CODEGEN_VERSION = '1';
+export const TYPESCRIPT_CODEGEN_VERSION = '2';
+
+// The taint set is `DEFAULT_REVIVABLE_SCALARS` rather than decimal alone, which is what makes a
+// temporal field a real Luxon object in an SDK client rather than a string wearing a `DateTime`
+// type. It also feeds every `hashFingerprint` that already slices this set, so a model gaining a
+// `datetime` in another `.ck` file invalidates this file's cached output with no extra plumbing.
 
 /** Filename for the persisted TypeScript manifest under the CLI cache directory. */
 const CACHE_MANIFEST_FILENAME = 'typescript-manifest.json';
@@ -241,9 +252,23 @@ async function runTypescriptCodegen(
 
     deleteStalePaths(result.deletedPaths);
 
+    const unresolved = new Set<string>();
     for (const { relativePath, content, ifAbsent } of result.filesToWrite) {
+        for (const [, key] of relativePath.matchAll(TEMPLATE_VAR_RE_G)) unresolved.add(`${key}::${relativePath}`);
         ctx.emitFile(relativePath, content, ifAbsent ? { ifAbsent: true } : undefined);
     }
+    // `resolveTemplate` leaves an unknown `{key}` in place, which then joins straight into the
+    // output path — producing a literal `{area}` directory rather than an error. `assertWithinBase`
+    // does not catch it, since the path is inside the base, just wrong. Checked here rather than
+    // threaded down through five path helpers: every output path passes through this one funnel,
+    // whichever helper built it.
+    for (const entry of [...unresolved].sort()) {
+        const [key, outPath] = entry.split('::');
+        ctx.warn?.(
+            `Output path template variable {${key}} has no value, so '${outPath}' contains it literally. ` +
+                `Declare it in the source file's 'options { keys { ${key}: ... } }' block, or remove it from the path template.`,
+        );
+    }
 
     writeManifest(manifestPath, result.manifest);
 }
@@ -467,7 +492,11 @@ function collectSdkOutput(
     const modelsWithOutput = inputs.modelsWithOutput as Set<string>;
     // Computed across every contract root, not per file: one decimal below a model taints it, and
     // the reference that reaches it may live in another .ck file entirely.
-    const modelsWithDecimal = computeModelsWithDecimal(inputs.contractRoots.flatMap(r => r.models));
+    const modelsWithDecimal = computeModelsWithScalar(inputs.contractRoots.flatMap(r => r.models), DEFAULT_REVIVABLE_SCALARS);
+    // Which response bodies need the `123n` reviver. Transitive, because a bigint reached through
+    // a referenced model counts, and cross-file, because that model may live in another .ck file —
+    // which is also why it is sliced into every fingerprint below, exactly as modelsWithDecimal is.
+    const modelsWithBigInt = computeModelsWithScalar(inputs.contractRoots.flatMap(r => r.models), BIGINT_SCALARS);
     const modelMap = buildModelMap(inputs.contractRoots);
     const allFiles = [...inputs.contractRoots.map(r => r.file), ...inputs.opRoots.map(r => r.file)];
     const ckCommonRoot = commonDir(allFiles, rootDir);
@@ -509,6 +538,7 @@ function collectSdkOutput(
             // Not covered by `root`: adding a decimal to a model in a *different* .ck file changes
             // this file's revivers with no change to `root` or the config.
             modelsWithDecimal: sliceModelSet(refs, ownNames, modelsWithDecimal),
+            modelsWithBigInt: sliceModelSet(refs, ownNames, modelsWithBigInt),
             sdkOptionsPath,
             sub: subConfigKey,
         });
@@ -527,6 +557,9 @@ function collectSdkOutput(
                         modelsWithOutput,
                         modelsWithDecimal,
                         emitRevivers: true,
+                        // An SDK client runs in a browser as readily as in Node, and its scaffold
+                        // declares no `@types/node`.
+                        target: 'client',
                     });
                 } else {
                     let rel = relative(dirname(typeOutPath), sdkOptionsPath).replace(/\.ts$/, '.js');
@@ -587,6 +620,7 @@ function collectSdkOutput(
                     modelsWithInput: sliceModelSet(refs, new Set(), modelsWithInput),
                     modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
                     modelsWithDecimal: sliceModelSet(refs, new Set(), modelsWithDecimal),
+                modelsWithBigInt: sliceModelSet(refs, new Set(), modelsWithBigInt),
                     sdkOptionsPath,
                     className,
                     includeInternal: config.includeInternal ?? false,
@@ -606,6 +640,7 @@ function collectSdkOutput(
                                 modelsWithInput,
                                 modelsWithOutput,
                                 modelsWithDecimal,
+                                modelsWithBigInt,
                                 modelMap,
                                 includeInternal: config.includeInternal,
                                 clientClassName: className,
@@ -630,6 +665,7 @@ function collectSdkOutput(
                 modelsWithInput: sliceModelSet(refs, new Set(), modelsWithInput),
                 modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
                 modelsWithDecimal: sliceModelSet(refs, new Set(), modelsWithDecimal),
+                modelsWithBigInt: sliceModelSet(refs, new Set(), modelsWithBigInt),
                 sdkOptionsPath,
                 includeInternal: config.includeInternal ?? false,
                 sub: subConfigKey,
@@ -648,6 +684,7 @@ function collectSdkOutput(
                             modelsWithInput,
                             modelsWithOutput,
                             modelsWithDecimal,
+                            modelsWithBigInt,
                             modelMap,
                             includeInternal: config.includeInternal,
                         }),
@@ -731,6 +768,7 @@ function collectSdkOutput(
                 modelsWithInput: sliceModelSet(allInlineRefs, new Set(), modelsWithInput),
                 modelsWithOutput: sliceModelSet(allInlineRefs, new Set(), modelsWithOutput),
                 modelsWithDecimal: sliceModelSet(allInlineRefs, new Set(), modelsWithDecimal),
+                modelsWithBigInt: sliceModelSet(allInlineRefs, new Set(), modelsWithBigInt),
                 sdkOptionsPath,
                 includeInternal: config.includeInternal ?? false,
                 sub: subConfigKey,
@@ -746,6 +784,7 @@ function collectSdkOutput(
                     modelsWithInput,
                     modelsWithOutput,
                     modelsWithDecimal,
+                    modelsWithBigInt,
                     modelMap,
                     includeInternal: config.includeInternal,
                 },
@@ -878,7 +917,10 @@ function collectZodOutput(
             render: () => [
                 {
                     relativePath: outPath,
-                    content: generateContract(ast, { modelOutPaths, currentOutPath: outPath, modelsWithInput, modelsWithOutput }),
+                    // Server-shaped, which is what this sub-generator has always emitted. The
+                    // standalone `zod:` output has no target option of its own; only the SDK's
+                    // schemas are client-shaped, and they pass their own target.
+                    content: generateContract(ast, { modelOutPaths, currentOutPath: outPath, modelsWithInput, modelsWithOutput, target: 'server' }),
                 },
             ],
         });

package/src/path-utils.ts

@@ -21,6 +21,16 @@ function assertWithinBase(baseOutDir: string, outPath: string): string {
     return outPath;
 }
 
+/** Global-flagged twin of {@link TEMPLATE_VAR_RE}, for finding every variable in a string. */
+export const TEMPLATE_VAR_RE_G = /\{(\w+)\}/g;
+
+/**
+ * Substitute `{key}` placeholders from `vars`.
+ *
+ * An unknown key is left in place rather than throwing, because the caller is mid-way through
+ * building a path and has better context for the complaint — see the check at the emit funnel in
+ * `index.ts`, which reports it against the file it would have been written to.
+ */
 export function resolveTemplate(template: string, vars: Record<string, string>): string {
     return template.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
 }

package/src/ts-render.ts

@@ -1,3 +1,4 @@
+import { dirname, relative } from 'node:path';
 import type { ContractTypeNode, FieldNode, ScalarTypeNode } from '@contractkit/core';
 
 /** Declaration emitted into generated files that reference the `json` scalar. */
@@ -20,6 +21,25 @@ export function escapeSingleQuoted(s: string): string {
     return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '\\r');
 }
 
+/**
+ * Render the markdown link back to the `.ck` declaration a generated construct came from, as
+ * `[label](./path/to/file.ck#L12)`. Returns the link only; callers supply the surrounding prose
+ * and comment prefix, since some sites emit it inside a JSDoc block and others inside a `//` line.
+ *
+ * The path is relative to the emitted file's own directory, so it resolves when the reader clicks
+ * it from wherever the file was written. `outPath` is optional because codegen can run without a
+ * destination (the prettier plugin, and several tests), in which case the source path is used
+ * as-is.
+ *
+ * Not `file://./path`: `file://` opens an authority component, so the `.` parses as the host and
+ * the link resolves to nothing. A plain relative path is the correct form.
+ */
+export function sourceLink(label: string, outPath: string | undefined, sourceFile: string, line?: number): string {
+    const rel = outPath ? relative(dirname(outPath), sourceFile) : sourceFile;
+    const href = rel.startsWith('.') ? rel : `./${rel}`;
+    return `[${label}](${href}${line === undefined ? '' : `#L${line}`})`;
+}
+
 /** Convert an HTTP header name (e.g. `preference-applied`, `X-Request-ID`, `ETag`) to camelCase for use as a JS property. */
 export function headerNameToProperty(name: string): string {
     const parts = name.split(/[-_]/).filter(Boolean);
@@ -107,8 +127,14 @@ function renderTsScalar(name: ScalarTypeNode['name'], target: TsRenderTarget): s
         case 'date':
         case 'time':
         case 'datetime':
+            // Luxon objects on both sides. The router parses them via `_ZodDatetime`, and the SDK
+            // rehydrates them in its generated revivers, so `string` was a claim neither honoured.
+            return 'DateTime';
         case 'duration':
+            return 'Duration';
         case 'interval':
+            // The exception: `_ZodInterval` transforms back to an ISO string on output, so a
+            // string is genuinely what a consumer receives.
             return 'string';
         case 'null':
             return 'null';

package/tests/codegen-contract.test.ts

@@ -1,7 +1,8 @@
-import { generateContract, renderType } from '../src/codegen-contract.js';
+import { generateContract, renderType, applyFieldModifiers } from '../src/codegen-contract.js';
 import type { ContractCodegenContext } from '../src/codegen-contract.js';
 import {
     scalarType,
+    opParam,
     arrayType,
     tupleType,
     recordType,
@@ -18,6 +19,10 @@ import {
 } from './helpers.js';
 import type { ScalarTypeNode } from '@contractkit/core';
 
+/** The narrowed numeric coercion `renderScalar` emits — see NUMERIC_PREPROCESS in codegen-contract. */
+const NUM = `z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number())`;
+const NUM_INT = `z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number().int())`;
+
 describe('renderType', () => {
     // ─── Scalar types ───────────────────────────────────────────────
 
@@ -70,24 +75,24 @@ describe('renderType', () => {
             expect(renderType(scalarType('string', { regex: 'price:\\$' }))).toBe('z.string().regex(/^price:\\$$/)');
         });
 
-        it('renders z.coerce.number()', () => {
-            expect(renderType(scalarType('number'))).toBe('z.coerce.number()');
+        it('coerces number from a string, rejecting what Number() would swallow', () => {
+            expect(renderType(scalarType('number'))).toBe(NUM);
         });
 
-        it('renders z.coerce.number() with min', () => {
-            expect(renderType(scalarType('number', { min: 0 }))).toBe('z.coerce.number().min(0)');
+        it('renders number with min', () => {
+            expect(renderType(scalarType('number', { min: 0 }))).toBe(`z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number().min(0))`);
         });
 
-        it('renders z.coerce.number() with min and max', () => {
-            expect(renderType(scalarType('number', { min: 0, max: 100 }))).toBe('z.coerce.number().min(0).max(100)');
+        it('renders number with min and max', () => {
+            expect(renderType(scalarType('number', { min: 0, max: 100 }))).toBe(`z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number().min(0).max(100))`);
         });
 
-        it('renders z.coerce.number().int()', () => {
-            expect(renderType(scalarType('int'))).toBe('z.coerce.number().int()');
+        it('coerces int from a string, rejecting what Number() would swallow', () => {
+            expect(renderType(scalarType('int'))).toBe(NUM_INT);
         });
 
-        it('renders z.coerce.number().int() with constraints', () => {
-            expect(renderType(scalarType('int', { min: 1, max: 10 }))).toBe('z.coerce.number().int().min(1).max(10)');
+        it('renders int with constraints, chained inside the preprocess', () => {
+            expect(renderType(scalarType('int', { min: 1, max: 10 }))).toBe(`z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number().int().min(1).max(10))`);
         });
 
         it('renders z.bigint() with preprocess coercion from string or bigint', () => {
@@ -238,11 +243,11 @@ describe('renderType', () => {
         });
 
         it('renders tuple type', () => {
-            expect(renderType(tupleType(scalarType('number'), scalarType('string')))).toBe('z.tuple([z.coerce.number(), z.string()])');
+            expect(renderType(tupleType(scalarType('number'), scalarType('string')))).toBe(`z.tuple([${NUM}, z.string()])`);
         });
 
         it('renders record type', () => {
-            expect(renderType(recordType(scalarType('string'), scalarType('number')))).toBe('z.record(z.string(), z.coerce.number())');
+            expect(renderType(recordType(scalarType('string'), scalarType('number')))).toBe(`z.record(z.string(), ${NUM})`);
         });
 
         it('renders enum type', () => {
@@ -266,7 +271,7 @@ describe('renderType', () => {
         });
 
         it('renders union type', () => {
-            expect(renderType(unionType(scalarType('string'), scalarType('number')))).toBe('z.union([z.string(), z.coerce.number()])');
+            expect(renderType(unionType(scalarType('string'), scalarType('number')))).toBe(`z.union([z.string(), ${NUM}])`);
         });
 
         it('renders discriminated union as z.discriminatedUnion', () => {
@@ -286,7 +291,7 @@ describe('renderType', () => {
             const result = renderType(inlineObjectType([field('key', scalarType('string')), field('value', scalarType('number'))]));
             expect(result).toContain('z.strictObject({');
             expect(result).toContain('key: z.string(),');
-            expect(result).toContain('value: z.coerce.number(),');
+            expect(result).toContain(`value: ${NUM},`);
         });
     });
 });
@@ -300,7 +305,7 @@ describe('generateContract', () => {
             const output = generateContract(root);
             expect(output).toContain('export const User = z.strictObject({');
             expect(output).toContain('name: z.string(),');
-            expect(output).toContain('age: z.coerce.number(),');
+            expect(output).toContain(`age: ${NUM},`);
             expect(output).toContain('export type User = z.infer<typeof User>;');
         });
 
@@ -458,13 +463,20 @@ describe('generateContract', () => {
             expect(output).toContain("import { DateTime } from 'luxon';");
         });
 
-        it('emits _ZodBinary helper when binary field present', () => {
+        it('emits a Blob _ZodBinary by default, since the default target is the client', () => {
             const root = contractRoot([model('M', [field('f', scalarType('binary'))])]);
             const output = generateContract(root);
-            expect(output).toContain('const _ZodBinary = z.custom<Buffer>');
+            expect(output).toContain('const _ZodBinary = z.custom<Blob>');
             expect(output).toContain('_ZodBinary,');
         });
 
+        it('emits a Buffer _ZodBinary for the server target', () => {
+            const root = contractRoot([model('M', [field('f', scalarType('binary'))])]);
+            const output = generateContract(root, { modelOutPaths: new Map(), currentOutPath: '/out/m.ts', target: 'server' });
+            // `Buffer` in an SDK type file is unresolvable: the scaffold declares no @types/node.
+            expect(output).toContain('const _ZodBinary = z.custom<Buffer>');
+        });
+
         it('omits _ZodBinary helper when no binary fields', () => {
             const root = contractRoot([model('M', [field('f', scalarType('string'))])]);
             const output = generateContract(root);
@@ -567,7 +579,7 @@ describe('generateContract', () => {
     // ─── Three-schema pattern (visibility) ─────────────────────────
 
     describe('three-schema pattern', () => {
-        it('generates Base, Read, and Write schemas when visibility fields exist', () => {
+        it('generates Read and Write schemas when visibility fields exist', () => {
             const root = contractRoot([
                 model('User', [
                     field('id', scalarType('uuid'), { visibility: 'readonly' }),
@@ -576,11 +588,12 @@ describe('generateContract', () => {
                 ]),
             ]);
             const output = generateContract(root);
-            expect(output).toContain('const UserBase = z.strictObject({');
             expect(output).toContain('export const User = z.strictObject({');
             expect(output).toContain('export const UserInput = z.strictObject({');
             expect(output).toContain('export type User = z.infer<typeof User>;');
             expect(output).toContain('export type UserInput = z.infer<typeof UserInput>;');
+            // No writeonly model extends User, so nothing would read a UserBase.
+            expect(output).not.toContain('const UserBase');
         });
 
         it('read schema omits writeonly fields', () => {
@@ -732,20 +745,31 @@ describe('generateContract', () => {
             expect(output).toContain('export const AdminInput = User.extend({');
         });
 
-        it('parent with writeonly fields generates Base; child Base extends ParentBase', () => {
+        it('inherits writeonly fields through the Input chain, with no Base schema', () => {
             const root = contractRoot([
                 model('User', [field('password', scalarType('string'), { visibility: 'writeonly' }), field('name', scalarType('string'))]),
-                model('Admin', [field('role', scalarType('string'))], { bases: ['User'] }),
+                model('Admin', [field('token', scalarType('string'), { visibility: 'writeonly' }), field('role', scalarType('string'))], {
+                    bases: ['User'],
+                }),
             ]);
             const output = generateContract(root);
-            // User has writeonly — Base !== Read, so UserBase is emitted
-            expect(output).toContain('const UserBase =');
-            expect(output).toContain('export const User =');
-            expect(output).toContain('export const UserInput =');
-            // Admin has no writeonly — no AdminBase; but its Input still extends UserInput
-            expect(output).not.toContain('AdminBase');
-            expect(output).toContain('export const Admin = User.extend({');
+            expect(output).not.toContain('Base');
+            // AdminInput extends UserInput, which carries User's writeonly `password` — which is
+            // what the Base schemas were meant to deliver and never did.
             expect(output).toContain('export const AdminInput = UserInput.extend({');
+            expect(output).toContain('export const Admin = User.extend({');
+        });
+
+        it('leaves a user-declared model named XBase alone', () => {
+            const root = contractRoot([
+                model('User', [field('password', scalarType('string'), { visibility: 'writeonly' }), field('name', scalarType('string'))]),
+                model('UserBase', [field('label', scalarType('string'))]),
+            ]);
+            const output = generateContract(root);
+            // A text-derived rule would have had to distinguish these two; nothing generated is
+            // named UserBase any more, so the user's own model is the only one.
+            expect(output.match(/const UserBase\b/g)).toHaveLength(1);
+            expect(output).toContain('export const UserBase = z.strictObject({');
         });
 
         it('child inheriting from external parent with Input variant uses ParentInput.extend()', () => {
@@ -922,7 +946,7 @@ describe('generateContract', () => {
         it('includes source location comment above schema', () => {
             const root = contractRoot([model('User', [field('name', scalarType('string'))], { loc: { file: 'user.ck', line: 5 } })]);
             const output = generateContract(root);
-            expect(output).toContain('file://./user.ck#L5');
+            expect(output).toContain('[User](./user.ck#L5)');
         });
 
         it('includes source location for three-schema models', () => {
@@ -932,7 +956,7 @@ describe('generateContract', () => {
                 }),
             ]);
             const output = generateContract(root);
-            expect(output).toContain('file://./user.ck#L1');
+            expect(output).toContain('[User](./user.ck#L1)');
         });
     });
 
@@ -1236,10 +1260,41 @@ describe('generateContract', () => {
             ]);
             const output = generateContract(root);
             // Inline object emits its own transform inside the Webhook input shape.
-            expect(output).toContain('Amount: z.coerce.number().nullish()');
+            expect(output).toContain(`Amount: ${NUM}.nullish()`);
             expect(output).toContain('id: data.Id,');
             expect(output).toContain('...(data.Amount != null ? { amount: data.Amount } : {}),');
             expect(output).not.toContain('?? undefined');
         });
     });
 });
+
+// ─── applyFieldModifiers ──────────────────────────────────────────────────
+
+describe('applyFieldModifiers', () => {
+    it('appends nothing for a plain required field', () => {
+        expect(applyFieldModifiers('z.string()', {})).toBe('z.string()');
+    });
+
+    it('chains nullable, then optionality, then the description', () => {
+        expect(applyFieldModifiers('z.string()', { nullable: true, optional: true, description: 'a note' })).toBe(
+            'z.string().nullable().optional().describe("a note")',
+        );
+    });
+
+    it('prefers a default over .optional()', () => {
+        // `.default()` already makes the input side optional; adding `.optional()` on top would
+        // widen the output type to include undefined, which is what a default exists to prevent.
+        expect(applyFieldModifiers('z.number()', { optional: true, default: 20 })).toBe('z.number().default(20)');
+    });
+
+    it('quotes and escapes a string default', () => {
+        expect(applyFieldModifiers('z.string()', { default: 'a "quoted" value' })).toBe('z.string().default("a \\"quoted\\" value")');
+    });
+
+    it('accepts an OpParamNode, which is a FieldNode without the visibility modifiers', () => {
+        // This is the point of the structural parameter type: it lets a `query:` or `headers:`
+        // field render through exactly the same path a model field does.
+        const param = opParam('limit', scalarType('int'), { optional: true, default: 20 });
+        expect(applyFieldModifiers(NUM_INT, param)).toBe(`${NUM_INT}.default(20)`);
+    });
+});

package/tests/codegen-mcp.test.ts

@@ -233,6 +233,37 @@ describe('generateMcpRouter', () => {
         expect(out).toContain("dispatcher.sessionMode === 'stateful'");
     });
 
+    it('parses the body before verifying the signature', () => {
+        const out = generateMcpRouter({ path: '/mcp' });
+        // `requireSignature` HMACs `ctx.rawBody`, which only `bodyParserMiddleware` populates,
+        // so the parser has to run first. Asserting the whole route line pins the order too.
+        expect(out).toContain("import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '@maroonedsoftware/koa';");
+        expect(out).toContain(
+            "router.post('/mcp', bodyParserMiddleware(['json']), requireSignature('mcp', { policy: MCP_AUTH_POLICY }), async (ctx) => {",
+        );
+    });
+
+    it('answers notifications with 202 rather than falling through to a 404', () => {
+        const out = generateMcpRouter();
+        // `dispatch` resolves undefined for a notification; an unset ctx.body 404s in errorMiddleware.
+        expect(out).toContain('if (response) ctx.body = response;');
+        expect(out).toContain('else ctx.status = 202;');
+    });
+
+    it('stringifies rawBody before JSON.parse', () => {
+        const out = generateMcpRouter();
+        // ctx.rawBody is BinaryLike; JSON.parse takes string.
+        expect(out).toContain('JSON.parse(String(ctx.rawBody))');
+        expect(out).not.toContain('JSON.parse(ctx.rawBody)');
+    });
+
+    it('hands the stateful transport the parsed body', () => {
+        const out = generateMcpRouter();
+        // The parser drains the stream and writes ctx.parsedBody; ctx.request.body is never set.
+        expect(out).toContain('body: ctx.parsedBody');
+        expect(out).not.toContain('ctx.request.body');
+    });
+
     it('defaults the mount path to /mcp', () => {
         expect(generateMcpRouter()).toContain("router.post('/mcp'");
     });

package/tests/codegen-operation.test.ts

@@ -19,6 +19,10 @@ import {
     opRoot,
 } from './helpers.js';
 
+/** The narrowed numeric coercion `renderScalar` emits — see NUMERIC_PREPROCESS in codegen-contract. */
+const NUM = `z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number())`;
+const NUM_INT = `z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number().int())`;
+
 describe('generateOperation', () => {
     // ─── Router name derivation ─────────────────────────────────────
 
@@ -401,8 +405,8 @@ describe('generateOperation', () => {
             ]);
             const output = generateOp(root);
             expect(output).toContain('ctx.query');
-            expect(output).toContain('page: z.coerce.number().int()');
-            expect(output).toContain('limit: z.coerce.number().int()');
+            expect(output).toContain(`page: ${NUM_INT}`);
+            expect(output).toContain(`limit: ${NUM_INT}`);
         });
 
         it('generates parseAndValidate import when operation has query', () => {
@@ -441,7 +445,7 @@ describe('generateOperation', () => {
             expect(output).toContain('z.preprocess');
             expect(output).toContain("typeof v === 'string' ? v.split(',') : v");
             // Non-array params should not be wrapped
-            expect(output).toContain('limit: z.coerce.number().int()');
+            expect(output).toContain(`limit: ${NUM_INT}`);
         });
 
         it('imports Input variant for refs inside an intersection query', () => {
@@ -542,7 +546,7 @@ describe('generateOperation', () => {
             // Boolean should use preprocess for string coercion
             expect(output).toContain("active: z.preprocess((v) => v === 'true' ? true : v === 'false' ? false : v, z.boolean())");
             // Int should still use z.coerce
-            expect(output).toContain('page: z.coerce.number().int()');
+            expect(output).toContain(`page: ${NUM_INT}`);
         });
     });
 
@@ -756,10 +760,21 @@ describe('generateOperation', () => {
             expect(output).not.toContain('ctx.body =');
         });
 
-        it('defaults to status 200 when no response specified', () => {
+        it('defaults to status 204 when no response is specified', () => {
             const root = opRoot([opRoute('/users', [opOperation('get')])]);
             const output = generateOp(root);
-            expect(output).toContain('ctx.status = 200');
+            // Nothing is emitted, so there is no body to send; 204 says that precisely, and it is
+            // what the SDK's `Promise<void>` for the same operation already means.
+            expect(output).toContain('ctx.status = 204');
+        });
+
+        it('returns 204 rather than an error status when only a 4xx is declared', () => {
+            const root = opRoot([opRoute('/users', [opOperation('delete', { responses: [opResponse(400)] })])]);
+            const output = generateOp(root);
+            // A bare `400:` is documentation — something else produces it. Falling back to the
+            // first declared status wrote 400 on the success path.
+            expect(output).toContain('ctx.status = 204');
+            expect(output).not.toContain('ctx.status = 400');
         });
 
         // ─── Which statuses the service produces ─────────────────────────
@@ -1345,7 +1360,7 @@ describe('generateOperation', () => {
         it('includes source location in JSDoc above handler', () => {
             const root = opRoot([opRoute('/users', [opOperation('get', { loc: { file: 'users.op', line: 3 } })])], 'users.op');
             const output = generateOp(root);
-            expect(output).toContain('file://./users.op#L3');
+            expect(output).toContain('[users.op](./users.op#L3)');
         });
     });
 
@@ -1369,7 +1384,7 @@ describe('generateOperation', () => {
             const root = opRoot([opRoute('/users', [opOperation('get')])]);
             const output = generateOp(root);
             expect(output).toContain('/**');
-            expect(output).toContain('file://');
+            expect(output).toMatch(/ \* from \[[^\]]+\]\(\.\/[^)]+#L\d+\)/);
         });
     });
 
@@ -1622,3 +1637,48 @@ describe('generateOp — route modifiers JSDoc', () => {
         });
     });
 });
+
+// ─── Hyphenated path parameters ───────────────────────────────────────────
+
+describe('generateOperation — path parameter names that are not identifiers', () => {
+    const root = () =>
+        opRoot([
+            opRoute(
+                '/invoices/{invoice-id}',
+                [opOperation('get', { service: 'InvoiceService.getById', responses: [opResponse(200, 'Invoice', 'application/json')] })],
+                [opParam('invoice-id', scalarType('uuid'))],
+            ),
+        ]);
+
+    it('registers a Koa pattern with a bindable name', () => {
+        const out = generateOp(root());
+        // Previously `{invoice-id}` survived verbatim, so the route was a literal path that no
+        // real request could ever match. The name is internal — Koa matches by position — so
+        // renaming it costs nothing on the wire.
+        expect(out).toContain("get('/invoices/:invoiceId'");
+        expect(out).not.toContain('{invoice-id}');
+    });
+
+    it('keys the params schema by the same name, since that is what ctx.params carries', () => {
+        const out = generateOp(root());
+        expect(out).toContain('const { invoiceId } = await parseAndValidate(');
+        expect(out).toContain('invoiceId: z.uuid()');
+        expect(out).toContain('service.getById(invoiceId)');
+    });
+
+    it('leaves query and header names alone, which the client actually sends', () => {
+        const out = generateOp(
+            opRoot([
+                opRoute('/things', [
+                    opOperation('get', {
+                        query: [opParam('sort-by', scalarType('string'))],
+                        headers: [opParam('x-api-key', scalarType('string'))],
+                        responses: [opResponse(200, 'Thing', 'application/json')],
+                    }),
+                ]),
+            ]),
+        );
+        expect(out).toContain("'sort-by': z.string()");
+        expect(out).toContain("'x-api-key': z.string()");
+    });
+});