counterfact 2.8.1 → 2.10.0

package/dist/api-runner.js

@@ -0,0 +1,202 @@
+import { rm } from "node:fs/promises";
+import { ContextRegistry } from "./server/context-registry.js";
+import { Dispatcher } from "./server/dispatcher.js";
+import { loadOpenApiDocument } from "./server/load-openapi-document.js";
+import { ModuleLoader } from "./server/module-loader.js";
+import { Registry } from "./server/registry.js";
+import { ScenarioRegistry } from "./server/scenario-registry.js";
+import { Transpiler } from "./server/transpiler.js";
+import { CodeGenerator } from "./typescript-generator/code-generator.js";
+import { ScenarioFileGenerator } from "./typescript-generator/scenario-file-generator.js";
+import { pathJoin } from "./util/forward-slash-path.js";
+import { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
+/**
+ * Encapsulates the creation and lifecycle management of all Counterfact
+ * sub-systems for a single API specification.
+ *
+ * Use the static {@link ApiRunner.create} factory method to construct an
+ * instance — the constructor requires async initialisation (loading the
+ * OpenAPI document and probing for native TypeScript support) that cannot
+ * be done in a synchronous constructor.
+ *
+ * Each sub-system is exposed as a public property so callers can interact
+ * with individual components directly when needed. The composite methods
+ * {@link generate}, {@link load}, {@link watch}, and {@link stopWatching}
+ * coordinate across multiple sub-systems and encapsulate the conditional
+ * logic driven by the configuration.
+ */
+export class ApiRunner {
+    /** Stores loaded route handlers, keyed by path. */
+    registry;
+    /** Stores context objects per route path and dispatches change events. */
+    contextRegistry;
+    /** Registry of loaded scenario modules (used by the REPL). */
+    scenarioRegistry;
+    /** Generates `types/_.context.ts` and the default `scenarios/index.ts`. */
+    scenarioFileGenerator;
+    /** Reads the OpenAPI spec and writes TypeScript route/type stub files. */
+    codeGenerator;
+    /** Routes incoming HTTP requests to the matching handler in `registry`. */
+    dispatcher;
+    /**
+     * Compiles TypeScript route files to JavaScript when the runtime cannot
+     * execute TypeScript natively.
+     */
+    transpiler;
+    /**
+     * Imports compiled route/context/scenario modules and hot-reloads them on
+     * file-system changes.
+     */
+    moduleLoader;
+    /**
+     * The loaded OpenAPI document, or `undefined` when `config.openApiPath`
+     * is `"_"` (spec-less mode).
+     */
+    openApiDocument;
+    /** `true` when the current Node.js runtime can execute TypeScript natively. */
+    nativeTs;
+    /** Path or URL to the OpenAPI document for this runner. */
+    openApiPath;
+    /** URL prefix that this runner intercepts (default `""`). */
+    prefix;
+    /**
+     * Optional group name that places generated code in a subdirectory.
+     * Defaults to `""` (no subdirectory).
+     */
+    group;
+    /**
+     * The subdirectory path segment derived from {@link group}.
+     * Returns `""` when `group` is empty, otherwise `"/${group}"`.
+     */
+    get subdirectory() {
+        return this.group ? `/${this.group}` : "";
+    }
+    config;
+    constructor(config, nativeTs, openApiDocument, group) {
+        this.group = group;
+        const modulesPath = this.group
+            ? pathJoin(config.basePath, this.group)
+            : config.basePath;
+        const compiledPathsDirectory = pathJoin(modulesPath, nativeTs ? "routes" : ".cache");
+        this.config = config;
+        this.nativeTs = nativeTs;
+        this.openApiDocument = openApiDocument;
+        this.openApiPath = config.openApiPath;
+        this.prefix = config.prefix;
+        this.registry = new Registry();
+        this.contextRegistry = new ContextRegistry();
+        this.scenarioRegistry = new ScenarioRegistry();
+        this.scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
+        this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate);
+        this.dispatcher = new Dispatcher(this.registry, this.contextRegistry, openApiDocument, config);
+        this.transpiler = new Transpiler(pathJoin(modulesPath, "routes"), compiledPathsDirectory, "commonjs");
+        this.moduleLoader = new ModuleLoader(compiledPathsDirectory, this.registry, this.contextRegistry, pathJoin(modulesPath, "scenarios"), this.scenarioRegistry);
+    }
+    /**
+     * Creates and returns a fully initialised `ApiRunner`.
+     *
+     * Probes for native TypeScript support, optionally cleans the compiled
+     * output directory, and loads the OpenAPI document before constructing
+     * the runner.
+     *
+     * @param config - Runtime configuration for this runner instance.
+     * @param group - Optional group name placing generated code in a subdirectory (default `""`).
+     */
+    static async create(config, group = "") {
+        const nativeTs = await runtimeCanExecuteErasableTs();
+        const modulesPath = group
+            ? pathJoin(config.basePath, group)
+            : config.basePath;
+        const compiledPathsDirectory = pathJoin(modulesPath, nativeTs ? "routes" : ".cache");
+        if (!nativeTs) {
+            await rm(compiledPathsDirectory, { force: true, recursive: true });
+        }
+        const openApiDocument = config.openApiPath === "_"
+            ? undefined
+            : await loadOpenApiDocument(config.openApiPath);
+        return new ApiRunner(config, nativeTs, openApiDocument, group);
+    }
+    /**
+     * Generates TypeScript route stubs and type files from the OpenAPI spec.
+     *
+     * Respects the `config.generate.routes` and `config.generate.types` flags:
+     * - Routes and types are only generated when `config.openApiPath` is not `"_"`.
+     * - The scenario context type file is always generated when
+     *   `config.generate.types` is `true`, even without a spec.
+     */
+    async generate() {
+        if (this.config.openApiPath !== "_" &&
+            (this.config.generate.routes || this.config.generate.types)) {
+            await this.codeGenerator.generate();
+        }
+        if (this.config.generate.types) {
+            await this.scenarioFileGenerator.generate();
+        }
+    }
+    /**
+     * Loads all compiled route, context, and scenario modules into the
+     * appropriate registries.
+     */
+    async load() {
+        await this.moduleLoader.load();
+    }
+    /**
+     * Starts watching the OpenAPI spec and scenario context files for changes
+     * and re-generates the corresponding TypeScript files on each change.
+     *
+     * - Re-generates route stubs when the spec changes (when
+     *   `config.watch.routes` or `config.watch.types` is `true`).
+     * - Re-generates `types/_.context.ts` when a `_.context.ts` file changes
+     *   (when `config.watch.types` is `true`).
+     */
+    async watch() {
+        if (this.config.openApiPath !== "_" &&
+            (this.config.watch.routes || this.config.watch.types)) {
+            await this.codeGenerator.watch();
+        }
+        if (this.config.watch.types) {
+            await this.scenarioFileGenerator.watch();
+        }
+    }
+    /**
+     * Starts the server-related sub-systems based on the supplied options.
+     *
+     * When `startServer` is `true`:
+     * - Watches the OpenAPI document for live reloads.
+     * - Transpiles TypeScript route files (when the runtime does not support
+     *   native TypeScript execution).
+     * - Loads all compiled modules into their registries.
+     * - Watches compiled modules for hot-reload.
+     *
+     * When `buildCache` is `true` (and `startServer` is `false`):
+     * - Runs the transpiler once to build the compiled-output cache, then stops.
+     *
+     * @param options - Subset of the runtime config that governs startup behaviour.
+     */
+    async start(options) {
+        const { startServer, buildCache } = options;
+        if (startServer) {
+            await this.openApiDocument?.watch();
+            if (!this.nativeTs) {
+                await this.transpiler.watch();
+            }
+            await this.moduleLoader.load();
+            await this.moduleLoader.watch();
+        }
+        else if (buildCache) {
+            // Transpile once to populate the cache, then immediately stop watching.
+            await this.transpiler.watch();
+            await this.transpiler.stopWatching();
+        }
+    }
+    /**
+     * Stops all active file-system watchers across every sub-system.
+     */
+    async stopWatching() {
+        await this.codeGenerator.stopWatching();
+        await this.scenarioFileGenerator.stopWatching();
+        await this.transpiler.stopWatching();
+        await this.moduleLoader.stopWatching();
+        await this.openApiDocument?.stopWatching();
+    }
+}

package/dist/app.js

@@ -1,20 +1,10 @@
-import fs, { rm } from "node:fs/promises";
 import { createHttpTerminator } from "http-terminator";
+import { ApiRunner } from "./api-runner.js";
 import { startRepl as startReplServer } from "./repl/repl.js";
 import { createRouteFunction } from "./repl/route-builder.js";
-import { ContextRegistry } from "./server/context-registry.js";
-import { createKoaApp } from "./server/create-koa-app.js";
-import { Dispatcher } from "./server/dispatcher.js";
-import { loadOpenApiDocument } from "./server/load-openapi-document.js";
-import { ModuleLoader } from "./server/module-loader.js";
-import { Registry } from "./server/registry.js";
-import { ScenarioRegistry } from "./server/scenario-registry.js";
-import { Transpiler } from "./server/transpiler.js";
-import { CodeGenerator } from "./typescript-generator/code-generator.js";
-import { ScenarioFileGenerator } from "./typescript-generator/scenario-file-generator.js";
-import { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
-import { pathJoin } from "./util/forward-slash-path.js";
+import { createKoaApp } from "./server/web-server/create-koa-app.js";
 export { loadOpenApiDocument } from "./server/load-openapi-document.js";
+export { createMswHandlers, handleMswRequest, } from "./msw.js";
 export async function runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument) {
     const indexModule = scenarioRegistry.getModule("index");
     if (!indexModule || typeof indexModule["startup"] !== "function") {
@@ -28,86 +18,59 @@ export async function runStartupScenario(scenarioRegistry, contextRegistry, conf
     };
     await indexModule["startup"](scenario$);
 }
-const allowedMethods = [
-    "all",
-    "head",
-    "get",
-    "post",
-    "put",
-    "delete",
-    "patch",
-    "options",
-];
-const mswHandlers = {};
 /**
- * Dispatches a single MSW (Mock Service Worker) intercepted request to the
- * matching Counterfact route handler registered via {@link createMswHandlers}.
+ * Normalises the spec configuration to an array.
  *
- * @param request - The intercepted request, including the HTTP method, path,
- *   headers, query, body, and a `rawPath` that preserves the original URL
- *   before base-path stripping.
- * @returns The response produced by the matching handler, or a 404 object when
- *   no handler has been registered for the given method and path.
+ * When `specs` is provided it is returned as-is. When it is omitted, a
+ * single-entry array is constructed from `config.openApiPath`,
+ * `config.prefix`, and `group = ""` so that the rest of the code never
+ * needs to branch on single-vs-multiple specs.
  */
-export async function handleMswRequest(request) {
-    const { method, rawPath } = request;
-    const handler = mswHandlers[`${method}:${rawPath}`];
-    if (handler) {
-        return handler(request);
+function normalizeSpecs(config, specs) {
+    if (specs !== undefined) {
+        return specs;
     }
-    console.warn(`No handler found for ${method} ${rawPath}`);
-    return { error: `No handler found for ${method} ${rawPath}`, status: 404 };
+    return [{ source: config.openApiPath, prefix: config.prefix, group: "" }];
 }
-/**
- * Loads an OpenAPI document, registers all routes from it as MSW handlers, and
- * returns the list of registered routes so callers (e.g. Vitest Browser mode)
- * can mount them on their own request-interception layer.
- *
- * @param config - Counterfact configuration; `openApiPath` and `basePath` are
- *   the most important fields for this function.
- * @param ModuleLoaderClass - Injectable module-loader constructor, primarily
- *   used in tests to substitute a test-friendly implementation.
- * @returns An array of `{ method, path }` objects describing every registered
- *   MSW handler.
- */
-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.
-    await fs.readFile(config.openApiPath);
-    const openApiDocument = await loadOpenApiDocument(config.openApiPath);
-    const modulesPath = config.basePath;
-    const compiledPathsDirectory = pathJoin(modulesPath, ".cache");
-    const registry = new Registry();
-    const contextRegistry = new ContextRegistry();
-    const dispatcher = new Dispatcher(registry, contextRegistry, openApiDocument, config);
-    const moduleLoader = new ModuleLoaderClass(compiledPathsDirectory, registry, contextRegistry);
-    await moduleLoader.load();
-    const routes = registry.routes;
-    const handlers = routes.flatMap((route) => {
-        const { methods, path } = route;
-        return Object.keys(methods)
-            .filter((method) => allowedMethods.includes(method.toLowerCase()))
-            .map((method) => {
-            const lowerMethod = method.toLowerCase();
-            const apiPath = `${openApiDocument.basePath ?? ""}${path.replaceAll("{", ":").replaceAll("}", "")}`;
-            const handler = async (request) => {
-                return await dispatcher.request(request);
-            };
-            mswHandlers[`${method}:${apiPath}`] = handler;
-            return { method: lowerMethod, path: apiPath };
-        });
-    });
-    return handlers;
+function validateSpecGroups(specs) {
+    if (specs.length <= 1) {
+        return;
+    }
+    const invalidSpecNumbers = specs
+        .map((spec, index) => ({ group: spec.group.trim(), index }))
+        .filter(({ group }) => group === "")
+        .map(({ index }) => String(index + 1));
+    if (invalidSpecNumbers.length === 0) {
+        const seenGroups = new Set();
+        const duplicateGroupNames = new Set();
+        for (const spec of specs) {
+            const group = spec.group.trim();
+            if (seenGroups.has(group)) {
+                duplicateGroupNames.add(group);
+                continue;
+            }
+            seenGroups.add(group);
+        }
+        if (duplicateGroupNames.size === 0) {
+            return;
+        }
+        throw new Error(`Each spec must define a unique group when multiple APIs are configured (duplicate groups: ${[...duplicateGroupNames].join(", ")}).`);
+    }
+    throw new Error(`Each spec must define a non-empty group when multiple APIs are configured (invalid spec entries: ${invalidSpecNumbers.join(", ")}).`);
 }
 /**
  * Creates and configures a full Counterfact server instance.
  *
- * Sets up the route registry, context registry, scenario registry, code
- * generator, transpiler, module loader, Koa application, and OpenAPI watcher.
- * The returned object exposes handles for starting the server, stopping it, and
- * launching the interactive REPL.
+ * Supports one or more API specifications. Each spec produces its own
+ * {@link ApiRunner}. When `specs` is omitted a single runner is created from
+ * `config.openApiPath` and `config.prefix`.
+ *
+ * The returned object exposes handles for starting the server, stopping it,
+ * and launching the interactive REPL.
  *
  * @param config - Runtime configuration (port, paths, feature flags, etc.).
+ * @param specs - Optional array of spec entries. Omit to use a single spec
+ *   derived from `config.openApiPath` and `config.prefix`.
  * @returns An object containing the configured sub-systems and two entry-point
  *   functions:
  *   - `start(options)` — generates/watches code and optionally starts the HTTP
@@ -115,53 +78,23 @@ export async function createMswHandlers(config, ModuleLoaderClass = ModuleLoader
  *   - `startRepl()` — launches the interactive Node.js REPL connected to the
  *     live server state.
  */
-export async function counterfact(config) {
-    const modulesPath = config.basePath;
-    const nativeTs = await runtimeCanExecuteErasableTs();
-    const compiledPathsDirectory = pathJoin(modulesPath, nativeTs ? "routes" : ".cache");
-    if (!nativeTs) {
-        await rm(compiledPathsDirectory, { force: true, recursive: true });
-    }
-    const registry = new Registry();
-    const contextRegistry = new ContextRegistry();
-    const scenarioRegistry = new ScenarioRegistry();
-    const scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
-    const codeGenerator = new CodeGenerator(config.openApiPath, config.basePath, config.generate);
-    const openApiDocument = config.openApiPath === "_"
-        ? undefined
-        : await loadOpenApiDocument(config.openApiPath);
-    const dispatcher = new Dispatcher(registry, contextRegistry, openApiDocument, config);
-    const transpiler = new Transpiler(pathJoin(modulesPath, "routes"), compiledPathsDirectory, "commonjs");
-    const moduleLoader = new ModuleLoader(compiledPathsDirectory, registry, contextRegistry, pathJoin(modulesPath, "scenarios"), scenarioRegistry);
+export async function counterfact(config, specs) {
+    const normalizedSpecs = normalizeSpecs({ openApiPath: config.openApiPath, prefix: config.prefix }, specs);
+    validateSpecGroups(normalizedSpecs);
+    const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({ ...config, openApiPath: spec.source, prefix: spec.prefix }, spec.group)));
     const koaApp = createKoaApp({
+        runners,
         config,
-        contextRegistry,
-        dispatcher,
-        registry,
     });
+    // The REPL is configured using the first runner.
+    const primaryRunner = runners[0];
     async function start(options) {
-        const { generate, startServer, watch, buildCache } = options;
-        if (config.openApiPath !== "_" && (generate.routes || generate.types)) {
-            await codeGenerator.generate();
-        }
-        if (generate.types) {
-            await scenarioFileGenerator.generate();
-        }
-        if (config.openApiPath !== "_" && (watch.routes || watch.types)) {
-            await codeGenerator.watch();
-        }
-        if (watch.types) {
-            await scenarioFileGenerator.watch();
-        }
+        await Promise.all(runners.map((runner) => runner.generate()));
+        await Promise.all(runners.map((runner) => runner.watch()));
+        await Promise.all(runners.map((runner) => runner.start(options)));
         let httpTerminator;
-        if (startServer) {
-            await openApiDocument?.watch();
-            if (!nativeTs) {
-                await transpiler.watch();
-            }
-            await moduleLoader.load();
-            await moduleLoader.watch();
-            await runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument);
+        if (options.startServer) {
+            await runStartupScenario(primaryRunner.scenarioRegistry, primaryRunner.contextRegistry, { port: config.port }, primaryRunner.openApiDocument);
             const server = koaApp.listen({
                 port: config.port,
             });
@@ -169,28 +102,29 @@ export async function counterfact(config) {
                 server,
             });
         }
-        else if (buildCache) {
-            // If we are not starting the server, we still want to transpile and load modules
-            await transpiler.watch();
-            await transpiler.stopWatching();
-        }
         return {
             async stop() {
-                await codeGenerator.stopWatching();
-                await scenarioFileGenerator.stopWatching();
-                await transpiler.stopWatching();
-                await moduleLoader.stopWatching();
-                await openApiDocument?.stopWatching();
+                await Promise.all(runners.map((runner) => runner.stopWatching()));
                 await httpTerminator?.terminate();
             },
         };
     }
     return {
-        contextRegistry,
+        contextRegistry: primaryRunner.contextRegistry,
         koaApp,
-        registry,
+        registry: primaryRunner.registry,
         start,
-        startRepl: () => startReplServer(contextRegistry, registry, config, undefined, // use the default print function (stdout)
-        openApiDocument, scenarioRegistry),
+        startRepl: () => startReplServer(primaryRunner.contextRegistry, primaryRunner.registry, {
+            port: config.port,
+            proxyPaths: config.proxyPaths,
+            proxyUrl: config.proxyUrl,
+        }, undefined, // use the default print function (stdout)
+        primaryRunner.openApiDocument, primaryRunner.scenarioRegistry, runners.map((runner) => ({
+            contextRegistry: runner.contextRegistry,
+            group: runner.group,
+            openApiDocument: runner.openApiDocument,
+            registry: runner.registry,
+            scenarioRegistry: runner.scenarioRegistry,
+        }))),
     };
 }

package/dist/cli/banner.js

@@ -0,0 +1,81 @@
+/**
+ * Centers a tag line within the fixed-width ASCII banner header.
+ */
+export function padTagLine(tagLine) {
+    const headerLength = 51;
+    const padding = " ".repeat((headerLength - tagLine.length) / 2);
+    return `${padding}${tagLine}`;
+}
+/**
+ * Returns a short human-readable message describing which files are being
+ * watched or generated, or `undefined` when neither is active.
+ */
+export function createWatchMessage(config) {
+    switch (true) {
+        case config.watch.routes && config.watch.types: {
+            return "   Watching for changes";
+        }
+        case config.watch.routes: {
+            return "   Watching routes for changes";
+        }
+        case config.watch.types: {
+            return "   Watching types for changes";
+        }
+        default: {
+            break;
+        }
+    }
+    switch (true) {
+        case config.generate.routes && config.generate.types: {
+            return "Generating routes and types";
+        }
+        case config.generate.routes: {
+            return "Generating routes";
+        }
+        case config.generate.types: {
+            return "Generating types";
+        }
+        default: {
+            return undefined;
+        }
+    }
+}
+/**
+ * Builds the startup introduction lines that are printed to stdout when
+ * Counterfact starts.
+ */
+export function createIntroduction(params) {
+    const { config, isTelemetryDisabled, source, swaggerUrl, taglines, url, version, } = params;
+    const watchMessage = createWatchMessage({
+        generate: config.generate,
+        watch: config.watch,
+    });
+    const telemetryWarning = isTelemetryDisabled
+        ? []
+        : [
+            "⚠️  Telemetry will be enabled by default starting May 1, 2026.",
+            "   Learn more and how to disable: https://counterfact.dev/telemetry-discussion",
+            "",
+        ];
+    const lines = [
+        "   ____ ____ _  _ _ _ ___ ____ ____ ____ ____ ____ ___",
+        String.raw `   |___ [__] |__| |\|  |  |=== |--< |--- |--| |___  | `,
+        "   " +
+            padTagLine(taglines[Math.floor(Math.random() * taglines.length)] ?? ""),
+        "",
+        `   Version       ${version}`,
+        `   API Base URL  ${url}`,
+        source === "_" ? undefined : `   Swagger UI    ${swaggerUrl}`,
+        "",
+        "   Instructions  https://counterfact.dev/docs/usage.html",
+        "   Help/feedback https://github.com/pmcelhaney/counterfact/issues",
+        "",
+        ...telemetryWarning,
+        watchMessage,
+        config.startServer ? "   Starting server" : undefined,
+        config.startRepl
+            ? "   Starting REPL (type .help for more info)"
+            : undefined,
+    ];
+    return lines.filter((line) => line !== undefined).join("\n");
+}

package/dist/cli/check-for-updates.js

@@ -0,0 +1,45 @@
+import createDebug from "debug";
+const debug = createDebug("counterfact:cli:check-for-updates");
+/**
+ * Returns `true` when `latest` is a strictly higher semver version than
+ * `current`.
+ */
+export function isOutdated(current, latest) {
+    const [cMajor = 0, cMinor = 0, cPatch = 0] = current.split(".").map(Number);
+    const [lMajor = 0, lMinor = 0, lPatch = 0] = latest.split(".").map(Number);
+    if (lMajor > cMajor)
+        return true;
+    if (lMajor === cMajor && lMinor > cMinor)
+        return true;
+    if (lMajor === cMajor && lMinor === cMinor && lPatch > cPatch)
+        return true;
+    return false;
+}
+/**
+ * Checks the npm registry for a newer version of counterfact and prints a
+ * warning when one is available.  Never throws — update checks are
+ * best-effort.
+ */
+export async function checkForUpdates(currentVersion) {
+    if (process.env["CI"]) {
+        debug("skipping update check in CI environment");
+        return;
+    }
+    try {
+        const response = await fetch("https://registry.npmjs.org/counterfact/latest");
+        if (!response.ok) {
+            debug("update check failed with status %d", response.status);
+            return;
+        }
+        const data = (await response.json());
+        const latestVersion = data.version;
+        if (isOutdated(currentVersion, latestVersion)) {
+            process.stdout.write(`\n⚠️  You're running counterfact ${currentVersion}\n`);
+            process.stdout.write(`   Latest version is ${latestVersion}\n`);
+            process.stdout.write(`   Run: npx counterfact@latest\n`);
+        }
+    }
+    catch (error) {
+        debug("update check error: %o", error);
+    }
+}