@contractkit/plugin-typescript 0.34.1 → 0.36.0

package/tests/codegen-server.test.ts

@@ -37,6 +37,13 @@ function inputs(opRoots = [opRoot([opRoute('/users', [opOperation('get')])], '/p
     };
 }
 
+/** Inputs carrying an MCP-exposed operation, which is what makes the mcp sub-generator emit a router. */
+function mcpInputs() {
+    return inputs([
+        opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])], '/project/contracts/users.ck'),
+    ]);
+}
+
 // ─── Tests ─────────────────────────────────────────────────────────────────
 
 describe('createTypescriptPlugin (server)', () => {
@@ -224,6 +231,55 @@ describe('createTypescriptPlugin (server)', () => {
         });
     });
 
+    describe('framework', () => {
+        it('emits a Koa router when no framework is configured', async () => {
+            const plugin = createTypescriptPlugin({ server: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(inputs(), ctx);
+            const [content] = [...ctx.emitted.values()];
+            expect(content).toContain("from '@maroonedsoftware/koa'");
+        });
+
+        it('emits byte-identical output when koa is named explicitly', async () => {
+            const runWith = async (server: Record<string, unknown>) => {
+                const ctx = makeCtx('/project');
+                await createTypescriptPlugin({ server }, '/project').generateTargets!(inputs(), ctx);
+                return [...ctx.emitted.values()].join('\n');
+            };
+            expect(await runWith({ framework: 'koa' })).toEqual(await runWith({}));
+        });
+
+        it('rejects a framework that has no adapter', async () => {
+            const plugin = createTypescriptPlugin({ server: { framework: 'express' as never } }, '/project');
+            await expect(plugin.generateTargets!(inputs(), makeCtx('/project'))).rejects.toThrow(
+                /server\.framework 'express' is not supported — expected one of: koa/,
+            );
+        });
+
+        it('rejects the unknown framework before any other config complaint', async () => {
+            // Both rules are broken here; the framework is the one reported, since a router for a
+            // framework that does not exist cannot be generated whatever the other settings say.
+            const plugin = createTypescriptPlugin({ server: { framework: 'express' as never, validateResponses: true } }, '/project');
+            await expect(plugin.generateTargets!(inputs(), makeCtx('/project'))).rejects.toThrow(/server\.framework/);
+        });
+
+        it('renders mcp.router.ts for the configured framework', async () => {
+            const plugin = createTypescriptPlugin({ server: { framework: 'koa' }, mcp: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(mcpInputs(), ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('mcp.router.ts'))?.[1];
+            expect(router).toContain("from '@maroonedsoftware/koa'");
+        });
+
+        it('still emits a Koa mcp.router.ts when there is no server sub-config', async () => {
+            const plugin = createTypescriptPlugin({ mcp: {} }, '/project');
+            const ctx = makeCtx('/project');
+            await plugin.generateTargets!(mcpInputs(), ctx);
+            const router = [...ctx.emitted.entries()].find(([p]) => p.endsWith('mcp.router.ts'))?.[1];
+            expect(router).toContain("from '@maroonedsoftware/koa'");
+        });
+    });
+
     describe('validateResponses', () => {
         const userRoot = () =>
             opRoot(

package/tests/server-framework-fastify.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { FASTIFY_SERVER_FRAMEWORK as fastify } from '../src/server-framework-fastify.js';
+
+/**
+ * Pinned method by method, the way the Koa adapter is. These strings are the contract with
+ * `@maroonedsoftware/fastify`, so a change to any of them should fail here, naming the piece,
+ * rather than only as a snapshot diff in another package.
+ */
+describe('FASTIFY_SERVER_FRAMEWORK', () => {
+    it('is named fastify', () => {
+        expect(fastify.name).toBe('fastify');
+    });
+
+    describe('imports', () => {
+        it('emits one line naming every symbol the body uses', () => {
+            expect(fastify.imports(() => true)).toEqual([
+                "import { ServerKitRouter, bodyParserMiddleware, requirePolicy, requireSignature, requestMediaType } from '@maroonedsoftware/fastify';",
+            ]);
+        });
+
+        it('narrows to the symbols the body actually references', () => {
+            expect(fastify.imports(s => s === 'requestMediaType')).toEqual(["import { requestMediaType } from '@maroonedsoftware/fastify';"]);
+        });
+
+        it('emits nothing when the body references none of them', () => {
+            expect(fastify.imports(() => false)).toEqual([]);
+        });
+    });
+
+    it('declares the router', () => {
+        expect(fastify.routerDeclaration('UsersRouter')).toBe('export const UsersRouter = ServerKitRouter();');
+    });
+
+    it('renders a path parameter with a colon', () => {
+        expect(fastify.pathParam('userId')).toBe(':userId');
+    });
+
+    it('reserves the two identifiers its handler signature binds', () => {
+        expect(fastify.handlerLocals).toEqual(['request', 'reply']);
+    });
+
+    describe('routeOpen', () => {
+        it('omits the middleware list when there is none', () => {
+            expect(fastify.routeOpen('UsersRouter', 'get', '/users', [])).toBe("UsersRouter.get('/users', async (request, reply) => {");
+        });
+
+        it('places the middleware between the path and the handler', () => {
+            expect(fastify.routeOpen('UsersRouter', 'post', '/users', ['requirePolicy()', "bodyParserMiddleware(['json'])"])).toBe(
+                "UsersRouter.post('/users', requirePolicy(), bodyParserMiddleware(['json']), async (request, reply) => {",
+            );
+        });
+    });
+
+    it('closes a route', () => {
+        expect(fastify.routeClose()).toEqual(['});']);
+    });
+
+    it('renders the route middleware factories, which take the same arguments as Koa\'s', () => {
+        expect(fastify.middleware.policy('')).toBe('requirePolicy()');
+        expect(fastify.middleware.policy("{ policy: 'admin' }")).toBe("requirePolicy({ policy: 'admin' })");
+        expect(fastify.middleware.bodyParser("'json', 'multipart'")).toBe("bodyParserMiddleware(['json', 'multipart'])");
+        expect(fastify.middleware.signature("'slack'")).toBe("requireSignature('slack')");
+    });
+
+    it('reads the request off the request object, which is the context', () => {
+        expect(fastify.request).toEqual({
+            params: 'request.params',
+            query: 'request.query',
+            headers: 'request.headers',
+            parsedBody: 'request.parsedBody',
+            // A call rather than a property: the raw header carries `; charset=…`, which matches no
+            // declared MIME literal.
+            contentType: 'requestMediaType(request)',
+        });
+    });
+
+    it('resolves a service from the request container', () => {
+        expect(fastify.resolveService('PaymentService')).toBe('request.container.get(PaymentService)');
+    });
+
+    describe('response', () => {
+        it('sets the status through reply', () => {
+            expect(fastify.response.status('200')).toBe('reply.status(200);');
+            expect(fastify.response.status('result.status')).toBe('reply.status(result.status);');
+        });
+
+        it('sets a header as a single statement, so the optional guard can wrap it', () => {
+            expect(fastify.response.header('x-request-id', 'String(result.headers["xRequestId"])')).toBe(
+                'reply.header(\'x-request-id\', String(result.headers["xRequestId"]));',
+            );
+        });
+
+        it('sets the content type', () => {
+            expect(fastify.response.type("'application/json'")).toBe("reply.type('application/json');");
+            expect(fastify.response.type('result.contentType')).toBe('reply.type(result.contentType);');
+        });
+
+        it('returns the send, including for a response with no body', () => {
+            expect(fastify.response.send('result')).toEqual(['return reply.send(result);']);
+            // Unlike Koa: a handler that neither returns a body nor calls send leaves the request hanging.
+            expect(fastify.response.send(undefined)).toEqual(['return reply.send();']);
+        });
+
+        it('closes a status case with nothing, since the case already returned', () => {
+            expect(fastify.response.caseEnd()).toEqual([]);
+        });
+    });
+
+    describe('mcpRouter', () => {
+        const out = fastify.mcpRouter({ path: '/mcp' });
+
+        it('mounts the dispatcher at the given path', () => {
+            expect(fastify.mcpRouter({ path: '/tools' })).toContain("router.post('/tools',");
+            expect(out).toContain("from '@maroonedsoftware/fastify'");
+            expect(out).toContain('const dispatcher = request.container.get(McpDispatcher);');
+        });
+
+        it('names the exported router type rather than inferring it', () => {
+            expect(out).toContain('export function mountMcp(router: ServerKitRouterType): void {');
+            // And therefore never imports the factory value, which `noUnusedLocals` would reject.
+            expect(out).toContain("import { type ServerKitRouterType, bodyParserMiddleware, requireSignature, requestHeader } from '@maroonedsoftware/fastify';");
+        });
+
+        it('hijacks the reply for a stateful session, which is Fastify\'s ctx.respond = false', () => {
+            expect(out).toContain('reply.hijack();');
+            expect(out).toContain('req: request.raw,');
+            expect(out).toContain('res: reply.raw,');
+        });
+
+        it('reads the parsed body, not Fastify\'s own request.body', () => {
+            expect(out).toContain('body: request.parsedBody,');
+            expect(out).not.toContain('request.body,');
+        });
+
+        it('passes undefined rather than the empty string for an absent session id', () => {
+            expect(out).toContain("sessionId: requestHeader(request, 'mcp-session-id') || undefined,");
+        });
+
+        it('answers a notification with a bodyless 202', () => {
+            expect(out).toContain('reply.status(202);');
+            expect(out).toContain('return reply.send();');
+        });
+
+        it('escapes the backticks in its own doc comment rather than closing the template', () => {
+            expect(out).toContain('Bind `registerMcpTools` to the `McpToolHandlerMap` token.');
+        });
+    });
+});

package/tests/server-framework-koa.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { KOA_SERVER_FRAMEWORK as koa } from '../src/server-framework-koa.js';
+
+/**
+ * The Koa adapter is the reference implementation: every string here is one the generator emitted
+ * inline before the seam existed. Pinning them individually means a change to any one of them shows
+ * up as a failure here, naming the piece, rather than only as a snapshot diff two packages away.
+ */
+describe('KOA_SERVER_FRAMEWORK', () => {
+    it('is named koa', () => {
+        expect(koa.name).toBe('koa');
+    });
+
+    describe('imports', () => {
+        it('emits one line naming every symbol the body uses', () => {
+            expect(koa.imports(() => true)).toEqual([
+                "import { ServerKitRouter, bodyParserMiddleware, requirePolicy, requireSignature } from '@maroonedsoftware/koa';",
+            ]);
+        });
+
+        it('narrows to the symbols the body actually references', () => {
+            expect(koa.imports(s => s === 'requirePolicy')).toEqual(["import { requirePolicy } from '@maroonedsoftware/koa';"]);
+        });
+
+        it('emits nothing when the body references none of them', () => {
+            expect(koa.imports(() => false)).toEqual([]);
+        });
+    });
+
+    it('declares the router', () => {
+        expect(koa.routerDeclaration('UsersRouter')).toBe('export const UsersRouter = ServerKitRouter();');
+    });
+
+    it('renders a path parameter with a colon', () => {
+        expect(koa.pathParam('userId')).toBe(':userId');
+    });
+
+    describe('routeOpen', () => {
+        it('omits the middleware list when there is none', () => {
+            expect(koa.routeOpen('UsersRouter', 'get', '/users', [])).toBe("UsersRouter.get('/users', async ctx => {");
+        });
+
+        it('places the middleware between the path and the handler', () => {
+            expect(koa.routeOpen('UsersRouter', 'post', '/users', ['requirePolicy()', "bodyParserMiddleware(['json'])"])).toBe(
+                "UsersRouter.post('/users', requirePolicy(), bodyParserMiddleware(['json']), async ctx => {",
+            );
+        });
+    });
+
+    it('closes a route', () => {
+        expect(koa.routeClose()).toEqual(['});']);
+    });
+
+    it('renders the route middleware factories', () => {
+        expect(koa.middleware.policy('')).toBe('requirePolicy()');
+        expect(koa.middleware.policy("{ policy: 'admin' }")).toBe("requirePolicy({ policy: 'admin' })");
+        expect(koa.middleware.bodyParser("'json', 'multipart'")).toBe("bodyParserMiddleware(['json', 'multipart'])");
+        expect(koa.middleware.signature("'slack'")).toBe("requireSignature('slack')");
+    });
+
+    it('reads the request off the context', () => {
+        expect(koa.request).toEqual({
+            params: 'ctx.params',
+            query: 'ctx.query',
+            headers: 'ctx.headers',
+            parsedBody: 'ctx.parsedBody',
+            contentType: 'ctx.request.type',
+        });
+    });
+
+    it('resolves a service from the request container', () => {
+        expect(koa.resolveService('PaymentService')).toBe('ctx.container.get(PaymentService)');
+    });
+
+    describe('response', () => {
+        it('assigns the status', () => {
+            expect(koa.response.status('200')).toBe('ctx.status = 200;');
+            expect(koa.response.status('result.status')).toBe('ctx.status = result.status;');
+        });
+
+        it('sets a header as a single statement, so the optional guard can wrap it', () => {
+            expect(koa.response.header('x-request-id', 'String(result.headers["xRequestId"])')).toBe(
+                'ctx.set(\'x-request-id\', String(result.headers["xRequestId"]));',
+            );
+        });
+
+        it('assigns the content type', () => {
+            expect(koa.response.type("'application/json'")).toBe("ctx.type = 'application/json';");
+            expect(koa.response.type('result.contentType')).toBe('ctx.type = result.contentType;');
+        });
+
+        it('assigns the body, and writes nothing at all when there is none', () => {
+            expect(koa.response.send('result')).toEqual(['ctx.body = result;']);
+            // Koa ends the response on its own once the handler resolves, so a 204 needs no statement.
+            expect(koa.response.send(undefined)).toEqual([]);
+        });
+
+        it('closes a status case with a break', () => {
+            expect(koa.response.caseEnd()).toEqual(['break;']);
+        });
+    });
+
+    describe('mcpRouter', () => {
+        it('mounts the dispatcher at the given path', () => {
+            const out = koa.mcpRouter({ path: '/tools' });
+            expect(out).toContain("router.post('/tools',");
+            expect(out).toContain("import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '@maroonedsoftware/koa';");
+            expect(out).toContain('const dispatcher = ctx.container.get(McpDispatcher);');
+        });
+
+        it('escapes the backticks in its own doc comment rather than closing the template', () => {
+            expect(koa.mcpRouter({ path: '/mcp' })).toContain('Bind `registerMcpTools` to the `McpToolHandlerMap` token.');
+        });
+    });
+});

package/tests/server-framework.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { resolveServerFramework, SERVER_FRAMEWORK_NAMES, SERVER_FRAMEWORKS, DEFAULT_SERVER_FRAMEWORK_NAME } from '../src/server-framework.js';
+
+describe('resolveServerFramework', () => {
+    it('defaults to koa when the config names none', () => {
+        expect(resolveServerFramework(undefined).name).toBe('koa');
+        expect(DEFAULT_SERVER_FRAMEWORK_NAME).toBe('koa');
+    });
+
+    it('resolves a supported name', () => {
+        expect(resolveServerFramework('koa').name).toBe('koa');
+        expect(resolveServerFramework('fastify').name).toBe('fastify');
+    });
+
+    it('rejects an unsupported name, naming what is supported', () => {
+        expect(() => resolveServerFramework('express')).toThrow(/server\.framework 'express' is not supported/);
+        expect(() => resolveServerFramework('express')).toThrow(/expected one of: koa/);
+    });
+
+    it('has an adapter for every declared name', () => {
+        for (const name of SERVER_FRAMEWORK_NAMES) {
+            expect(SERVER_FRAMEWORKS[name]?.name).toBe(name);
+        }
+    });
+});