counterfact 2.14.0 → 2.14.2

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

@@ -82,7 +82,7 @@ export class ApiRunner {
         return this.group ? `/${this.group}` : "";
     }
     config;
-    constructor(config, nativeTs, openApiDocument, group, version = "", versions = []) {
+    constructor(config, nativeTs, openApiDocument, group, version = "", versions = [], groupState) {
         this.group = group;
         this.version = version;
         const modulesPath = this.group
@@ -96,8 +96,9 @@ export class ApiRunner {
         this.prefix = config.prefix;
         this.overlays = config.overlays ?? [];
         this.registry = new Registry();
-        this.contextRegistry = new ContextRegistry();
-        this.scenarioRegistry = new ScenarioRegistry();
+        this.contextRegistry = groupState?.contextRegistry ?? new ContextRegistry();
+        this.scenarioRegistry =
+            groupState?.scenarioRegistry ?? new ScenarioRegistry();
         this.scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
         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);
@@ -115,8 +116,9 @@ export class ApiRunner {
      * @param group - Optional group name placing generated code in a subdirectory (default `""`).
      * @param version - Optional version label for this spec (e.g. `"v1"`, `"v2"`).
      * @param versions - Optional ordered list of all version labels in this group (oldest first).
+     * @param groupState - Optional context/scenario registries shared by the group's runners.
      */
-    static async create(config, group = "", version = "", versions = []) {
+    static async create(config, group = "", version = "", versions = [], groupState) {
         const nativeTs = await runtimeCanExecuteErasableTs();
         const modulesPath = group
             ? pathJoin(config.basePath, group)
@@ -128,7 +130,7 @@ export class ApiRunner {
         const openApiDocument = config.openApiPath === "_"
             ? undefined
             : await loadOpenApiDocument(config.openApiPath, config.overlays ?? []);
-        return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions);
+        return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions, groupState);
     }
     /**
      * Generates TypeScript route stubs and type files from the OpenAPI spec.

package/dist/app.js

@@ -4,7 +4,9 @@ import { createHttpTerminator } from "http-terminator";
 import { ApiRunner } from "./api-runner.js";
 import { startRepl as startReplServer } from "./repl/repl.js";
 import { createRouteFunction } from "./repl/route-builder.js";
+import { ContextRegistry } from "./server/context-registry.js";
 import { createKoaApp } from "./server/web-server/create-koa-app.js";
+import { ScenarioRegistry } from "./server/scenario-registry.js";
 import { Repository } from "./typescript-generator/repository.js";
 import { ensureDirectoryExists } from "./util/ensure-directory-exists.js";
 import { generateVersionsTsContent } from "./typescript-generator/versions-ts-generator.js";
@@ -24,37 +26,42 @@ export async function runStartupScenario(scenarioRegistry, contextRegistry, conf
     await indexModule["startup"](scenario$);
 }
 /**
- * Derives the URL prefix for a spec entry.
- *
- * Applies the following precedence rules:
- *  1. Explicit `prefix` (even `""`) → returned as-is.
- *  2. `group` + `version` both present → `/<group>/<version>`.
- *  3. `group` present (no `version`) → `/<group>`.
- *  4. Neither → `""` (root).
+ * Runs one startup scenario per API group, in specification declaration order.
+ * Versioned runners in one group share the same scenario and context registries,
+ * so only the group's first runner participates in startup.
  */
-function derivePrefix(spec) {
-    if (spec.prefix !== undefined) {
-        return spec.prefix;
-    }
-    if (spec.group && spec.version) {
-        return `/${spec.group}/${spec.version}`;
-    }
-    if (spec.group) {
-        return `/${spec.group}`;
+async function runGroupStartupScenarios(runners, config) {
+    const startedGroups = new Set();
+    for (const runner of runners) {
+        if (startedGroups.has(runner.group)) {
+            continue;
+        }
+        startedGroups.add(runner.group);
+        try {
+            await runStartupScenario(runner.scenarioRegistry, runner.contextRegistry, config, runner.openApiDocument);
+        }
+        catch (error) {
+            const groupLabel = runner.group
+                ? `group "${runner.group}"${runner.version ? ` (version "${runner.version}")` : ""}`
+                : "the primary API";
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Startup scenario failed for ${groupLabel}: ${message}`, {
+                cause: error,
+            });
+        }
     }
-    return "";
 }
 /**
  * Normalises the spec configuration to an array.
  *
- * When `specs` is provided, each entry's `prefix` is resolved via
- * {@link derivePrefix} so the rest of the code can assume `prefix` is always
- * a string. When `specs` is omitted, a single-entry array is constructed from
- * `config.openApiPath`, `config.prefix`, and `group = ""`.
+ * When `specs` is provided, each omitted `prefix` defaults to `""` so the rest
+ * of the code can assume it is always a string. When `specs` is omitted, a
+ * single-entry array is constructed from `config.openApiPath`, `config.prefix`,
+ * and `group = ""`.
  */
 function normalizeSpecs(config, specs) {
     if (specs !== undefined) {
-        return specs.map((spec) => ({ ...spec, prefix: derivePrefix(spec) }));
+        return specs.map((spec) => ({ ...spec, prefix: spec.prefix ?? "" }));
     }
     return [
         {
@@ -131,6 +138,18 @@ export async function counterfact(config, specs) {
             versionsByGroup.set(spec.group, [...existing, version]);
         }
     }
+    // A group is one state boundary even when it contains several versioned
+    // specification runners. Preserve separate registries between groups while
+    // sharing context and scenarios between every runner in the same group.
+    const stateByGroup = new Map();
+    for (const spec of normalizedSpecs) {
+        if (!stateByGroup.has(spec.group)) {
+            stateByGroup.set(spec.group, {
+                contextRegistry: new ContextRegistry(),
+                scenarioRegistry: new ScenarioRegistry(),
+            });
+        }
+    }
     const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({
         ...config,
         openApiPath: spec.source,
@@ -138,7 +157,7 @@ export async function counterfact(config, specs) {
         // 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) ?? [])));
+    }, spec.group, spec.version ?? "", versionsByGroup.get(spec.group) ?? [], stateByGroup.get(spec.group))));
     const koaApp = createKoaApp({
         runners,
         config,
@@ -205,7 +224,15 @@ export async function counterfact(config, specs) {
         await Promise.all(runners.map((runner) => runner.start(options)));
         let httpTerminator;
         if (options.startServer) {
-            await runStartupScenario(primaryRunner.scenarioRegistry, primaryRunner.contextRegistry, { port: config.port }, primaryRunner.openApiDocument);
+            try {
+                await runGroupStartupScenarios(runners, { port: config.port });
+            }
+            catch (error) {
+                // Startup happens after the runner watchers are active. If a scenario
+                // fails, release those resources and leave the HTTP port untouched.
+                await Promise.allSettled(runners.map((runner) => runner.stopWatching()));
+                throw error;
+            }
             const server = koaApp.listen({
                 port: config.port,
             });

package/dist/cli/run.js

@@ -29,8 +29,7 @@ const DEFAULT_PORT = 3100;
  *   (single spec derived from config).
  *
  * Note: `prefix` is intentionally left `undefined` when not supplied so that
- * `normalizeSpecs` (in `app.ts`) can derive it automatically from
- * `group`/`version`.
+ * `normalizeSpecs` (in `app.ts`) can apply the root-prefix default.
  */
 export function normalizeSpecOption(specOption) {
     if (Array.isArray(specOption)) {

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

@@ -4,7 +4,7 @@ import Koa from "koa";
 import bodyParser from "koa-bodyparser";
 import { koaSwagger } from "koa2-swagger-ui";
 import { adminApiMiddleware } from "./admin-api-middleware.js";
-import { routesMiddleware } from "./routes-middleware.js";
+import { routesMiddleware, routesMiddlewareForRunners, } from "./routes-middleware.js";
 import { openapiMiddleware } from "./openapi-middleware.js";
 const debug = createDebug("counterfact:server:create-koa-app");
 /**
@@ -61,8 +61,15 @@ export function createKoaApp({ runners, config, }) {
             ctx.type = "application/json";
         }
     });
-    for (const runner of runners) {
-        app.use(routesMiddleware(runner.prefix, runner.dispatcher, {
+    const [onlyRunner] = runners;
+    if (runners.length === 1 && onlyRunner !== undefined) {
+        app.use(routesMiddleware(onlyRunner.prefix, onlyRunner.dispatcher, {
+            proxyPaths: config.proxyPaths,
+            proxyUrl: config.proxyUrl,
+        }));
+    }
+    else {
+        app.use(routesMiddlewareForRunners(runners, {
             proxyPaths: config.proxyPaths,
             proxyUrl: config.proxyUrl,
         }));

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

@@ -91,7 +91,7 @@ function getAuthObject(ctx) {
  * @param proxy - Proxy factory; injectable for testing.
  * @returns A Koa middleware function.
  */
-export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
+export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy, allowedMethodsOverride) {
     return async function middleware(ctx, next) {
         const { proxyUrl } = config;
         debug("middleware running for path: %s", ctx.request.path);
@@ -106,7 +106,7 @@ export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
         if (isProxyEnabledForPath(path, config) && proxyUrl) {
             return proxy("/", { changeOrigin: true, target: proxyUrl })(ctx, next);
         }
-        addCors(ctx, dispatcher.registry.allowedMethods(path), headers);
+        addCors(ctx, allowedMethodsOverride ?? dispatcher.registry.allowedMethods(path), headers);
         if (method === "OPTIONS") {
             ctx.status = HTTP_STATUS_CODE_OK;
             return undefined;
@@ -156,7 +156,56 @@ export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
                 ctx.res.appendHeader(key, value);
             }
         }
+        if (response.status === 405 && allowedMethodsOverride !== undefined) {
+            ctx.set("Allow", allowedMethodsOverride);
+        }
         ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
         return undefined;
     };
 }
+/**
+ * Selects the first runner that can handle a request, allowing runners with
+ * overlapping prefixes to share one public URL space.
+ */
+export function routesMiddlewareForRunners(runners, config, proxy = koaProxy) {
+    return async function multiRunnerRoutesMiddleware(ctx, next) {
+        const candidates = runners
+            .filter(({ prefix }) => ctx.request.path.startsWith(prefix))
+            .map((runner) => ({
+            path: ctx.request.path.slice(runner.prefix.length),
+            runner,
+        }));
+        if (candidates.length === 0) {
+            return await next();
+        }
+        const method = ctx.request.method;
+        for (const candidate of candidates) {
+            if ((config.proxyUrl && isProxyEnabledForPath(candidate.path, config)) ||
+                candidate.runner.dispatcher.registry.exists(method, candidate.path)) {
+                return routesMiddleware(candidate.runner.prefix, candidate.runner.dispatcher, config, proxy)(ctx, next);
+            }
+        }
+        const allowedMethods = new Set();
+        let pathOwner;
+        for (const candidate of candidates) {
+            const methods = candidate.runner.dispatcher.registry.allowedMethods(candidate.path);
+            if (methods === "")
+                continue;
+            pathOwner ??= candidate;
+            for (const allowedMethod of methods.split(", ")) {
+                allowedMethods.add(allowedMethod);
+            }
+        }
+        if (method === "OPTIONS") {
+            const selected = pathOwner ?? candidates[0];
+            if (selected === undefined) {
+                return await next();
+            }
+            return routesMiddleware(selected.runner.prefix, selected.runner.dispatcher, config, proxy, [...allowedMethods].join(", "))(ctx, next);
+        }
+        if (pathOwner === undefined) {
+            return await next();
+        }
+        return routesMiddleware(pathOwner.runner.prefix, pathOwner.runner.dispatcher, config, proxy, [...allowedMethods].join(", "))(ctx, next);
+    };
+}

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

@@ -8,7 +8,8 @@ import { CHOKIDAR_OPTIONS } from "../server/constants.js";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { waitForEvent } from "../util/wait-for-event.js";
 import { OperationCoder } from "./operation-coder.js";
-import { pruneRoutes } from "./prune.js";
+import { assertNoNormalizedPathCollisions, normalizeOpenApiPath, } from "./openapi-path.js";
+import { pruneRoutes, pruneTypes } from "./prune.js";
 import { Repository } from "./repository.js";
 import { Specification } from "./specification.js";
 const debug = createDebug("counterfact:typescript-generator:generate");
@@ -94,9 +95,11 @@ export class CodeGenerator extends EventTarget {
         debug("reading the #/paths from the specification");
         const paths = await this.getPathsFromSpecification(specification);
         debug("got %i paths", paths?.map?.length ?? 0);
+        const openApiPaths = paths.map((_pathDefinition, key) => key);
+        assertNoNormalizedPathCollisions(openApiPaths);
         if (this.generateOptions.prune && this.generateOptions.routes) {
             debug("pruning defunct route files");
-            await pruneRoutes(destination, paths.map((_v, key) => key));
+            await pruneRoutes(destination, openApiPaths);
             debug("done pruning");
         }
         const securityRequirement = specification.getRequirement("#/components/securitySchemes");
@@ -125,13 +128,24 @@ export class CodeGenerator extends EventTarget {
         });
         paths.forEach((pathDefinition, key) => {
             debug("processing path %s", key);
-            const path = key === "/" ? "/index" : key;
+            const normalizedPath = normalizeOpenApiPath(key);
+            const path = normalizedPath === "/" ? "/index" : normalizedPath;
             operationMethodsForPath(pathDefinition).forEach(([operation, requestMethod]) => {
                 repository
                     .get(`routes${path}.ts`)
                     .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));
             });
         });
+        if (this.generateOptions.prune && this.generateOptions.types) {
+            debug("resolving the expected generated type files");
+            await repository.finished();
+            debug("pruning defunct generated type files");
+            await pruneTypes(destination, [
+                ...repository.scripts.keys(),
+                ...(this.version === "" ? [] : ["types/versions.ts"]),
+            ]);
+            debug("done pruning generated type files");
+        }
         debug("telling the repository to write the files to %s", destination);
         await repository.writeFiles(destination, this.generateOptions);
         debug("finished writing the files");

package/dist/typescript-generator/openapi-path.js

@@ -0,0 +1,23 @@
+/**
+ * Normalizes an OpenAPI path for Counterfact's route and type module trees.
+ *
+ * Incoming requests already match route modules with or without a terminal
+ * slash, so terminal slashes must not create an extra empty file segment.
+ */
+export function normalizeOpenApiPath(openApiPath) {
+    return openApiPath.replace(/\/+$/u, "") || "/";
+}
+/**
+ * Rejects path keys that would target the same generated route module.
+ */
+export function assertNoNormalizedPathCollisions(openApiPaths) {
+    const originalPathByNormalizedPath = new Map();
+    for (const openApiPath of openApiPaths) {
+        const normalizedPath = normalizeOpenApiPath(openApiPath);
+        const existingPath = originalPathByNormalizedPath.get(normalizedPath);
+        if (existingPath !== undefined && existingPath !== openApiPath) {
+            throw new Error(`OpenAPI paths "${existingPath}" and "${openApiPath}" normalize to the same path "${normalizedPath}". Remove one of the conflicting paths.`);
+        }
+        originalPathByNormalizedPath.set(normalizedPath, openApiPath);
+    }
+}

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

@@ -1,5 +1,6 @@
 import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
+import { normalizeOpenApiPath } from "./openapi-path.js";
 import { OperationTypeCoder, VersionedArgTypeCoder, } from "./operation-type-coder.js";
 import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 /**
@@ -66,10 +67,7 @@ export class OperationCoder extends Coder {
         return script.importType(operationTypeCoder);
     }
     modulePath() {
-        const pathString = this.requirement.url
-            .split("/")
-            .at(-2)
-            .replaceAll("~1", "/");
+        const pathString = normalizeOpenApiPath(this.requirement.url.split("/").at(-2).replaceAll("~1", "/"));
         return `${pathJoin("routes", pathString)}.types.ts`;
     }
 }

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

@@ -9,6 +9,7 @@ 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 { normalizeOpenApiPath } from "./openapi-path.js";
 import { Requirement } from "./requirement.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
 function sanitizeIdentifier(value) {
@@ -145,10 +146,7 @@ export class OperationTypeCoder extends TypeCoder {
             .join(" | ");
     }
     modulePath() {
-        const pathString = this.requirement.url
-            .split("/")
-            .at(-2)
-            .replaceAll("~1", "/");
+        const pathString = normalizeOpenApiPath(this.requirement.url.split("/").at(-2).replaceAll("~1", "/"));
         return `${pathJoin("types/paths", pathString === "/" ? "/index" : pathString)}.types.ts`;
     }
     /**

package/dist/typescript-generator/prune.js

@@ -1,8 +1,9 @@
 import fs from "node:fs/promises";
 import nodePath from "node:path";
-/* eslint-disable security/detect-non-literal-fs-filename -- pruning only traverses and removes files under destination/routes. */
+/* eslint-disable security/detect-non-literal-fs-filename -- pruning only traverses and removes files under generator-owned destination subdirectories. */
 import createDebug from "debug";
 import { toForwardSlashPath } from "../util/forward-slash-path.js";
+import { normalizeOpenApiPath } from "./openapi-path.js";
 const debug = createDebug("counterfact:typescript-generator:prune");
 /**
  * Collects all .ts route files in a directory recursively.
@@ -11,21 +12,19 @@ const debug = createDebug("counterfact:typescript-generator:prune");
  * @param currentPath - Current subdirectory being processed (relative to routesDir)
  * @returns Array of relative paths (using forward slashes)
  */
-async function collectRouteFiles(routesDir, currentPath = "") {
+async function collectTypeScriptFiles(rootDir, currentPath = "") {
     const files = [];
     try {
-        const fullDir = currentPath
-            ? nodePath.join(routesDir, currentPath)
-            : routesDir;
+        const fullDir = currentPath ? nodePath.join(rootDir, currentPath) : rootDir;
         const entries = await fs.readdir(fullDir, { withFileTypes: true });
         for (const entry of entries) {
             const relativePath = currentPath
                 ? `${currentPath}/${entry.name}`
                 : entry.name;
             if (entry.isDirectory()) {
-                files.push(...(await collectRouteFiles(routesDir, relativePath)));
+                files.push(...(await collectTypeScriptFiles(rootDir, relativePath)));
             }
-            else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
+            else if (entry.name.endsWith(".ts")) {
                 files.push(relativePath);
             }
         }
@@ -71,7 +70,8 @@ async function removeEmptyDirectories(dir, rootDir) {
  * @param openApiPath - The OpenAPI path string
  */
 function openApiPathToRouteFile(openApiPath) {
-    const filePath = openApiPath === "/" ? "index" : openApiPath.slice(1);
+    const normalizedPath = normalizeOpenApiPath(openApiPath);
+    const filePath = normalizedPath === "/" ? "index" : normalizedPath.slice(1);
     return `${filePath}.ts`;
 }
 /**
@@ -85,7 +85,7 @@ export async function pruneRoutes(destination, openApiPaths) {
     const routesDir = nodePath.join(destination, "routes");
     const expectedFiles = new Set(Array.from(openApiPaths).map(openApiPathToRouteFile));
     debug("expected route files: %o", Array.from(expectedFiles));
-    const actualFiles = await collectRouteFiles(routesDir);
+    const actualFiles = (await collectTypeScriptFiles(routesDir)).filter((file) => nodePath.basename(file) !== "_.context.ts");
     debug("actual route files: %o", actualFiles);
     let prunedCount = 0;
     for (const file of actualFiles) {
@@ -101,3 +101,46 @@ export async function pruneRoutes(destination, openApiPaths) {
     debug("pruned %d files", prunedCount);
     return prunedCount;
 }
+/**
+ * Returns whether a path below `types/` belongs to a namespace populated by
+ * the OpenAPI generator. Context support and arbitrary user-authored type
+ * modules are deliberately outside this ownership policy.
+ */
+function isGeneratorOwnedTypePath(path) {
+    const [first, second] = toForwardSlashPath(path).split("/");
+    const generatedCategory = (segment) => segment === "paths" || segment === "components" || segment === "#";
+    return (path === "versions.ts" ||
+        generatedCategory(first) ||
+        generatedCategory(second));
+}
+/**
+ * Prunes obsolete files from the OpenAPI generator-owned namespaces below
+ * `types/`. Hidden files are included by the recursive directory walk.
+ *
+ * `types/_.context.ts` and paths outside the known generated namespaces are
+ * preserved because separate generators or users own them.
+ *
+ * @param destination - Base destination directory (contains `types/`).
+ * @param expectedPaths - Repository-relative generated paths to retain.
+ * @returns Number of files removed.
+ */
+export async function pruneTypes(destination, expectedPaths) {
+    const typesDir = nodePath.join(destination, "types");
+    const expectedFiles = new Set(Array.from(expectedPaths, (path) => toForwardSlashPath(path).replace(/^types\//u, "")));
+    const actualFiles = (await collectTypeScriptFiles(typesDir)).filter(isGeneratorOwnedTypePath);
+    let prunedCount = 0;
+    debug("expected type files: %o", Array.from(expectedFiles));
+    debug("actual generated type files: %o", actualFiles);
+    for (const file of actualFiles) {
+        const normalizedFile = toForwardSlashPath(file);
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(typesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(typesDir, typesDir);
+    debug("pruned %d type files", prunedCount);
+    return prunedCount;
+}

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,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "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",
@@ -65,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",
@@ -82,10 +82,10 @@
     "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.40",
+    "@swc/core": "1.15.46",
     "@swc/jest": "0.2.39",
     "@testing-library/dom": "10.4.1",
     "@types/debug": "4.1.13",
@@ -96,44 +96,44 @@
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",
     "@types/node": "22",
-    "@typescript-eslint/eslint-plugin": "8.60.0",
-    "@typescript-eslint/parser": "8.60.0",
+    "@typescript-eslint/eslint-plugin": "8.65.0",
+    "@typescript-eslint/parser": "8.65.0",
     "copyfiles": "2.4.1",
-    "eslint": "10.4.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",
+    "js-yaml": "5.2.2",
     "json-schema-faker": "0.6.2",
     "jsonpath-plus": "10.4.0",
     "jsonwebtoken": "9.0.3",
@@ -143,16 +143,15 @@
     "koa2-swagger-ui": "5.12.0",
     "node-fetch": "3.3.2",
     "open": "11.0.0",
-    "posthog-node": "5.35.5",
-    "precinct": "13.0.0",
-    "prettier": "3.8.3",
-    "recast": "0.23.11",
-    "tsx": "4.22.3",
+    "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"
   }
 }