@contractkit/plugin-typescript 0.34.0 → 0.35.0

package/src/server-framework.ts

@@ -0,0 +1,119 @@
+import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
+
+/**
+ * HTTP frameworks the server sub-generator can target. Adding a name here without adding an adapter
+ * to {@link SERVER_FRAMEWORKS} fails to compile, which is the point of keeping the two in step.
+ */
+export const SERVER_FRAMEWORK_NAMES = ['koa'] as const;
+
+/** One of {@link SERVER_FRAMEWORK_NAMES}. */
+export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
+
+/** The framework assumed when a config names none. */
+export const DEFAULT_SERVER_FRAMEWORK_NAME: ServerFrameworkName = 'koa';
+
+/**
+ * Every framework-specific string the router and MCP router generators emit.
+ *
+ * Granularity is one statement (or one fragment) per method, so the shared codegen keeps ownership
+ * of control flow — which branches exist, what order they run in, and which values reach them — and
+ * an adapter only decides how a given step is spelled. Anything an adapter cannot express as a
+ * statement, such as ending a response, is returned as a list of lines so it can also be empty.
+ */
+export interface ServerFramework {
+    readonly name: ServerFrameworkName;
+
+    /**
+     * Import lines for the framework runtime, already filtered down to what the generated body uses.
+     *
+     * The adapter applies `uses` itself rather than declaring a symbol list, because a framework may
+     * need more than one import line, and because only names the adapter chooses ever go through the
+     * word-boundary probe — a handler-local identifier can never be mistaken for an import.
+     */
+    imports(uses: (symbol: string) => boolean): string[];
+
+    /** The module-level router value every handler attaches to. */
+    routerDeclaration(routerName: string): string;
+
+    /** Placeholder syntax for one path parameter, given a name already mapped to a valid identifier. */
+    pathParam(identifier: string): string;
+
+    /** Opening line of a handler, including its middleware and the handler function's parameters. */
+    routeOpen(routerName: string, method: string, path: string, middlewares: readonly string[]): string;
+
+    /** Lines that close a handler opened by {@link routeOpen}. */
+    routeClose(): string[];
+
+    /** Route middleware factory calls, rendered as expressions for {@link routeOpen}. */
+    readonly middleware: {
+        policy(args: string): string;
+        bodyParser(tokensExpr: string): string;
+        signature(args: string): string;
+    };
+
+    /** Expressions a handler reads the request through. */
+    readonly request: {
+        params: string;
+        query: string;
+        headers: string;
+        /** The body already parsed by the body-parser middleware. */
+        parsedBody: string;
+        /**
+         * The request's media type with any parameters stripped. It is matched against declared MIME
+         * literals, so an adapter whose framework exposes only the raw header must normalise it here
+         * — a `; charset=utf-8` left on the end matches nothing.
+         */
+        contentType: string;
+    };
+
+    /** Expression resolving a service class out of the request-scoped DI container. */
+    resolveService(className: string): string;
+
+    /** Statements a handler writes the response with. */
+    readonly response: {
+        status(expr: string): string;
+        /**
+         * One statement setting a response header. It is emitted bare or behind an `if` guard for an
+         * optional header, so it must stay a single statement.
+         */
+        header(name: string, valueExpr: string): string;
+        type(expr: string): string;
+        /**
+         * The terminal write for a response, or for one without a body when `bodyExpr` is undefined.
+         * A framework that ends a response by returning needs a statement in both cases; Koa, which
+         * ends it by assignment, emits nothing for a bodyless one.
+         */
+        send(bodyExpr: string | undefined): string[];
+        /** What closes one `case` of the multi-status switch, after that status has been written. */
+        caseEnd(): string[];
+    };
+
+    /** The whole `mcp.router.ts` file, which is boilerplate rather than a per-operation render. */
+    mcpRouter(options: { path: string }): string;
+}
+
+/**
+ * Every supported framework, keyed by name. The annotation is what ties this to
+ * {@link SERVER_FRAMEWORK_NAMES}: adding a name without an adapter is a compile error.
+ */
+export const SERVER_FRAMEWORKS: Readonly<Record<ServerFrameworkName, ServerFramework>> = {
+    koa: KOA_SERVER_FRAMEWORK,
+};
+
+/**
+ * Resolve a configured framework name to its adapter.
+ *
+ * @param name The `server.framework` value, or undefined for {@link DEFAULT_SERVER_FRAMEWORK_NAME}.
+ * @throws When `name` is not a supported framework. Config arrives as JSON, so this is a runtime
+ *   check and not something the `ServerFrameworkName` type can enforce on its own.
+ */
+export function resolveServerFramework(name: string | undefined): ServerFramework {
+    const resolved = name ?? DEFAULT_SERVER_FRAMEWORK_NAME;
+    const framework = (SERVER_FRAMEWORKS as Record<string, ServerFramework | undefined>)[resolved];
+    if (!framework) {
+        throw new Error(
+            `plugin-typescript: server.framework '${resolved}' is not supported — expected one of: ${SERVER_FRAMEWORK_NAMES.join(', ')}.`,
+        );
+    }
+    return framework;
+}

package/tests/codegen-mcp.test.ts

@@ -141,6 +141,16 @@ describe('generateMcpFile', () => {
             expect(out).toContain('const CreatePaymentArgs = z.object({ body: PaymentInput });');
             expect(out).toContain('const { body } = await parseAndValidate(args, CreatePaymentArgs);');
         });
+
+        it('underscores the args param when the op takes no arguments', () => {
+            const root = opRoot([opRoute('/health', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Health', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            // Nothing destructures `args` here, so an un-prefixed name trips no-unused-vars in
+            // consumers that lint generated output.
+            expect(out).toContain('async handle(_args: Record<string, unknown>, _context: McpToolContext)');
+            expect(out).not.toContain('async handle(args:');
+            expect(out).not.toContain('parseAndValidate');
+        });
     });
 
     describe('service call + result', () => {
@@ -220,7 +230,13 @@ describe('generateMcpAggregator', () => {
         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 });');
+        expect(out).toContain('return map;');
+    });
+
+    it('only builds the map — Container has no register, that belongs to Registry', () => {
+        const out = generateMcpAggregator([{ registerFn: 'registerPaymentsMcpTools', importPath: './payments.mcp.js' }]);
+        expect(out).not.toContain('container.register');
+        expect(out).toContain('registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();');
     });
 });
 
@@ -233,6 +249,12 @@ describe('generateMcpRouter', () => {
         expect(out).toContain("dispatcher.sessionMode === 'stateful'");
     });
 
+    it('tells consumers to bind the aggregator rather than call it at startup', () => {
+        const out = generateMcpRouter();
+        expect(out).toContain('Bind `registerMcpTools` to the `McpToolHandlerMap` token.');
+        expect(out).not.toContain('Call `registerMcpTools(container)` at startup');
+    });
+
     it('parses the body before verifying the signature', () => {
         const out = generateMcpRouter({ path: '/mcp' });
         // `requireSignature` HMACs `ctx.rawBody`, which only `bodyParserMiddleware` populates,
@@ -264,6 +286,18 @@ describe('generateMcpRouter', () => {
         expect(out).not.toContain('ctx.request.body');
     });
 
+        it('delegates the whole file to the framework adapter', () => {
+            const stub = { mcpRouter: ({ path }: { path: string }) => `// stub mount at ${path}` };
+            // Only `mcpRouter` is reachable from here, so the rest of the adapter is left off the stub.
+            const out = generateMcpRouter({ framework: stub as never });
+            expect(out).toBe('// stub mount at /mcp');
+        });
+
+        it('passes a configured path through to the adapter', () => {
+            const stub = { mcpRouter: ({ path }: { path: string }) => `// stub mount at ${path}` };
+            expect(generateMcpRouter({ path: '/tools', framework: stub as never })).toBe('// stub mount at /tools');
+        });
+
     it('defaults the mount path to /mcp', () => {
         expect(generateMcpRouter()).toContain("router.post('/mcp'");
     });

package/tests/codegen-operation-framework.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from 'vitest';
+import { generateOp } from '../src/codegen-operation.js';
+import type { ServerFramework } from '../src/server-framework.js';
+import { scalarType, refType, opParam, opRequest, opMultiRequest, opResponse, opResponseMulti, opOperation, opRoute, opRoot } from './helpers.js';
+
+/**
+ * A framework whose every string is unmistakable. Rendering a router through it and finding no Koa
+ * left in the output is what proves the seam is complete: a `ctx.` the generator still emits inline
+ * would survive this substitution, and a `toContain` test against the Koa output never notices,
+ * because the default adapter puts the very same string there.
+ */
+const STUB: ServerFramework = {
+    // The registry's key type admits only shipped frameworks; the adapter under test is a fake.
+    name: 'koa',
+    imports: uses => (uses('StubRouter') ? ["import { StubRouter } from '@stub/http';"] : []),
+    routerDeclaration: routerName => `export const ${routerName} = StubRouter();`,
+    pathParam: identifier => `<${identifier}>`,
+    routeOpen: (routerName, method, path, middlewares) => `${routerName}.route('${method}', '${path}', [${middlewares.join(', ')}], async (rq, rs) => {`,
+    routeClose: () => ['}, END);'],
+    middleware: {
+        policy: args => `stubPolicy(${args})`,
+        bodyParser: tokens => `stubBody(${tokens})`,
+        signature: args => `stubSignature(${args})`,
+    },
+    request: {
+        params: 'rq.pathParams',
+        query: 'rq.searchParams',
+        headers: 'rq.headerBag',
+        parsedBody: 'rq.payload',
+        contentType: 'rq.mediaType',
+    },
+    resolveService: className => `rq.services.resolve(${className})`,
+    response: {
+        status: expr => `rs.setStatus(${expr});`,
+        header: (name, valueExpr) => `rs.putHeader('${name}', ${valueExpr});`,
+        type: expr => `rs.setMedia(${expr});`,
+        send: bodyExpr => (bodyExpr === undefined ? ['return rs.finish();'] : [`return rs.deliver(${bodyExpr});`]),
+        caseEnd: () => [],
+    },
+    mcpRouter: ({ path }) => `// stub mcp at ${path}\n`,
+};
+
+/** One op root touching every branch of the generator that can emit a framework string. */
+function everyBranchRoot() {
+    return opRoot([
+        opRoute(
+            '/payments/{paymentId}',
+            [
+            // Path params + query + headers + a single JSON body, with policy and signature middleware.
+            opOperation('post', {
+                request: opRequest('Payment'),
+                query: [opParam('limit', scalarType('int'))],
+                headers: [opParam('x-tenant', scalarType('string'))],
+                signature: 'stripe',
+                responses: [opResponse(201, 'Payment')],
+            }),
+            // Several request MIMEs with different shapes — the content-type switch.
+            opOperation('put', {
+                request: opMultiRequest([
+                    ['application/json', 'Payment'],
+                    ['multipart/form-data', 'Receipt'],
+                ]),
+                responses: [opResponse(200, 'Payment')],
+            }),
+            // No emitted body at all — the bodyless 204 path.
+            opOperation('delete', { responses: [] }),
+            // Several emitted statuses, one carrying response headers — the status switch.
+            opOperation('patch', {
+                responses: [
+                    opResponseMulti(200, [{ contentType: 'application/json', bodyType: 'Payment' }], {
+                        headers: [{ name: 'etag', optional: false, type: scalarType('string') }],
+                    }),
+                    opResponseMulti(202, [{ contentType: 'application/json', bodyType: refType('Payment') }], {
+                        headers: [{ name: 'retry-after', optional: true, type: scalarType('string') }],
+                    }),
+                ],
+            }),
+            ],
+            [opParam('paymentId', scalarType('uuid'))],
+        ),
+    ]);
+}
+
+describe('generateOp — framework seam', () => {
+    const output = generateOp(everyBranchRoot(), { framework: STUB });
+
+    it('leaves no Koa string anywhere in the output', () => {
+        expect(output).not.toMatch(/\bctx\b/);
+        expect(output).not.toContain('ServerKitRouter');
+        expect(output).not.toContain('@maroonedsoftware/koa');
+        expect(output).not.toContain('requirePolicy');
+        expect(output).not.toContain('bodyParserMiddleware');
+        expect(output).not.toContain('requireSignature');
+    });
+
+    it('renders the router shell through the adapter', () => {
+        expect(output).toContain('export const UsersRouter = StubRouter();');
+        expect(output).toContain("import { StubRouter } from '@stub/http';");
+        expect(output).toContain('}, END);');
+    });
+
+    it('renders the route line, its path params and its middleware through the adapter', () => {
+        expect(output).toContain("UsersRouter.route('post', '/payments/<paymentId>', [stubPolicy(), stubBody('json'), stubSignature('stripe')], async (rq, rs) => {");
+    });
+
+    it('reads params, query, headers and the body through the adapter', () => {
+        expect(output).toContain('rq.pathParams');
+        expect(output).toContain('rq.searchParams');
+        expect(output).toContain('rq.headerBag');
+        expect(output).toContain('rq.payload');
+        expect(output).toContain('switch (rq.mediaType) {');
+    });
+
+    it('resolves services through the adapter', () => {
+        expect(output).toContain('rq.services.resolve(UsersService)');
+    });
+
+    it('writes status, headers, content type and body through the adapter', () => {
+        expect(output).toContain('rs.setStatus(201);');
+        expect(output).toContain("rs.setMedia('application/json');");
+        expect(output).toContain('return rs.deliver(result);');
+        expect(output).toContain('rs.putHeader(\'etag\', String(result.headers["etag"]));');
+        expect(output).toContain('if (result.headers["retryAfter"] !== undefined) rs.putHeader(\'retry-after\', String(result.headers["retryAfter"]));');
+    });
+
+    it('gives a bodyless response the adapter\'s terminal statement', () => {
+        // Koa needs none, so the generator only emits one because the adapter asked for it.
+        expect(output).toContain('rs.setStatus(204);');
+        expect(output).toContain('return rs.finish();');
+    });
+
+    it('omits the status-case terminator when the adapter has none', () => {
+        expect(output).toContain('rs.setStatus(result.status);');
+        // Scoped to the status switch: the multi-MIME request dispatch is the generator's own control
+        // flow and keeps its `break;` whatever the framework is.
+        const statusSwitch = output.slice(output.indexOf('switch (result.status) {'));
+        expect(statusSwitch).toContain('case 202:');
+        expect(statusSwitch).not.toContain('break;');
+    });
+});

package/tests/codegen-operation.test.ts

@@ -567,6 +567,35 @@ describe('generateOperation', () => {
             expect(output).toContain('z.object({');
         });
 
+        it('renders an inline array header through renderInputType, without the query coercion', () => {
+            // The comma-splitting preprocess belongs to query strings only. Headers and params share
+            // the same inline-param renderer, so the block has to be told which one it is rendering.
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        headers: [opParam('x-tags', arrayType(scalarType('string')))],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('ctx.headers');
+            expect(output).not.toContain('z.preprocess');
+            expect(output).not.toContain("v.split(',')");
+        });
+
+        it('declares headers as a whole object rather than destructuring it', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        headers: [opParam('authorization', scalarType('string'))],
+                    }),
+                ]),
+            ]);
+            const output = generateOp(root);
+            expect(output).toContain('const headers = await parseAndValidate(');
+            expect(output).not.toContain('const { authorization }');
+        });
+
         it('generates parseAndValidate import when operation has headers', () => {
             const root = opRoot([
                 opRoute('/users', [

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-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,24 @@
+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');
+    });
+
+    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);
+        }
+    });
+});