counterfact 2.2.1 → 2.4.0

package/README.md

@@ -202,6 +202,7 @@ npx counterfact@latest [openapi.yaml] [destination] [options]
 | `-w, --watch`       | Generate and watch for spec changes         |
 | `-s, --serve`       | Start the mock server                       |
 | `-r, --repl`        | Start the interactive REPL                  |
+| `--spec <path>`     | Path or URL to the OpenAPI document         |
 | `--proxy-url <url>` | Forward all requests to this URL by default |
 | `--prefix <path>`   | Base path prefix (e.g. `/api/v1`)           |
 

package/bin/README.md

@@ -37,6 +37,7 @@ npx counterfact openapi.yaml ./api [options]
 | `-w, --watch` | Re-generate whenever the spec changes |
 | `-s, --serve` | Start the HTTP server |
 | `-r, --repl` | Start the interactive REPL |
+| `--spec <path>` | Path or URL to the OpenAPI document (alternative to positional argument) |
 | `--proxy-url <url>` | Forward all unmatched requests to this upstream URL |
 | `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
 

package/bin/counterfact.js

@@ -47,7 +47,7 @@ function padTagLine(tagLine) {
 }
 
 function createWatchMessage(config) {
-  let watchMessage = "";
+  let watchMessage;
 
   switch (true) {
     case config.watch.routes && config.watch.types: {
@@ -102,11 +102,18 @@ async function main(source, destination) {
 
   const options = program.opts();
 
-  const args = process.argv;
+  // --spec takes precedence over the positional [openapi.yaml] argument.
+  // When --spec is provided, the [openapi.yaml] positional slot shifts to
+  // become the [destination] argument (so `counterfact --spec api.yaml ./api`
+  // works the same as `counterfact api.yaml ./api`).
+  if (options.spec) {
+    if (source !== "_") {
+      destination = source;
+    }
+    source = options.spec;
+  }
 
-  const destinationPath = nodePath
-    .join(process.cwd(), destination)
-    .replaceAll("\\", "/");
+  const destinationPath = nodePath.resolve(destination).replaceAll("\\", "/");
 
   const basePath = nodePath.resolve(destinationPath).replaceAll("\\", "/");
 
@@ -155,6 +162,8 @@ async function main(source, destination) {
         options.watch ||
         options.watchTypes ||
         options.buildCache,
+
+      prune: Boolean(options.prune),
     },
 
     openApiPath: source,
@@ -181,9 +190,8 @@ async function main(source, destination) {
   debug("loading counterfact (%o)", configForLogging);
 
   let didMigrate = false;
-  let didMigrateRouteTypes = false;
+  let didMigrateRouteTypes;
 
-  // eslint-disable-next-line n/no-sync
   if (fs.existsSync(nodePath.join(config.basePath, "paths"))) {
     await pathsToRoutes(config.basePath);
     await fs.promises.rmdir(nodePath.join(config.basePath, "paths"), {
@@ -199,7 +207,7 @@ async function main(source, destination) {
     didMigrate = true;
   }
 
-  const { start } = await counterfact(config);
+  const { start, startRepl } = await counterfact(config);
 
   debug("loaded counterfact", configForLogging);
 
@@ -246,6 +254,10 @@ async function main(source, destination) {
   await start(config);
   debug("started server");
 
+  if (config.startRepl) {
+    startRepl();
+  }
+
   if (openBrowser) {
     debug("opening browser");
     await open(guiUrl);
@@ -326,5 +338,13 @@ program
     "--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)",
+  )
   .action(main)
   .parse(process.argv);

package/dist/app.js

@@ -2,8 +2,7 @@ import fs, { rm } from "node:fs/promises";
 import nodePath from "node:path";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
 import { createHttpTerminator } from "http-terminator";
-import yaml from "js-yaml";
-import { startRepl } from "./repl/repl.js";
+import { startRepl as startReplServer } from "./repl/repl.js";
 import { ContextRegistry } from "./server/context-registry.js";
 import { createKoaApp } from "./server/create-koa-app.js";
 import { Dispatcher, } from "./server/dispatcher.js";
@@ -12,7 +11,6 @@ import { ModuleLoader } from "./server/module-loader.js";
 import { Registry } from "./server/registry.js";
 import { Transpiler } from "./server/transpiler.js";
 import { CodeGenerator } from "./typescript-generator/code-generator.js";
-import { readFile } from "./util/read-file.js";
 const allowedMethods = [
     "all",
     "head",
@@ -25,9 +23,7 @@ const allowedMethods = [
 ];
 export async function loadOpenApiDocument(source) {
     try {
-        const text = await readFile(source);
-        const openApiDocument = await yaml.load(text);
-        return (await dereference(openApiDocument));
+        return (await dereference(source));
     }
     catch {
         return undefined;
@@ -46,7 +42,7 @@ export async function handleMswRequest(request) {
 export async function createMswHandlers(config, ModuleLoaderClass = ModuleLoader) {
     // TODO: For some reason the Vitest Custom Commands needed by Vitest Browser mode fail on fs.readFile when they are called from the nested loadOpenApiDocument function.
     // If we "pre-read" the file here it works. This is a workaround to avoid the issue.
-    const _ = await fs.readFile(config.openApiPath);
+    await fs.readFile(config.openApiPath);
     const openApiDocument = await loadOpenApiDocument(config.openApiPath);
     if (openApiDocument === undefined) {
         throw new Error(`Could not load OpenAPI document from ${config.openApiPath}`);
@@ -92,7 +88,7 @@ export async function counterfact(config) {
     const middleware = koaMiddleware(dispatcher, config);
     const koaApp = createKoaApp(registry, middleware, config, contextRegistry);
     async function start(options) {
-        const { generate, startRepl: shouldStartRepl, startServer, watch, buildCache, } = options;
+        const { generate, startServer, watch, buildCache } = options;
         if (generate.routes || generate.types) {
             await codeGenerator.generate();
         }
@@ -116,9 +112,7 @@ export async function counterfact(config) {
             await transpiler.watch();
             await transpiler.stopWatching();
         }
-        const replServer = shouldStartRepl && startRepl(contextRegistry, config);
         return {
-            replServer,
             async stop() {
                 await codeGenerator.stopWatching();
                 await transpiler.stopWatching();
@@ -133,5 +127,6 @@ export async function counterfact(config) {
         koaMiddleware: middleware,
         registry,
         start,
+        startRepl: () => startReplServer(contextRegistry, registry, config),
     };
 }

package/dist/counterfact-types/index.js

@@ -1,5 +1,2 @@
 const counterfactResponse = Symbol("Counterfact Response");
-const counterfactResponseObject = {
-    [counterfactResponse]: counterfactResponse,
-};
 export {};

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

@@ -94,7 +94,7 @@ async function updateRouteFile(filePath, methodToTypeName) {
     // Build a map of old type names to new type names found in this file
     const replacements = new Map();
     // Find all import statements with HTTP_ patterns
-    const importRegex = /import\s+type\s+\{(?<types>[^}]+)\}\s+from\s+["'](?<source>[^"']+)["'];?/gu;
+    const importRegex = /import\s+type\s+\{(?<types>[^}]+)\}\s+from\s+["'][^"']+["'];?/gu;
     let importMatch;
     while ((importMatch = importRegex.exec(content)) !== null) {
         const importedTypes = importMatch.groups.types

package/dist/repl/repl.js

@@ -3,7 +3,25 @@ import { RawHttpClient } from "./RawHttpClient.js";
 function printToStdout(line) {
     process.stdout.write(`${line}\n`);
 }
-export function startRepl(contextRegistry, config, print = printToStdout) {
+export function createCompleter(registry, fallback) {
+    return (line, callback) => {
+        const match = line.match(/client\.(?:get|post|put|patch|delete)\("(?<partial>[^"]*)$/u);
+        if (!match) {
+            if (fallback) {
+                fallback(line, callback);
+            }
+            else {
+                callback(null, [[], line]);
+            }
+            return;
+        }
+        const partial = match.groups?.["partial"] ?? "";
+        const routes = registry.routes.map((route) => route.path);
+        const matches = routes.filter((route) => route.startsWith(partial));
+        callback(null, [matches, partial]);
+    };
+}
+export function startRepl(contextRegistry, registry, config, print = printToStdout) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -41,7 +59,13 @@ export function startRepl(contextRegistry, config, print = printToStdout) {
             print(`Requests to ${printEndpoint} will be handled by local code`);
         }
     }
-    const replServer = repl.start({ prompt: "⬣> " });
+    const replServer = repl.start({
+        prompt: "⬣> ",
+    });
+    const builtinCompleter = replServer.completer;
+    // completer is typed as readonly in @types/node but is writable at runtime
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    replServer.completer = createCompleter(registry, builtinCompleter);
     replServer.defineCommand("counterfact", {
         action() {
             print("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.");

package/dist/server/admin-api-middleware.js

@@ -118,10 +118,10 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
             // ===== Update Context =====
             if (resource === "contexts" && rest.length > 0 && ctx.method === "POST") {
                 const path = "/" + rest.join("/");
-                const newContext = ctx.request.body;
-                if (!newContext ||
-                    typeof newContext !== "object" ||
-                    Array.isArray(newContext)) {
+                const newContextCandidate = ctx.request.body;
+                if (!newContextCandidate ||
+                    typeof newContextCandidate !== "object" ||
+                    Array.isArray(newContextCandidate)) {
                     ctx.status = 400;
                     ctx.body = {
                         success: false,
@@ -130,6 +130,7 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
                     return;
                 }
                 // Update the context using the registry's smart diffing
+                const newContext = newContextCandidate;
                 contextRegistry.update(path, newContext);
                 ctx.body = {
                     success: true,

package/dist/server/counterfact-types/OpenApiHeader.ts

@@ -1,3 +1,4 @@
 export interface OpenApiHeader {
-  schema: unknown;
+  required?: boolean;
+  schema: { [key: string]: unknown };
 }

package/dist/server/counterfact-types/index.ts

@@ -10,14 +10,22 @@ interface Example {
   value: unknown;
 }
 
+interface CookieOptions {
+  domain?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "lax" | "none" | "strict";
+  secure?: boolean;
+}
+
 const counterfactResponse = Symbol("Counterfact Response");
 
-const counterfactResponseObject = {
-  [counterfactResponse]: counterfactResponse,
+type COUNTERFACT_RESPONSE = {
+  [counterfactResponse]: typeof counterfactResponse;
 };
 
-type COUNTERFACT_RESPONSE = typeof counterfactResponseObject;
-
 type MediaType = `${string}/${string}`;
 
 type MaybePromise<T> = T | Promise<T>;
@@ -38,7 +46,7 @@ type OmitValueWhenNever<Base> = Pick<
 interface OpenApiResponse {
   content: { [key: MediaType]: OpenApiContent };
   examples?: { [key: string]: unknown };
-  headers: { [key: string]: OpenApiHeader };
+  headers: { [key: string]: { schema: unknown } };
   requiredHeaders: string;
 }
 
@@ -55,12 +63,12 @@ type IfHasKey<
   infer FirstKey extends string,
   ...infer RestKeys extends string[],
 ]
-  ? keyof SomeObject extends FirstKey
-    ? Yes
-    : IfHasKey<SomeObject, RestKeys, Yes, No>
+  ? Extract<keyof SomeObject, `${string}${FirstKey}${string}`> extends never
+    ? IfHasKey<SomeObject, RestKeys, Yes, No>
+    : Yes
   : No;
 
-type SchemasOf<T extends { [key: string]: { schema: any } }> = {
+type SchemasOf<T extends { [key: string]: { schema: unknown } }> = {
   [K in keyof T]: T[K]["schema"];
 }[keyof T];
 
@@ -78,7 +86,7 @@ type MaybeShortcut<
   never
 >;
 
-type NeverIfEmpty<Record> = {} extends Record ? never : Record;
+type NeverIfEmpty<Record> = object extends Record ? never : Record;
 
 type MatchFunction<Response extends OpenApiResponse> = <
   ContentType extends MediaType & keyof Response["content"],
@@ -102,9 +110,7 @@ type HeaderFunction<Response extends OpenApiResponse> = <
   requiredHeaders: Exclude<Response["requiredHeaders"], Header>;
 }>;
 
-type RandomFunction<Response extends OpenApiResponse> = <
-  Header extends string & keyof Response["headers"],
->() => COUNTERFACT_RESPONSE;
+type RandomFunction = () => MaybePromise<COUNTERFACT_RESPONSE>;
 
 type ExampleNames<Response extends OpenApiResponse> = Response extends {
   examples: infer E;
@@ -114,15 +120,21 @@ type ExampleNames<Response extends OpenApiResponse> = Response extends {
 
 interface ResponseBuilder {
   [status: number | `${number} ${string}`]: ResponseBuilder;
+  binary: (body: Uint8Array | string) => ResponseBuilder;
   content?: { body: unknown; type: string }[];
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => ResponseBuilder;
   example: (name: string) => ResponseBuilder;
   header: (name: string, value: string) => ResponseBuilder;
-  headers: { [name: string]: string };
+  headers: { [name: string]: string | string[] };
   html: (body: unknown) => ResponseBuilder;
   json: (body: unknown) => ResponseBuilder;
   match: (contentType: string, body: unknown) => ResponseBuilder;
-  random: () => ResponseBuilder;
-  randomLegacy: () => ResponseBuilder;
+  random: () => MaybePromise<ResponseBuilder>;
+  randomLegacy: () => MaybePromise<ResponseBuilder>;
   status?: number;
   text: (body: unknown) => ResponseBuilder;
   xml: (body: unknown) => ResponseBuilder;
@@ -131,6 +143,12 @@ interface ResponseBuilder {
 export type GenericResponseBuilderInner<
   Response extends OpenApiResponse = OpenApiResponse,
 > = OmitValueWhenNever<{
+  binary: MaybeShortcut<["application/octet-stream"], Response>;
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => GenericResponseBuilder<Response>;
   header: [keyof Response["headers"]] extends [never]
     ? never
     : HeaderFunction<Response>;
@@ -148,9 +166,7 @@ export type GenericResponseBuilderInner<
   match: [keyof Response["content"]] extends [never]
     ? never
     : MatchFunction<Response>;
-  random: [keyof Response["content"]] extends [never]
-    ? never
-    : RandomFunction<Response>;
+  random: [keyof Response["content"]] extends [never] ? never : RandomFunction;
   example: [ExampleNames<Response>] extends [never]
     ? never
     : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
@@ -257,18 +273,27 @@ interface OpenApiOperation {
         };
       };
       examples?: { [key: string]: unknown };
+      headers?: {
+        [name: string]: OpenApiHeader;
+      };
       schema?: { [key: string]: unknown };
     };
   };
 }
 
 interface WideResponseBuilder {
+  binary: (body: Uint8Array | string) => WideResponseBuilder;
   example: (name: string) => WideResponseBuilder;
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => WideResponseBuilder;
   header: (body: unknown) => WideResponseBuilder;
   html: (body: unknown) => WideResponseBuilder;
   json: (body: unknown) => WideResponseBuilder;
   match: (contentType: string, body: unknown) => WideResponseBuilder;
-  random: () => WideResponseBuilder;
+  random: () => MaybePromise<WideResponseBuilder>;
   text: (body: unknown) => WideResponseBuilder;
   xml: (body: unknown) => WideResponseBuilder;
 }
@@ -286,6 +311,7 @@ interface WideOperationArgument {
 export type { COUNTERFACT_RESPONSE };
 
 export type {
+  CookieOptions,
   ExampleNames,
   HttpStatusCode,
   MaybePromise,

package/dist/server/determine-module-kind.js

@@ -1,4 +1,3 @@
-/* eslint-disable n/no-sync */
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";

package/dist/server/dispatcher.js

@@ -4,6 +4,26 @@ import fetch, { Headers } from "node-fetch";
 import { createResponseBuilder } from "./response-builder.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
+function parseCookies(cookieHeader) {
+    const cookies = {};
+    for (const part of cookieHeader.split(";")) {
+        const eqIndex = part.indexOf("=");
+        if (eqIndex === -1) {
+            continue;
+        }
+        const key = part.slice(0, eqIndex).trim();
+        const value = part.slice(eqIndex + 1).trim();
+        if (key && !(key in cookies)) {
+            try {
+                cookies[key] = decodeURIComponent(value);
+            }
+            catch {
+                cookies[key] = value;
+            }
+        }
+    }
+    return cookies;
+}
 export class Dispatcher {
     registry;
     contextRegistry;
@@ -143,6 +163,7 @@ export class Dispatcher {
                     : continuousDistribution(milliseconds, maxMilliseconds);
                 return new Promise((resolve) => setTimeout(resolve, delayInMs));
             },
+            cookie: parseCookies(headers.cookie ?? headers.Cookie ?? ""),
             headers,
             proxy: async (url) => {
                 if (body !== undefined && headers.contentType !== "application/json") {

package/dist/server/koa-middleware.js

@@ -72,10 +72,19 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
             req: { path: "", ...ctx.req },
         });
         ctx.body = response.body;
+        if (response.contentType !== undefined &&
+            response.contentType !== "unknown/unknown") {
+            ctx.type = response.contentType;
+        }
         if (response.headers) {
             for (const [key, value] of Object.entries(response.headers)) {
                 if (!HEADERS_TO_DROP.has(key.toLowerCase())) {
-                    ctx.set(key, value.toString());
+                    if (Array.isArray(value)) {
+                        ctx.set(key, value);
+                    }
+                    else {
+                        ctx.set(key, value.toString());
+                    }
                 }
             }
         }

package/dist/server/module-loader.js

@@ -1,4 +1,3 @@
-/* eslint-disable n/no-sync */
 import { once } from "node:events";
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
@@ -103,17 +102,35 @@ export class ModuleLoader extends EventTarget {
             const doImport = (await determineModuleKind(pathName)) === "commonjs"
                 ? uncachedRequire
                 : uncachedImport;
-            const endpoint = (await doImport(pathName).catch((err) => {
+            const endpoint = (await doImport(pathName).catch(() => {
                 console.log("ERROR");
             }));
             this.dispatchEvent(new Event("add"));
             if (basename(pathName).startsWith("_.context.") &&
                 isContextModule(endpoint)) {
                 const loadContext = (path) => this.contextRegistry.find(path);
+                const contextDir = nodePath.dirname(unescapePathForWindows(pathName));
+                const readJson = async (relativePath) => {
+                    const absolutePath = nodePath.resolve(contextDir, relativePath);
+                    let content;
+                    try {
+                        content = await fs.readFile(absolutePath, "utf8");
+                    }
+                    catch {
+                        throw new Error(`readJson: could not read file at "${absolutePath}" (resolved from "${relativePath}" relative to "${contextDir}")`);
+                    }
+                    try {
+                        return JSON.parse(content);
+                    }
+                    catch {
+                        throw new Error(`readJson: file at "${absolutePath}" does not contain valid JSON`);
+                    }
+                };
                 this.contextRegistry.update(directory, 
                 // @ts-expect-error TS says Context has no constructable signatures but that's not true?
                 new endpoint.Context({
                     loadContext,
+                    readJson,
                 }));
                 return;
             }

package/dist/server/module-tree.js

@@ -17,6 +17,7 @@ export class ModuleTree {
         if (remainingSegments.length === 0) {
             return directory;
         }
+        const isNewDirectory = directory.directories[segment.toLowerCase()] === undefined;
         const nextDirectory = (directory.directories[segment.toLowerCase()] ??= {
             directories: {},
             files: {},
@@ -24,6 +25,12 @@ export class ModuleTree {
             name: segment.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
             rawName: segment,
         });
+        if (isNewDirectory && segment.startsWith("{")) {
+            const ambiguousWildcardDirectories = Object.values(directory.directories).filter((subdirectory) => subdirectory.isWildcard);
+            if (ambiguousWildcardDirectories.length > 1) {
+                process.stderr.write(`[counterfact] ERROR: Ambiguous wildcard paths detected. Multiple wildcard directories exist at the same level: ${ambiguousWildcardDirectories.map((d) => d.rawName).join(", ")}. Requests may be routed unpredictably.\n`);
+            }
+        }
         return this.putDirectory(nextDirectory, remainingSegments);
     }
     addModuleToDirectory(directory, segments, module) {
@@ -41,6 +48,12 @@ export class ModuleTree {
             name: filename.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
             rawName: filename,
         };
+        if (filename.startsWith("{")) {
+            const ambiguousWildcardFiles = Object.values(targetDirectory.files).filter((file) => file.isWildcard);
+            if (ambiguousWildcardFiles.length > 1) {
+                process.stderr.write(`[counterfact] ERROR: Ambiguous wildcard paths detected. Multiple wildcard files exist at the same path level: ${ambiguousWildcardFiles.map((f) => f.rawName).join(", ")}. Requests may be routed unpredictably.\n`);
+            }
+        }
     }
     add(url, module) {
         this.addModuleToDirectory(this.root, url.split("/").slice(1), module);
@@ -75,8 +88,31 @@ export class ModuleTree {
             }
             return "";
         }
-        const match = directory.files[normalizedSegment(segment, directory)] ??
-            Object.values(directory.files).find((file) => file.isWildcard && this.fileModuleDefined(file, method));
+        const exactMatchFile = directory.files[normalizedSegment(segment, directory)];
+        // If the URL segment literally matches a file key (e.g., requesting "/{x}"
+        // as a literal URL value), exactMatchFile may be a wildcard file. In that
+        // case, fall through to wildcard matching below.
+        if (exactMatchFile !== undefined && !exactMatchFile.isWildcard) {
+            return {
+                ...exactMatchFile,
+                matchedPath: `${matchedPath}/${exactMatchFile.rawName}`,
+                pathVariables,
+            };
+        }
+        const wildcardFiles = Object.values(directory.files).filter((file) => file.isWildcard && this.fileModuleDefined(file, method));
+        if (wildcardFiles.length > 1) {
+            const firstWildcard = wildcardFiles[0];
+            return {
+                ...firstWildcard,
+                ambiguous: true,
+                matchedPath: `${matchedPath}/${firstWildcard.rawName}`,
+                pathVariables: {
+                    ...pathVariables,
+                    [firstWildcard.name]: segment,
+                },
+            };
+        }
+        const match = exactMatchFile ?? wildcardFiles[0];
         if (match === undefined) {
             return undefined;
         }
@@ -113,16 +149,21 @@ export class ModuleTree {
             return this.matchWithinDirectory(exactMatch, remainingSegments, pathVariables, `${matchedPath}/${segment}`, method);
         }
         const wildcardDirectories = Object.values(directory.directories).filter((subdirectory) => subdirectory.isWildcard);
+        const wildcardMatches = [];
         for (const wildcardDirectory of wildcardDirectories) {
-            const match = this.matchWithinDirectory(wildcardDirectory, remainingSegments, {
+            const wildcardMatch = this.matchWithinDirectory(wildcardDirectory, remainingSegments, {
                 ...pathVariables,
                 [wildcardDirectory.name]: segment,
             }, `${matchedPath}/${wildcardDirectory.rawName}`, method);
-            if (match !== undefined) {
-                return match;
+            if (wildcardMatch !== undefined) {
+                wildcardMatches.push(wildcardMatch);
             }
         }
-        return undefined;
+        if (wildcardMatches.length > 1) {
+            const firstMatch = wildcardMatches[0];
+            return { ...firstMatch, ambiguous: true };
+        }
+        return wildcardMatches[0];
     }
     match(url, method) {
         return this.matchWithinDirectory(this.root, url.split("/").slice(1), {}, "", method);

package/dist/server/openapi-middleware.js

@@ -1,9 +1,9 @@
+import { bundle } from "@apidevtools/json-schema-ref-parser";
 import yaml from "js-yaml";
-import { readFile } from "../util/read-file.js";
 export function openapiMiddleware(openApiPath, url) {
     return async (ctx, next) => {
         if (ctx.URL.pathname === "/counterfact/openapi") {
-            const openApiDocument = (await yaml.load(await readFile(openApiPath)));
+            const openApiDocument = (await bundle(openApiPath));
             openApiDocument.servers ??= [];
             openApiDocument.servers.unshift({
                 description: "Counterfact",

package/dist/server/registry.js

@@ -37,7 +37,7 @@ export class Registry {
     moduleTree = new ModuleTree();
     middlewares = new Map();
     constructor() {
-        this.middlewares.set("/", ($, respondTo) => respondTo($));
+        this.middlewares.set("", ($, respondTo) => respondTo($));
     }
     get routes() {
         return this.moduleTree.routes;
@@ -46,7 +46,7 @@ export class Registry {
         this.moduleTree.add(url, module);
     }
     addMiddleware(url, callback) {
-        this.middlewares.set(url, callback);
+        this.middlewares.set(url === "/" ? "" : url, callback);
     }
     remove(url) {
         this.moduleTree.remove(url);
@@ -57,6 +57,7 @@ export class Registry {
     handler(url, method) {
         const match = this.moduleTree.match(url, method);
         return {
+            ambiguous: match?.ambiguous ?? false,
             matchedPath: match?.matchedPath ?? "",
             module: match?.module,
             path: match?.pathVariables ?? {},
@@ -71,6 +72,14 @@ export class Registry {
     endpoint(httpRequestMethod, url, parameterTypes = {}) {
         const handler = this.handler(url, httpRequestMethod);
         debug("handler for %s: %o", url, handler);
+        if (handler.ambiguous) {
+            return () => ({
+                body: `Ambiguous wildcard paths: the request to ${url} matches multiple routes. Please resolve the ambiguity in your API spec or route handlers.`,
+                contentType: "text/plain",
+                headers: {},
+                status: 500,
+            });
+        }
         const execute = handler.module?.[httpRequestMethod];
         if (!execute) {
             debug(`Could not find a ${httpRequestMethod} method matching ${url}\n`);
@@ -111,11 +120,10 @@ export class Registry {
             };
             const middlewares = this.middlewares;
             function recurse(path, respondTo) {
+                debug("recursing path", path);
                 if (path === null)
                     return respondTo;
-                const nextPath = path === "/" || path === ""
-                    ? null
-                    : path.slice(0, path.lastIndexOf("/")) || "/";
+                const nextPath = path === "" ? null : path.slice(0, path.lastIndexOf("/"));
                 const middleware = middlewares.get(path);
                 if (middleware !== undefined) {
                     return recurse(nextPath, ($) => middleware($, respondTo));

package/dist/server/response-builder.js

@@ -1,11 +1,12 @@
-import { JSONSchemaFaker } from "json-schema-faker";
+import { generate } from "json-schema-faker";
 import { jsonToXml } from "./json-to-xml.js";
-JSONSchemaFaker.option("useExamplesValue", true);
-JSONSchemaFaker.option("minItems", 0);
-JSONSchemaFaker.option("maxItems", 20);
-JSONSchemaFaker.option("failOnInvalidTypes", false);
-JSONSchemaFaker.option("failOnInvalidFormat", false);
-JSONSchemaFaker.option("fillProperties", false);
+const DEFAULT_GENERATE_OPTIONS = {
+    useExamplesValue: true,
+    minItems: 0,
+    maxItems: 20,
+    failOnInvalidTypes: false,
+    fillProperties: false,
+};
 function convertToXmlIfNecessary(type, body, schema) {
     if (type.endsWith("/xml")) {
         return jsonToXml(body, schema, "root");
@@ -18,6 +19,32 @@ function oneOf(items) {
     }
     return oneOf(Object.values(items));
 }
+function serializeCookie(name, value, options = {}) {
+    const parts = [`${name}=${value}`];
+    if (options.path !== undefined) {
+        parts.push(`Path=${options.path}`);
+    }
+    if (options.domain !== undefined) {
+        parts.push(`Domain=${options.domain}`);
+    }
+    if (options.maxAge !== undefined) {
+        parts.push(`Max-Age=${options.maxAge}`);
+    }
+    if (options.expires !== undefined) {
+        parts.push(`Expires=${options.expires.toUTCString()}`);
+    }
+    if (options.httpOnly) {
+        parts.push("HttpOnly");
+    }
+    if (options.secure) {
+        parts.push("Secure");
+    }
+    if (options.sameSite !== undefined) {
+        const sameSiteMap = { lax: "Lax", none: "None", strict: "Strict" };
+        parts.push(`SameSite=${sameSiteMap[options.sameSite]}`);
+    }
+    return parts.join("; ");
+}
 function unknownStatusCodeResponse(statusCode) {
     return {
         content: [
@@ -41,6 +68,28 @@ export function createResponseBuilder(operation, config) {
                     },
                 };
             },
+            binary(body) {
+                const buffer = typeof body === "string"
+                    ? Buffer.from(body, "base64")
+                    : Buffer.from(body);
+                return this.match("application/octet-stream", buffer);
+            },
+            cookie(name, value, options = {}) {
+                const cookieString = serializeCookie(name, value, options);
+                const existing = this.headers?.["set-cookie"];
+                const existingArray = Array.isArray(existing)
+                    ? existing
+                    : existing !== undefined
+                        ? [existing]
+                        : [];
+                return {
+                    ...this,
+                    headers: {
+                        ...this.headers,
+                        "set-cookie": [...existingArray, cookieString],
+                    },
+                };
+            },
             html(body) {
                 return this.match("text/html", body);
             },
@@ -73,6 +122,18 @@ export function createResponseBuilder(operation, config) {
                     return unknownStatusCodeResponse(this.status);
                 }
                 const { content } = response;
+                const exampleExists = Object.values(content).some((contentType) => contentType?.examples?.[name] !== undefined);
+                if (!exampleExists) {
+                    return {
+                        content: [
+                            {
+                                body: `The OpenAPI document does not define an example named "${name}" for status code ${this.status ?? "unknown"}`,
+                                type: "text/plain",
+                            },
+                        ],
+                        status: 500,
+                    };
+                }
                 return {
                     ...this,
                     content: Object.keys(content).map((type) => ({
@@ -81,12 +142,15 @@ export function createResponseBuilder(operation, config) {
                     })),
                 };
             },
-            random() {
-                if (config?.alwaysFakeOptionals) {
-                    JSONSchemaFaker.option("alwaysFakeOptionals", true);
-                    JSONSchemaFaker.option("fixedProbabilities", true);
-                    JSONSchemaFaker.option("optionalsProbability", 1.0);
-                }
+            async random() {
+                const generateOptions = config?.alwaysFakeOptionals
+                    ? {
+                        ...DEFAULT_GENERATE_OPTIONS,
+                        alwaysFakeOptionals: true,
+                        fixedProbabilities: true,
+                        optionalsProbability: 1.0,
+                    }
+                    : DEFAULT_GENERATE_OPTIONS;
                 if (operation.produces) {
                     return this.randomLegacy();
                 }
@@ -96,17 +160,29 @@ export function createResponseBuilder(operation, config) {
                     return unknownStatusCodeResponse(this.status);
                 }
                 const { content } = response;
+                const generatedHeaders = {};
+                for (const [name, header] of Object.entries(response.headers ?? {})) {
+                    if (header.required && !(name in (this.headers ?? {}))) {
+                        generatedHeaders[name] = (await generate((header.schema ?? { type: "string" }), generateOptions));
+                    }
+                }
                 return {
                     ...this,
-                    content: Object.keys(content).map((type) => ({
+                    content: await Promise.all(Object.keys(content).map(async (type) => ({
                         body: convertToXmlIfNecessary(type, content[type]?.examples
                             ? oneOf(Object.values(content[type]?.examples ?? []).map((example) => example.value))
-                            : JSONSchemaFaker.generate(content[type]?.schema ?? { type: "object" }), content[type]?.schema),
+                            : await generate((content[type]?.schema ?? {
+                                type: "object",
+                            }), generateOptions), content[type]?.schema),
                         type,
-                    })),
+                    }))),
+                    headers: {
+                        ...generatedHeaders,
+                        ...this.headers,
+                    },
                 };
             },
-            randomLegacy() {
+            async randomLegacy() {
                 const response = operation.responses[this.status ?? "default"] ??
                     operation.responses.default;
                 if (response === undefined) {
@@ -114,7 +190,7 @@ export function createResponseBuilder(operation, config) {
                 }
                 const body = response.examples
                     ? oneOf(response.examples)
-                    : JSONSchemaFaker.generate(response.schema ?? { type: "object" });
+                    : await generate((response.schema ?? { type: "object" }), DEFAULT_GENERATE_OPTIONS);
                 return {
                     ...this,
                     content: operation.produces?.map((type) => ({

package/dist/server/tools.js

@@ -1,6 +1,4 @@
-import { JSONSchemaFaker } from "json-schema-faker";
-JSONSchemaFaker.option("useExamplesValue", true);
-JSONSchemaFaker.option("fillProperties", false);
+import { generate } from "json-schema-faker";
 export class Tools {
     headers;
     constructor({ headers = {}, } = {}) {
@@ -22,6 +20,6 @@ export class Tools {
         });
     }
     randomFromSchema(schema) {
-        return JSONSchemaFaker.generate(schema);
+        return generate(schema, { useExamplesValue: true, fillProperties: false });
     }
 }

package/dist/typescript-generator/generate.js

@@ -1,10 +1,10 @@
-/* eslint-disable n/no-sync */
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
 import createDebug from "debug";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { OperationCoder } from "./operation-coder.js";
+import { pruneRoutes } from "./prune.js";
 import { Repository } from "./repository.js";
 import { Specification } from "./specification.js";
 const debug = createDebug("counterfact:typescript-generator:generate");
@@ -41,6 +41,11 @@ export async function generate(source, destination, generateOptions, repository
     debug("reading the #/paths from the specification");
     const paths = await getPathsFromSpecification(specification);
     debug("got %i paths", paths.size);
+    if (generateOptions.prune && generateOptions.routes) {
+        debug("pruning defunct route files");
+        await pruneRoutes(destination, paths.keys());
+        debug("done pruning");
+    }
     const securityRequirement = specification.getRequirement("#/components/securitySchemes");
     const securitySchemes = Object.values(securityRequirement?.data ?? {});
     paths.forEach((pathDefinition, key) => {

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

@@ -102,6 +102,7 @@ export class OperationTypeCoder extends TypeCoder {
         const queryType = new ParametersTypeCoder(parameters, "query").write(script);
         const pathType = new ParametersTypeCoder(parameters, "path").write(script);
         const headersType = new ParametersTypeCoder(parameters, "header").write(script);
+        const cookieType = new ParametersTypeCoder(parameters, "cookie").write(script);
         const bodyRequirement = this.requirement.get("consumes") ||
             this.requirement.specification?.rootRequirement?.get("consumes")
             ? parameters
@@ -121,6 +122,7 @@ export class OperationTypeCoder extends TypeCoder {
         const queryTypeName = this.exportParameterType(script, "query", queryType, baseName, modulePath);
         const pathTypeName = this.exportParameterType(script, "path", pathType, baseName, modulePath);
         const headersTypeName = this.exportParameterType(script, "headers", headersType, baseName, modulePath);
-        return `($: OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType} }>) => MaybePromise<${this.responseTypes(script)} | { status: 415, contentType: "text/plain", body: string } | COUNTERFACT_RESPONSE | { ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE }>`;
+        const cookieTypeName = this.exportParameterType(script, "cookie", cookieType, baseName, modulePath);
+        return `($: OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType} }>) => MaybePromise<${this.responseTypes(script)} | { status: 415, contentType: "text/plain", body: string } | COUNTERFACT_RESPONSE | { ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE }>`;
     }
 }

package/dist/typescript-generator/prune.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+import createDebug from "debug";
+const debug = createDebug("counterfact:typescript-generator:prune");
+/**
+ * Collects all .ts route files in a directory recursively.
+ * Context files (_.context.ts) are excluded.
+ * @param {string} routesDir - Path to routes directory
+ * @param {string} currentPath - Current subdirectory being processed (relative to routesDir)
+ * @returns {Promise<string[]>} - Array of relative paths (using forward slashes)
+ */
+async function collectRouteFiles(routesDir, currentPath = "") {
+    const files = [];
+    try {
+        const fullDir = currentPath
+            ? nodePath.join(routesDir, currentPath)
+            : routesDir;
+        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)));
+            }
+            else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    return files;
+}
+/**
+ * Recursively removes empty directories under rootDir, but not rootDir itself.
+ * @param {string} dir - Directory to check
+ * @param {string} rootDir - Root directory that should never be removed
+ */
+async function removeEmptyDirectories(dir, rootDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await removeEmptyDirectories(nodePath.join(dir, entry.name), rootDir);
+        }
+    }
+    if (nodePath.resolve(dir) === nodePath.resolve(rootDir)) {
+        return;
+    }
+    const remaining = await fs.readdir(dir);
+    if (remaining.length === 0) {
+        await fs.rmdir(dir);
+        debug("removed empty directory: %s", dir);
+    }
+}
+/**
+ * Converts an OpenAPI path to the expected route file path (relative to routesDir).
+ * e.g. "/pet/{id}" -> "pet/{id}.ts", "/" -> "index.ts"
+ * @param {string} openApiPath
+ * @returns {string}
+ */
+function openApiPathToRouteFile(openApiPath) {
+    const filePath = openApiPath === "/" ? "index" : openApiPath.slice(1);
+    return `${filePath}.ts`;
+}
+/**
+ * Prunes route files that no longer correspond to any path in the OpenAPI spec.
+ * Context files (_.context.ts) are never pruned.
+ * @param {string} destination - Base destination directory (contains the routes/ sub-directory)
+ * @param {Iterable<string>} openApiPaths - Iterable of OpenAPI path strings (e.g. "/pet/{id}")
+ * @returns {Promise<number>} - Number of files removed
+ */
+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);
+    debug("actual route files: %o", actualFiles);
+    let prunedCount = 0;
+    for (const file of actualFiles) {
+        const normalizedFile = file.replaceAll("\\", "/");
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(routesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(routesDir, routesDir);
+    debug("pruned %d files", prunedCount);
+    return prunedCount;
+}

package/dist/typescript-generator/repository.js

@@ -1,4 +1,3 @@
-/* eslint-disable n/no-sync */
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath, { dirname } from "node:path";
@@ -38,6 +37,7 @@ export class Repository {
         if (!existsSync(sourcePath)) {
             return false;
         }
+        // eslint-disable-next-line n/no-unsupported-features/node-builtins
         return fs.cp(sourcePath, destinationPath, { recursive: true });
     }
     async writeFiles(destination, { routes, types }) {

package/dist/typescript-generator/requirement.js

@@ -25,7 +25,7 @@ export class Requirement {
         }
         return new Requirement(this.data[item], `${this.url}/${this.escapeJsonPointer(item)}`, this.specification);
     }
-    select(path, data = this.data, basePath = "") {
+    select(path) {
         const parts = path
             .split("/")
             .map(this.unescapeJsonPointer)

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

@@ -80,13 +80,16 @@ export class SchemaTypeCoder extends TypeCoder {
     }
     writeCode(script) {
         // script.comments = READ_ONLY_COMMENTS;
-        const { allOf, anyOf, oneOf, type } = this.requirement.data;
+        const { allOf, anyOf, oneOf, type, format } = this.requirement.data;
         if (allOf ?? anyOf ?? oneOf) {
             return this.writeGroup(script, { allOf, anyOf, oneOf });
         }
         if (this.requirement.has("enum")) {
             return this.writeEnum(script, this.requirement.get("enum"));
         }
+        if ((type === "string" && format === "binary") || type === "file") {
+            return "Uint8Array | string";
+        }
         return this.writeType(script, type);
     }
 }

package/dist/typescript-generator/script.js

@@ -1,6 +1,6 @@
 import nodePath from "node:path";
 import createDebugger from "debug";
-import prettier from "prettier";
+import { format } from "prettier";
 const debug = createDebugger("counterfact:typescript-generator:script");
 export class Script {
     constructor(repository, path) {
@@ -137,7 +137,7 @@ export class Script {
         });
     }
     contents() {
-        return prettier.format([
+        return format([
             this.comments.map((comment) => `// ${comment}`).join("\n"),
             this.comments.length > 0 ? "\n\n" : "",
             this.externalImportStatements().join("\n"),

package/dist/typescript-generator/specification.js

@@ -1,4 +1,3 @@
-import nodePath from "node:path";
 import createDebug from "debug";
 import { Requirement } from "./requirement.js";
 import { bundle } from "@apidevtools/json-schema-ref-parser";

package/dist/util/ensure-directory-exists.js

@@ -1,4 +1,3 @@
-/* eslint-disable n/no-sync */
 import fs from "node:fs";
 import nodePath from "node:path";
 export function ensureDirectoryExists(filePath) {

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "counterfact",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Generate a TypeScript-based mock server from an OpenAPI spec in seconds — with stateful routes, hot reload, and REPL support.",
   "type": "module",
   "main": "./dist/app.js",
-  "exports": "./dist/app.js",
+  "exports": {
+    ".": {
+      "import": "./dist/app.js"
+    }
+  },
   "types": "./dist/server/types.d.ts",
   "typesVersions": {
     "*": {
@@ -49,7 +53,7 @@
     "swagger-tools"
   ],
   "engines": {
-    "node": ">=17.0.0"
+    "node": ">=22"
   },
   "bin": {
     "counterfact": "./bin/counterfact.js"
@@ -61,7 +65,7 @@
   "sideEffects": false,
   "scripts": {
     "test": "yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest --testPathIgnorePatterns=black-box",
-    "test:black-box": "rimraf dist && rimraf out && yarn build && yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest black-box --forceExit --coverage=false",
+    "test:black-box": "rimraf dist && yarn build && python3 -m pytest test-black-box/ -v",
     "test:mutants": "stryker run stryker.config.json",
     "test:tsd": "tsd --typings ./dist/server/counterfact-types/index.ts --files ./test/**/*.test-d.ts",
     "build": "rm -rf dist && tsc && copyfiles -f \"src/client/**\" dist/client && copyfiles -f \"src/counterfact-types/*.ts\" dist/server/counterfact-types && copyfiles -f \"src/server/*.cjs\" dist/server",
@@ -78,30 +82,33 @@
   },
   "devDependencies": {
     "@changesets/cli": "2.30.0",
+    "@eslint/js": "10.0.1",
+    "@jest/globals": "^30.3.0",
     "@stryker-mutator/core": "9.6.0",
     "@stryker-mutator/jest-runner": "9.6.0",
     "@stryker-mutator/typescript-checker": "9.6.0",
-    "@swc/core": "1.15.18",
+    "@swc/core": "1.15.21",
     "@swc/jest": "0.2.39",
     "@testing-library/dom": "10.4.1",
     "@types/debug": "^4.1.12",
     "@types/jest": "30.0.0",
     "@types/js-yaml": "4.0.9",
-    "@types/koa": "3.0.1",
+    "@types/koa": "3.0.2",
     "@types/koa-bodyparser": "4.3.13",
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",
     "@types/lodash": "4.17.24",
+    "@types/node": "22",
     "@typescript-eslint/eslint-plugin": "^8.53.0",
     "@typescript-eslint/parser": "^8.53.0",
     "copyfiles": "2.4.1",
-    "eslint": "9.39.4",
+    "eslint": "10.1.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-etc": "2.0.3",
-    "eslint-plugin-file-progress": "3.0.2",
+    "eslint-plugin-file-progress": "4.0.0",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-jest": "29.15.0",
+    "eslint-plugin-jest": "29.15.1",
     "eslint-plugin-jest-dom": "5.5.0",
     "eslint-plugin-n": "^17.24.0",
     "eslint-plugin-no-explicit-type-exports": "0.12.1",
@@ -129,10 +136,10 @@
     "debug": "4.4.3",
     "fetch": "1.1.0",
     "fs-extra": "11.3.4",
-    "handlebars": "4.7.8",
+    "handlebars": "4.7.9",
     "http-terminator": "3.2.0",
     "js-yaml": "4.1.1",
-    "json-schema-faker": "0.5.9",
+    "json-schema-faker": "0.6.0",
     "jsonwebtoken": "9.0.3",
     "koa": "3.1.2",
     "koa-bodyparser": "4.4.1",
@@ -144,10 +151,11 @@
     "patch-package": "8.0.1",
     "precinct": "12.2.0",
     "prettier": "3.8.1",
-    "typescript": "5.9.3"
+    "typescript": "6.0.2"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
   "resolutions": {
-    "js-yaml": "4.1.1"
+    "js-yaml": "4.1.1",
+    "@typescript-eslint/utils": "^8.58.0"
   }
 }