counterfact 2.12.0 → 2.14.1

package/README.md

@@ -1,61 +1,77 @@
 <div align="center" markdown="1">
 
-<h1><img src="./counterfact.svg" alt="Counterfact" border=0></h1>
+<h1><img src="./counterfact.svg" alt="Counterfact" border="0"></h1>
 
-<br>
+![MIT License](https://img.shields.io/badge/license-MIT-blue) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/counterfact/api-simulator) ![Swagger 2.0](https://img.shields.io/badge/Swagger-2.0-85EA2D) ![OpenAPI 3.0–3.2](https://img.shields.io/badge/OpenAPI-3.x-6BA539) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/counterfact/api-simulator)
 
-![MIT License](https://img.shields.io/badge/license-MIT-blue) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) ![friction 0%](https://img.shields.io/badge/friction-0%25-brightgreen) ![Swagger 2.0](https://img.shields.io/badge/Swagger-2.0-85EA2D) ![OpenAPI 3.0-3.2](https://img.shields.io/badge/OpenAPI-3.x-6BA539)
+## Turn an OpenAPI document into an editable, stateful local API.
 
 </div>
 
-<div align="center" markdown="1">
-<h2>Mock servers work—until you need state, failures, or control mid-run.</h2>
-</div
+Counterfact generates TypeScript handlers and request/response types for supported OpenAPI operations, then starts a local server. Begin with schema-derived sample responses; add shared state, failures, latency, middleware, or selective proxying as your workflow needs them. Route and context files hot-reload while their in-memory state stays available.
 
-Static responses aren’t enough. There’s no shared state. You can’t inject failures. You can’t test real workflows.<br>
-Mock servers make it easy to get started, but hard to keep going.<br>
-Counterfact is an API simulator without those limits. 
+Counterfact checks contract shape while giving you a path to shape the behavior. Start with schema-derived responses, then turn them into deterministic, stateful scenarios by editing the generated typed handlers and adding shared context. You can explore in seconds and keep the behavior you author as a repeatable local or CI fixture.
 
-Point it at an [OpenAPI](https://www.openapis.org) document and get a live, stateful API in seconds. 
-Supports Swagger 2.0 and OpenAPI 3.0, 3.1, and 3.2.
-- Type-safe TypeScript handlers for every endpoint  
-- Hot reloading as you edit  
-- Shared state across routes  
-- **A built-in REPL to control behavior at runtime**  
-- Optional proxying to real backends
+## Run a live API in 60 seconds
 
-Flexbile for humans. Stable for [AI agents](https://github.com/counterfact/api-simulator/blob/main/docs/patterns/ai-assisted-implementation.md).
+```sh
+npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
+```
 
-You’re in control—without restarting.
+This generates editable files in `api/`, starts the server at `http://localhost:3100`, serves Swagger UI at `http://localhost:3100/counterfact/swagger/`, and opens the live REPL. Exit with `.exit`, <kbd>Ctrl</kbd>+<kbd>D</kbd>, or <kbd>Ctrl</kbd>+<kbd>C</kbd> twice.
 
-For a *frontend developer* waiting on a backend,<br>
-a *test engineer* who needs clean, reproducible state,<br>
-or an *AI agent* that needs a stable API
+Requires Node.js 22 or newer. For a repeatable project or CI workflow, install Counterfact as a dev dependency and commit the lockfile:
 
-Real enough to be useful. Fake enough to be usable.
+```sh
+npm install --save-dev counterfact
+npx counterfact ./openapi.yaml api
+```
 
+## Start with the workflow you need
 
-## Try it now 
+| When you need to…                      | You can…                                                         | Start here                                                                                                  |
+| -------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Build ahead of your backend            | Create a record, read it later, and shape the failure paths      | [Build a stateful flow](./docs/first-10-minutes.md#build-a-stateful-flow)                                   |
+| Make failures repeatable               | Reset, fail, recover, and tear down the same way every run       | [Automate a deterministic test](./docs/first-10-minutes.md#automate-a-deterministic-test)                   |
+| Give a coding agent a reliable sandbox | Leave a resettable context and an HTTP test for review           | [Give an agent a verifiable task](./docs/first-10-minutes.md#give-an-agent-a-verifiable-task)               |
+| Bring endpoints online gradually       | Keep one client base URL while paths move from local to upstream | [Run the checked hybrid path](./examples/first-10-minutes/#hybrid-path-ownership)                           |
+| Keep the contract in the loop          | Regenerate types and catch drift in your normal type check       | [See a contract change reach a client](./examples/first-10-minutes/#see-a-contract-change-reach-the-client) |
 
-```sh
-npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
-```
+The [first-10-minutes guide](./docs/first-10-minutes.md) includes the shared setup, reset and isolation rules, CI lifecycle, and the boundary between contract checks and behavior realism.
+
+Prefer a complete artifact to copy? The [CI-checked first-10-minutes example](./examples/first-10-minutes/) contains a minimal OpenAPI contract, resettable context, typed handlers, real-HTTP test, lockfile, and type-check configuration.
+
+## Confidence you can build on
+
+| Where Counterfact helps               | What you get                                                                                                           | What remains yours                                                        |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Generated TypeScript types            | Supported status codes, media types, declared headers, and request/response shapes when your project runs a type check | The business rules that make the API truly yours                          |
+| Request validation                    | Required query, header, and cookie parameters plus supported JSON/form bodies; detected mismatches return `400`        | Authentication, authorization, path-parameter schemas, and business rules |
+| Response checks                       | Required response headers and their schema types, with advisory `response-type-error` details when something is off    | Response-body enforcement and production correctness                      |
+| Your handlers, context, and scenarios | The state, rules, failures, reset behavior, and deterministic fixtures your workflow needs                             | Targeted real-backend and end-to-end coverage for the real service        |
+
+Counterfact gives you a fast, contract-shaped world to build against. Keep targeted real-backend and end-to-end coverage for the parts only the real service can prove. See [how to make the workflow yours](./docs/first-10-minutes.md#make-it-yours-with-confidence) for the practical checklist.
+
+## Project lifecycle
 
-> Starts a local server with a live REPL to inspect and control API behavior  
-> Requires Node ≥ 22.0.0
+- Commit your OpenAPI document, editable `routes/`, scenarios, and usually the generated `types/` so collaborators share a working contract snapshot.
+- Regeneration overwrites generated types and may append scaffolding for newly added operations; it preserves existing handler bodies unless you explicitly use a destructive option such as `--prune`.
+- In-memory context survives hot reload. A new process creates fresh context, and its constructor or `startup` scenario defines the initial state.
+- Counterfact executes TypeScript route files, but it does not run a TypeScript type-check step for you. Include generated files in your project and run your normal type check in CI.
+- Use a user-defined `reset()` in test setup, and use separate server instances and ports for parallel workers.
 
-## Go deeper
+## Documentation
 
-- [Getting started](./docs/getting-started.md) – Detailed walkthrough with state, REPL, and proxy  
-- [Patterns](./docs/patterns/index.md) – How Counterfact transforms your workflow  
-- [Example repo](https://github.com/counterfact/example-petstore) – Using Counterfact to implement the Swagger Petstore  
-- [How it compares](./docs/comparison.md) – json-server, WireMock, Prism, Microcks, MSW  
-- [Usage](./docs/usage.md) – Explore features and how to use them  
-- [Reference](./docs/reference.md) – `$` API, CLI flags, architecture  
-- [FAQ](./docs/faq.md) – State, types, regeneration  
+- [Getting started](./docs/getting-started.md) – Generated files, state, REPL, proxying, and spec changes
+- [Usage](./docs/usage.md) – Feature map
+- [Patterns](./docs/patterns/index.md) – Reusable development and testing workflows
+- [Reference](./docs/reference.md) – `$` API, CLI flags, and architecture
+- [FAQ](./docs/faq.md) – State, types, validation, and regeneration
+- [How it compares](./docs/comparison.md) – json-server, WireMock, Prism, Microcks, and MSW
+- [Example repository](https://github.com/counterfact/example-petstore) – A larger Petstore implementation
 
 <div align="center" markdown="1">
 
-[Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
+[Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md)
 
 </div>

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/dist/util/load-config-file.js

@@ -33,6 +33,9 @@ export async function loadConfigFile(configPath, required = false) {
         }
         throw error;
     }
+    if (!content.trim()) {
+        return {};
+    }
     const parsed = loadYaml(content);
     if (parsed === null || parsed === undefined) {
         return {};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "counterfact",
-  "version": "2.12.0",
+  "version": "2.14.1",
   "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",
@@ -64,7 +65,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "test": "yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest --testPathIgnorePatterns=black-box",
+    "test": "yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest --testPathIgnorePatterns=black-box --testPathIgnorePatterns=examples",
     "test:black-box": "rimraf dist && yarn build && python3 -m pytest test-black-box/ -v",
     "test:tsd": "tsd --typings ./dist/server/counterfact-types/index.ts --files ./test/**/*.test-d.ts",
     "build": "rm -rf dist && tsc && copyfiles -f \"src/counterfact-types/*.ts\" dist/server/counterfact-types && copyfiles -f \"src/server/*.cjs\" dist/server",
@@ -81,76 +82,76 @@
     "counterfact": "./bin/counterfact.js"
   },
   "devDependencies": {
-    "@changesets/cli": "2.31.0",
+    "@changesets/cli": "2.31.1",
     "@eslint/js": "10.0.1",
     "@jest/globals": "30.4.1",
-    "@swc/core": "1.15.33",
+    "@swc/core": "1.15.46",
     "@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.65.0",
+    "@typescript-eslint/parser": "8.65.0",
     "copyfiles": "2.4.1",
-    "eslint": "10.3.0",
+    "eslint": "10.8.0",
     "eslint-formatter-github-annotations": "0.1.0",
-    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-import-resolver-typescript": "4.4.5",
     "eslint-plugin-etc": "2.0.3",
     "eslint-plugin-file-progress": "4.0.0",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-jest": "29.15.2",
-    "eslint-plugin-jest-dom": "5.5.0",
-    "eslint-plugin-n": "18.0.1",
+    "eslint-plugin-jest": "29.16.0",
+    "eslint-plugin-jest-dom": "5.6.0",
+    "eslint-plugin-n": "18.2.2",
     "eslint-plugin-no-explicit-type-exports": "0.12.1",
-    "eslint-plugin-prettier": "5.5.5",
+    "eslint-plugin-prettier": "5.5.6",
     "eslint-plugin-promise": "7.3.0",
-    "eslint-plugin-regexp": "3.1.0",
-    "eslint-plugin-security": "4.0.0",
+    "eslint-plugin-regexp": "3.1.1",
+    "eslint-plugin-security": "4.0.1",
     "eslint-plugin-unused-imports": "4.4.1",
     "husky": "9.1.7",
     "jest": "30.4.2",
     "jest-retries": "1.0.1",
-    "node-mocks-http": "1.17.2",
+    "node-mocks-http": "1.18.1",
     "rimraf": "6.1.3",
     "supertest": "7.2.2",
     "tsd": "0.33.0",
     "using-temporary-files": "2.2.1"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "15.3.5",
+    "@apidevtools/json-schema-ref-parser": "15.5.0",
     "@hapi/accept": "6.0.3",
     "@types/json-schema": "7.0.15",
     "ajv": "8.20.0",
     "chokidar": "5.0.0",
-    "commander": "14.0.3",
+    "commander": "15.0.0",
     "debug": "4.4.3",
-    "fs-extra": "11.3.5",
+    "fs-extra": "11.4.0",
     "http-terminator": "3.2.0",
-    "js-yaml": "4.1.1",
-    "json-schema-faker": "0.6.1",
+    "js-yaml": "5.2.2",
+    "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",
-    "prettier": "3.8.3",
-    "recast": "0.23.11",
-    "tsx": "4.21.0",
+    "posthog-node": "5.46.0",
+    "precinct": "13.0.1",
+    "prettier": "3.8.5",
+    "recast": "0.23.12",
+    "tsx": "4.23.1",
     "typescript": "6.0.3"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
   "resolutions": {
-    "js-yaml": "4.1.1",
     "@typescript-eslint/utils": "^8.58.0"
   }
 }