@contractkit/plugin-typescript 0.34.1 → 0.36.0

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

@@ -0,0 +1,8 @@
+import type { ServerFramework } from './server-framework.js';
+/**
+ * ServerKit on Fastify: `ServerKitRouter()` collects routes the way a Koa app reads and mounts them
+ * as a Fastify plugin, handlers take `(request, reply)` where the request *is* the ServerKit
+ * context, and a response is sent by returning `reply.send(...)` rather than by assignment.
+ */
+export declare const FASTIFY_SERVER_FRAMEWORK: ServerFramework;
+//# sourceMappingURL=server-framework-fastify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-framework-fastify.d.ts","sourceRoot":"","sources":["../src/server-framework-fastify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAc7D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,eA4GtC,CAAC"}

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,eAkGlC,CAAC"}

package/dist/server-framework.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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", "fastify"];
+/** 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;
+    /**
+     * Identifiers the handler signature itself binds — `ctx`, or `request` and `reply`. A path
+     * parameter is destructured into the handler body, so one declared with the same name would
+     * shadow the handler's own parameter: a redeclaration under `tsc`, and a temporal-dead-zone
+     * `ReferenceError` at runtime. Codegen renames the local binding to avoid these.
+     */
+    readonly handlerLocals: readonly 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":"AAGA;;;GAGG;AACH,eAAO,MAAM,sBAAsB,6BAA8B,CAAC;AAElE,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;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C,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,CAGpF,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: `koa` or `fastify` |
 | `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` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.34.1",
-  "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
+  "version": "0.36.0",
+  "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa or Fastify routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {
     "name": "Marooned Software",

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 ────────────────────────────────────────────────────────────────
 
@@ -498,29 +500,13 @@ export function generateMcpAggregator(entries: McpAggregatorEntry[]): string {
     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. Bind \`registerMcpTools\` to the \`McpToolHandlerMap\` token. */
-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' });
 }