counterfact 2.9.0 → 2.11.0

package/README.md

@@ -1,34 +1,57 @@
 <div align="center" markdown="1">
 
-<img src="./counterfact.svg" alt="Counterfact" border=0>
+<h1><img src="./counterfact.svg" alt="Counterfact" border=0></h1>
 
 <br>
 
-![MIT License](https://img.shields.io/badge/license-MIT-blue) [![TypeScript](./typescript-badge.png)](https://github.com/ellerbrock/typescript-badges/) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
+![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)
 
 </div>
 
-You've used mock servers. You know where they stop being useful: static responses, no shared state, no way to inject a failure mid-run, no control without restarting. Counterfact picks up where they leave off.
+<div align="center" markdown="1">
+<h2>Mock servers work—until you need state, failures, or control mid-run.</h2>
+</div
+
+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. 
+
+Point it at an [OpenAPI](https://www.openapis.org) document and get a live, stateful API in seconds. 
+- 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
+
+Flexbile for humans. Stable for [AI agents](https://github.com/counterfact/api-simulator/blob/main/docs/patterns/ai-assisted-implementation.md).
+
+You’re in control—without restarting.
+
+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
+
+Real enough to be useful. Fake enough to be usable.
+
 
-Point it at an OpenAPI spec and it generates TypeScript handlers for every endpoint—type-safe, hot-reloading, sharing state across routes. A built-in REPL gives you a live control surface: seed data, trigger error conditions, proxy individual routes to a real backend, all on a running server. Whether you're a frontend developer waiting on a backend, a test engineer who needs clean reproducible state, or an AI agent that needs a stable API to work against, Counterfact is the simulator that doesn't plateau.
+## Try it now 
 
 ```sh
 npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ```
 
+> Starts a local server with a live REPL to inspect and control API behavior  
 > Requires Node ≥ 22.0.0
 
 ## Go deeper
 
-| | |
-|---|---|
-| [Getting started](./docs/getting-started.md) | Detailed walkthrough with state, REPL, and proxy |
-| [Usage](./docs/usage.md) | Feature index: routes, context, REPL, proxy, middleware, and more |
-| [Patterns](./docs/patterns/index.md) | Failures, latency, AI sandboxes, integration tests |
-| [Reference](./docs/reference.md) | `$` API, CLI flags, architecture |
-| [How it compares](./docs/comparison.md) | json-server, WireMock, Prism, Microcks, MSW |
-| [FAQ](./docs/faq.md) | State, types, regeneration |
-| [Petstore example](https://github.com/counterfact/example-petstore) | Full working example |
+- [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  
 
 <div align="center" markdown="1">
 

package/dist/api-runner.js

@@ -64,6 +64,11 @@ export class ApiRunner {
      * Defaults to `""` (no subdirectory).
      */
     group;
+    /**
+     * Optional version label for this runner's spec (e.g. `"v1"`, `"v2"`).
+     * Defaults to `""` (unversioned).
+     */
+    version;
     /**
      * The subdirectory path segment derived from {@link group}.
      * Returns `""` when `group` is empty, otherwise `"/${group}"`.
@@ -72,8 +77,9 @@ export class ApiRunner {
         return this.group ? `/${this.group}` : "";
     }
     config;
-    constructor(config, nativeTs, openApiDocument, group) {
+    constructor(config, nativeTs, openApiDocument, group, version = "", versions = []) {
         this.group = group;
+        this.version = version;
         const modulesPath = this.group
             ? pathJoin(config.basePath, this.group)
             : config.basePath;
@@ -87,8 +93,8 @@ export class ApiRunner {
         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);
-        this.dispatcher = new Dispatcher(this.registry, this.contextRegistry, openApiDocument, config);
+        this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate, version);
+        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);
     }
@@ -101,8 +107,10 @@ export class ApiRunner {
      *
      * @param config - Runtime configuration for this runner instance.
      * @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).
      */
-    static async create(config, group = "") {
+    static async create(config, group = "", version = "", versions = []) {
         const nativeTs = await runtimeCanExecuteErasableTs();
         const modulesPath = group
             ? pathJoin(config.basePath, group)
@@ -114,7 +122,7 @@ export class ApiRunner {
         const openApiDocument = config.openApiPath === "_"
             ? undefined
             : await loadOpenApiDocument(config.openApiPath);
-        return new ApiRunner(config, nativeTs, openApiDocument, group);
+        return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions);
     }
     /**
      * Generates TypeScript route stubs and type files from the OpenAPI spec.
@@ -123,11 +131,15 @@ export class ApiRunner {
      * - Routes and types are only generated when `config.openApiPath` is not `"_"`.
      * - The scenario context type file is always generated when
      *   `config.generate.types` is `true`, even without a spec.
+     *
+     * @param repository - Optional shared repository.  Pass a shared instance
+     *   when multiple versioned specs in the same group should merge their types
+     *   into the same output tree.
      */
-    async generate() {
+    async generate(repository) {
         if (this.config.openApiPath !== "_" &&
             (this.config.generate.routes || this.config.generate.types)) {
-            await this.codeGenerator.generate();
+            await this.codeGenerator.generate(repository);
         }
         if (this.config.generate.types) {
             await this.scenarioFileGenerator.generate();

package/dist/app.js

@@ -1,8 +1,13 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
 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 { createKoaApp } from "./server/web-server/create-koa-app.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";
 export { loadOpenApiDocument } from "./server/load-openapi-document.js";
 export { createMswHandlers, handleMswRequest, } from "./msw.js";
 export async function runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument) {
@@ -18,19 +23,47 @@ 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).
+ */
+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}`;
+    }
+    return "";
+}
 /**
  * Normalises the spec configuration to an array.
  *
- * When `specs` is provided it is returned as-is. When it is omitted, a
- * single-entry array is constructed from `config.openApiPath`,
- * `config.prefix`, and `group = ""` so that the rest of the code never
- * needs to branch on single-vs-multiple specs.
+ * 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 = ""`.
  */
 function normalizeSpecs(config, specs) {
     if (specs !== undefined) {
-        return specs;
+        return specs.map((spec) => ({ ...spec, prefix: derivePrefix(spec) }));
     }
-    return [{ source: config.openApiPath, prefix: config.prefix, group: "" }];
+    return [
+        {
+            source: config.openApiPath,
+            prefix: config.prefix,
+            group: "",
+            version: "",
+        },
+    ];
 }
 function validateSpecGroups(specs) {
     if (specs.length <= 1) {
@@ -41,20 +74,26 @@ function validateSpecGroups(specs) {
         .filter(({ group }) => group === "")
         .map(({ index }) => String(index + 1));
     if (invalidSpecNumbers.length === 0) {
-        const seenGroups = new Set();
-        const duplicateGroupNames = new Set();
+        const seenKeys = new Set();
+        const duplicateKeys = new Set();
         for (const spec of specs) {
             const group = spec.group.trim();
-            if (seenGroups.has(group)) {
-                duplicateGroupNames.add(group);
+            const version = spec.version?.trim() ?? "";
+            // Use group@version as the uniqueness key so that the same group can
+            // appear with different versions (e.g. v1 and v2 of the same API).
+            // The empty-group case is already rejected above, so `group` is always
+            // non-empty here and the `@version` suffix remains unambiguous.
+            const key = version ? `${group}@${version}` : group;
+            if (seenKeys.has(key)) {
+                duplicateKeys.add(key);
                 continue;
             }
-            seenGroups.add(group);
+            seenKeys.add(key);
         }
-        if (duplicateGroupNames.size === 0) {
+        if (duplicateKeys.size === 0) {
             return;
         }
-        throw new Error(`Each spec must define a unique group when multiple APIs are configured (duplicate groups: ${[...duplicateGroupNames].join(", ")}).`);
+        throw new Error(`Each spec must define a unique group (and version) when multiple APIs are configured (duplicates: ${[...duplicateKeys].join(", ")}).`);
     }
     throw new Error(`Each spec must define a non-empty group when multiple APIs are configured (invalid spec entries: ${invalidSpecNumbers.join(", ")}).`);
 }
@@ -81,7 +120,18 @@ function validateSpecGroups(specs) {
 export async function counterfact(config, specs) {
     const normalizedSpecs = normalizeSpecs({ openApiPath: config.openApiPath, prefix: config.prefix }, specs);
     validateSpecGroups(normalizedSpecs);
-    const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({ ...config, openApiPath: spec.source, prefix: spec.prefix }, spec.group)));
+    // Compute the ordered versions per group (oldest first, as declared in specs).
+    // This list is passed to each runner so that $.minVersion() can compare
+    // version positions at runtime.
+    const versionsByGroup = new Map();
+    for (const spec of normalizedSpecs) {
+        const version = spec.version ?? "";
+        if (version) {
+            const existing = versionsByGroup.get(spec.group) ?? [];
+            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 koaApp = createKoaApp({
         runners,
         config,
@@ -89,7 +139,61 @@ export async function counterfact(config, specs) {
     // The REPL is configured using the first runner.
     const primaryRunner = runners[0];
     async function start(options) {
-        await Promise.all(runners.map((runner) => runner.generate()));
+        // Serialize generate() calls within each group to avoid concurrent writes
+        // to the same output directory.  Runners that share a group share the same
+        // basePath subdirectory (and therefore the same counterfact-types
+        // destination), so running them in parallel would cause a race when both
+        // try to create that directory at startup.  Different groups are still
+        // generated in parallel.
+        //
+        // When multiple versioned specs share the same group, they also share a
+        // single Repository instance so that the shared `types/paths/…` files
+        // accumulate all versions into a merged Versioned<…> type instead of each
+        // overwriting the previous version's types.
+        const runnersByGroup = new Map();
+        for (const runner of runners) {
+            const bucket = runnersByGroup.get(runner.group) ?? [];
+            bucket.push(runner);
+            runnersByGroup.set(runner.group, bucket);
+        }
+        await Promise.all(Array.from(runnersByGroup.values()).map(async (bucket) => {
+            const sharedRepository = bucket.length > 1 ? new Repository() : undefined;
+            for (const runner of bucket) {
+                await runner.generate(sharedRepository);
+            }
+        }));
+        if (options.generate?.types) {
+            // Build a per-group map of unique non-empty version strings in
+            // declaration order. new Set() preserves insertion order so the first
+            // occurrence of each version is kept and duplicates are dropped without
+            // reordering.
+            const versionsByGroup = new Map();
+            for (const spec of normalizedSpecs) {
+                const group = spec.group;
+                const version = (spec.version ?? "").trim();
+                if (version === "") {
+                    continue;
+                }
+                const existing = versionsByGroup.get(group) ?? [];
+                if (!existing.includes(version)) {
+                    existing.push(version);
+                }
+                versionsByGroup.set(group, existing);
+            }
+            // Write <basePath>/<group>/types/versions.ts for every group that has
+            // at least one versioned spec.  When the group is empty the path
+            // collapses to <basePath>/types/versions.ts (the single-spec case).
+            await Promise.all(Array.from(versionsByGroup.entries()).map(async ([group, versions]) => {
+                const content = await generateVersionsTsContent(versions);
+                const versionsFilePath = group
+                    ? nodePath.join(config.basePath, group, "types", "versions.ts")
+                    : nodePath.join(config.basePath, "types", "versions.ts");
+                /* eslint-disable security/detect-non-literal-fs-filename -- path is derived from the caller-supplied basePath and fixed suffixes. */
+                await ensureDirectoryExists(versionsFilePath);
+                await fs.writeFile(versionsFilePath, content, "utf8");
+                /* eslint-enable security/detect-non-literal-fs-filename */
+            }));
+        }
         await Promise.all(runners.map((runner) => runner.watch()));
         await Promise.all(runners.map((runner) => runner.start(options)));
         let httpTerminator;

package/dist/cli/banner.js

@@ -67,7 +67,7 @@ export function createIntroduction(params) {
         `   API Base URL  ${url}`,
         source === "_" ? undefined : `   Swagger UI    ${swaggerUrl}`,
         "",
-        "   Instructions  https://counterfact.dev/docs/usage.html",
+        "   Instructions  https://github.com/counterfact/api-simulator/blob/main/docs/usage.md",
         "   Help/feedback https://github.com/pmcelhaney/counterfact/issues",
         "",
         ...telemetryWarning,

package/dist/cli/run.js

@@ -22,18 +22,23 @@ 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}` with defaults.
+ * - **Array**: each entry is mapped to `{source, prefix, group, version}` 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
  *   (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`.
  */
 export function normalizeSpecOption(specOption) {
     if (Array.isArray(specOption)) {
         return specOption.map((entry) => ({
             source: entry.source,
-            prefix: entry.prefix ?? "",
+            prefix: entry.prefix,
             group: entry.group ?? "",
+            version: entry.version,
         }));
     }
     if (typeof specOption === "object" &&
@@ -42,8 +47,9 @@ export function normalizeSpecOption(specOption) {
         return [
             {
                 source: specOption.source,
-                prefix: specOption.prefix ?? "",
+                prefix: specOption.prefix,
                 group: specOption.group ?? "",
+                version: specOption.version,
             },
         ];
     }
@@ -253,7 +259,7 @@ function buildProgram(version, taglines) {
         .option("--watch-routes", "generate + watch routes for changes")
         .option("-s, --serve", "start the server")
         .option("-b, --build-cache", "builds the cache of compiled routes and types")
-        .option("--no-admin-api", "disable the admin API at /_counterfact/api/*")
+        .option("--admin-api", "enable the admin API at /_counterfact/api/*")
         .option("-r, --repl", "start the REPL")
         .option("--proxy-url <string>", "proxy URL")
         .option("--admin-api-token <string>", "bearer token required for /_counterfact/api/* endpoints (defaults to COUNTERFACT_ADMIN_API_TOKEN)")

package/dist/cli/telemetry.js

@@ -5,9 +5,7 @@ const POSTHOG_HOST = "https://us.i.posthog.com";
 /**
  * Returns `true` when telemetry should be sent.
  *
- * Telemetry is disabled in CI, when `COUNTERFACT_TELEMETRY_DISABLED=true`,
- * or before the May 2026 rollout date unless the user has explicitly opted
- * in with `COUNTERFACT_TELEMETRY_DISABLED=false`.
+ * Telemetry is disabled in CI or when `COUNTERFACT_TELEMETRY_DISABLED=true`.
  */
 export function isTelemetryEnabled() {
     if (process.env["CI"])
@@ -15,9 +13,6 @@ export function isTelemetryEnabled() {
     const telemetryDisabledEnv = process.env["COUNTERFACT_TELEMETRY_DISABLED"];
     if (telemetryDisabledEnv === "true")
         return false;
-    const isBeforeRollout = new Date() < new Date("2026-05-01");
-    if (isBeforeRollout && telemetryDisabledEnv !== "false")
-        return false;
     return true;
 }
 /**

package/dist/migrate/update-route-types.js

@@ -67,7 +67,7 @@ async function buildTypeNameMapping(specification) {
                     return;
                 }
                 // Create the type coder to get the correct type name
-                const typeCoder = new OperationTypeCoder(operation, requestMethod, securitySchemes);
+                const typeCoder = new OperationTypeCoder(operation, "", requestMethod, securitySchemes);
                 // Get the type name (first from the names generator)
                 const typeName = typeCoder.names().next().value;
                 methodMap.set(requestMethod.toUpperCase(), typeName);

package/dist/repl/repl.js

@@ -194,9 +194,6 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             }
             seenGroups.add(binding.key);
         }
-        if (duplicateGroups.size > 0) {
-            throw new Error(`Duplicate API groups are not allowed when multiple APIs are configured (duplicate groups: ${[...duplicateGroups].join(", ")}).`);
-        }
     }
     const rootBinding = groupedBindings[0];
     if (rootBinding === undefined) {
@@ -268,7 +265,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             print("- context: the root context ( same as loadContext('/') )");
             print("- route('/some/path'): create a request builder for the given path");
             print("");
-            print("For more information, see https://counterfact.dev/docs/usage.html");
+            print("For more information, see https://github.com/counterfact/api-simulator/blob/main/docs/usage.md");
             print("");
             this.clearBufferedCommand();
             this.displayPrompt();

package/dist/server/counterfact-types/generic-response-builder.ts

@@ -157,8 +157,7 @@ export type GenericResponseBuilder<
   : object extends OmitValueWhenNever<Omit<Response, "examples">>
     ? COUNTERFACT_RESPONSE
     : keyof OmitValueWhenNever<Omit<Response, "examples">> extends "headers"
-      ? {
-          ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE;
+      ? COUNTERFACT_RESPONSE & {
           header: HeaderFunction<Response>;
         }
       : GenericResponseBuilderInner<Response>;

package/dist/server/counterfact-types/open-api-parameters.ts

@@ -5,12 +5,15 @@
  * argument object.
  */
 export interface OpenApiParameters {
+  explode?: boolean;
   in: "body" | "cookie" | "formData" | "header" | "path" | "query";
   name: string;
   required?: boolean;
   schema?: {
     [key: string]: unknown;
+    properties?: Record<string, unknown>;
     type?: string;
   };
+  style?: string;
   type?: "string" | "number" | "integer" | "boolean";
 }