@contractkit/plugin-typescript 0.28.0 → 0.28.2

package/src/codegen-operation.ts

@@ -9,7 +9,7 @@ import {
     typeNeedsScalar,
     modeToWrapper,
 } from './codegen-contract.js';
-import { renderOutputTsType, quoteKey, headerNameToProperty } from './ts-render.js';
+import { renderOutputTsType, quoteKey, headerNameToProperty, escapeJsDocLines, escapeSingleQuoted } from './ts-render.js';
 import { basename, dirname, relative } from 'path';
 
 // ─── Content-type helpers ──────────────────────────────────────────────────
@@ -107,6 +107,7 @@ export function bodyTypesStructurallyEqual(a: ContractTypeNode, b: ContractTypeN
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
+/** Options controlling how {@link generateOp} renders a Koa router module. */
 export interface OpCodegenOptions {
     servicePathTemplate?: string;
     typeImportPathTemplate?: string;
@@ -217,7 +218,7 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     // JSDoc from description
     const desc = op.description ?? route.description;
     if (desc) {
-        lines.push(` * ${desc}`);
+        for (const l of escapeJsDocLines(desc)) lines.push(` * ${l}`);
     }
     // Source location comment
     const relFile = outPath ? relative(dirname(outPath), file) : file;
@@ -261,13 +262,13 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     }
     if (op.signature) {
         const sigArgs = op.signaturePolicy
-            ? `'${op.signature}', { policy: '${op.signaturePolicy}' }`
-            : `'${op.signature}'`;
+            ? `'${escapeSingleQuoted(op.signature)}', { policy: '${escapeSingleQuoted(op.signaturePolicy)}' }`
+            : `'${escapeSingleQuoted(op.signature)}'`;
         middlewares.push(`requireSignature(${sigArgs})`);
     }
     const middlewareStr = middlewares.length > 0 ? `, ${middlewares.join(', ')},` : ',';
 
-    lines.push(`${deriveRouterName(file)}.${method}('${path}'${middlewareStr} async (ctx, next) => {`);
+    lines.push(`${deriveRouterName(file)}.${method}('${path}'${middlewareStr} async ctx => {`);
 
     // Params / query / headers validation (request-side — use Input variants)
     lines.push(...generateParamValidation(route.params, 'ctx.params', 'params', route.paramsMode ?? 'strict', '', modelsWithInput));
@@ -368,7 +369,16 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
 
 // ─── Inference helpers ─────────────────────────────────────────────────────
 
-function inferService(op: OpOperationNode, route: OpRouteNode, file: string): { className: string; methodName: string } {
+/**
+ * Resolve the service class and method a handler should delegate to.
+ *
+ * Uses the operation's explicit `service: Class.method` declaration when present; otherwise derives
+ * the class from the contract file name (`ledger.categories.ck` → `LedgerCategoriesService`) and the
+ * method from the HTTP verb and whether the path carries a parameter (`get` → `list` / `getById`).
+ *
+ * @param file Path of the `.ck` file the operation came from.
+ */
+export function inferService(op: OpOperationNode, route: OpRouteNode, file: string): { className: string; methodName: string } {
     // If explicitly declared: service: ServiceClass.methodName
     if (op.service) {
         const [cls = '', method] = op.service.split('.');
@@ -400,7 +410,16 @@ function inferMethodName(method: string, path: string): string {
     }
 }
 
-function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
+/**
+ * Build the comma-separated argument list passed to the service method in a generated handler.
+ *
+ * Order is params, body, query, headers. Inline path params are spread as individual identifiers;
+ * a referenced/compound params type is passed as a single `params` object. A lone
+ * `multipart/form-data` request body is passed as `multipartBody` rather than `body`.
+ *
+ * @returns The rendered argument list, or an empty string when the method takes no arguments.
+ */
+export function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
     const args: string[] = [];
     // Path params: spread individually (inline) or pass 'params' object (type-ref/ContractTypeNode)
     if (route.params) {
@@ -792,7 +811,13 @@ function isValidIdentifier(name: string): boolean {
 
 // ─── Naming conventions ────────────────────────────────────────────────────
 
-function deriveBaseName(file: string): string {
+/**
+ * Derive the PascalCase base name used for router, service, and type names from a contract file path.
+ *
+ * Strips directories and the `.op`/`.ck` extension, then PascalCases each dot-separated segment
+ * (`contracts/ledger.categories.ck` → `LedgerCategories`). Falls back to `Resource` for an empty path.
+ */
+export function deriveBaseName(file: string): string {
     const base =
         file
             .split('/')
@@ -809,7 +834,16 @@ function deriveRouterName(file: string): string {
     return `${deriveBaseName(file)}Router`;
 }
 
-function deriveModulePath(serviceName: string, template?: string): string {
+/**
+ * Resolve the import specifier for a service class.
+ *
+ * Drops the trailing `Service` suffix and kebab-cases the remainder, then applies `template` if given
+ * (`{name}` → `Ledger`, `{kebab}` → `ledger`). Without a template, defaults to
+ * `#modules/<kebab>/<kebab>.service.js`.
+ *
+ * @param template Optional `servicePathTemplate` from the plugin config.
+ */
+export function deriveModulePath(serviceName: string, template?: string): string {
     // LedgerService -> #modules/ledger/ledger.service.js
     const base = serviceName.replace(/Service$/, '');
     const kebab = base.replace(/([A-Z])/g, m => `-${m.toLowerCase()}`).replace(/^-/, '');

package/src/codegen-plain-types.ts

@@ -10,7 +10,7 @@ import {
     resolveImportPath,
     rootNeedsScalar,
 } from './codegen-contract.js';
-import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, JSON_VALUE_TYPE_DECL } from './ts-render.js';
+import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJsDocLines, JSON_VALUE_TYPE_DECL } from './ts-render.js';
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
@@ -123,7 +123,7 @@ function generateComments(model: ModelNode, outPath?: string): string[] {
         lines.push(` * @deprecated`);
     }
     if (model.description) {
-        lines.push(` * ${model.description}`);
+        for (const l of escapeJsDocLines(model.description)) lines.push(` * ${l}`);
     }
 
     const relPath = outPath ? relative(dirname(outPath), model.loc.file) : model.loc.file;
@@ -205,6 +205,18 @@ function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithI
 
 // ─── Field rendering ──────────────────────────────────────────────────────
 
+/** Prefix a field declaration with a JSDoc comment built from `@deprecated` / description parts,
+ *  neutralizing any block-comment terminator and expanding embedded newlines into continuation lines. */
+function withFieldJsDoc(jsdocParts: string[], line: string): string {
+    if (jsdocParts.length === 0) return line;
+    const contentLines = escapeJsDocLines(jsdocParts.join(' '));
+    if (contentLines.length === 1) {
+        return `/** ${contentLines[0]} */\n    ${line}`;
+    }
+    const body = contentLines.map(l => `     * ${l}`).join('\n');
+    return `/**\n${body}\n     */\n    ${line}`;
+}
+
 function renderField(field: FieldNode): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
     let typeStr = renderTsType(field.type);
@@ -213,10 +225,7 @@ function renderField(field: FieldNode): string {
     const jsdocParts: string[] = [];
     if (field.deprecated) jsdocParts.push('@deprecated');
     if (field.description) jsdocParts.push(field.description);
-    if (jsdocParts.length > 0) {
-        return `/** ${jsdocParts.join(' ')} */\n    ${line}`;
-    }
-    return line;
+    return withFieldJsDoc(jsdocParts, line);
 }
 
 function renderInputField(field: FieldNode, modelsWithInput: Set<string>): string {
@@ -227,10 +236,7 @@ function renderInputField(field: FieldNode, modelsWithInput: Set<string>): strin
     const jsdocParts: string[] = [];
     if (field.deprecated) jsdocParts.push('@deprecated');
     if (field.description) jsdocParts.push(field.description);
-    if (jsdocParts.length > 0) {
-        return `/** ${jsdocParts.join(' ')} */\n    ${line}`;
-    }
-    return line;
+    return withFieldJsDoc(jsdocParts, line);
 }
 
 // ─── Output (post-transform wire shape) ──────────────────────────────────
@@ -297,8 +303,5 @@ function renderOutputField(field: FieldNode, outputCase: 'camel' | 'snake' | 'pa
     const jsdocParts: string[] = [];
     if (field.deprecated) jsdocParts.push('@deprecated');
     if (field.description) jsdocParts.push(field.description);
-    if (jsdocParts.length > 0) {
-        return `/** ${jsdocParts.join(' ')} */\n    ${line}`;
-    }
-    return line;
+    return withFieldJsDoc(jsdocParts, line);
 }

package/src/codegen-sdk.ts

@@ -1,6 +1,6 @@
 import type { OpRootNode, OpRouteNode, OpOperationNode, OpRequestBodyNode, ContractTypeNode, ParamSource } from '@contractkit/core';
 import { resolveModifiers, isJsonMime, classifyContentType } from '@contractkit/core';
-import { renderInputTsType, renderOutputTsType, quoteKey, headerNameToProperty, JSON_VALUE_TYPE_DECL } from './ts-render.js';
+import { renderInputTsType, renderOutputTsType, quoteKey, headerNameToProperty, escapeJsDocLines, JSON_VALUE_TYPE_DECL } from './ts-render.js';
 import { pascalToDotCase, typeNeedsScalar } from './codegen-contract.js';
 import { bodyTypesStructurallyEqual } from './codegen-operation.js';
 import { basename, dirname, relative } from 'path';
@@ -289,11 +289,12 @@ function generateMethod(route: OpRouteNode, op: OpOperationNode, file: string, o
         const tags: string[] = [];
         if (op.name) tags.push(`@name ${op.name}`);
         if (desc) tags.push(`@description ${desc}`);
-        if (tags.length === 1) {
-            lines.push(`    /** ${tags[0]} */`);
+        const contentLines = tags.flatMap(t => escapeJsDocLines(t));
+        if (contentLines.length === 1) {
+            lines.push(`    /** ${contentLines[0]} */`);
         } else {
             lines.push(`    /**`);
-            for (const tag of tags) lines.push(`     * ${tag}`);
+            for (const l of contentLines) lines.push(`     * ${l}`);
             lines.push(`     */`);
         }
     }

package/src/index.ts

@@ -41,6 +41,7 @@ import {
     type SdkScaffoldDeps,
 } from './codegen-sdk.js';
 import { generatePlainTypes } from './codegen-plain-types.js';
+import { generateMcpFile, generateMcpAggregator, generateMcpRouter, hasMcpOperations, deriveMcpRegisterFnName } from './codegen-mcp.js';
 import {
     TEMPLATE_VAR_RE,
     resolveTemplate,
@@ -104,11 +105,39 @@ export interface TypesConfig {
     output?: string;
 }
 
+export interface McpConfig {
+    /** Directory (relative to rootDir) where MCP files are written. Default: rootDir. */
+    baseDir?: string;
+    output?: {
+        /** Path template for per-op-file tool handlers. Supports {filename}, {dir}, {area}. Default `{filename}.mcp.ts`. */
+        tools?: string;
+        /** Path (or template) for the aggregator that assembles the McpToolHandlerMap. Default `mcp.tools.ts`. */
+        index?: string;
+        /** Path (or template) for the optional POST /mcp route file. Default `mcp.router.ts`. */
+        router?: string;
+        /**
+         * Path template for the model **Zod schema** files the tools import (for arg validation and
+         * `z.toJSONSchema`). When omitted, falls back to the `server` sub-config's `output.types`
+         * (if `server.zod`) or the `zod` sub-config's output. Tools require Zod schemas, not plain types.
+         */
+        types?: string;
+    };
+    /** Emit the `mcp.router.ts` route boilerplate. Default true. */
+    emitRouter?: boolean;
+    /** Mount path used in the emitted router. Default `/mcp`. */
+    path?: string;
+    /** Import path template for service implementations (same semantics as ServerConfig). */
+    servicePathTemplate?: string;
+    /** Whether to expose operations marked `internal` as MCP tools. Default false. */
+    includeInternal?: boolean;
+}
+
 export interface TypescriptPluginConfig {
     server?: ServerConfig;
     sdk?: SdkConfig;
     zod?: ZodConfig;
     types?: TypesConfig;
+    mcp?: McpConfig;
 }
 
 // ─── Caching constants ─────────────────────────────────────────────────────
@@ -165,6 +194,7 @@ async function runTypescriptCodegen(
     if (config.sdk) collectSdkOutput(config.sdk, rootDir, inputs, units, globalFiles);
     if (config.zod) collectZodOutput(config.zod, rootDir, inputs, units);
     if (config.types) collectTypesOutput(config.types, rootDir, inputs, units);
+    if (config.mcp) collectMcpOutput(config.mcp, config, rootDir, inputs, units, globalFiles);
 
     const result = runIncrementalCodegen({
         codegenVersion: TYPESCRIPT_CODEGEN_VERSION,
@@ -838,6 +868,130 @@ function collectTypesOutput(
     }
 }
 
+// ─── MCP sub-generator ─────────────────────────────────────────────────────
+
+/**
+ * Resolve where the model **Zod schema** files live so the MCP tools can import them (for arg
+ * validation + `z.toJSONSchema`). Precedence: explicit `mcp.output.types` → the `server` sub-config's
+ * `output.types` (only when `server.zod`) → the `zod` sub-config's output. Returns an empty map when
+ * none resolve (imports then fall back to a colocated `./<name>.js` guess).
+ */
+function resolveMcpModelOutPaths(
+    config: TypescriptPluginConfig,
+    rootDir: string,
+    contractRoots: readonly ContractRootNode[],
+    commonRoot: string,
+    modelsWithInput: Set<string>,
+    modelsWithOutput: Set<string>,
+): Map<string, string> {
+    const map = new Map<string, string>();
+    let base: string;
+    let template: string | undefined;
+    let suffix: string;
+    if (config.mcp?.output?.types) {
+        base = resolve(rootDir, config.mcp.baseDir ?? '.');
+        template = config.mcp.output.types;
+        suffix = '.ts';
+    } else if (config.server?.zod && config.server.output?.types) {
+        base = resolve(rootDir, config.server.baseDir ?? '.');
+        template = config.server.output.types;
+        suffix = '.ts';
+    } else if (config.zod) {
+        base = resolve(rootDir, config.zod.baseDir ?? '.');
+        template = config.zod.output;
+        suffix = '.schema.ts';
+    } else {
+        return map;
+    }
+
+    for (const ast of contractRoots) {
+        const outPath = computeContractOutPath(ast.file, base, template, suffix, commonRoot, ast.meta);
+        for (const model of ast.models) {
+            map.set(model.name, outPath);
+            if (modelsWithInput.has(model.name)) map.set(`${model.name}Input`, outPath);
+            if (modelsWithOutput.has(model.name)) map.set(`${model.name}Output`, outPath);
+        }
+    }
+    return map;
+}
+
+function collectMcpOutput(
+    config: McpConfig,
+    fullConfig: TypescriptPluginConfig,
+    rootDir: string,
+    inputs: Parameters<NonNullable<ContractKitPlugin['generateTargets']>>[0],
+    units: IncrementalUnit[],
+    globalFiles: IncrementalOutputFile[],
+): void {
+    const mcpBase = resolve(rootDir, config.baseDir ?? '.');
+    const modelsWithInput = inputs.modelsWithInput as Set<string>;
+    const modelsWithOutput = inputs.modelsWithOutput as Set<string>;
+    const modelMap = buildModelMap(inputs.contractRoots);
+    const allFiles = [...inputs.contractRoots.map(r => r.file), ...inputs.opRoots.map(r => r.file)];
+    const commonRoot = commonDir(allFiles, rootDir);
+    const subConfigKey = stableSubConfig(config);
+    const includeInternal = config.includeInternal ?? false;
+
+    const modelOutPaths = resolveMcpModelOutPaths(fullConfig, rootDir, inputs.contractRoots, commonRoot, modelsWithInput, modelsWithOutput);
+
+    // ── Per-op-root tool-handler units (only files with MCP-exposed ops) ──
+    const entries: { outPath: string; registerFn: string }[] = [];
+    for (const ast of inputs.opRoots) {
+        if (!hasMcpOperations(ast, includeInternal)) continue;
+        const outPath = computeOpOutPath(ast.file, mcpBase, config.output?.tools, '.mcp.ts', commonRoot, ast.meta);
+        const refs = collectOpRootRefs(ast, modelMap);
+        const fingerprint = hashFingerprint({
+            kind: 'mcp-tools',
+            v: TYPESCRIPT_CODEGEN_VERSION,
+            outPath,
+            root: ast,
+            outPathSlice: sliceOutPathMap(refs, modelOutPaths, modelsWithInput, modelsWithOutput),
+            modelsWithInput: sliceModelSet(refs, new Set(), modelsWithInput),
+            modelsWithOutput: sliceModelSet(refs, new Set(), modelsWithOutput),
+            servicePathTemplate: config.servicePathTemplate ?? null,
+            includeInternal,
+            sub: subConfigKey,
+        });
+        units.push({
+            key: `mcp-tools::${outPath}`,
+            fingerprint,
+            render: () => [
+                {
+                    relativePath: outPath,
+                    content: generateMcpFile(ast, {
+                        outPath,
+                        modelOutPaths,
+                        modelsWithInput,
+                        modelsWithOutput,
+                        servicePathTemplate: config.servicePathTemplate,
+                        includeInternal,
+                    }),
+                },
+            ],
+        });
+        entries.push({ outPath, registerFn: deriveMcpRegisterFnName(ast.file) });
+    }
+
+    if (entries.length === 0) return;
+
+    // ── Aggregator (global) ──
+    const indexPath = join(mcpBase, config.output?.index ?? 'mcp.tools.ts');
+    const aggregatorEntries = entries
+        .map(e => {
+            let rel = relative(dirname(indexPath), e.outPath).replace(/\.ts$/, '.js');
+            if (!rel.startsWith('.')) rel = './' + rel;
+            return { registerFn: e.registerFn, importPath: rel };
+        })
+        .sort((a, b) => a.registerFn.localeCompare(b.registerFn));
+    globalFiles.push({ relativePath: indexPath, content: generateMcpAggregator(aggregatorEntries) });
+
+    // ── Router (global, optional) ──
+    if (config.emitRouter !== false) {
+        const routerPath = join(mcpBase, config.output?.router ?? 'mcp.router.ts');
+        globalFiles.push({ relativePath: routerPath, content: generateMcpRouter({ path: config.path }) });
+    }
+}
+
 // ─── Manifest IO + cleanup ─────────────────────────────────────────────────
 
 function readManifest(manifestPath: string): IncrementalManifest {

package/src/path-utils.ts

@@ -1,9 +1,26 @@
-import { resolve, join, relative, dirname } from 'node:path';
+import { resolve, join, relative, dirname, isAbsolute } from 'node:path';
 import type { ContractRootNode, OpRootNode } from '@contractkit/core';
 import { collectTypeRefs, collectPublicTypeNames } from '@contractkit/core';
 
 export const TEMPLATE_VAR_RE = /\{\w+\}/;
 
+/**
+ * Guard against path traversal in output-path templates. Output-path template variables
+ * (`{area}`, `{dir}`, `{filename}`, `{name}`) can be sourced from a `.ck` file's
+ * `options { keys }` block, so a malicious value like `../../../tmp/x` could escape the
+ * plugin's output directory. After the final absolute path is computed, verify it stays
+ * within `baseOutDir`; otherwise throw.
+ */
+function assertWithinBase(baseOutDir: string, outPath: string): string {
+    const rel = relative(resolve(baseOutDir), resolve(outPath));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(
+            `Refusing to emit outside output directory: resolved path "${outPath}" escapes "${baseOutDir}" (check options { keys } values used in output path templates)`,
+        );
+    }
+    return outPath;
+}
+
 export function resolveTemplate(template: string, vars: Record<string, string>): string {
     return template.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
 }
@@ -47,14 +64,14 @@ export function computeOpOutPath(
 
     if (output && TEMPLATE_VAR_RE.test(output)) {
         const resolved = resolveTemplate(output, { filename, dir: relDir, ext: 'ck', ...meta });
-        if (includesFilename(resolved)) return join(baseOutDir, resolved);
-        return join(baseOutDir, resolved, defaultName);
+        if (includesFilename(resolved)) return assertWithinBase(baseOutDir, join(baseOutDir, resolved));
+        return assertWithinBase(baseOutDir, join(baseOutDir, resolved, defaultName));
     }
     if (output) {
-        if (includesFilename(output)) return join(baseOutDir, output);
-        return join(baseOutDir, output, relDir, defaultName);
+        if (includesFilename(output)) return assertWithinBase(baseOutDir, join(baseOutDir, output));
+        return assertWithinBase(baseOutDir, join(baseOutDir, output, relDir, defaultName));
     }
-    return join(baseOutDir, relDir, defaultName);
+    return assertWithinBase(baseOutDir, join(baseOutDir, relDir, defaultName));
 }
 
 export function computeContractOutPath(
@@ -86,14 +103,14 @@ export function computeSdkOutPath(
 
     if (clientOutput && TEMPLATE_VAR_RE.test(clientOutput)) {
         const resolved = resolveTemplate(clientOutput, { filename, dir: relDir, ext: 'ck', ...meta });
-        if (includesFilename(resolved)) return join(baseOutDir, resolved);
-        return join(baseOutDir, resolved, defaultOutName);
+        if (includesFilename(resolved)) return assertWithinBase(baseOutDir, join(baseOutDir, resolved));
+        return assertWithinBase(baseOutDir, join(baseOutDir, resolved, defaultOutName));
     }
     if (clientOutput) {
-        if (includesFilename(clientOutput)) return join(baseOutDir, clientOutput);
-        return join(baseOutDir, clientOutput, relDir, defaultOutName);
+        if (includesFilename(clientOutput)) return assertWithinBase(baseOutDir, join(baseOutDir, clientOutput));
+        return assertWithinBase(baseOutDir, join(baseOutDir, clientOutput, relDir, defaultOutName));
     }
-    return join(baseOutDir, relDir, defaultOutName);
+    return assertWithinBase(baseOutDir, join(baseOutDir, relDir, defaultOutName));
 }
 
 /**
@@ -118,14 +135,14 @@ export function computeSdkAreaClientOutPath(area: string, rootDir: string, clien
     if (clientOutput && TEMPLATE_VAR_RE.test(clientOutput)) {
         const resolved = resolveTemplate(clientOutput, { filename, dir: '', ext: 'ck', area, subarea: '' });
         const cleaned = fixHiddenSegment(resolved.replace(/\/+/g, '/').replace(/^\//, ''));
-        if (includesFilename(cleaned)) return join(baseOutDir, cleaned);
-        return join(baseOutDir, cleaned, `${filename}.client.ts`);
+        if (includesFilename(cleaned)) return assertWithinBase(baseOutDir, join(baseOutDir, cleaned));
+        return assertWithinBase(baseOutDir, join(baseOutDir, cleaned, `${filename}.client.ts`));
     }
     if (clientOutput) {
-        if (includesFilename(clientOutput)) return join(baseOutDir, clientOutput);
-        return join(baseOutDir, clientOutput, `${filename}.client.ts`);
+        if (includesFilename(clientOutput)) return assertWithinBase(baseOutDir, join(baseOutDir, clientOutput));
+        return assertWithinBase(baseOutDir, join(baseOutDir, clientOutput, `${filename}.client.ts`));
     }
-    return join(baseOutDir, `${filename}.client.ts`);
+    return assertWithinBase(baseOutDir, join(baseOutDir, `${filename}.client.ts`));
 }
 
 export function computeSdkTypeOutPath(
@@ -144,11 +161,11 @@ export function computeSdkTypeOutPath(
 
     if (TEMPLATE_VAR_RE.test(typeOutput)) {
         const resolved = resolveTemplate(typeOutput, { filename, dir: relDir, ext: 'ck', ...meta });
-        if (includesFilename(resolved)) return join(baseOutDir, resolved);
-        return join(baseOutDir, resolved, defaultOutName);
+        if (includesFilename(resolved)) return assertWithinBase(baseOutDir, join(baseOutDir, resolved));
+        return assertWithinBase(baseOutDir, join(baseOutDir, resolved, defaultOutName));
     }
-    if (includesFilename(typeOutput)) return join(baseOutDir, typeOutput);
-    return join(baseOutDir, typeOutput, relDir, defaultOutName);
+    if (includesFilename(typeOutput)) return assertWithinBase(baseOutDir, join(baseOutDir, typeOutput));
+    return assertWithinBase(baseOutDir, join(baseOutDir, typeOutput, relDir, defaultOutName));
 }
 
 export function generateBarrelFiles(contractPaths: string[]): { outPath: string; content: string }[] {

package/src/ts-render.ts

@@ -1,4 +1,4 @@
-import type { ContractTypeNode, FieldNode } from '@contractkit/core';
+import type { ContractTypeNode, FieldNode, ScalarTypeNode } from '@contractkit/core';
 
 export const JSON_VALUE_TYPE_DECL = 'export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };';
 
@@ -6,6 +6,18 @@ export function quoteKey(name: string): string {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `'${name}'`;
 }
 
+/** Escape text for safe inclusion inside a JSDoc block comment: neutralize the
+ *  block-comment terminator sequence and split embedded newlines into separate
+ *  ` * ` continuation lines. Returns the content lines (WITHOUT a leading prefix). */
+export function escapeJsDocLines(text: string): string[] {
+    return text.replace(/\*\//g, '*\\/').split('\n');
+}
+
+/** Escape a string for inclusion inside a single-quoted TypeScript string literal. */
+export function escapeSingleQuoted(s: string): string {
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+}
+
 /** 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);
@@ -37,9 +49,9 @@ export function renderTsType(type: ContractTypeNode): string {
         case 'record':
             return `Record<${renderTsType(type.key)}, ${renderTsType(type.value)}>`;
         case 'enum':
-            return type.values.map(v => `'${v}'`).join(' | ');
+            return type.values.map(v => `'${escapeSingleQuoted(v)}'`).join(' | ');
         case 'literal':
-            return typeof type.value === 'string' ? `'${type.value}'` : String(type.value);
+            return typeof type.value === 'string' ? `'${escapeSingleQuoted(type.value)}'` : String(type.value);
         case 'union':
             return type.members.map(renderTsType).join(' | ');
         case 'discriminatedUnion':
@@ -57,7 +69,7 @@ export function renderTsType(type: ContractTypeNode): string {
     }
 }
 
-function renderTsScalar(name: string): string {
+function renderTsScalar(name: ScalarTypeNode['name']): string {
     switch (name) {
         case 'string':
         case 'email':
@@ -72,6 +84,7 @@ function renderTsScalar(name: string): string {
         case 'boolean':
             return 'boolean';
         case 'date':
+        case 'time':
         case 'datetime':
         case 'duration':
         case 'interval':
@@ -86,8 +99,10 @@ function renderTsScalar(name: string): string {
             return 'Blob';
         case 'json':
             return 'JsonValue';
-        default:
-            return 'unknown';
+        default: {
+            const _exhaustive: never = name;
+            throw new Error(`plugin-typescript: unmapped scalar '${String(_exhaustive)}' — add a case`);
+        }
     }
 }
 

package/tests/codegen-contract.test.ts

@@ -26,6 +26,10 @@ describe('renderType', () => {
             expect(renderType(scalarType('string'))).toBe('z.string()');
         });
 
+        it('throws on an unmapped scalar name', () => {
+            expect(() => renderType({ kind: 'scalar', name: 'decimal' } as any)).toThrow(/unmapped scalar 'decimal'/);
+        });
+
         it('renders z.string() with min/max', () => {
             expect(renderType(scalarType('string', { min: 1, max: 100 }))).toBe('z.string().min(1).max(100)');
         });