counterfact 2.8.1 → 2.10.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/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";
 }

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/dispatcher.js

@@ -2,7 +2,7 @@ import { mediaTypes } from "@hapi/accept";
 import createDebugger from "debug";
 import fetch, { Headers } from "node-fetch";
 import { createResponseBuilder } from "./response-builder.js";
-import { validateRequest } from "./request-validator.js";
+import { isExplodedObjectQueryParam, validateRequest, } from "./request-validator.js";
 import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
@@ -36,6 +36,45 @@ function parseCookies(cookieHeader) {
     }
     return cookies;
 }
+/**
+ * Gathers exploded object query parameters back into a nested object under the
+ * parameter's own name.
+ *
+ * Per OpenAPI 3.x, a query parameter of type `object` with `style: form` and
+ * `explode: true` (both defaults for query params) is serialised as individual
+ * query parameters — one per object property.  This function reconstructs the
+ * object so that the route handler can access `$.query.<paramName>` rather than
+ * only the individual flat parameters.
+ *
+ * Properties that are "claimed" by an object parameter are removed from the
+ * top-level map and placed under the parameter name. Unclaimed keys remain at
+ * the top level.
+ *
+ * @param query - The raw parsed query-string map from the HTTP request.
+ * @param parameters - The OpenAPI parameter definitions for the current operation.
+ * @returns A new map with exploded object parameters reconstructed as nested objects.
+ */
+export function collectExplodedObjectParams(query, parameters) {
+    const result = { ...query };
+    for (const parameter of parameters) {
+        if (!isExplodedObjectQueryParam(parameter))
+            continue;
+        const properties = parameter.schema?.properties;
+        if (!properties)
+            continue;
+        const obj = {};
+        for (const key of Object.keys(properties)) {
+            if (key in result) {
+                obj[key] = result[key];
+                delete result[key];
+            }
+        }
+        if (Object.keys(obj).length > 0) {
+            result[parameter.name] = obj;
+        }
+    }
+    return result;
+}
 /**
  * Core HTTP request dispatcher.
  *
@@ -208,6 +247,9 @@ export class Dispatcher {
                 };
             }
         }
+        // Reconstruct exploded object query parameters so that `$.query.<name>`
+        // contains the assembled object instead of only the individual flat keys.
+        const processedQuery = collectExplodedObjectParams(query, operation?.parameters ?? []);
         const continuousDistribution = (min, max) => {
             return min + Math.random() * (max - min);
         };
@@ -238,7 +280,8 @@ export class Dispatcher {
                     status: fetchResponse.status,
                 };
             },
-            query,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- object params are reconstructed and typed by generated route types
+            query: processedQuery,
             // @ts-expect-error - Might be pushing the limits of what TypeScript can do here
             response: createResponseBuilder(operation ?? { responses: {} }, this.config), // Pass config
             tools: new Tools({ headers }),

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/request-validator.js

@@ -4,10 +4,51 @@ const ajv = new Ajv({
     strict: false,
     coerceTypes: false,
 });
+/**
+ * Returns `true` when a query parameter should be serialized as exploded form
+ * style — meaning its object properties appear as individual query parameters
+ * instead of being passed under the parameter's own name.
+ *
+ * Per OpenAPI 3.x: for `in: query`, the default `style` is `form` and the
+ * default `explode` for `form` is `true`.  An object-type parameter with these
+ * defaults (or with them set explicitly) uses exploded form serialization.
+ */
+export function isExplodedObjectQueryParam(parameter) {
+    if (parameter.in !== "query")
+        return false;
+    const schema = parameter.schema;
+    if (!schema)
+        return false;
+    // Must be an object type (explicit type or implied by presence of properties)
+    const isObjectType = schema.type === "object" || schema.properties !== undefined;
+    if (!isObjectType)
+        return false;
+    // style must be "form" (the default for query params) or unset
+    if (parameter.style !== undefined && parameter.style !== "form")
+        return false;
+    // explode must not be explicitly false (default for form style is true)
+    if (parameter.explode === false)
+        return false;
+    return true;
+}
 function findMissingRequired(parameters, location, values) {
     return parameters
         .filter((p) => p.in === location && p.required === true)
-        .filter((p) => !(p.name in values) || values[p.name] === undefined)
+        .filter((p) => {
+        // For exploded object query params the individual properties appear as
+        // separate query parameters, so we check for those instead of the name.
+        if (location === "query" && isExplodedObjectQueryParam(p)) {
+            const properties = p.schema?.properties;
+            if (!properties) {
+                // Free-form object with no declared properties: treat as always
+                // satisfied — we cannot know which keys belong to the parameter.
+                return false;
+            }
+            // The parameter is "missing" only when none of its properties are present.
+            return !Object.keys(properties).some((key) => key in values);
+        }
+        return !(p.name in values) || values[p.name] === undefined;
+    })
         .map((p) => `${location} parameter '${p.name}' is required`);
 }
 export function validateRequest(operation, request) {

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,