@contractkit/plugin-typescript 0.33.3 → 0.34.1

package/dist/path-utils.d.ts

@@ -1,5 +1,14 @@
 import type { ContractRootNode, OpRootNode } from '@contractkit/core';
 export declare const TEMPLATE_VAR_RE: RegExp;
+/** Global-flagged twin of {@link TEMPLATE_VAR_RE}, for finding every variable in a string. */
+export declare const TEMPLATE_VAR_RE_G: RegExp;
+/**
+ * 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 declare function resolveTemplate(template: string, vars: Record<string, string>): string;
 export declare function includesFilename(p: string): boolean;
 export declare function commonDir(files: string[], rootDir: string): string;

package/dist/path-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGtE,eAAO,MAAM,eAAe,QAAY,CAAC;AAmBzC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEtF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAclE;AAID,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAiBR;AAED,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAER;AAID,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAkBf;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBnH;AAED,wBAAgB,qBAAqB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAiBnG;AAED,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,UAAU,EAAE,EACpB,YAAY,EAAE,gBAAgB,EAAE,EAChC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,gBAAgB,GAAE,GAAG,CAAC,MAAM,CAAa,GAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CA0CpB"}
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGtE,eAAO,MAAM,eAAe,QAAY,CAAC;AAmBzC,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QAAe,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEtF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAclE;AAID,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAiBR;AAED,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,CAER;AAID,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAkBf;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBnH;AAED,wBAAgB,qBAAqB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAiBnG;AAED,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,UAAU,EAAE,EACpB,YAAY,EAAE,gBAAgB,EAAE,EAChC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,gBAAgB,GAAE,GAAG,CAAC,MAAM,CAAa,GAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CA0CpB"}

package/dist/ts-render.d.ts

@@ -9,6 +9,20 @@ export declare function quoteKey(name: string): string;
 export declare function escapeJsDocLines(text: string): string[];
 /** Escape a string for inclusion inside a single-quoted TypeScript string literal. */
 export declare function escapeSingleQuoted(s: string): string;
+/**
+ * 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 declare function sourceLink(label: string, outPath: string | undefined, sourceFile: string, line?: number): string;
 /** Convert an HTTP header name (e.g. `preference-applied`, `X-Request-ID`, `ETag`) to camelCase for use as a JS property. */
 export declare function headerNameToProperty(name: string): string;
 /**

package/dist/ts-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-render.d.ts","sourceRoot":"","sources":["../src/ts-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAA6B,MAAM,mBAAmB,CAAC;AAErF,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,2GAA2G,CAAC;AAE7I,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;sFAEsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvD;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAID;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CAoC9F;AAsDD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CA2BlI;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CA2BpI"}
+{"version":3,"file":"ts-render.d.ts","sourceRoot":"","sources":["../src/ts-render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAA6B,MAAM,mBAAmB,CAAC;AAErF,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,2GAA2G,CAAC;AAE7I,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;sFAEsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvD;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAIhH;AAED,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAID;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CAoC9F;AA4DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CA2BlI;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CA2BpI"}

package/llms.txt

@@ -82,6 +82,20 @@ Options worth knowing:
   schema for argument validation and `z.toJSONSchema`. It falls back to `server.output.types` (when
   `server.zod`) or the `zod` sub-config's output.
 
+## Wiring the MCP tools
+
+`mcp.tools.ts` exports `registerMcpTools(container)`, which **builds and returns** the
+`McpToolHandlerMap`. It registers nothing: `register` belongs to InjectKit's `Registry`
+(composition phase), while a `Container` (resolution phase) only resolves. Bind the aggregator from
+a factory, which is also what supplies the `Container` it needs:
+
+```typescript
+registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();
+```
+
+The emitted tool classes are not registered for you either, so register each one on the same
+`Registry` before the aggregator resolves it.
+
 ## Programmatic use
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.33.3",
+  "version": "0.34.1",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {
@@ -27,9 +27,10 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.28.2"
+    "@contractkit/core": "0.29.0"
   },
   "devDependencies": {
+    "zod": "^4.3.6",
     "@repo/config-eslint": "0.3.1",
     "@repo/config-typescript": "0.1.0"
   },

package/src/codegen-contract.ts

@@ -21,10 +21,10 @@ import {
     computeModelsWithOutput as ckComputeModelsWithOutput,
     collectExternalOutputRefs as ckCollectExternalOutputRefs,
 } from '@contractkit/core';
-import { escapeJsDocLines } from './ts-render.js';
+import { escapeJsDocLines, sourceLink } from './ts-render.js';
 import type { TsRenderTarget } from './ts-render.js';
 import { DECIMAL_IMPORT, DECIMAL_PRELUDE_LINES } from './decimal-runtime.js';
-import { renderReviveFunctions, reviveFnName, DECIMAL_COERCE_DECL } from './codegen-revive.js';
+import { renderReviveFunctions, reviveFnName, coerceDeclsFor } from './codegen-revive.js';
 
 /**
  * Maps a ContractKit object mode to its Zod constructor name.
@@ -57,9 +57,9 @@ export interface ContractCodegenContext {
     /** If set, import JsonValue from this path instead of re-declaring it (avoids barrel re-export conflicts) */
     jsonValueImportPath?: string;
     /**
-     * Runtime the emitted plain types describe. Only affects scalars whose TypeScript type differs
-     * per runtime (`binary` → `Buffer` on the server, `Blob` in the client). Ignored by
-     * `generateContract`, whose Zod schemas are server-shaped by construction. Default `'client'`.
+     * Runtime the emitted types describe. Only affects scalars whose TypeScript type differs per
+     * runtime: `binary` is a `Buffer` on a Node server and a `Blob` in a fetch client, and
+     * `_ZodBinary` is generated to match. Default `'client'`.
      */
     target?: TsRenderTarget;
     /** Model names that carry a `decimal`, directly or transitively. */
@@ -128,8 +128,7 @@ function generateComments(model: ModelNode, outPath?: string): string[] {
         for (const l of escapeJsDocLines(model.description)) lines.push(` * ${l}`);
     }
 
-    const relPath = outPath ? relative(dirname(outPath), model.loc.file) : model.loc.file;
-    lines.push(` * generated from [${model.name}](file://./${relPath}#L${model.loc.line})`);
+    lines.push(` * generated from ${sourceLink(model.name, outPath, model.loc.file, model.loc.line)}`);
     lines.push('*/');
     return lines;
 }
@@ -137,8 +136,10 @@ function generateComments(model: ModelNode, outPath?: string): string[] {
 /**
  * Generate a TypeScript module containing Zod schemas for every model in `root`.
  *
- * Emits up to three schemas per model when visibility modifiers are present:
- * `ModelBase` (all fields), `Model` (read — no writeonly), `ModelInput` (write — no readonly).
+ * Emits two schemas per model when visibility modifiers are present: `Model` (read — no
+ * writeonly fields) and `ModelInput` (write — no readonly fields). Writeonly inheritance rides
+ * on the Input chain, since a child's `Input` extends its parent's `Input`, which already carries
+ * the parent's writeonly fields.
  *
  * @param root - The parsed contract root node.
  * @param context - Optional cross-file context for import resolution and Input/Output variant tracking.
@@ -187,7 +188,15 @@ export function generateContract(root: ContractRootNode, context?: ContractCodeg
     }
     lines.push('');
     if (needsBinary) {
-        lines.push(`const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`);
+        // The one scalar with no single correct runtime type, so it follows `target` here exactly
+        // as `renderTsScalar` does. An SDK type file reaching this through the shared
+        // `generateContract` used to emit `Buffer.isBuffer` into a browser client, whose scaffold
+        // declares no `@types/node` — the type did not resolve and the check could not run.
+        lines.push(
+            context?.target === 'server'
+                ? `const _ZodBinary = z.custom<Buffer>((val) => Buffer.isBuffer(val), { error: 'Must be binary data' });`
+                : `const _ZodBinary = z.custom<Blob>((val) => val instanceof Blob, { error: 'Must be binary data' });`,
+        );
     }
     if (needsDatetime) {
         lines.push(
@@ -210,9 +219,9 @@ export function generateContract(root: ContractRootNode, context?: ContractCodeg
     }
     if (needsBinary || needsDatetime || needsInterval || needsDecimal || needsJson) lines.push('');
 
-    const modelsWithWriteonly = new Set(root.models.filter(m => m.fields.some(f => f.visibility === 'writeonly')).map(m => m.name));
     const modelMap = new Map(root.models.map(m => [m.name, m]));
 
+
     const reviveOpts =
         context?.emitRevivers && context.modelsWithDecimal
             ? { modelsWithDecimal: context.modelsWithDecimal, modelsWithOutput: allModelsWithOutput, modelMap }
@@ -220,7 +229,7 @@ export function generateContract(root: ContractRootNode, context?: ContractCodeg
 
     const bodyLines: string[] = [];
     for (const model of topoSortModels(root.models)) {
-        bodyLines.push(...generateModel(model, context?.currentOutPath, allModelsWithInput, modelsWithWriteonly, modelMap, allModelsWithOutput));
+        bodyLines.push(...generateModel(model, context?.currentOutPath, allModelsWithInput, modelMap, allModelsWithOutput));
         if (reviveOpts) {
             const revivers = renderReviveFunctions(model, reviveOpts);
             if (revivers.length > 0) {
@@ -232,9 +241,10 @@ export function generateContract(root: ContractRootNode, context?: ContractCodeg
     }
 
     // Decided from the emitted revivers rather than from a predicate over the AST, so the
-    // declaration and its uses cannot drift apart and leave an unused local behind.
-    if (bodyLines.some(l => l.includes('__dec('))) {
-        lines.push(...DECIMAL_COERCE_DECL);
+    // declarations and their uses cannot drift apart and leave an unused local behind.
+    const coerceDecls = coerceDeclsFor(bodyLines);
+    if (coerceDecls.length > 0) {
+        lines.push(...coerceDecls);
         lines.push('');
     }
     lines.push(...bodyLines);
@@ -282,7 +292,6 @@ function generateModel(
     model: ModelNode,
     outPath?: string,
     modelsWithInput?: Set<string>,
-    modelsWithWriteonly?: Set<string>,
     modelMap?: Map<string, ModelNode>,
     modelsWithOutput?: Set<string>,
 ): string[] {
@@ -298,7 +307,7 @@ function generateModel(
     const needsInputSplit = effective.fields.some(f => f.visibility !== 'normal') || (modelsWithInput?.has(effective.name) ?? false);
 
     const lines = needsInputSplit
-        ? generateThreeSchemaModel(effective, outPath, modelsWithInput, modelsWithWriteonly, modelMap)
+        ? generateThreeSchemaModel(effective, outPath, modelsWithInput, modelMap)
         : generateSimpleModel(effective, outPath);
 
     // Emit Output type alias when this model (transitively) has format(output=...)
@@ -418,7 +427,6 @@ function generateThreeSchemaModel(
     model: ModelNode,
     outPath?: string,
     modelsWithInput?: Set<string>,
-    modelsWithWriteonly?: Set<string>,
     modelMap?: Map<string, ModelNode>,
 ): string[] {
     const lines: string[] = [];
@@ -429,25 +437,9 @@ function generateThreeSchemaModel(
     const wrapper = modeToWrapper(model.mode ?? 'strict');
 
     const allFields = model.fields;
-    const hasWriteonly = allFields.some(f => f.visibility === 'writeonly');
 
     const bases = model.bases ?? [];
 
-    // Base schema — all fields (used internally when a submodel extends this one).
-    // Only needed when this model has writeonly fields; otherwise Base === Read.
-    if (hasWriteonly) {
-        const baseBody = renderFields(allFields, model.mode);
-        if (bases.length > 0) {
-            const { head, tail } = buildExtendChain(bases, b => (modelsWithWriteonly?.has(b) ? `${b}Base` : b));
-            lines.push(`const ${name}Base = ${head}${tail}.extend({`);
-        } else {
-            lines.push(`const ${name}Base = ${wrapper}({`);
-        }
-        lines.push(...baseBody.map(l => `    ${l}`));
-        lines.push(`});`);
-        lines.push('');
-    }
-
     // Read schema — omit writeonly fields; extends parent read schema
     const readFields = allFields.filter(f => f.visibility !== 'writeonly');
     const readBody = renderFields(readFields, model.mode);
@@ -555,12 +547,20 @@ function renderFieldsAsSnakeCase(fields: FieldNode[], defaultMode?: ObjectMode):
     });
 }
 
-function renderField(field: FieldNode, defaultMode?: ObjectMode): string[] {
-    const lines: string[] = [];
-    if (field.deprecated) lines.push('/** @deprecated */');
-
-    let expr = renderType(field.type, undefined, defaultMode);
-
+/**
+ * Append the modifier chain a declared field carries: nullability, then a default or optionality,
+ * then the description.
+ *
+ * Takes a structural subset of `FieldNode` rather than the node itself, so an `OpParamNode` — which
+ * is a `FieldNode` minus `visibility`, `deprecated` and `override` — can be rendered through the
+ * same path. That is what lets the router, the SDK and OpenAPI agree on what an inline `query:` or
+ * `headers:` field means.
+ *
+ * A default and `optional` are mutually exclusive on purpose: `.default()` already makes the input
+ * side optional, and adding `.optional()` on top would widen the *output* type to include
+ * `undefined`, which is exactly what a default exists to prevent.
+ */
+export function applyFieldModifiers(expr: string, field: Pick<FieldNode, 'nullable' | 'default' | 'optional' | 'description'>): string {
     if (field.nullable) expr += '.nullable()';
     if (field.default !== undefined) {
         const dv = typeof field.default === 'string' ? `"${escapeString(field.default)}"` : String(field.default);
@@ -569,6 +569,16 @@ function renderField(field: FieldNode, defaultMode?: ObjectMode): string[] {
         expr += '.optional()';
     }
     if (field.description) expr += `.describe("${escapeString(field.description)}")`;
+    return expr;
+}
+
+function renderField(field: FieldNode, defaultMode?: ObjectMode): string[] {
+    const lines: string[] = [];
+    if (field.deprecated) lines.push('/** @deprecated */');
+
+    let expr = renderType(field.type, undefined, defaultMode);
+
+    expr = applyFieldModifiers(expr, field);
 
     lines.push(`${quoteKey(field.name)}: ${expr},`);
     return lines;
@@ -641,6 +651,21 @@ function regexHasAnchor(source: string): boolean {
     return backslashes % 2 === 0;
 }
 
+/**
+ * Coercion for the numeric scalars: convert a non-empty string, pass everything else through for
+ * `z.number()` to judge.
+ *
+ * `z.coerce.number()` is `Number(v)`, which accepts far more than a number. `[]` and `''` become
+ * `0`, `null` becomes `0`, `true` becomes `1` — so `{"quantity": []}` validated as `0` and the
+ * handler ran on a value the client never sent. Only the string case is a real coercion; it exists
+ * because query strings and headers arrive as text, and it stays because a JSON body carrying
+ * `"42"` is common enough that rejecting it would break working callers.
+ *
+ * The `boolean` scalar below already has this shape and needed no change: its preprocess maps only
+ * the two literal strings and hands everything else to `z.boolean()`, which rejects it.
+ */
+const NUMERIC_PREPROCESS = `(v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v)`;
+
 function renderScalar(s: ScalarTypeNode): string {
     switch (s.name) {
         case 'string': {
@@ -652,17 +677,14 @@ function renderScalar(s: ScalarTypeNode): string {
             if (s.regex) e += `.regex(${renderRegexLiteral(s.regex)})`;
             return e;
         }
-        case 'number': {
-            let e = 'z.coerce.number()';
-            if (s.min !== undefined) e += `.min(${s.min})`;
-            if (s.max !== undefined) e += `.max(${s.max})`;
-            return e;
-        }
+        case 'number':
         case 'int': {
-            let e = 'z.coerce.number().int()';
-            if (s.min !== undefined) e += `.min(${s.min})`;
-            if (s.max !== undefined) e += `.max(${s.max})`;
-            return e;
+            // Constraints go on the inner schema, not the outer expression: `z.preprocess` returns
+            // a ZodPipe, which has no `.min()`. Same shape as the `bigint` case below.
+            let inner = s.name === 'int' ? 'z.number().int()' : 'z.number()';
+            if (s.min !== undefined) inner += `.min(${s.min})`;
+            if (s.max !== undefined) inner += `.max(${s.max})`;
+            return `z.preprocess(${NUMERIC_PREPROCESS}, ${inner})`;
         }
         case 'bigint': {
             let inner = 'z.bigint()';
@@ -848,8 +870,16 @@ function renderInlineObject(o: InlineObjectTypeNode, parseCaseTransform?: 'snake
 // ─── Input type rendering ─────────────────────────────────────────────────
 
 /**
- * Like renderScalar, but coerces from string input (JSON wire format).
- * Used for Input (write) schemas where data arrives as JSON strings.
+ * The request-side rendering of a scalar. A pure passthrough today, and the seam where a genuine
+ * input/wire split would live.
+ *
+ * The docstring here used to claim it "coerces from string input", describing a distinction the
+ * body does not make: `XInput` is a single exported `const`, and `generateParamValidation`'s ref
+ * branch uses that same schema for `query: X` that the body path uses for
+ * `request: { application/json: X }`. Making it strict would break query-by-model; leaving it
+ * coercing leaves a JSON body accepting string-shaped numbers. A real split needs a second emitted
+ * variant (`XInputWire`) plus the import plumbing to reach it, which is separate work — the
+ * narrowed coercion in `renderScalar` closes the soundness hole in the meantime.
  */
 function renderInputScalar(s: ScalarTypeNode): string {
     return renderScalar(s);
@@ -924,14 +954,7 @@ function renderInputField(field: FieldNode, modelsWithInput: Set<string>, defaul
 
     let expr = renderInputType(field.type, modelsWithInput, defaultMode);
 
-    if (field.nullable) expr += '.nullable()';
-    if (field.default !== undefined) {
-        const dv = typeof field.default === 'string' ? `"${escapeString(field.default)}"` : String(field.default);
-        expr += `.default(${dv})`;
-    } else if (field.optional) {
-        expr += '.optional()';
-    }
-    if (field.description) expr += `.describe("${escapeString(field.description)}")`;
+    expr = applyFieldModifiers(expr, field);
 
     lines.push(`${quoteKey(field.name)}: ${expr},`);
     return lines;
@@ -996,14 +1019,7 @@ function renderQueryField(field: FieldNode, modelsWithInput?: Set<string>, defau
               ? renderInputType(field.type, modelsWithInput, defaultMode)
               : renderType(field.type, undefined, defaultMode);
 
-    if (field.nullable) expr += '.nullable()';
-    if (field.default !== undefined) {
-        const dv = typeof field.default === 'string' ? `"${escapeString(field.default)}"` : String(field.default);
-        expr += `.default(${dv})`;
-    } else if (field.optional) {
-        expr += '.optional()';
-    }
-    if (field.description) expr += `.describe("${escapeString(field.description)}")`;
+    expr = applyFieldModifiers(expr, field);
 
     return `${quoteKey(field.name)}: ${expr},`;
 }

package/src/codegen-mcp.ts

@@ -1,8 +1,8 @@
 import type { OpRootNode, OpRouteNode, OpOperationNode, McpConfigNode, ParamSource, ContractTypeNode } from '@contractkit/core';
-import { resolveModifiers, emittedResponses } from '@contractkit/core';
+import { resolveModifiers, emittedResponses, toIdentifier } from '@contractkit/core';
 import { renderType, renderInputType, pascalToDotCase } from './codegen-contract.js';
 import { inferService, deriveModulePath, buildArgs, deriveBaseName } from './codegen-operation.js';
-import { quoteKey, escapeSingleQuoted } from './ts-render.js';
+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';
 
@@ -110,7 +110,9 @@ function buildArgsProps(route: OpRouteNode, op: OpOperationNode, modelsWithInput
     if (route.params) {
         if (route.params.kind === 'params') {
             for (const node of route.params.nodes) {
-                props.push({ key: node.name, expr: renderInputType(node.type, modelsWithInput), optional: false });
+                // The handler destructures these, so the key has to be a valid identifier. The MCP
+                // input schema is ours to name — nothing on an HTTP wire depends on it.
+                props.push({ key: toIdentifier(node.name), expr: renderInputType(node.type, modelsWithInput), optional: false });
             }
         } else if (route.params.kind === 'ref') {
             props.push({ key: 'params', expr: refSchema(route.params.name, modelsWithInput), optional: false });
@@ -337,9 +339,8 @@ function renderToolClass(plan: ToolPlan, file: string, options: McpCodegenOption
     const lines: string[] = [];
 
     // JSDoc source link
-    const relFile = options.outPath ? relative(dirname(options.outPath), file) : file;
     lines.push('/**');
-    lines.push(` * from [${basename(file)}](file://./${relFile}#L${op.loc.line})`);
+    lines.push(` * from ${sourceLink(basename(file), options.outPath, file, op.loc.line)}`);
     lines.push(' */');
 
     lines.push('@Injectable()');
@@ -371,7 +372,10 @@ function renderToolClass(plan: ToolPlan, file: string, options: McpCodegenOption
     const isVoid = !primaryResponseBody(op);
     const structured = !!outExpr;
 
-    lines.push('    async handle(args: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {');
+    // No args to destructure means the parameter goes unread, which trips no-unused-vars in
+    // consumers that lint generated output; the leading underscore opts it out.
+    const argsParam = destructure.length > 0 ? 'args' : '_args';
+    lines.push(`    async handle(${argsParam}: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {`);
     if (destructure.length > 0) {
         lines.push(`        const { ${destructure.join(', ')} } = await parseAndValidate(args, ${argsConstName});`);
     }
@@ -455,8 +459,7 @@ export function generateMcpFile(root: OpRootNode, options: McpCodegenOptions = {
     // Schema imports.
     imports.push(...schemaImportLines(collectSchemaIds(plans, options.modelsWithInput), options));
 
-    const relFile = options.outPath ? relative(dirname(options.outPath), root.file) : root.file;
-    const header = `// Auto-generated MCP tools\n// generated from [${basename(root.file)}](file://./${relFile})`;
+    const header = `// Auto-generated MCP tools\n// generated from ${sourceLink(basename(root.file), options.outPath, root.file)}`;
 
     return `${header}\n${imports.join('\n')}\n\n${bodyWithHelpers}\n`;
 }
@@ -477,11 +480,19 @@ export function generateMcpAggregator(entries: McpAggregatorEntry[]): string {
     lines.push(`import { McpToolHandlerMap } from '@maroonedsoftware/mcp';`);
     for (const e of sorted) lines.push(`import { ${e.registerFn} } from '${e.importPath}';`);
     lines.push('');
-    lines.push('/** Build + register the MCP tool catalog. Call once at startup. */');
+    lines.push('/**');
+    lines.push(' * Build the MCP tool catalog.');
+    lines.push(' *');
+    lines.push(' * Bind it to the `McpToolHandlerMap` token from a factory, which is what supplies the');
+    lines.push(' * `Container` needed to resolve each handler:');
+    lines.push(' *');
+    lines.push(' * ```ts');
+    lines.push(' * registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();');
+    lines.push(' * ```');
+    lines.push(' */');
     lines.push('export function registerMcpTools(container: Container): McpToolHandlerMap {');
     lines.push('    const map = new McpToolHandlerMap();');
     for (const e of sorted) lines.push(`    ${e.registerFn}(map, container);`);
-    lines.push('    container.register(McpToolHandlerMap, { useValue: map });');
     lines.push('    return map;');
     lines.push('}');
     return lines.join('\n') + '\n';
@@ -493,7 +504,7 @@ export function generateMcpRouter(options: { path?: string } = {}): string {
     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. Call \`registerMcpTools(container)\` at startup. */
+/** 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);

package/src/codegen-operation.ts

@@ -9,15 +9,16 @@ import type {
     ParamSource,
     ObjectMode,
 } from '@contractkit/core';
-import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType, emittedResponses } from '@contractkit/core';
+import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType, emittedResponses, PATH_PARAM_RE_G, toIdentifier } from '@contractkit/core';
 import {
     renderType,
     renderInputType,
     renderQueryType,
+    applyFieldModifiers,
     pascalToDotCase,
     modeToWrapper,
 } from './codegen-contract.js';
-import { renderOutputTsType, quoteKey, headerNameToProperty, escapeJsDocLines, escapeSingleQuoted } from './ts-render.js';
+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';
 
@@ -174,8 +175,7 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
 
     lines.push('');
     lines.push('/**');
-    const relFile = options.outPath ? relative(dirname(options.outPath), root.file) : root.file;
-    lines.push(` * generated from [${basename(root.file)}](file://./${relFile})`);
+    lines.push(` * generated from ${sourceLink(basename(root.file), options.outPath, root.file)}`);
     lines.push('*/');
     lines.push(`export const ${routerName} = ServerKitRouter();`);
     lines.push('');
@@ -294,8 +294,7 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
         for (const l of escapeJsDocLines(desc)) lines.push(` * ${l}`);
     }
     // Source location comment
-    const relFile = outPath ? relative(dirname(outPath), file) : file;
-    lines.push(` * from [${basename(file)}](file://./${relFile}#L${op.loc.line})`);
+    lines.push(` * from ${sourceLink(basename(file), outPath, file, op.loc.line)}`);
 
     // Security annotation (operation-level wins; falls back to route → file level)
     const effectiveSecurity = resolveSecurity(route, op, root);
@@ -311,7 +310,10 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     lines.push('*/');
 
     const method = op.method;
-    const path = route.path.replace(/\{(\w+)\}/g, ':$1');
+    // `: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)}`);
     const bodies = op.request?.bodies ?? [];
     const hasBody = bodies.length > 0;
     const isSingleMultipart = bodies.length === 1 && bodies[0]!.contentType === 'multipart/form-data';
@@ -449,9 +451,12 @@ function generateSingleStatusResult(
     }
 
     lines.push('');
-    // With nothing emitted, the status is still declared somewhere — fall back to the first
-    // one written, which is what a documentation-only 3xx/4xx operation means.
-    lines.push(`    ctx.status = ${resp?.statusCode ?? op.responses[0]?.statusCode ?? 200};`);
+    // 204 when the operation emits nothing. Falling back to the first *declared* status wrote an
+    // error code on the success path, since a documentation-only block starts at a 4xx. 204 is
+    // 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, '    '));
 
     if (bodies.length === 1) {
@@ -627,7 +632,7 @@ export function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
     // Path params: spread individually (inline) or pass 'params' object (type-ref/ContractTypeNode)
     if (route.params) {
         if (route.params.kind === 'params') {
-            args.push(...route.params.nodes.map(p => p.name));
+            args.push(...route.params.nodes.map(p => toIdentifier(p.name)));
         } else {
             args.push('params');
         }
@@ -803,18 +808,26 @@ function generateParamValidation(
         if (source.nodes.length > 0) {
             // Destructure only for params (spread individually in service call);
             // query/headers are passed as whole objects.
-            const lhs = varName === 'params' ? `{ ${source.nodes.map(p => p.name).join(', ')} }` : varName;
+            // 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;
             lines.push(`    const ${lhs} = await parseAndValidate(`);
             lines.push(`        ${ctxExpr},`);
             lines.push(`        ${modeToWrapper(mode)}({`);
             for (const param of source.nodes) {
-                const key = isValidIdentifier(param.name) ? param.name : `'${param.name}'`;
-                if (isQuery && param.type.kind === 'array') {
-                    const inner = renderType(param.type);
-                    lines.push(`            ${key}: z.preprocess((v) => typeof v === 'string' ? v.split(',') : v, ${inner}),`);
-                } else {
-                    lines.push(`            ${key}: ${renderType(param.type)},`);
-                }
+                // 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.
+                const bound = bind(param.name);
+                const key = isValidIdentifier(bound) ? bound : `'${bound}'`;
+                // Delegating to renderQueryType rather than hand-rolling the array preprocess here:
+                // it is the same rule, and a second copy is a second thing to keep in sync. The
+                // modifier chain then comes from the shared helper, so an inline param means the
+                // same thing to the router as a model field does.
+                const base = isQuery ? renderQueryType(param.type, modelsWithInput) : renderInputType(param.type, modelsWithInput);
+                lines.push(`            ${key}: ${applyFieldModifiers(base, param)},`);
             }
             lines.push(`        })${suffix},`);
             lines.push(`    );`);