counterfact 2.8.1 → 2.9.0

package/dist/repl/repl.js

@@ -15,61 +15,125 @@ const ROUTE_BUILDER_METHODS = [
     "ready(",
     "send(",
 ];
+function getScenarioCompletions(line, scenarioRegistry, groupedScenarioRegistries) {
+    function getPathCompletions(partial, registry) {
+        if (registry === undefined) {
+            return [[], partial];
+        }
+        const slashIdx = partial.lastIndexOf("/");
+        if (slashIdx === -1) {
+            const indexFunctions = registry.getExportedFunctionNames("index");
+            const fileKeys = registry.getFileKeys().filter((k) => k !== "index");
+            const topLevelPrefixes = [
+                ...new Set(fileKeys.map((k) => k.split("/")[0] + "/")),
+            ];
+            const allOptions = [...indexFunctions, ...topLevelPrefixes];
+            const matches = allOptions.filter((c) => c.startsWith(partial));
+            return [matches, partial];
+        }
+        const fileKey = partial.slice(0, slashIdx);
+        const funcPartial = partial.slice(slashIdx + 1);
+        const functions = registry.getExportedFunctionNames(fileKey);
+        const matches = functions
+            .filter((e) => e.startsWith(funcPartial))
+            .map((e) => `${fileKey}/${e}`);
+        return [matches, partial];
+    }
+    if (groupedScenarioRegistries !== undefined) {
+        if (!/^\.scenario(?:\s|$)/u.test(line)) {
+            return undefined;
+        }
+        const hasTrailingWhitespace = /\s$/u.test(line);
+        const args = line.trim().split(/\s+/u).slice(1);
+        const groupKeys = Object.keys(groupedScenarioRegistries);
+        if (args.length === 0) {
+            return [groupKeys, ""];
+        }
+        if (args.length === 1 && !hasTrailingWhitespace) {
+            const groupPartial = args[0] ?? "";
+            const matches = groupKeys.filter((key) => key.startsWith(groupPartial));
+            return [matches, groupPartial];
+        }
+        const selectedGroup = args[0] ?? "";
+        const selectedRegistry = groupedScenarioRegistries[selectedGroup];
+        if (selectedRegistry === undefined) {
+            const scenarioPartial = hasTrailingWhitespace
+                ? ""
+                : (args[args.length - 1] ?? "");
+            return [[], scenarioPartial];
+        }
+        if (args.length === 1 && hasTrailingWhitespace) {
+            return getPathCompletions("", selectedRegistry);
+        }
+        if (args.length === 2 && !hasTrailingWhitespace) {
+            const scenarioPartial = args[1];
+            if (scenarioPartial === undefined) {
+                return [[], ""];
+            }
+            return getPathCompletions(scenarioPartial, selectedRegistry);
+        }
+        // More than two args (or trailing whitespace after the second arg) means
+        // no additional `.scenario` arguments are valid in multi-API mode.
+        return [[], args[args.length - 1] ?? ""];
+    }
+    const applyMatch = line.match(/^\.scenario\s+(?<partial>\S*)$/u);
+    if (!applyMatch) {
+        return undefined;
+    }
+    const partial = applyMatch.groups?.["partial"] ?? "";
+    return getPathCompletions(partial, scenarioRegistry);
+}
+function getRouteBuilderMethodCompletions(line) {
+    const builderMatch = line.match(/route\(.*\)\.(?<partial>[a-zA-Z]*)$/u);
+    if (!builderMatch) {
+        return undefined;
+    }
+    const partial = builderMatch.groups?.["partial"] ?? "";
+    const matches = ROUTE_BUILDER_METHODS.filter((m) => m.startsWith(partial));
+    return [matches, partial];
+}
+function getRoutesForCompletion(registry, openApiDocument) {
+    const openApiPaths = openApiDocument
+        ? Object.keys(openApiDocument.paths)
+        : [];
+    if (openApiPaths.length > 0) {
+        return openApiPaths;
+    }
+    return registry.routes.map((route) => route.path);
+}
+function getRouteCompletions(line, routes) {
+    const routeMatch = line.match(/(?:client\.(?:get|post|put|patch|delete)|route)\("(?<partial>[^"]*)$/u);
+    if (!routeMatch) {
+        return undefined;
+    }
+    const partial = routeMatch.groups?.["partial"] ?? "";
+    const matches = routes.filter((route) => route.startsWith(partial));
+    return [matches, partial];
+}
 /**
  * Creates a tab-completion function for the REPL.
  *
  * @param registry - The route registry used to complete path arguments for `route()` and `client.*()` calls.
  * @param fallback - Optional fallback completer (e.g. the Node.js built-in completer) invoked when no custom completion matches.
+ * @param openApiDocument - Optional OpenAPI document used as the source of route completions when available.
  * @param scenarioRegistry - When provided, enables tab completion for `.scenario` commands by enumerating
  *   exported function names and file-key prefixes from the loaded scenario modules.
  */
-export function createCompleter(registry, fallback, scenarioRegistry) {
+export function createCompleter(registry, fallback, openApiDocument, scenarioRegistry, groupedScenarioRegistries) {
+    const routes = getRoutesForCompletion(registry, openApiDocument);
     return (line, callback) => {
-        // Check for .scenario completion: .scenario <partial>
-        const applyMatch = line.match(/^\.scenario\s+(?<partial>\S*)$/u);
-        if (applyMatch) {
-            const partial = applyMatch.groups?.["partial"] ?? "";
-            if (scenarioRegistry !== undefined) {
-                const slashIdx = partial.lastIndexOf("/");
-                if (slashIdx === -1) {
-                    // No slash: complete exports from "index" key + top-level file prefixes
-                    const indexFunctions = scenarioRegistry.getExportedFunctionNames("index");
-                    const fileKeys = scenarioRegistry
-                        .getFileKeys()
-                        .filter((k) => k !== "index");
-                    const topLevelPrefixes = [
-                        ...new Set(fileKeys.map((k) => k.split("/")[0] + "/")),
-                    ];
-                    const allOptions = [...indexFunctions, ...topLevelPrefixes];
-                    const matches = allOptions.filter((c) => c.startsWith(partial));
-                    callback(null, [matches, partial]);
-                }
-                else {
-                    // Has slash: complete exports from the named file key
-                    const fileKey = partial.slice(0, slashIdx);
-                    const funcPartial = partial.slice(slashIdx + 1);
-                    const functions = scenarioRegistry.getExportedFunctionNames(fileKey);
-                    const matches = functions
-                        .filter((e) => e.startsWith(funcPartial))
-                        .map((e) => `${fileKey}/${e}`);
-                    callback(null, [matches, partial]);
-                }
-            }
-            else {
-                callback(null, [[], partial]);
-            }
+        const scenarioCompletions = getScenarioCompletions(line, scenarioRegistry, groupedScenarioRegistries);
+        if (scenarioCompletions !== undefined) {
+            callback(null, scenarioCompletions);
             return;
         }
-        // Check for RouteBuilder method completion: route("..."). or chained calls
-        const builderMatch = line.match(/route\(.*\)\.(?<partial>[a-zA-Z]*)$/u);
-        if (builderMatch) {
-            const partial = builderMatch.groups?.["partial"] ?? "";
-            const matches = ROUTE_BUILDER_METHODS.filter((m) => m.startsWith(partial));
-            callback(null, [matches, partial]);
+        const routeBuilderCompletions = getRouteBuilderMethodCompletions(line);
+        if (routeBuilderCompletions !== undefined) {
+            callback(null, routeBuilderCompletions);
             return;
         }
-        const match = line.match(/(?:client\.(?:get|post|put|patch|delete)|route)\("(?<partial>[^"]*)$/u);
-        if (!match) {
+        const routeCompletions = getRouteCompletions(line, routes);
+        if (routeCompletions === undefined) {
             if (fallback) {
                 fallback(line, callback);
             }
@@ -78,10 +142,7 @@ export function createCompleter(registry, fallback, scenarioRegistry) {
             }
             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]);
+        callback(null, routeCompletions);
     };
 }
 /**
@@ -103,7 +164,52 @@ export function createCompleter(registry, fallback, scenarioRegistry) {
  * @param scenarioRegistry - Optional scenario registry for `.scenario` support.
  * @returns The configured Node.js REPL server instance.
  */
-export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry) {
+export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry, apiBindings) {
+    const bindings = apiBindings === undefined || apiBindings.length === 0
+        ? [
+            {
+                contextRegistry,
+                group: "",
+                openApiDocument,
+                registry,
+                scenarioRegistry,
+            },
+        ]
+        : apiBindings;
+    const isMultiApi = bindings.length > 1;
+    const groupedBindings = bindings.map((binding) => ({
+        ...binding,
+        key: binding.group.trim(),
+    }));
+    if (isMultiApi) {
+        const invalidBindings = groupedBindings.filter((binding) => binding.key === "");
+        if (invalidBindings.length > 0) {
+            throw new Error("Each API binding must define a non-empty group when multiple APIs are configured.");
+        }
+        const seenGroups = new Set();
+        const duplicateGroups = new Set();
+        for (const binding of groupedBindings) {
+            if (seenGroups.has(binding.key)) {
+                duplicateGroups.add(binding.key);
+            }
+            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) {
+        throw new Error("startRepl requires at least one API binding");
+    }
+    const groupedLoadContext = Object.fromEntries(groupedBindings.map((binding) => [
+        binding.key,
+        (path) => binding.contextRegistry.find(path),
+    ]));
+    const groupedRoute = Object.fromEntries(groupedBindings.map((binding) => [
+        binding.key,
+        createRouteFunction(config.port, "localhost", binding.openApiDocument),
+    ]));
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -147,7 +253,12 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     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, scenarioRegistry);
+    replServer.completer = createCompleter(rootBinding.registry, builtinCompleter, rootBinding.openApiDocument, rootBinding.scenarioRegistry, isMultiApi
+        ? Object.fromEntries(groupedBindings.map((binding) => [
+            binding.key,
+            binding.scenarioRegistry,
+        ]))
+        : undefined);
     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.");
@@ -186,17 +297,63 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         },
         help: 'proxy configuration (".proxy help" for details)',
     });
-    replServer.context.loadContext = (path) => contextRegistry.find(path);
-    replServer.context.context = replServer.context.loadContext("/");
+    replServer.context.loadContext = isMultiApi
+        ? groupedLoadContext
+        : groupedLoadContext[rootBinding.key];
+    replServer.context.context = isMultiApi
+        ? Object.fromEntries(groupedBindings.map((binding) => [
+            binding.key,
+            binding.contextRegistry.find("/"),
+        ]))
+        : rootBinding.contextRegistry.find("/");
     replServer.context.client = new RawHttpClient("localhost", config.port);
     replServer.context.RawHttpClient = RawHttpClient;
-    replServer.context.route = createRouteFunction(config.port, "localhost", openApiDocument);
-    replServer.context.routes = {};
+    replServer.context.route = isMultiApi
+        ? groupedRoute
+        : groupedRoute[rootBinding.key];
+    replServer.context.routes = isMultiApi
+        ? Object.fromEntries(groupedBindings.map((binding) => [binding.key, {}]))
+        : {};
     replServer.defineCommand("scenario", {
         async action(text) {
-            const parts = text.trim().split("/").filter(Boolean);
+            const trimmedText = text.trim();
+            const parsedArgs = trimmedText.split(/\s+/u).filter(Boolean);
+            const usage = isMultiApi
+                ? "usage: .scenario <group> <path>"
+                : "usage: .scenario <path>";
+            const { selectedBinding, scenarioPath } = (() => {
+                if (!isMultiApi) {
+                    if (trimmedText === "") {
+                        return { scenarioPath: undefined, selectedBinding: undefined };
+                    }
+                    return { scenarioPath: trimmedText, selectedBinding: rootBinding };
+                }
+                if (parsedArgs.length !== 2) {
+                    return { scenarioPath: undefined, selectedBinding: undefined };
+                }
+                return {
+                    scenarioPath: parsedArgs[1],
+                    selectedBinding: groupedBindings.find((binding) => binding.key === parsedArgs[0]),
+                };
+            })();
+            if (selectedBinding === undefined || scenarioPath === undefined) {
+                if (isMultiApi &&
+                    scenarioPath !== undefined &&
+                    selectedBinding === undefined) {
+                    const groupName = parsedArgs[0] ?? "";
+                    const availableGroups = groupedBindings.map((binding) => binding.key);
+                    print(`Error: Unknown API group "${groupName}". Available groups: ${availableGroups.join(", ")}`);
+                }
+                else {
+                    print(usage);
+                }
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            const parts = scenarioPath.split("/").filter(Boolean);
             if (parts.length === 0) {
-                print("usage: .scenario <path>");
+                print(usage);
                 this.clearBufferedCommand();
                 this.displayPrompt();
                 return;
@@ -209,7 +366,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             }
             const functionName = parts[parts.length - 1] ?? "";
             const fileKey = parts.length === 1 ? "index" : parts.slice(0, -1).join("/");
-            const module = scenarioRegistry?.getModule(fileKey);
+            const module = selectedBinding.scenarioRegistry?.getModule(fileKey);
             if (module === undefined) {
                 print(`Error: Could not find scenario file "${fileKey}"`);
                 this.clearBufferedCommand();
@@ -224,11 +381,20 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
                 return;
             }
             try {
+                const selectedRoutes = isMultiApi
+                    ? replServer.context["routes"][selectedBinding.key]
+                    : replServer.context["routes"];
+                if (isMultiApi && selectedRoutes === undefined) {
+                    print(`Error: Could not resolve routes for API group "${selectedBinding.key}"`);
+                    this.clearBufferedCommand();
+                    this.displayPrompt();
+                    return;
+                }
                 const applyContext = {
-                    context: replServer.context["context"],
-                    loadContext: replServer.context["loadContext"],
-                    route: replServer.context["route"],
-                    routes: replServer.context["routes"],
+                    context: selectedBinding.contextRegistry.find("/"),
+                    loadContext: ((path) => selectedBinding.contextRegistry.find(path)),
+                    route: groupedRoute[selectedBinding.key],
+                    routes: selectedRoutes,
                 };
                 await fn(applyContext);
                 print(`Applied ${text.trim()}`);
@@ -239,7 +405,9 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             this.clearBufferedCommand();
             this.displayPrompt();
         },
-        help: 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
+        help: isMultiApi
+            ? 'apply a scenario script (".scenario <group> <path>" calls the named export from that group\'s scenarios/)'
+            : 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
     });
     return replServer;
 }

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

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- module kind detection only probes package.json while walking parent directories. */
 const DEFAULT_MODULE_KIND = "commonjs";
 /**
  * Determines whether a module file should be treated as CommonJS or ESM.

package/dist/server/file-discovery.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
+/* eslint-disable security/detect-non-literal-fs-filename -- discovery walks directories rooted at basePath and uses Dirent-provided names. */
 import { toForwardSlashPath, pathJoin } from "../util/forward-slash-path.js";
 import { escapePathForWindows } from "../util/windows-escape.js";
 const JS_EXTENSIONS = new Set(["cjs", "cts", "js", "mjs", "mts", "ts"]);

package/dist/server/module-loader.js

@@ -1,6 +1,7 @@
 import { once } from "node:events";
 import fs from "node:fs/promises";
 import nodePath, { basename } from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- readJson resolves paths against the current context directory before file access. */
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
@@ -185,6 +186,13 @@ export class ModuleLoader extends EventTarget {
                 const isSyntaxError = importError instanceof SyntaxError ||
                     String(importError).startsWith("SyntaxError:");
                 const displayPath = pathRelative(process.cwd(), unescapePathForWindows(pathName));
+                if (this.isContextFile(pathName)) {
+                    const warning = isSyntaxError
+                        ? `Warning: There is a syntax error in the context file: ${displayPath}`
+                        : `Warning: There was an error loading the context file: ${displayPath}`;
+                    process.stdout.write(`\n${warning}\n`);
+                    return;
+                }
                 const message = isSyntaxError
                     ? `There is a syntax error in the route file: ${displayPath}`
                     : `There was an error loading the route file: ${displayPath}`;

package/dist/server/transpiler.js

@@ -1,6 +1,7 @@
 // Stryker disable all
 import { once } from "node:events";
 import fs from "node:fs/promises";
+/* eslint-disable security/detect-non-literal-fs-filename -- transpiler consumes watched source files and writes paired outputs under configured directories. */
 import { watch as chokidarWatch } from "chokidar";
 import createDebug from "debug";
 import ts from "typescript";

package/dist/server/{admin-api-middleware.js → web-server/admin-api-middleware.js}

@@ -24,16 +24,25 @@ function isLoopbackIp(ip) {
 /**
  * Admin API middleware for programmatic access to Counterfact internals.
  * Exposes context management, proxy configuration, and route discovery
- * through HTTP endpoints at /_counterfact/api/*
+ * through HTTP endpoints at the given path prefix.
  *
  * This enables AI agents and external tools to interact with the mock server
  * in the same way the REPL does, but via HTTP requests.
+ *
+ * @param pathPrefix - The URL path prefix at which the admin API is mounted,
+ *   e.g. `"/_counterfact/api"`. Requests to paths that do not start with this
+ *   prefix fall through to the next middleware.
+ * @param registry - The route registry used to list available routes.
+ * @param contextRegistry - The context registry used to read and update
+ *   per-path context objects.
+ * @param config - Server configuration (proxy settings, port, etc.).
+ * @returns A Koa middleware function.
  */
-export function adminApiMiddleware(registry, contextRegistry, config) {
+export function adminApiMiddleware(pathPrefix, registry, contextRegistry, config) {
     return async (ctx, next) => {
         const { pathname } = ctx.URL;
-        // Only handle admin API routes
-        if (!pathname.startsWith("/_counterfact/api/")) {
+        // Only handle admin API routes (exact prefix or paths beneath it)
+        if (pathname !== pathPrefix && !pathname.startsWith(`${pathPrefix}/`)) {
             return await next();
         }
         // ===== Admin API Access Guard =====
@@ -72,9 +81,10 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
             }
         }
         debug("Admin API request: %s %s", ctx.method, pathname);
-        // Extract route components: ["_counterfact", "api", "resource", ...rest]
-        const parts = pathname.split("/").filter(Boolean);
-        const [, , resource, ...rest] = parts;
+        // Extract the resource path after the prefix
+        const subPath = pathname.slice(pathPrefix.length);
+        const parts = subPath.split("/").filter(Boolean);
+        const [resource, ...rest] = parts;
         try {
             // ===== Health Check =====
             if (resource === "health" && ctx.method === "GET") {
@@ -83,7 +93,7 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
                     port: config.port,
                     uptime: process.uptime(),
                     basePath: config.basePath,
-                    routePrefix: config.routePrefix,
+                    prefix: config.prefix,
                 };
                 return;
             }
@@ -155,7 +165,7 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
                         openApiPath: config.openApiPath,
                         port: config.port,
                         proxyUrl: config.proxyUrl,
-                        routePrefix: config.routePrefix,
+                        prefix: config.prefix,
                         startAdminApi: config.startAdminApi,
                         startRepl: config.startRepl,
                         startServer: config.startServer,

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

@@ -0,0 +1,68 @@
+import createDebug from "debug";
+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 { openapiMiddleware } from "./openapi-middleware.js";
+const debug = createDebug("counterfact:server:create-koa-app");
+/**
+ * Builds and configures the Koa application with all built-in middleware.
+ *
+ * The middleware stack (in order) is:
+ * 1. Per runner: OpenAPI document serving at `/counterfact/openapi${runner.subdirectory}`
+ * 2. Per runner: Swagger UI at `/counterfact/swagger${runner.subdirectory}`
+ * 3. Per runner: Admin API (when `config.startAdminApi` is `true`) at `/_counterfact/api${runner.subdirectory}`
+ * 4. Redirect `/counterfact` → `/counterfact/swagger`
+ * 5. Body parser
+ * 6. JSON serialisation of object bodies
+ * 7. Per runner: Route-dispatching middleware at `runner.prefix`
+ *
+ * @param runners - The ApiRunner instances, one per API spec.
+ * @param config - Server configuration.
+ * @returns A configured Koa application (not yet listening).
+ */
+export function createKoaApp({ runners, config, }) {
+    const app = new Koa();
+    for (const runner of runners) {
+        app.use(openapiMiddleware(`/counterfact/openapi${runner.subdirectory}`, {
+            path: runner.openApiPath,
+            baseUrl: `//localhost:${config.port}${runner.prefix}`,
+        }));
+        app.use(koaSwagger({
+            routePrefix: `/counterfact/swagger${runner.subdirectory}`,
+            swaggerOptions: {
+                url: `/counterfact/openapi${runner.subdirectory}`,
+            },
+        }));
+        if (config.startAdminApi) {
+            app.use(adminApiMiddleware(`/_counterfact/api${runner.subdirectory}`, runner.registry, runner.contextRegistry, config));
+        }
+    }
+    debug("basePath: %s", config.basePath);
+    app.use(async (ctx, next) => {
+        if (ctx.URL.pathname === "/counterfact") {
+            ctx.redirect("/counterfact/swagger");
+            return;
+        }
+        await next();
+    });
+    app.use(bodyParser());
+    app.use(async (ctx, next) => {
+        await next();
+        if (ctx.body !== null &&
+            ctx.body !== undefined &&
+            typeof ctx.body === "object" &&
+            !Buffer.isBuffer(ctx.body)) {
+            ctx.body = JSON.stringify(ctx.body, null, 2);
+            ctx.type = "application/json";
+        }
+    });
+    for (const runner of runners) {
+        app.use(routesMiddleware(runner.prefix, runner.dispatcher, {
+            proxyPaths: config.proxyPaths,
+            proxyUrl: config.proxyUrl,
+        }));
+    }
+    return app;
+}

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

@@ -0,0 +1,34 @@
+import { bundle } from "@apidevtools/json-schema-ref-parser";
+import { dump } from "js-yaml";
+/**
+ * Returns a Koa middleware that serves a bundled OpenAPI document as YAML at
+ * the given `pathPrefix`.
+ *
+ * The served document is augmented with a `servers` entry (OpenAPI 3.x) and a
+ * `host` field (OpenAPI 2.x / Swagger) so that the Swagger UI can send
+ * requests to the running Counterfact instance.
+ *
+ * @param pathPrefix - The URL path at which to serve the document, e.g.
+ *   `"/counterfact/openapi"`. Requests to any other path fall through to the
+ *   next middleware.
+ * @param document - Descriptor providing `path` (file path or URL to the
+ *   source OpenAPI document) and `baseUrl` (the base URL to inject, e.g.
+ *   `"//localhost:3100/api"`).
+ * @returns A Koa middleware function.
+ */
+export function openapiMiddleware(pathPrefix, document) {
+    return async (ctx, next) => {
+        if (ctx.URL.pathname !== pathPrefix) {
+            return await next();
+        }
+        const openApiDocument = (await bundle(document.path));
+        openApiDocument.servers ??= [];
+        openApiDocument.servers.unshift({
+            description: "Counterfact",
+            url: document.baseUrl,
+        });
+        // OpenApi 2 support:
+        openApiDocument.host = document.baseUrl;
+        ctx.body = dump(openApiDocument);
+    };
+}

package/dist/server/{koa-middleware.js → web-server/routes-middleware.js}

@@ -1,6 +1,6 @@
 import createDebug from "debug";
 import koaProxy from "koa-proxies";
-import { isProxyEnabledForPath } from "./is-proxy-enabled-for-path.js";
+import { isProxyEnabledForPath } from "../is-proxy-enabled-for-path.js";
 const debug = createDebug("counterfact:server:create-koa-app");
 const HTTP_STATUS_CODE_OK = 200;
 const HEADERS_TO_DROP = new Set([
@@ -45,29 +45,32 @@ function getAuthObject(ctx) {
  * the Counterfact {@link Dispatcher}.
  *
  * Responsibilities:
- * - Respects `routePrefix` — requests outside the prefix are passed to `next`.
+ * - Respects `prefix` — requests outside the prefix are passed to `next`.
  * - Adds CORS headers to every response.
  * - Handles `OPTIONS` pre-flight requests (200 with CORS headers, no body).
  * - Proxies the request upstream when proxy is enabled for the path.
  * - Forwards the request to the dispatcher and maps the response back onto
  *   the Koa context.
  *
+ * @param prefix - The URL path prefix that this middleware handles, e.g.
+ *   `"/api/v1"`. Requests to paths that do not start with this prefix fall
+ *   through to the next middleware.
  * @param dispatcher - The {@link Dispatcher} instance that handles requests.
- * @param config - Server configuration (proxy settings, route prefix, etc.).
+ * @param config - Server configuration (proxy settings, etc.).
  * @param proxy - Proxy factory; injectable for testing.
  * @returns A Koa middleware function.
  */
-export function routesMiddleware(dispatcher, config, proxy = koaProxy) {
+export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
     return async function middleware(ctx, next) {
-        const { proxyUrl, routePrefix } = config;
+        const { proxyUrl } = config;
         debug("middleware running for path: %s", ctx.request.path);
-        debug("routePrefix: %s", routePrefix);
-        if (!ctx.request.path.startsWith(routePrefix)) {
+        debug("prefix: %s", prefix);
+        if (!ctx.request.path.startsWith(prefix)) {
             return await next();
         }
         const auth = getAuthObject(ctx);
         const { body, headers, query, rawBody } = ctx.request;
-        const path = ctx.request.path.slice(routePrefix.length);
+        const path = ctx.request.path.slice(prefix.length);
         const method = ctx.request.method;
         if (isProxyEnabledForPath(path, config) && proxyUrl) {
             return proxy("/", { changeOrigin: true, target: proxyUrl })(ctx, next);

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

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- generated files are written under the caller-provided destination tree. */
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "../server/constants.js";

package/dist/typescript-generator/prune.js

@@ -1,5 +1,6 @@
 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. */
 import createDebug from "debug";
 import { toForwardSlashPath } from "../util/forward-slash-path.js";
 const debug = createDebug("counterfact:typescript-generator:prune");

package/dist/typescript-generator/repository.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath, { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+/* eslint-disable security/detect-non-literal-fs-filename -- repository writes and stats generated files only inside destination output directories. */
 import createDebug from "debug";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { toForwardSlashPath, pathJoin, pathRelative, pathDirname, } from "../util/forward-slash-path.js";

package/dist/typescript-generator/scenario-file-generator.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- scenario files are discovered and generated under the configured destination tree. */
 import { watch } from "chokidar";
 import { CHOKIDAR_OPTIONS } from "../server/constants.js";
 import { pathRelative } from "../util/forward-slash-path.js";