counterfact 2.12.0 → 2.14.0

package/dist/api-runner.js

@@ -59,6 +59,11 @@ export class ApiRunner {
     openApiPath;
     /** URL prefix that this runner intercepts (default `""`). */
     prefix;
+    /**
+     * Ordered list of overlay file paths/URLs applied to the OpenAPI document
+     * after loading.  Empty when no overlays are configured.
+     */
+    overlays;
     /**
      * Optional group name that places generated code in a subdirectory.
      * Defaults to `""` (no subdirectory).
@@ -89,11 +94,12 @@ export class ApiRunner {
         this.openApiDocument = openApiDocument;
         this.openApiPath = config.openApiPath;
         this.prefix = config.prefix;
+        this.overlays = config.overlays ?? [];
         this.registry = new Registry();
         this.contextRegistry = new ContextRegistry();
         this.scenarioRegistry = new ScenarioRegistry();
         this.scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
-        this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate, version);
+        this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate, version, config.overlays ?? []);
         this.dispatcher = new Dispatcher(this.registry, this.contextRegistry, openApiDocument, config, version, versions);
         this.transpiler = new Transpiler(pathJoin(modulesPath, "routes"), compiledPathsDirectory, "commonjs");
         this.moduleLoader = new ModuleLoader(compiledPathsDirectory, this.registry, this.contextRegistry, pathJoin(modulesPath, "scenarios"), this.scenarioRegistry);
@@ -121,7 +127,7 @@ export class ApiRunner {
         }
         const openApiDocument = config.openApiPath === "_"
             ? undefined
-            : await loadOpenApiDocument(config.openApiPath);
+            : await loadOpenApiDocument(config.openApiPath, config.overlays ?? []);
         return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions);
     }
     /**

package/dist/app.js

@@ -131,7 +131,14 @@ export async function counterfact(config, specs) {
             versionsByGroup.set(spec.group, [...existing, version]);
         }
     }
-    const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({ ...config, openApiPath: spec.source, prefix: spec.prefix }, spec.group, spec.version ?? "", versionsByGroup.get(spec.group) ?? [])));
+    const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({
+        ...config,
+        openApiPath: spec.source,
+        // Per-spec overlays take precedence; fall back to config-level overlays
+        // so that the --overlay CLI flag works in single-spec mode.
+        overlays: spec.overlays ?? config.overlays ?? [],
+        prefix: spec.prefix,
+    }, spec.group, spec.version ?? "", versionsByGroup.get(spec.group) ?? [])));
     const koaApp = createKoaApp({
         runners,
         config,

package/dist/cli/run.js

@@ -22,7 +22,7 @@ const DEFAULT_PORT = 3100;
  * CLI flag) into an array of {@link SpecConfig} objects, or `undefined` when
  * the option is a plain string (single OpenAPI document path).
  *
- * - **Array**: each entry is mapped to `{source, prefix, group, version}` with defaults.
+ * - **Array**: each entry is mapped to `{source, prefix, group, version, overlays}` with defaults.
  * - **Object**: wrapped in a single-element array.
  * - **String / undefined**: returns `undefined` — caller handles the string
  *   case (it shifts the positional argument) and the `undefined` case
@@ -39,6 +39,7 @@ export function normalizeSpecOption(specOption) {
             prefix: entry.prefix,
             group: entry.group ?? "",
             version: entry.version,
+            overlays: entry.overlays,
         }));
     }
     if (typeof specOption === "object" &&
@@ -50,6 +51,7 @@ export function normalizeSpecOption(specOption) {
                 prefix: specOption.prefix,
                 group: specOption.group ?? "",
                 version: specOption.version,
+                overlays: specOption.overlays,
             },
         ];
     }
@@ -104,11 +106,17 @@ function buildProgram(version, taglines) {
         const configFilePath = resolve(options.config ?? "counterfact.yaml");
         const fileConfig = await loadConfigFile(configFilePath, options.config !== undefined);
         debug("fileConfig: %o", fileConfig);
+        const knownOptionKeys = new Set(program.options.map((option) => option.attributeName()));
         // Apply config file values for any option that was not explicitly set on
         // the command line (i.e. its source is "default" or it was never defined).
         for (const [key, value] of Object.entries(fileConfig)) {
+            if (!knownOptionKeys.has(key)) {
+                debug("ignoring unknown config key %s", key);
+                continue;
+            }
             const optionSource = program.getOptionValueSource(key);
             if (optionSource !== "cli") {
+                // eslint-disable-next-line security/detect-object-injection -- key is validated against known Commander option names above.
                 options[key] = value;
             }
         }
@@ -139,6 +147,7 @@ function buildProgram(version, taglines) {
         const actions = ["repl", "serve", "watch", "generate", "buildCache"];
         if (!Object.keys(options).some((argument) => actions.some((action) => argument.startsWith(action)))) {
             for (const action of actions) {
+                // eslint-disable-next-line security/detect-object-injection -- action names come from the local allowlist above.
                 options[action] = true;
             }
         }
@@ -170,6 +179,7 @@ function buildProgram(version, taglines) {
                 prune: Boolean(options.prune),
             },
             openApiPath: source,
+            overlays: options.overlay ?? [],
             port: options.port,
             proxyPaths: new Map([["", Boolean(options.proxyUrl)]]),
             proxyUrl: options.proxyUrl ?? "",
@@ -298,6 +308,7 @@ function buildProgram(version, taglines) {
         .option("--always-fake-optionals", "random responses will include optional fields")
         .option("--prune", "remove route files that no longer exist in the OpenAPI spec")
         .option("--spec <string>", "path or URL to OpenAPI document (alternative to the positional [openapi.yaml] argument)")
+        .option("--overlay <path>", "path or URL to an OpenAPI overlay file to apply (repeatable)", (value, previous) => [...previous, value], [])
         .option("--no-update-check", "disable the npm update check on startup")
         .option("--no-validate-request", "disable request validation against the OpenAPI spec")
         .option("--no-validate-response", "disable response validation against the OpenAPI spec")

package/dist/server/dispatcher.js

@@ -165,6 +165,36 @@ export class Dispatcher {
         }
         return undefined;
     }
+    apiKeySecurityParameters() {
+        const schemes = this.openApiDocument?.components?.securitySchemes;
+        return Object.values(schemes ?? {})
+            .filter(({ in: location, name, type }) => type === "apiKey" &&
+            typeof name === "string" &&
+            (location === "header" ||
+                location === "query" ||
+                location === "cookie"))
+            .map(({ in: location, name }) => ({
+            in: location,
+            name: name,
+            required: false,
+            schema: { type: "string" },
+        }));
+    }
+    authWithApiKey(auth, cookie, headers, query) {
+        const apiKeyScheme = this.apiKeySecurityParameters().find((parameter) => ["cookie", "header", "query"].includes(parameter.in));
+        if (!apiKeyScheme) {
+            return auth;
+        }
+        const apiKey = apiKeyScheme.in === "query"
+            ? query[apiKeyScheme.name]
+            : apiKeyScheme.in === "cookie"
+                ? cookie[apiKeyScheme.name]
+                : Object.entries(headers).find(([key]) => key.toLowerCase() === apiKeyScheme.name.toLowerCase())?.[1];
+        const normalizedApiKey = Array.isArray(apiKey)
+            ? (apiKey[0] ?? "")
+            : (apiKey ?? "");
+        return { ...auth, apiKey: normalizedApiKey };
+    }
     /**
      * Resolves the OpenAPI operation for `path` and `method`, merging any
      * top-level `produces` array from the document root and any path-item-level
@@ -203,13 +233,20 @@ export class Dispatcher {
         const mergedOperation = mergedParameters !== undefined
             ? { ...operation, parameters: mergedParameters }
             : operation;
+        const apiKeyParameters = this.apiKeySecurityParameters();
+        const operationWithSecurity = apiKeyParameters.length > 0
+            ? {
+                ...mergedOperation,
+                parameters: mergeParameters(mergedOperation.parameters ?? [], apiKeyParameters),
+            }
+            : mergedOperation;
         if (this.openApiDocument?.produces) {
             return {
                 produces: this.openApiDocument.produces,
-                ...mergedOperation,
+                ...operationWithSecurity,
             };
         }
-        return mergedOperation;
+        return operationWithSecurity;
     }
     normalizeResponse(response, acceptHeader) {
         if (response.content !== undefined) {
@@ -299,8 +336,14 @@ export class Dispatcher {
             };
         }
         const operation = this.operationForPathAndMethod(matchedPath, method);
+        const requestCookie = parseCookies(headers.cookie ?? headers.Cookie ?? "");
         if (this.config?.validateRequests !== false) {
-            const validation = validateRequest(operation, { body, headers, query });
+            const validation = validateRequest(operation, {
+                body,
+                cookie: requestCookie,
+                headers,
+                query,
+            });
             if (!validation.valid) {
                 return {
                     body: `Request validation failed:\n${validation.errors.join("\n")}`,
@@ -316,7 +359,7 @@ export class Dispatcher {
             return min + Math.random() * (max - min);
         };
         const response = await this.registry.endpoint(method, path, this.parameterTypes(operation?.parameters))({
-            auth,
+            auth: this.authWithApiKey(auth, requestCookie, headers, query),
             body,
             context: this.contextRegistry.find(matchedPath),
             async delay(milliseconds = 0, maxMilliseconds = 0) {
@@ -325,7 +368,7 @@ export class Dispatcher {
                     : continuousDistribution(milliseconds, maxMilliseconds);
                 return new Promise((resolve) => setTimeout(resolve, delayInMs));
             },
-            cookie: parseCookies(headers.cookie ?? headers.Cookie ?? ""),
+            cookie: requestCookie,
             headers,
             proxy: async (url) => {
                 delete headers.host;

package/dist/server/load-openapi-document.js

@@ -1,6 +1,6 @@
 import { OpenApiDocument } from "./openapi-document.js";
-export async function loadOpenApiDocument(source) {
-    const document = new OpenApiDocument(source);
+export async function loadOpenApiDocument(source, overlays = []) {
+    const document = new OpenApiDocument(source, overlays);
     await document.load();
     return document;
 }

package/dist/server/openapi-document.js

@@ -1,6 +1,7 @@
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
+import { applyOverlays } from "../util/apply-overlay.js";
 import { waitForEvent } from "../util/wait-for-event.js";
 import { sendTelemetry } from "../cli/telemetry.js";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
@@ -14,13 +15,20 @@ const debug = createDebug("counterfact:server:openapi-document");
 export class OpenApiDocument extends EventTarget {
     /** The path or URL of the OpenAPI source file. */
     source;
+    /**
+     * Optional ordered list of overlay file paths/URLs to apply after each
+     * load of the document.
+     */
+    overlays;
     basePath;
+    components;
     paths = {};
     produces;
     watcher;
-    constructor(source) {
+    constructor(source, overlays = []) {
         super();
         this.source = source;
+        this.overlays = overlays;
     }
     /**
      * Reads the source file and populates the document's properties.
@@ -29,7 +37,11 @@ export class OpenApiDocument extends EventTarget {
     async load() {
         try {
             const data = (await dereference(this.source));
+            if (this.overlays.length > 0) {
+                await applyOverlays(data, this.overlays);
+            }
             this.basePath = data.basePath;
+            this.components = data.components;
             this.paths = data.paths;
             this.produces = data.produces;
         }

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,4 +1,5 @@
 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 = {

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

@@ -29,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}`,

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,6 +23,9 @@ 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",

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

@@ -24,10 +24,10 @@ const HEADERS_TO_DROP = new Set([
  * 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 = {
-    "text/event-stream": (item) => `data: ${JSON.stringify(item)}\n\n`,
-    "application/json-seq": (item) => `\x1e${JSON.stringify(item)}\n`,
-};
+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`;
 }
@@ -42,7 +42,7 @@ function isAsyncIterable(value) {
  * each item according to the given content type.
  */
 function asyncIterableToReadable(iterable, contentType) {
-    const formatter = STREAMING_FORMATTERS[contentType] ?? defaultStreamFormatter;
+    const formatter = STREAMING_FORMATTERS.get(contentType) ?? defaultStreamFormatter;
     async function* generate() {
         for await (const item of iterable) {
             yield formatter(item);

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);
@@ -135,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/operation-type-coder.js

@@ -163,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,
@@ -178,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);
@@ -195,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);
     }
     /**
@@ -245,7 +281,7 @@ export class OperationTypeCoder extends TypeCoder {
             : "never";
         const querystringTypeName = this.exportParameterType(script, "querystring", querystringType, baseName, modulePath);
         const versionLiteralType = this.version !== "" ? `"${this.version}"` : "never";
-        return `OmitValueWhenNever<{ query: ${queryTypeName}, querystring: ${querystringTypeName}, 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.

package/dist/typescript-generator/specification.js

@@ -1,5 +1,6 @@
 import { bundle } from "@apidevtools/json-schema-ref-parser";
 import createDebug from "debug";
+import { applyOverlays } from "../util/apply-overlay.js";
 import { Requirement } from "./requirement.js";
 const debug = createDebug("counterfact:typescript-generator:specification");
 /**
@@ -23,12 +24,14 @@ export class Specification {
      * Loads the OpenAPI document at `urlOrPath`, bundles all external `$ref`
      * references, and returns a fully initialised {@link Specification}.
      *
-     * @param urlOrPath - A local file path or HTTP(S) URL.
+     * @param urlOrPath   - A local file path or HTTP(S) URL.
+     * @param overlays    - Optional ordered list of overlay file paths/URLs to
+     *   apply after loading the document.
      * @throws When the document cannot be found or parsed.
      */
-    static async fromFile(urlOrPath) {
+    static async fromFile(urlOrPath, overlays = []) {
         const specification = new Specification();
-        await specification.load(urlOrPath);
+        await specification.load(urlOrPath, overlays);
         return specification;
     }
     /**
@@ -42,16 +45,22 @@ export class Specification {
         return this.rootRequirement.select(url.slice(2));
     }
     /**
-     * Loads (or reloads) the specification from `urlOrPath`.
+     * Loads (or reloads) the specification from `urlOrPath`, then applies any
+     * overlay files listed in `overlays` in order.
      *
      * @param urlOrPath - A local file path or HTTP(S) URL.
+     * @param overlays  - Optional ordered list of overlay file paths/URLs.
      * @throws When the document cannot be found or parsed.
      */
-    async load(urlOrPath) {
+    async load(urlOrPath, overlays = []) {
         try {
-            this.rootRequirement = new Requirement((await bundle(urlOrPath, {
+            const document = (await bundle(urlOrPath, {
                 resolve: { http: { safeUrlResolver: false } },
-            })), urlOrPath, this);
+            }));
+            if (overlays.length > 0) {
+                await applyOverlays(document, overlays);
+            }
+            this.rootRequirement = new Requirement(document, urlOrPath, this);
         }
         catch (error) {
             const details = error instanceof Error ? error.message : String(error);

package/dist/util/apply-overlay.js

@@ -0,0 +1,119 @@
+import { load as loadYaml } from "js-yaml";
+import { JSONPath } from "jsonpath-plus";
+import { readFile } from "./read-file.js";
+/**
+ * Deeply merges `source` into `target`, overwriting scalar values and
+ * recursively merging plain objects.  Arrays and non-plain-object values in
+ * `source` always overwrite the corresponding entry in `target`.
+ */
+function deepMerge(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        // Guard against prototype pollution attacks.
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            continue;
+        }
+        if (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof target[key] === "object" &&
+            target[key] !== null &&
+            !Array.isArray(target[key])) {
+            deepMerge(target[key], value);
+        }
+        else {
+            target[key] = value;
+        }
+    }
+}
+/**
+ * Applies a list of overlay actions to `document` in place.
+ *
+ * Each action may either:
+ * - **update**: deep-merge the `action.update` object into every node matched
+ *   by the JSONPath `action.target`.
+ * - **remove**: delete every node matched by `action.target` from its parent.
+ *
+ * @param document - The OpenAPI document object to mutate.
+ * @param actions  - The ordered list of overlay actions to apply.
+ */
+export function applyOverlayActions(document, actions) {
+    for (const action of actions) {
+        const results = JSONPath({
+            path: action.target,
+            json: document,
+            resultType: "all",
+        });
+        if (action.remove === true) {
+            // Iterate in reverse so that removing by numeric index doesn't shift
+            // subsequent items in the same parent array.
+            for (const result of [...results].reverse()) {
+                const { parent, parentProperty } = result;
+                if (Array.isArray(parent)) {
+                    parent.splice(Number(parentProperty), 1);
+                }
+                else {
+                    delete parent[String(parentProperty)];
+                }
+            }
+        }
+        else if (action.update !== undefined) {
+            for (const result of results) {
+                if (typeof result.value === "object" &&
+                    result.value !== null &&
+                    !Array.isArray(result.value)) {
+                    deepMerge(result.value, action.update);
+                }
+            }
+        }
+    }
+}
+/**
+ * Loads and parses an overlay file (YAML or JSON), validates that it looks
+ * like a valid OpenAPI overlay document, and returns the parsed object.
+ *
+ * @param overlayPath - Path or URL to the overlay file.
+ * @throws When the file cannot be read, parsed, or does not contain an
+ *   `overlay` version field and an `actions` array.
+ */
+export async function loadOverlay(overlayPath) {
+    let content;
+    try {
+        content = await readFile(overlayPath);
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read overlay file "${overlayPath}".\n${details}`, { cause: error });
+    }
+    let parsed;
+    try {
+        parsed = loadYaml(content);
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not parse overlay file "${overlayPath}".\n${details}`, { cause: error });
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("overlay" in parsed) ||
+        !("actions" in parsed) ||
+        !Array.isArray(parsed.actions)) {
+        throw new Error(`"${overlayPath}" does not appear to be a valid OpenAPI overlay file. ` +
+            `Expected an object with "overlay" and "actions" fields.`);
+    }
+    return parsed;
+}
+/**
+ * Applies all overlays listed in `overlayPaths` to `document` in order.
+ *
+ * Each overlay is loaded from disk (or a URL), parsed, and its actions are
+ * applied sequentially.  The document is mutated in place.
+ *
+ * @param document      - The OpenAPI document object to mutate.
+ * @param overlayPaths  - Ordered list of paths/URLs to overlay files.
+ */
+export async function applyOverlays(document, overlayPaths) {
+    for (const overlayPath of overlayPaths) {
+        const overlay = await loadOverlay(overlayPath);
+        applyOverlayActions(document, overlay.actions);
+    }
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "counterfact",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "Generate a TypeScript-based mock server from an OpenAPI spec in seconds — with stateful routes, hot reload, and REPL support.",
   "type": "module",
   "main": "./dist/app.js",
   "exports": {
     ".": {
-      "import": "./dist/app.js"
+      "import": "./dist/app.js",
+      "types": "./dist/server/types.d.ts"
     }
   },
   "types": "./dist/server/types.d.ts",
@@ -84,21 +85,21 @@
     "@changesets/cli": "2.31.0",
     "@eslint/js": "10.0.1",
     "@jest/globals": "30.4.1",
-    "@swc/core": "1.15.33",
+    "@swc/core": "1.15.40",
     "@swc/jest": "0.2.39",
     "@testing-library/dom": "10.4.1",
     "@types/debug": "4.1.13",
     "@types/jest": "30.0.0",
     "@types/js-yaml": "4.0.9",
-    "@types/koa": "3.0.2",
+    "@types/koa": "3.0.3",
     "@types/koa-bodyparser": "4.3.13",
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",
     "@types/node": "22",
-    "@typescript-eslint/eslint-plugin": "8.59.3",
-    "@typescript-eslint/parser": "8.59.3",
+    "@typescript-eslint/eslint-plugin": "8.60.0",
+    "@typescript-eslint/parser": "8.60.0",
     "copyfiles": "2.4.1",
-    "eslint": "10.3.0",
+    "eslint": "10.4.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-etc": "2.0.3",
@@ -133,19 +134,20 @@
     "fs-extra": "11.3.5",
     "http-terminator": "3.2.0",
     "js-yaml": "4.1.1",
-    "json-schema-faker": "0.6.1",
+    "json-schema-faker": "0.6.2",
+    "jsonpath-plus": "10.4.0",
     "jsonwebtoken": "9.0.3",
-    "koa": "3.2.0",
+    "koa": "3.2.1",
     "koa-bodyparser": "4.4.1",
     "koa-proxies": "0.12.4",
     "koa2-swagger-ui": "5.12.0",
     "node-fetch": "3.3.2",
     "open": "11.0.0",
-    "posthog-node": "5.34.1",
-    "precinct": "12.3.2",
+    "posthog-node": "5.35.5",
+    "precinct": "13.0.0",
     "prettier": "3.8.3",
     "recast": "0.23.11",
-    "tsx": "4.21.0",
+    "tsx": "4.22.3",
     "typescript": "6.0.3"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",