counterfact 2.11.0 → 2.14.0

package/dist/server/registry.js

@@ -1,7 +1,7 @@
 import createDebugger from "debug";
 import { ModuleTree } from "./module-tree.js";
 const debug = createDebugger("counterfact:server:registry");
-const ALL_HTTP_METHODS = [
+const DEFAULT_HTTP_METHODS = [
     "DELETE",
     "GET",
     "HEAD",
@@ -9,6 +9,7 @@ const ALL_HTTP_METHODS = [
     "PATCH",
     "POST",
     "PUT",
+    "QUERY",
     "TRACE",
 ];
 /**
@@ -60,6 +61,7 @@ function castParameters(parameters = {}, parameterTypes = new Map()) {
 export class Registry {
     moduleTree = new ModuleTree();
     middlewares = new Map();
+    methodNames = new Set(DEFAULT_HTTP_METHODS);
     constructor() {
         this.middlewares.set("", ($, respondTo) => respondTo($));
     }
@@ -75,6 +77,9 @@ export class Registry {
      */
     add(url, module) {
         this.moduleTree.add(url, module);
+        for (const methodName of Object.keys(module)) {
+            this.methodNames.add(methodName.toUpperCase());
+        }
     }
     /**
      * Registers a middleware function that wraps every handler under `url`.
@@ -102,8 +107,20 @@ export class Registry {
      * @param method - HTTP method (e.g. `"GET"`).
      * @param url - The request URL.
      */
+    methodFromModule(module, method) {
+        if (module === undefined) {
+            return undefined;
+        }
+        return (module[method] ??
+            module[method.toUpperCase()] ??
+            module[method.toLowerCase()]);
+    }
     exists(method, url) {
-        return Boolean(this.handler(url, method).module?.[method]);
+        return (this.methodFromModule(this.handler(url, method).module, method) !==
+            undefined);
+    }
+    methodsForPath(url) {
+        return [...this.methodNames].filter((method) => this.methodFromModule(this.moduleTree.match(url, method)?.module, method) !== undefined);
     }
     /**
      * Finds the best-matching module and extracts path-variable bindings for a
@@ -133,7 +150,7 @@ export class Registry {
      * @param excludeMethod - The method to exclude from the check.
      */
     pathExistsWithAnyMethod(url, excludeMethod) {
-        return ALL_HTTP_METHODS.filter((method) => method !== excludeMethod).some((method) => this.moduleTree.match(url, method) !== undefined);
+        return this.methodsForPath(url).some((method) => method.toUpperCase() !== excludeMethod.toUpperCase());
     }
     /**
      * Returns a comma-separated list of HTTP methods that have a registered
@@ -143,7 +160,7 @@ export class Registry {
      * @param url - The request URL.
      */
     allowedMethods(url) {
-        return ALL_HTTP_METHODS.filter((method) => Boolean(this.moduleTree.match(url, method)?.module?.[method])).join(", ");
+        return this.methodsForPath(url).join(", ");
     }
     /**
      * Returns an async function that executes the registered handler for
@@ -169,7 +186,7 @@ export class Registry {
                 status: 500,
             });
         }
-        const execute = handler.module?.[httpRequestMethod];
+        const execute = this.methodFromModule(handler.module, httpRequestMethod);
         if (!execute) {
             debug(`Could not find a ${httpRequestMethod} method matching ${url}\n`);
             return () => ({

package/dist/server/request-validator.js

@@ -62,6 +62,7 @@ export function validateRequest(operation, request) {
     // by the registry before the route handler is called.
     errors.push(...findMissingRequired(parameters, "query", request.query));
     errors.push(...findMissingRequired(parameters, "header", request.headers));
+    errors.push(...findMissingRequired(parameters, "cookie", request.cookie));
     // Validate request body (OpenAPI 3.x requestBody)
     if (operation.requestBody?.content !== undefined) {
         const schema = operation.requestBody.content["application/json"]?.schema ??

package/dist/server/response-builder.js

@@ -1,5 +1,7 @@
 import { generate } from "json-schema-faker";
+/* eslint-disable security/detect-object-injection -- OpenAPI response/content maps are spec-defined dictionaries accessed by status code, media type, and example name. */
 import { jsonToXml } from "./json-to-xml.js";
+import { STREAMING_CONTENT_TYPES } from "../typescript-generator/streaming-content-types.js";
 const DEFAULT_GENERATE_OPTIONS = {
     useExamplesValue: true,
     minItems: 0,
@@ -154,10 +156,16 @@ export function createResponseBuilder(operation, config) {
                 }
                 return {
                     ...this,
-                    content: Object.keys(content).map((type) => ({
-                        body: convertToXmlIfNecessary(type, content[type]?.examples?.[name]?.value, content[type]?.schema),
-                        type,
-                    })),
+                    content: Object.keys(content).map((type) => {
+                        const example = content[type]?.examples?.[name];
+                        const body = example !== undefined && "dataValue" in example
+                            ? example.dataValue
+                            : example?.value;
+                        return {
+                            body: convertToXmlIfNecessary(type, body, content[type]?.schema),
+                            type,
+                        };
+                    }),
                 };
             },
             async random() {
@@ -188,7 +196,9 @@ export function createResponseBuilder(operation, config) {
                     ...this,
                     content: await Promise.all(Object.keys(content).map(async (type) => ({
                         body: convertToXmlIfNecessary(type, content[type]?.examples
-                            ? oneOf(Object.values(content[type]?.examples ?? []).map((example) => example.value))
+                            ? oneOf(Object.values(content[type]?.examples ?? []).map((example) => "dataValue" in example
+                                ? example.dataValue
+                                : example.value))
                             : await generate((content[type]?.schema ?? {
                                 type: "object",
                             }), generateOptions), content[type]?.schema),
@@ -217,6 +227,19 @@ export function createResponseBuilder(operation, config) {
                     })),
                 };
             },
+            stream(iterable) {
+                const response = operation.responses[this.status ?? "default"] ??
+                    operation.responses.default;
+                const contentTypes = Object.keys(response?.content ?? {});
+                const contentType = contentTypes.find((ct) => STREAMING_CONTENT_TYPES.has(ct)) ??
+                    "text/event-stream";
+                return {
+                    body: iterable,
+                    contentType,
+                    headers: this.headers,
+                    status: this.status,
+                };
+            },
             status: Number.parseInt(statusCode, 10),
             text(body) {
                 return this.match("text/plain", body);

package/dist/server/web-server/create-koa-app.js

@@ -1,3 +1,4 @@
+import { Readable } from "node:stream";
 import createDebug from "debug";
 import Koa from "koa";
 import bodyParser from "koa-bodyparser";
@@ -28,6 +29,7 @@ export function createKoaApp({ runners, config, }) {
         app.use(openapiMiddleware(`/counterfact/openapi${runner.subdirectory}`, {
             path: runner.openApiPath,
             baseUrl: `//localhost:${config.port}${runner.prefix}`,
+            overlays: runner.overlays,
         }));
         app.use(koaSwagger({
             routePrefix: `/counterfact/swagger${runner.subdirectory}`,
@@ -53,7 +55,8 @@ export function createKoaApp({ runners, config, }) {
         if (ctx.body !== null &&
             ctx.body !== undefined &&
             typeof ctx.body === "object" &&
-            !Buffer.isBuffer(ctx.body)) {
+            !Buffer.isBuffer(ctx.body) &&
+            !(ctx.body instanceof Readable)) {
             ctx.body = JSON.stringify(ctx.body, null, 2);
             ctx.type = "application/json";
         }

package/dist/server/web-server/openapi-middleware.js

@@ -1,5 +1,6 @@
 import { bundle } from "@apidevtools/json-schema-ref-parser";
 import { dump } from "js-yaml";
+import { applyOverlays } from "../../util/apply-overlay.js";
 /**
  * Returns a Koa middleware that serves a bundled OpenAPI document as YAML at
  * the given `pathPrefix`.
@@ -22,8 +23,12 @@ export function openapiMiddleware(pathPrefix, document) {
             return await next();
         }
         const openApiDocument = (await bundle(document.path));
+        if (document.overlays && document.overlays.length > 0) {
+            await applyOverlays(openApiDocument, document.overlays);
+        }
         openApiDocument.servers ??= [];
         openApiDocument.servers.unshift({
+            name: "Counterfact",
             description: "Counterfact",
             url: document.baseUrl,
         });

package/dist/server/web-server/routes-middleware.js

@@ -1,3 +1,4 @@
+import { Readable } from "node:stream";
 import createDebug from "debug";
 import koaProxy from "koa-proxies";
 import { isProxyEnabledForPath } from "../is-proxy-enabled-for-path.js";
@@ -19,6 +20,36 @@ const HEADERS_TO_DROP = new Set([
     "trailer",
     "trailers",
 ]);
+/**
+ * SSE/JSONL/JSON-seq formatter map. Each entry maps a content-type to the
+ * function that serialises a single stream item into the wire format.
+ */
+const STREAMING_FORMATTERS = new Map([
+    ["text/event-stream", (item) => `data: ${JSON.stringify(item)}\n\n`],
+    ["application/json-seq", (item) => `\x1e${JSON.stringify(item)}\n`],
+]);
+function defaultStreamFormatter(item) {
+    return `${JSON.stringify(item)}\n`;
+}
+function isAsyncIterable(value) {
+    return (value !== null &&
+        value !== undefined &&
+        typeof value === "object" &&
+        Symbol.asyncIterator in value);
+}
+/**
+ * Converts an `AsyncIterable` to a Node.js `Readable` stream, serialising
+ * each item according to the given content type.
+ */
+function asyncIterableToReadable(iterable, contentType) {
+    const formatter = STREAMING_FORMATTERS.get(contentType) ?? defaultStreamFormatter;
+    async function* generate() {
+        for await (const item of iterable) {
+            yield formatter(item);
+        }
+    }
+    return Readable.from(generate());
+}
 function addCors(ctx, allowedMethods, headers) {
     // Always append CORS headers, reflecting back the headers requested if any
     ctx.set("Access-Control-Allow-Origin", headers?.origin ?? "*");
@@ -92,7 +123,18 @@ export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
             rawBody: method === "HEAD" || method === "GET" ? undefined : rawBody,
             req: { path: "", ...ctx.req },
         });
-        ctx.body = response.body;
+        if (isAsyncIterable(response.body)) {
+            const contentType = response.contentType ?? "application/jsonl";
+            ctx.type = contentType;
+            ctx.body = asyncIterableToReadable(response.body, contentType);
+            if (contentType === "text/event-stream") {
+                ctx.set("Cache-Control", "no-cache");
+                ctx.set("X-Accel-Buffering", "no");
+            }
+        }
+        else {
+            ctx.body = response.body;
+        }
         if (response.contentType !== undefined &&
             response.contentType !== "unknown/unknown") {
             ctx.type = response.contentType;

package/dist/typescript-generator/code-generator.js

@@ -23,13 +23,15 @@ export class CodeGenerator extends EventTarget {
     openapiPath;
     destination;
     version;
+    overlays;
     generateOptions;
     watcher;
-    constructor(openApiPath, destination, generateOptions, version = "") {
+    constructor(openApiPath, destination, generateOptions, version = "", overlays = []) {
         super();
         this.openapiPath = openApiPath;
         this.destination = destination;
         this.version = version;
+        this.overlays = overlays;
         this.generateOptions = generateOptions;
     }
     /**
@@ -87,7 +89,7 @@ export class CodeGenerator extends EventTarget {
         await this.buildCacheDirectory(destination);
         debug("done initializing the .cache directory");
         debug("creating specification from %s", this.openapiPath);
-        const specification = await Specification.fromFile(this.openapiPath);
+        const specification = await Specification.fromFile(this.openapiPath, this.overlays);
         debug("created specification: $o", specification);
         debug("reading the #/paths from the specification");
         const paths = await this.getPathsFromSpecification(specification);
@@ -109,13 +111,22 @@ export class CodeGenerator extends EventTarget {
             "patch",
             "trace",
         ]);
+        const operationMethodsForPath = (pathDefinition) => pathDefinition.flatMap((operation, requestMethod) => {
+            if (requestMethod === "additionalOperations") {
+                return operation.map((additionalOperation, additionalMethod) => [
+                    additionalOperation,
+                    additionalMethod.toLowerCase(),
+                ]);
+            }
+            if (!HTTP_VERBS.has(requestMethod)) {
+                return [];
+            }
+            return [[operation, requestMethod]];
+        });
         paths.forEach((pathDefinition, key) => {
             debug("processing path %s", key);
             const path = key === "/" ? "/index" : key;
-            pathDefinition.forEach((operation, requestMethod) => {
-                if (!HTTP_VERBS.has(requestMethod)) {
-                    return;
-                }
+            operationMethodsForPath(pathDefinition).forEach(([operation, requestMethod]) => {
                 repository
                     .get(`routes${path}.ts`)
                     .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));
@@ -126,16 +137,20 @@ export class CodeGenerator extends EventTarget {
         debug("finished writing the files");
     }
     /**
-     * Starts watching the OpenAPI document for changes.
+     * Starts watching the OpenAPI document and any overlay files for changes.
      *
-     * Has no effect when `openApiPath` is a URL (HTTP sources are not watched).
+     * Has no effect when neither source is watchable (for example, an HTTP
+     * OpenAPI source with no local overlays).
      * Resolves once the watcher is ready.
      */
     async watch() {
-        if (this.openapiPath.startsWith("http")) {
+        const watchablePaths = this.openapiPath.startsWith("http")
+            ? [...this.overlays]
+            : [this.openapiPath, ...this.overlays];
+        if (watchablePaths.length === 0) {
             return;
         }
-        this.watcher = watch(this.openapiPath, CHOKIDAR_OPTIONS).on("change", () => {
+        this.watcher = watch(watchablePaths, CHOKIDAR_OPTIONS).on("change", () => {
             void this.generate().then(() => {
                 this.dispatchEvent(new Event("generate"));
                 return true;

package/dist/typescript-generator/coder.js

@@ -23,7 +23,7 @@ export class Coder {
      */
     get id() {
         if (this.requirement.isReference) {
-            return `${this.constructor.name}@${this.requirement.data["$ref"]}`;
+            return `${this.constructor.name}@${this.requirement.refUrl}`;
         }
         return `${this.constructor.name}@${this.requirement.url}`;
     }

package/dist/typescript-generator/jsdoc.js

@@ -3,14 +3,18 @@
  * Returns an empty string if there is no relevant metadata.
  */
 export function buildJsDoc(data) {
+    if (typeof data !== "object" || data === null) {
+        return "";
+    }
+    const record = data;
     const lines = [];
-    const description = data["description"];
-    const summary = data["summary"];
-    const example = data["example"];
-    const examples = data["examples"];
-    const defaultValue = data["default"];
-    const format = data["format"];
-    const deprecated = data["deprecated"];
+    const description = record["description"];
+    const summary = record["summary"];
+    const example = record["example"];
+    const examples = record["examples"];
+    const defaultValue = record["default"];
+    const format = record["format"];
+    const deprecated = record["deprecated"];
     const mainText = description ?? summary;
     if (mainText) {
         // Escape */ to prevent prematurely closing the JSDoc block

package/dist/typescript-generator/operation-coder.js

@@ -1,6 +1,7 @@
 import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
 import { OperationTypeCoder, VersionedArgTypeCoder, } from "./operation-type-coder.js";
+import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 /**
  * Generates the default route handler stub for a single OpenAPI operation.
  *
@@ -33,6 +34,19 @@ export class OperationCoder extends Coder {
             !("content" in firstResponse || "schema" in firstResponse)) {
             return `async ($) => {
         return $.response[${firstStatusCode === "default" ? 200 : firstStatusCode}].empty();
+      }`;
+        }
+        // Detect streaming responses (OpenAPI 3.2 itemSchema)
+        const content = firstResponse.content;
+        const hasStreamingContent = content !== undefined &&
+            Object.keys(content).some((ct) => STREAMING_CONTENT_TYPES.has(ct) &&
+                content[ct]?.itemSchema !== undefined);
+        if (hasStreamingContent) {
+            return `async ($) => {
+        async function* items() {
+          // yield items here
+        }
+        return $.response[${firstStatusCode === "default" ? 200 : firstStatusCode}].stream(items());
       }`;
         }
         return `async ($) => {

package/dist/typescript-generator/operation-type-coder.js

@@ -7,6 +7,7 @@ import { READ_ONLY_COMMENTS } from "./read-only-comments.js";
 import { RESERVED_WORDS } from "./reserved-words.js";
 import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
+import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 import { TypeCoder } from "./type-coder.js";
 import { Requirement } from "./requirement.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
@@ -105,11 +106,23 @@ export class OperationTypeCoder extends TypeCoder {
                 ? "number | undefined"
                 : Number.parseInt(responseCode, 10);
             if (response.has("content")) {
-                return response.get("content").map((content, contentType) => `{  
+                return response.get("content").map((content, contentType) => {
+                    let bodyType;
+                    if (content.has("itemSchema") &&
+                        STREAMING_CONTENT_TYPES.has(contentType)) {
+                        bodyType = `AsyncIterable<${new SchemaTypeCoder(content.get("itemSchema"), this.version).write(script)}>`;
+                    }
+                    else {
+                        bodyType = content.has("schema")
+                            ? new SchemaTypeCoder(content.get("schema"), this.version).write(script)
+                            : "unknown";
+                    }
+                    return `{  
               status: ${status}, 
               contentType?: "${contentType}",
-              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
-            }`);
+              body?: ${bodyType}
+            }`;
+                });
             }
             if (response.has("schema")) {
                 const producesReq = this.requirement?.get("produces") ??
@@ -150,6 +163,23 @@ export class OperationTypeCoder extends TypeCoder {
         }
         return "never";
     }
+    /**
+     * Returns the TypeScript type for the `auth` argument.
+     *
+     * Includes basic-auth credentials when present and `apiKey` when at least one
+     * apiKey security scheme is configured.
+     */
+    authType() {
+        const fields = new Set();
+        if (this.securitySchemes.some(({ scheme, type }) => type === "http" && scheme === "basic")) {
+            fields.add("username?: string");
+            fields.add("password?: string");
+        }
+        if (this.securitySchemes.some(({ type }) => type === "apiKey")) {
+            fields.add("apiKey: string");
+        }
+        return fields.size === 0 ? "never" : `{${[...fields].join(", ")}}`;
+    }
     /**
      * Returns the effective parameters for this operation by merging path-item-level
      * parameters with operation-level parameters. Per the OpenAPI specification,
@@ -165,16 +195,32 @@ export class OperationTypeCoder extends TypeCoder {
     getEffectiveParameters() {
         const operationParams = this.requirement.get("parameters");
         const pathItemParams = this.requirement.parent?.get("parameters");
-        if (!pathItemParams) {
+        const apiKeyParameters = this.securitySchemes
+            .filter(({ in: location, name, type }) => type === "apiKey" &&
+            typeof name === "string" &&
+            (location === "header" ||
+                location === "query" ||
+                location === "cookie"))
+            .map(({ in: location, name }) => ({
+            in: location,
+            name,
+            required: true,
+            schema: { type: "string" },
+        }));
+        if (!pathItemParams && !operationParams && apiKeyParameters.length === 0) {
+            return undefined;
+        }
+        if (!pathItemParams && apiKeyParameters.length === 0) {
             return operationParams;
         }
-        if (!operationParams) {
+        if (!operationParams && apiKeyParameters.length === 0) {
             return pathItemParams;
         }
         // Merge using a Map keyed on `${in}:${name}`.
-        // Path-level params are added first; operation-level overrides them.
-        const pathData = pathItemParams.data;
-        const opData = operationParams.data;
+        // Path-level params are added first; operation-level and security-level
+        // params override them.
+        const pathData = pathItemParams?.data ?? [];
+        const opData = operationParams?.data ?? [];
         const map = new Map();
         for (const p of pathData) {
             map.set(`${p.in}:${p.name}`, p);
@@ -182,6 +228,9 @@ export class OperationTypeCoder extends TypeCoder {
         for (const p of opData) {
             map.set(`${p.in}:${p.name}`, p);
         }
+        for (const p of apiKeyParameters) {
+            map.set(`${p.in}:${p.name}`, p);
+        }
         return new Requirement([...map.values()], this.requirement.url, this.requirement.specification);
     }
     /**
@@ -224,8 +273,15 @@ export class OperationTypeCoder extends TypeCoder {
         const pathTypeName = this.exportParameterType(script, "path", pathType, baseName, modulePath);
         const headersTypeName = this.exportParameterType(script, "headers", headersType, baseName, modulePath);
         const cookieTypeName = this.exportParameterType(script, "cookie", cookieType, baseName, modulePath);
+        // OpenAPI 3.2 querystring parameter: the entire query string treated as a
+        // single typed object (similar to requestBody for query strings).
+        const querystringParam = parameters?.find((parameter) => parameter.get("in")?.data === "querystring");
+        const querystringType = querystringParam?.has("schema") === true
+            ? new SchemaTypeCoder(querystringParam.get("schema"), this.version).write(script)
+            : "never";
+        const querystringTypeName = this.exportParameterType(script, "querystring", querystringType, baseName, modulePath);
         const versionLiteralType = this.version !== "" ? `"${this.version}"` : "never";
-        return `OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType}, version: ${versionLiteralType} }>`;
+        return `OmitValueWhenNever<{ query: ${queryTypeName}, querystring: ${querystringTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, auth: ${this.authType()}, user: ${this.userType()}, delay: ${delayType}, version: ${versionLiteralType} }>`;
     }
     writeCode(script) {
         script.comments = READ_ONLY_COMMENTS;

package/dist/typescript-generator/repository.js

@@ -70,9 +70,11 @@ export class Repository {
     /**
      * Waits for all scripts to finish, then writes each one to disk.
      *
-     * Route files (`routes/…`) are never overwritten if they already exist on
-     * disk, preserving user edits.  Type files (`types/…`) are always
-     * overwritten.
+     * Route files (`routes/…`) are never fully overwritten if they already exist
+     * on disk, preserving user edits.  However, if the generated script contains
+     * HTTP-method handler exports that are absent from the existing file, those
+     * new exports (and their `import type` statements) are appended to the file.
+     * Type files (`types/…`) are always overwritten.
      *
      * @param destination - Absolute path to the output root directory.
      * @param options - Controls which artefacts are written.
@@ -87,13 +89,16 @@ export class Repository {
             await ensureDirectoryExists(fullPath);
             const shouldWriteRoutes = routes && path.startsWith("routes");
             const shouldWriteTypes = types && !path.startsWith("routes");
-            if (shouldWriteRoutes &&
-                (await fs
+            if (shouldWriteRoutes) {
+                const fileExists = await fs
                     .stat(fullPath)
                     .then((stat) => stat.isFile())
-                    .catch(() => false))) {
-                debug(`not overwriting ${fullPath}\n`);
-                return;
+                    .catch(() => false);
+                if (fileExists) {
+                    debug(`route file exists, checking for new handlers: ${fullPath}`);
+                    await this.appendNewHandlers(fullPath, contents.replaceAll(CONTEXT_FILE_TOKEN, this.findContextPath(destination, path)));
+                    return;
+                }
             }
             if (shouldWriteRoutes || shouldWriteTypes) {
                 debug("about to write", fullPath);
@@ -139,6 +144,90 @@ export class Context {
 }
 `);
     }
+    /**
+     * Appends any HTTP-method handler exports that appear in `generatedContent`
+     * but are absent from the existing file at `fullPath`.
+     *
+     * For each new export the corresponding `import type` statement is inserted
+     * after the last existing import line (or prepended when no imports exist),
+     * and the export block is appended at the end of the file.
+     *
+     * @param fullPath - Absolute path of the route file to update.
+     * @param generatedContent - The fully-generated file content (used as the
+     *   source of new import and export statements).
+     */
+    async appendNewHandlers(fullPath, generatedContent) {
+        const existingContent = await fs.readFile(fullPath, "utf8");
+        // Names already exported by the existing file (e.g. GET, POST).
+        // RegExp match groups are typed as optional strings, so narrow defensively.
+        const existingExportNames = new Set(Array.from(existingContent.matchAll(/^export\s+const\s+(\w+)/gmu), (m) => m[1]).filter((name) => name !== undefined));
+        // All named exports in the generated content together with their type names.
+        const generatedExports = Array.from(generatedContent.matchAll(/^export\s+const\s+(\w+)\s*:\s*(\w+)/gmu), (m) => ({ methodName: m[1], typeName: m[2] })).filter((value) => value.methodName !== undefined && value.typeName !== undefined);
+        const newExports = generatedExports.filter(({ methodName }) => !existingExportNames.has(methodName));
+        if (newExports.length === 0) {
+            debug(`no new handlers to append to ${fullPath}`);
+            return;
+        }
+        debug(`appending ${newExports.length} new handler(s) to ${fullPath}: %o`, newExports.map(({ methodName }) => methodName));
+        const newImportLines = [];
+        const newExportBlocks = [];
+        for (const { methodName, typeName } of newExports) {
+            // Both names come from \w+ captures so they are safe identifiers, but
+            // guard explicitly to satisfy static analysis and avoid RegExp injection.
+            if (!/^\w+$/u.test(typeName) || !/^\w+$/u.test(methodName)) {
+                debug(`skipping handler with unsafe name – methodName: %s, typeName: %s`, methodName, typeName);
+                continue;
+            }
+            // Find the `import type { TypeName } from "..."` line for this type.
+            const importMatch = generatedContent.match(new RegExp(`^import\\s+type\\s+\\{[^}]*\\b${typeName}\\b[^}]*\\}\\s+from\\s+["'][^"']+["'];`, "mu"));
+            if (importMatch?.[0] && !existingContent.includes(importMatch[0])) {
+                newImportLines.push(importMatch[0]);
+            }
+            // Find the export block: from `export const METHOD` to the closing `};`.
+            // The generated code is always Prettier-formatted, so the closing brace
+            // and semicolon of every top-level arrow-function export appear on their
+            // own line as `\n};`.
+            const startMatch = new RegExp(`^export\\s+const\\s+${methodName}\\b`, "mu").exec(generatedContent);
+            if (startMatch) {
+                const fromExport = generatedContent.slice(startMatch.index);
+                const closingIndex = fromExport.indexOf("\n};");
+                if (closingIndex !== -1) {
+                    // Include the closing `};` (3 chars: \n, }, ;)
+                    newExportBlocks.push(fromExport.slice(0, closingIndex + 3));
+                }
+            }
+        }
+        let updatedContent = existingContent;
+        // Insert new import lines right after the last existing import statement.
+        if (newImportLines.length > 0) {
+            const importMatches = [...existingContent.matchAll(/^import\s[^\n]*/gmu)];
+            if (importMatches.length > 0) {
+                const lastImport = importMatches[importMatches.length - 1];
+                const importIndex = lastImport?.index;
+                const insertPos = importIndex === undefined
+                    ? 0
+                    : (() => {
+                        const lineEnd = existingContent.indexOf("\n", importIndex);
+                        return lineEnd === -1 ? existingContent.length : lineEnd + 1;
+                    })();
+                updatedContent =
+                    existingContent.slice(0, insertPos) +
+                        newImportLines.join("\n") +
+                        "\n" +
+                        existingContent.slice(insertPos);
+            }
+            else {
+                updatedContent = newImportLines.join("\n") + "\n" + existingContent;
+            }
+        }
+        // Append new export blocks at the end of the file.
+        if (newExportBlocks.length > 0) {
+            const separator = updatedContent.endsWith("\n") ? "\n" : "\n\n";
+            updatedContent += separator + newExportBlocks.join("\n\n") + "\n";
+        }
+        await fs.writeFile(fullPath, updatedContent);
+        debug(`appended new handlers to ${fullPath}`);
+    }
     /**
      * Returns the path of the `_.context.ts` file that is nearest to `path` in
      * the directory hierarchy, relative to the script's output directory.