@contractkit/plugin-typescript 0.28.0 → 0.28.2

package/tests/codegen-mcp.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import type { McpConfigNode } from '@contractkit/core';
+import {
+    generateMcpFile,
+    generateMcpAggregator,
+    generateMcpRouter,
+    hasMcpOperations,
+    deriveMcpRegisterFnName,
+} from '../src/codegen-mcp.js';
+import { opRoot, opRoute, opOperation, opParam, opRequest, opResponse, scalarType, loc } from './helpers.js';
+
+function mcpBlock(over: Partial<McpConfigNode>): McpConfigNode {
+    return { loc: loc(), ...over };
+}
+
+describe('hasMcpOperations', () => {
+    it('is false when no op is flagged', () => {
+        const root = opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])]);
+        expect(hasMcpOperations(root)).toBe(false);
+    });
+
+    it('is true when an op is flagged', () => {
+        const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+        expect(hasMcpOperations(root)).toBe(true);
+    });
+
+    it('excludes internal ops unless includeInternal', () => {
+        const root = opRoot([
+            opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })], undefined, ['internal']),
+        ]);
+        expect(hasMcpOperations(root)).toBe(false);
+        expect(hasMcpOperations(root, true)).toBe(true);
+    });
+});
+
+describe('generateMcpFile', () => {
+    describe('op selection', () => {
+        it('emits a tool class only for flagged ops', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', { sdk: 'listUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] }),
+                    opOperation('post', { sdk: 'createUser', request: opRequest('User'), responses: [opResponse(201, 'User', 'application/json')] }),
+                ]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('export class ListUsersMcpTool');
+            expect(out).not.toContain('CreateUserMcpTool');
+        });
+
+        it('skips mcp: false', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { sdk: 'listUsers', mcp: false, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            expect(out).not.toContain('implements McpToolHandler');
+        });
+
+        it('skips internal ops unless includeInternal', () => {
+            const root = opRoot([
+                opRoute('/users', [opOperation('get', { sdk: 'listUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })], undefined, [
+                    'internal',
+                ]),
+            ]);
+            expect(generateMcpFile(root)).not.toContain('ListUsersMcpTool');
+            expect(generateMcpFile(root, { includeInternal: true })).toContain('ListUsersMcpTool');
+        });
+    });
+
+    describe('tool name + class name', () => {
+        it('uses explicit mcp.name verbatim', () => {
+            const root = opRoot([
+                opRoute('/routes', [opOperation('post', { mcp: mcpBlock({ name: 'searchRoutes' }), request: opRequest('Query'), responses: [opResponse(200, 'RouteList', 'application/json')] })]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("name: 'searchRoutes'");
+            expect(out).toContain('export class SearchRoutesMcpTool');
+        });
+
+        it('snake_cases the sdk field', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { sdk: 'listAllUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("name: 'list_all_users'");
+            expect(out).toContain('export class ListAllUsersMcpTool');
+        });
+
+        it('snake_cases the name field', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { name: 'Get User', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).toContain("name: 'get_user'");
+        });
+
+        it('infers snake_case name from method + path', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            expect(generateMcpFile(root)).toContain("name: 'get_payments_by_id'");
+        });
+    });
+
+    describe('definition metadata', () => {
+        it('emits title, description, and only the defined annotations', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [
+                    opOperation('get', {
+                        mcp: mcpBlock({ title: 'Get Payment', description: 'Fetch a payment by id.', readOnlyHint: true, idempotentHint: true, destructiveHint: false }),
+                        responses: [opResponse(200, 'Payment', 'application/json')],
+                    }),
+                ], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("title: 'Get Payment'");
+            expect(out).toContain("description: 'Fetch a payment by id.'");
+            expect(out).toContain('annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }');
+            expect(out).not.toContain('openWorldHint');
+        });
+
+        it('omits annotations when no hints set', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).not.toContain('annotations:');
+        });
+
+        it('falls back to op description', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, description: 'List users.', responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).toContain("description: 'List users.'");
+        });
+    });
+
+    describe('input schema + validation', () => {
+        it('folds path params into a shared args const used for schema and validation', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('const GetPaymentsByIdArgs = z.object({ id: z.uuid() });');
+            expect(out).toContain("inputSchema: z.toJSONSchema(GetPaymentsByIdArgs, { unrepresentable: 'any' }) as Tool['inputSchema']");
+            expect(out).toContain('const { id } = await parseAndValidate(args, GetPaymentsByIdArgs);');
+        });
+
+        it('nests the request body under a body field', () => {
+            const root = opRoot([
+                opRoute('/payments', [opOperation('post', { sdk: 'createPayment', mcp: true, request: opRequest('PaymentInput'), responses: [opResponse(201, 'Payment', 'application/json')] })]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('const CreatePaymentArgs = z.object({ body: PaymentInput });');
+            expect(out).toContain('const { body } = await parseAndValidate(args, CreatePaymentArgs);');
+        });
+    });
+
+    describe('service call + result', () => {
+        it('injects the declared service and calls it', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('constructor(private readonly service: PaymentsService) {}');
+            expect(out).toContain('const result = await this.service.getById(id);');
+            expect(out).toContain('structuredContent: result');
+        });
+
+        it('returns bare content (no structuredContent / outputSchema) for a void response', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('delete', { mcp: true, service: 'PaymentsService.remove', responses: [opResponse(204)] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('await this.service.remove(id);');
+            expect(out).toContain("return { content: [{ type: 'text', text: 'OK' }] };");
+            expect(out).not.toContain('structuredContent');
+            expect(out).not.toContain('outputSchema');
+        });
+
+        it('emits outputSchema for an object response', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            expect(generateMcpFile(root)).toContain("outputSchema: z.toJSONSchema(Payment, { unrepresentable: 'any' }) as Tool['outputSchema']");
+        });
+    });
+
+    describe('imports + registration', () => {
+        it('imports the MCP + injectkit primitives and emits a per-file register fn', () => {
+            const root = opRoot(
+                [opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))])],
+                'payments.op',
+            );
+            const out = generateMcpFile(root);
+            expect(out).toContain("import { Injectable, type Container } from 'injectkit';");
+            expect(out).toContain("import type { McpToolHandler, McpToolHandlerMap, McpToolContext } from '@maroonedsoftware/mcp';");
+            expect(out).toContain("import { parseAndValidate } from '@maroonedsoftware/zod';");
+            expect(out).toContain('export function registerPaymentsMcpTools(map: McpToolHandlerMap, container: Container): void {');
+            expect(out).toContain("map.set('get_payments_by_id', container.get(GetPaymentsByIdMcpTool));");
+        });
+
+        it('resolves service + schema imports via modelOutPaths', () => {
+            const root = opRoot(
+                [opRoute('/payments', [opOperation('post', { sdk: 'createPayment', mcp: true, service: 'PaymentsService.create', request: opRequest('PaymentInput'), responses: [opResponse(201, 'Payment', 'application/json')] })])],
+                'payments.op',
+            );
+            const modelOutPaths = new Map<string, string>([
+                ['Payment', '/api/src/types/payment.ts'],
+                ['PaymentInput', '/api/src/types/payment.ts'],
+            ]);
+            const out = generateMcpFile(root, {
+                outPath: '/api/src/mcp/payments.mcp.ts',
+                modelOutPaths,
+                modelsWithInput: new Set(['Payment']),
+                servicePathTemplate: '#modules/{kebab}/{kebab}.service.js',
+            });
+            expect(out).toContain("import { PaymentsService } from '#modules/payments/payments.service.js';");
+            expect(out).toContain("import { Payment, PaymentInput } from '../types/payment.js';");
+        });
+    });
+});
+
+describe('generateMcpAggregator', () => {
+    it('imports each register fn and assembles one map', () => {
+        const out = generateMcpAggregator([
+            { registerFn: 'registerPaymentsMcpTools', importPath: './payments.mcp.js' },
+            { registerFn: 'registerUsersMcpTools', importPath: './users.mcp.js' },
+        ]);
+        expect(out).toContain("import { McpToolHandlerMap } from '@maroonedsoftware/mcp';");
+        expect(out).toContain("import { registerPaymentsMcpTools } from './payments.mcp.js';");
+        expect(out).toContain('export function registerMcpTools(container: Container): McpToolHandlerMap {');
+        expect(out).toContain('const map = new McpToolHandlerMap();');
+        expect(out).toContain('registerPaymentsMcpTools(map, container);');
+        expect(out).toContain('registerUsersMcpTools(map, container);');
+        expect(out).toContain('container.register(McpToolHandlerMap, { useValue: map });');
+    });
+});
+
+describe('generateMcpRouter', () => {
+    it('emits a ServerKit route wired to the dispatcher at the configured path', () => {
+        const out = generateMcpRouter({ path: '/mcp' });
+        expect(out).toContain("import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';");
+        expect(out).toContain("router.post('/mcp'");
+        expect(out).toContain('ctx.container.get(McpDispatcher)');
+        expect(out).toContain("dispatcher.sessionMode === 'stateful'");
+    });
+
+    it('defaults the mount path to /mcp', () => {
+        expect(generateMcpRouter()).toContain("router.post('/mcp'");
+    });
+});
+
+describe('deriveMcpRegisterFnName', () => {
+    it('derives from the op-root filename', () => {
+        expect(deriveMcpRegisterFnName('payments.op')).toBe('registerPaymentsMcpTools');
+        expect(deriveMcpRegisterFnName('ledger.categories.op')).toBe('registerLedgerCategoriesMcpTools');
+    });
+});

package/tests/codegen-operation.test.ts

@@ -103,6 +103,24 @@ describe('generateOperation', () => {
         });
     });
 
+    // ─── Handler signature ─────────────────────────────────────────
+
+    describe('handler signature', () => {
+        it('emits a single-parameter handler without the unused next argument', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { security: SECURITY_NONE })])]);
+            const output = generateOp(root);
+            expect(output).toContain(".get('/users', async ctx => {");
+            expect(output).not.toContain('ctx, next');
+        });
+
+        it('omits next on handlers that carry middleware', () => {
+            const root = opRoot([opRoute('/users', [opOperation('post', { request: opRequest('CreateUser') })])]);
+            const output = generateOp(root);
+            expect(output).toContain('async ctx => {');
+            expect(output).not.toContain('ctx, next');
+        });
+    });
+
     // ─── Handler generation — GET ──────────────────────────────────
 
     describe('GET handlers', () => {

package/tests/codegen-sdk.test.ts

@@ -1110,6 +1110,14 @@ describe('renderTsType', () => {
         it('maps json to JsonValue', () => {
             expect(renderTsType(scalarType('json'))).toBe('JsonValue');
         });
+
+        it('maps time to string', () => {
+            expect(renderTsType(scalarType('time'))).toBe('string');
+        });
+
+        it('throws on an unmapped scalar name', () => {
+            expect(() => renderTsType({ kind: 'scalar', name: 'decimal' } as any)).toThrow(/unmapped scalar 'decimal'/);
+        });
     });
 
     it('renders tuple type', () => {

package/tests/escaping-security.test.ts

@@ -0,0 +1,143 @@
+import { generateContract, renderType } from '../src/codegen-contract.js';
+import { generatePlainTypes } from '../src/codegen-plain-types.js';
+import { generateOp } from '../src/codegen-operation.js';
+import { renderTsType, escapeJsDocLines, escapeSingleQuoted } from '../src/ts-render.js';
+import { computeOpOutPath, computeSdkOutPath, computeSdkTypeOutPath, computeSdkAreaClientOutPath } from '../src/path-utils.js';
+import { field, model, contractRoot, enumType, scalarType, opRoot, opRoute, opOperation, opResponse } from './helpers.js';
+
+// ─── Fix 1: JSDoc comment injection via descriptions ────────────────────────
+
+describe('JSDoc comment injection (descriptions)', () => {
+    it('neutralizes `*/` in a model description (Zod codegen)', () => {
+        const root = contractRoot([model('Widget', [field('id', scalarType('uuid'))], { description: 'closes */ early' })]);
+        const out = generateContract(root);
+        // The raw terminator must not appear inside the generated comment.
+        expect(out).not.toContain('closes */ early');
+        expect(out).toContain('closes *\\/ early');
+    });
+
+    it('splits a two-line model description into ` * ` continuation lines (Zod codegen)', () => {
+        const root = contractRoot([model('Widget', [field('id', scalarType('uuid'))], { description: 'line one\nline two' })]);
+        const out = generateContract(root);
+        expect(out).toContain(' * line one');
+        expect(out).toContain(' * line two');
+    });
+
+    it('neutralizes `*/` in a model description (plain-types codegen)', () => {
+        const root = contractRoot([model('Widget', [field('id', scalarType('uuid'))], { description: 'closes */ early' })]);
+        const out = generatePlainTypes(root);
+        expect(out).not.toContain('closes */ early');
+        expect(out).toContain('closes *\\/ early');
+    });
+
+    it('neutralizes `*/` in a field description (plain-types codegen)', () => {
+        const root = contractRoot([model('Widget', [field('id', scalarType('uuid'), { description: 'bad */ desc' })])]);
+        const out = generatePlainTypes(root);
+        expect(out).not.toContain('bad */ desc');
+        expect(out).toContain('bad *\\/ desc');
+    });
+
+    it('splits a two-line field description into a multi-line JSDoc block (plain-types codegen)', () => {
+        const root = contractRoot([model('Widget', [field('id', scalarType('uuid'), { description: 'first\nsecond' })])]);
+        const out = generatePlainTypes(root);
+        expect(out).toContain('first');
+        expect(out).toContain('* second');
+        // No premature close on the same physical line as content.
+        expect(out).not.toMatch(/first\nsecond/);
+    });
+
+    it('neutralizes `*/` in an operation description (server codegen)', () => {
+        const root = opRoot([opRoute('/x', [opOperation('get', { description: 'op */ desc', responses: [opResponse(200)] })])]);
+        const out = generateOp(root);
+        expect(out).not.toContain('op */ desc');
+        expect(out).toContain('op *\\/ desc');
+    });
+
+    it('escapeJsDocLines neutralizes terminators and splits newlines', () => {
+        expect(escapeJsDocLines('a */ b')).toEqual(['a *\\/ b']);
+        expect(escapeJsDocLines('a\nb')).toEqual(['a', 'b']);
+    });
+});
+
+// ─── Fix 2: enum / literal value escaping ───────────────────────────────────
+
+describe('enum value escaping', () => {
+    it('escapes double and single quotes in a Zod enum', () => {
+        const out = renderType(enumType('a"b', "c'd"));
+        expect(out).toBe('z.enum(["a\\"b", "c\'d"])');
+    });
+
+    it('escapes single quotes in a TS union of enum values', () => {
+        const out = renderTsType(enumType('a"b', "c'd"));
+        expect(out).toBe("'a\"b' | 'c\\'d'");
+    });
+
+    it('escapes single quotes in a TS string literal', () => {
+        expect(renderTsType({ kind: 'literal', value: "it's" })).toBe("'it\\'s'");
+    });
+
+    it('escapeSingleQuoted escapes backslashes, quotes and newlines', () => {
+        expect(escapeSingleQuoted("a'b\\c\nd")).toBe("a\\'b\\\\c\\nd");
+    });
+});
+
+// ─── Fix 3: signature interpolation escaping ────────────────────────────────
+
+describe('signature escaping (server codegen)', () => {
+    it('escapes a single quote in the signature value', () => {
+        const root = opRoot([opRoute('/x', [opOperation('get', { signature: "sig'v", responses: [opResponse(200)] })])]);
+        const out = generateOp(root);
+        expect(out).toContain("requireSignature('sig\\'v')");
+    });
+
+    it('escapes single quotes in signature and policy', () => {
+        const root = opRoot([
+            opRoute('/x', [opOperation('get', { signature: "sig'v", signaturePolicy: "pol'y", responses: [opResponse(200)] })]),
+        ]);
+        const out = generateOp(root);
+        expect(out).toContain("requireSignature('sig\\'v', { policy: 'pol\\'y' })");
+    });
+});
+
+// ─── Fix 4: path traversal via .ck-derived template vars ────────────────────
+
+describe('path traversal containment', () => {
+    const base = '/project/out';
+
+    it('throws when a `.ck`-derived {area} escapes the base output dir', () => {
+        expect(() =>
+            computeOpOutPath('/project/contracts/a.ck', base, '{area}/{filename}.ts', '.ts', '/project/contracts', {
+                area: '../../../tmp/x',
+            }),
+        ).toThrow(/Refusing to emit outside output directory/);
+    });
+
+    it('throws when a `.ck`-derived {filename} escapes the base output dir', () => {
+        expect(() =>
+            computeSdkTypeOutPath('/project/contracts/a.ck', base, '{filename}.ts', '/project/contracts', {
+                filename: '../../etc/passwd',
+            }),
+        ).toThrow(/Refusing to emit outside output directory/);
+    });
+
+    it('throws for computeSdkOutPath traversal', () => {
+        expect(() =>
+            computeSdkOutPath('/project/contracts/a.ck', base, '{area}/{filename}.ts', '/project/contracts', {
+                area: '../../../evil',
+            }),
+        ).toThrow(/Refusing to emit outside output directory/);
+    });
+
+    it('throws for computeSdkAreaClientOutPath traversal', () => {
+        expect(() => computeSdkAreaClientOutPath('../../../evil', base, '{area}/{filename}.client.ts')).toThrow(
+            /Refusing to emit outside output directory/,
+        );
+    });
+
+    it('allows a normal in-base path', () => {
+        const p = computeOpOutPath('/project/contracts/a.ck', base, '{area}/{filename}.ts', '.ts', '/project/contracts', {
+            area: 'billing',
+        });
+        expect(p).toBe('/project/out/billing/a.ts');
+    });
+});

package/tests/pipeline.test.ts

@@ -2,6 +2,7 @@ import { parseCk, decomposeCk, validateOp, validateRefs, applyOptionsDefaults, D
 import { generateContract } from '../src/codegen-contract.js';
 import { generateOp } from '../src/codegen-operation.js';
 import { generateSdk } from '../src/codegen-sdk.js';
+import { generateMcpFile } from '../src/codegen-mcp.js';
 import { SIMPLE_USER_CONTRACT, VISIBILITY_CONTRACT, INHERITANCE_CONTRACT, SIMPLE_USERS_OP, PARAMETERIZED_OP } from './helpers.js';
 
 function compileContractSource(source: string) {
@@ -118,6 +119,64 @@ describe('OP pipeline (source -> parse -> codegen)', () => {
     });
 });
 
+describe('MCP pipeline (source -> parse -> codegen)', () => {
+    function compileMcp(source: string, file = 'payments.ck') {
+        const diag = new DiagnosticCollector();
+        const ck = parseCk(source, file, diag);
+        const { op } = decomposeCk(ck);
+        return { output: generateMcpFile(op, { includeInternal: false }), diag };
+    }
+
+    it('generates a tool handler from a parsed mcp block', () => {
+        const source = `\
+operation /payments/{id}: {
+    params: { id: uuid }
+    get: {
+        mcp: {
+            title: "Get Payment"
+            description: "Fetch a payment by id."
+            hint: readOnly, idempotent, nonDestructive
+        }
+        service: PaymentsService.getById
+        response: { 200: { application/json: Payment } }
+    }
+}`;
+        const { output, diag } = compileMcp(source);
+        expect(diag.hasErrors()).toBe(false);
+        expect(output).toContain('export class GetPaymentsByIdMcpTool implements McpToolHandler');
+        expect(output).toContain("title: 'Get Payment'");
+        expect(output).toContain('annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }');
+        expect(output).toContain('const GetPaymentsByIdArgs = z.object({ id: z.uuid() });');
+        expect(output).toContain('constructor(private readonly service: PaymentsService) {}');
+        expect(output).toContain('const result = await this.service.getById(id);');
+        expect(output).toContain('export function registerPaymentsMcpTools(map: McpToolHandlerMap, container: Container): void {');
+        expect(output).toContain("map.set('get_payments_by_id', container.get(GetPaymentsByIdMcpTool));");
+    });
+
+    it('generates a tool from mcp: true with an inferred name', () => {
+        const source = `\
+operation /payments: {
+    post: {
+        mcp: true
+        service: PaymentsService.create
+        request: { application/json: PaymentInput }
+        response: { 201: { application/json: Payment } }
+    }
+}`;
+        const { output, diag } = compileMcp(source);
+        expect(diag.hasErrors()).toBe(false);
+        expect(output).toContain("name: 'post_payments'");
+        expect(output).toContain('const PostPaymentsArgs = z.object({ body: PaymentInput });');
+        expect(output).not.toContain('annotations:');
+    });
+
+    it('emits nothing tool-like for a file with no flagged ops', () => {
+        const source = `operation /payments: { get: { response: { 200: { application/json: Payment } } } }`;
+        const { output } = compileMcp(source);
+        expect(output).not.toContain('implements McpToolHandler');
+    });
+});
+
 describe('undeclared path param warnings', () => {
     it('warns when a route has path params but no params block', () => {
         const source = `operation /users/{id}: { get: {} }`;