@contractkit/plugin-typescript 0.34.0 → 0.35.0

package/dist/server-framework-koa.d.ts

@@ -0,0 +1,7 @@
+import type { ServerFramework } from './server-framework.js';
+/**
+ * ServerKit on Koa: the router is a `@koa/router` instance, handlers take a single `ctx`, and a
+ * response is written by assigning to `ctx.status` / `ctx.type` / `ctx.body` rather than returned.
+ */
+export declare const KOA_SERVER_FRAMEWORK: ServerFramework;
+//# sourceMappingURL=server-framework-koa.d.ts.map

package/dist/server-framework-koa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-framework-koa.d.ts","sourceRoot":"","sources":["../src/server-framework-koa.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAW7D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAgGlC,CAAC"}

package/dist/server-framework.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 declare const SERVER_FRAMEWORK_NAMES: readonly ["koa"];
+/** One of {@link SERVER_FRAMEWORK_NAMES}. */
+export type ServerFrameworkName = (typeof SERVER_FRAMEWORK_NAMES)[number];
+/** The framework assumed when a config names none. */
+export declare const DEFAULT_SERVER_FRAMEWORK_NAME: ServerFrameworkName;
+/**
+ * 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 declare const SERVER_FRAMEWORKS: Readonly<Record<ServerFrameworkName, ServerFramework>>;
+/**
+ * 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 declare function resolveServerFramework(name: string | undefined): ServerFramework;
+//# sourceMappingURL=server-framework.d.ts.map

package/dist/server-framework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-framework.d.ts","sourceRoot":"","sources":["../src/server-framework.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,sBAAsB,kBAAmB,CAAC;AAEvD,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,sDAAsD;AACtD,eAAO,MAAM,6BAA6B,EAAE,mBAA2B,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,EAAE,CAAC;IAErD,+DAA+D;IAC/D,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAE9C,oGAAoG;IACpG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtC,iGAAiG;IACjG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IAEpG,8DAA8D;IAC9D,UAAU,IAAI,MAAM,EAAE,CAAC;IAEvB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE;QACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;QACvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;KACnC,CAAC;IAEF,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,6DAA6D;QAC7D,UAAU,EAAE,MAAM,CAAC;QACnB;;;;WAIG;QACH,WAAW,EAAE,MAAM,CAAC;KACvB,CAAC;IAEF,mFAAmF;IACnF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE;QACf,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC7B;;;WAGG;QACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC3B;;;;WAIG;QACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAAC;QAC7C,6FAA6F;QAC7F,OAAO,IAAI,MAAM,EAAE,CAAC;KACvB,CAAC;IAEF,+FAA+F;IAC/F,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAEpF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAShF"}

package/llms.txt

@@ -56,7 +56,7 @@ Path templates accept `{filename}`, `{dir}`, `{area}`, and — in `sdk.output.sd
 
 | Key | Emits |
 | --- | --- |
-| `server` | Koa routers from `operation` declarations, plus the type or Zod files they import |
+| `server` | Server routers from `operation` declarations, plus the type or Zod files they import. `framework` selects the HTTP framework; only `koa` today |
 | `sdk` | The SDK class, per-area operation clients, and their types |
 | `zod` | Standalone Zod schemas, independent of `server` and `sdk` |
 | `types` | Standalone plain TypeScript types, independent of `server` and `sdk` |
@@ -82,6 +82,20 @@ Options worth knowing:
   schema for argument validation and `z.toJSONSchema`. It falls back to `server.output.types` (when
   `server.zod`) or the `zod` sub-config's output.
 
+## Wiring the MCP tools
+
+`mcp.tools.ts` exports `registerMcpTools(container)`, which **builds and returns** the
+`McpToolHandlerMap`. It registers nothing: `register` belongs to InjectKit's `Registry`
+(composition phase), while a `Container` (resolution phase) only resolves. Bind the aggregator from
+a factory, which is also what supplies the `Container` it needs:
+
+```typescript
+registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();
+```
+
+The emitted tool classes are not registered for you either, so register each one on the same
+`Registry` before the aggregator resolves it.
+
 ## Programmatic use
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {

package/src/codegen-mcp.ts

@@ -5,6 +5,8 @@ import { inferService, deriveModulePath, buildArgs, deriveBaseName } from './cod
 import { quoteKey, escapeSingleQuoted, sourceLink } from './ts-render.js';
 import { DECIMAL_IMPORT, DECIMAL_PRELUDE_LINES } from './decimal-runtime.js';
 import { basename, dirname, relative } from 'node:path';
+import type { ServerFramework } from './server-framework.js';
+import { KOA_SERVER_FRAMEWORK } from './server-framework-koa.js';
 
 // ─── Options ────────────────────────────────────────────────────────────────
 
@@ -372,7 +374,10 @@ function renderToolClass(plan: ToolPlan, file: string, options: McpCodegenOption
     const isVoid = !primaryResponseBody(op);
     const structured = !!outExpr;
 
-    lines.push('    async handle(args: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {');
+    // No args to destructure means the parameter goes unread, which trips no-unused-vars in
+    // consumers that lint generated output; the leading underscore opts it out.
+    const argsParam = destructure.length > 0 ? 'args' : '_args';
+    lines.push(`    async handle(${argsParam}: Record<string, unknown>, _context: McpToolContext): Promise<CallToolResult> {`);
     if (destructure.length > 0) {
         lines.push(`        const { ${destructure.join(', ')} } = await parseAndValidate(args, ${argsConstName});`);
     }
@@ -477,39 +482,31 @@ export function generateMcpAggregator(entries: McpAggregatorEntry[]): string {
     lines.push(`import { McpToolHandlerMap } from '@maroonedsoftware/mcp';`);
     for (const e of sorted) lines.push(`import { ${e.registerFn} } from '${e.importPath}';`);
     lines.push('');
-    lines.push('/** Build + register the MCP tool catalog. Call once at startup. */');
+    lines.push('/**');
+    lines.push(' * Build the MCP tool catalog.');
+    lines.push(' *');
+    lines.push(' * Bind it to the `McpToolHandlerMap` token from a factory, which is what supplies the');
+    lines.push(' * `Container` needed to resolve each handler:');
+    lines.push(' *');
+    lines.push(' * ```ts');
+    lines.push(' * registry.register(McpToolHandlerMap).useFactory(registerMcpTools).asSingleton();');
+    lines.push(' * ```');
+    lines.push(' */');
     lines.push('export function registerMcpTools(container: Container): McpToolHandlerMap {');
     lines.push('    const map = new McpToolHandlerMap();');
     for (const e of sorted) lines.push(`    ${e.registerFn}(map, container);`);
-    lines.push('    container.register(McpToolHandlerMap, { useValue: map });');
     lines.push('    return map;');
     lines.push('}');
     return lines.join('\n') + '\n';
 }
 
-/** Generate the optional `mcp.router.ts` — the standard ServerKit route wiring for the dispatcher. */
-export function generateMcpRouter(options: { path?: string } = {}): string {
-    const path = options.path ?? '/mcp';
-    return `import { ServerKitRouter, bodyParserMiddleware, requireSignature } from '@maroonedsoftware/koa';
-import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';
-
-/** Mount the MCP endpoint onto a ServerKit router. Call \`registerMcpTools(container)\` at startup. */
-export function mountMcp(router: ReturnType<typeof ServerKitRouter>): void {
-    router.post('${path}', bodyParserMiddleware(['json']), requireSignature('mcp', { policy: MCP_AUTH_POLICY }), async (ctx) => {
-        const dispatcher = ctx.container.get(McpDispatcher);
-        const context = createMcpRequestContext({ requestId: ctx.requestId, logger: ctx.logger });
-        if (dispatcher.sessionMode === 'stateful') {
-            ctx.respond = false;
-            await dispatcher.dispatchStateful(
-                { req: ctx.req, res: ctx.res, body: ctx.parsedBody, sessionId: ctx.get('mcp-session-id') },
-                context,
-            );
-        } else {
-            const response = await dispatcher.dispatch(JSON.parse(String(ctx.rawBody)), context);
-            if (response) ctx.body = response;
-            else ctx.status = 202; // a notification — nothing to return
-        }
-    });
-}
-`;
+/**
+ * Generate the optional `mcp.router.ts` — the standard ServerKit route wiring for the dispatcher.
+ *
+ * The whole file is framework-specific boilerplate rather than a per-operation render, so the
+ * adapter owns the template. Defaults to Koa, matching the router generator.
+ */
+export function generateMcpRouter(options: { path?: string; framework?: ServerFramework } = {}): string {
+    const framework = options.framework ?? KOA_SERVER_FRAMEWORK;
+    return framework.mcpRouter({ path: options.path ?? '/mcp' });
 }