counterfact 2.6.0 → 2.8.1

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

@@ -1,15 +1,37 @@
-import { pathToFileURL } from "node:url";
 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 "./koa-middleware.js";
 import { openapiMiddleware } from "./openapi-middleware.js";
-import { pageMiddleware } from "./page-middleware.js";
 const debug = createDebug("counterfact:server:create-koa-app");
-export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
+/**
+ * Builds and configures the Koa application with all built-in middleware.
+ *
+ * The middleware stack (in order) is:
+ * 1. OpenAPI document serving at `/counterfact/openapi`
+ * 2. Swagger UI at `/counterfact/swagger`
+ * 3. Admin API (when `config.startAdminApi` is `true`) at `/_counterfact/api/`
+ * 4. Redirect `/counterfact` → `/counterfact/swagger`
+ * 5. Body parser
+ * 6. JSON serialisation of object bodies
+ * 7. Route-dispatching middleware
+ *
+ * @param config - Server configuration.
+ * @param dispatcher - The Dispatcher used to build the route-dispatching middleware.
+ * @param registry - The route Registry used to build the admin API middleware.
+ * @param contextRegistry - The ContextRegistry used to build the admin API middleware.
+ * @returns A configured Koa application (not yet listening).
+ */
+export function createKoaApp({ config, contextRegistry, dispatcher, registry, }) {
     const app = new Koa();
-    app.use(openapiMiddleware(config.openApiPath, `//localhost:${config.port}${config.routePrefix}`));
+    app.use(openapiMiddleware([
+        {
+            path: config.openApiPath,
+            baseUrl: `//localhost:${config.port}${config.routePrefix}`,
+        },
+    ]));
     app.use(koaSwagger({
         routePrefix: "/counterfact/swagger",
         swaggerOptions: {
@@ -20,31 +42,13 @@ export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
         app.use(adminApiMiddleware(registry, contextRegistry, config));
     }
     debug("basePath: %s", config.basePath);
-    debug("routes", registry.routes);
-    app.use(pageMiddleware("/counterfact/", "index", {
-        basePath: config.basePath,
-        methods: ["get", "post", "put", "delete", "patch"],
-        openApiHref: config.openApiPath.includes("://")
-            ? config.openApiPath
-            : pathToFileURL(config.openApiPath).href,
-        openApiPath: config.openApiPath,
-        get routes() {
-            return registry.routes;
-        },
-    }));
     app.use(async (ctx, next) => {
         if (ctx.URL.pathname === "/counterfact") {
-            ctx.redirect("/counterfact/");
+            ctx.redirect("/counterfact/swagger");
             return;
         }
         await next();
     });
-    app.use(pageMiddleware("/counterfact/rapidoc", "rapi-doc", {
-        basePath: config.basePath,
-        get routes() {
-            return registry.routes;
-        },
-    }));
     app.use(bodyParser());
     app.use(async (ctx, next) => {
         await next();
@@ -56,6 +60,6 @@ export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
             ctx.type = "application/json";
         }
     });
-    app.use(koaMiddleware);
+    app.use(routesMiddleware(dispatcher, config));
     return app;
 }

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

@@ -2,6 +2,19 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 const DEFAULT_MODULE_KIND = "commonjs";
+/**
+ * Determines whether a module file should be treated as CommonJS or ESM.
+ *
+ * Resolution order (matches Node.js conventions):
+ * 1. `.cjs` extension → `"commonjs"`.
+ * 2. `.mjs` or `.ts` extension → `"module"`.
+ * 3. Walk up the directory tree looking for a `package.json` with a `"type"`
+ *    field.
+ * 4. Falls back to `"commonjs"` at the filesystem root.
+ *
+ * @param modulePath - Absolute or relative path to the module file.
+ * @returns `"commonjs"` or `"module"`.
+ */
 export async function determineModuleKind(modulePath) {
     if (modulePath.endsWith(".cjs")) {
         return "commonjs";

package/dist/server/dispatcher.js

@@ -3,8 +3,18 @@ import createDebugger from "debug";
 import fetch, { Headers } from "node-fetch";
 import { createResponseBuilder } from "./response-builder.js";
 import { validateRequest } from "./request-validator.js";
+import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
+/**
+ * Parses the `Cookie` request header into a key/value map.
+ *
+ * Duplicate keys are silently dropped (first occurrence wins) and values are
+ * percent-decoded where possible.
+ *
+ * @param cookieHeader - The raw `Cookie` header string.
+ * @returns A record mapping cookie name to decoded value.
+ */
 function parseCookies(cookieHeader) {
     const cookies = {};
     for (const part of cookieHeader.split(";")) {
@@ -26,6 +36,16 @@ function parseCookies(cookieHeader) {
     }
     return cookies;
 }
+/**
+ * Core HTTP request dispatcher.
+ *
+ * Receives incoming requests from the Koa middleware layer, matches them
+ * against the {@link Registry}, optionally validates the request and response
+ * against the OpenAPI spec, and invokes the matching route-handler function.
+ *
+ * Content-negotiation (Accept header handling) is performed before returning
+ * the response so the caller always receives the most appropriate content type.
+ */
 export class Dispatcher {
     registry;
     contextRegistry;
@@ -69,6 +89,14 @@ export class Dispatcher {
         }
         return undefined;
     }
+    /**
+     * Resolves the OpenAPI operation for `path` and `method`, merging any
+     * top-level `produces` array from the document root into the operation.
+     *
+     * @param path - The matched route path (e.g. `"/pets/{petId}"`).
+     * @param method - The HTTP method.
+     * @returns The {@link OpenApiOperation} if found, or `undefined`.
+     */
     operationForPathAndMethod(path, method) {
         const operation = this.findOperation(path, method);
         if (operation === undefined) {
@@ -107,6 +135,16 @@ export class Dispatcher {
                 "unknown/unknown",
         };
     }
+    /**
+     * Picks the best matching content entry from a multi-type response using the
+     * request's `Accept` header preferences.
+     *
+     * @param acceptHeader - The value of the `Accept` request header.
+     * @param content - Array of `{ type, body }` objects representing all
+     *   available content-type variants.
+     * @returns The first entry whose MIME type satisfies the accept preferences,
+     *   or `undefined` when none match.
+     */
     selectContent(acceptHeader, content) {
         const preferredMediaTypes = mediaTypes(acceptHeader);
         for (const mediaType of preferredMediaTypes) {
@@ -131,7 +169,16 @@ export class Dispatcher {
         }
         return false;
     }
-    async request({ auth, body, headers = {}, method, path, query, req, }) {
+    /**
+     * Main request handler.
+     *
+     * Orchestrates base-path stripping, route matching, request validation,
+     * handler invocation, content negotiation, and response validation.
+     *
+     * @param request - The incoming request descriptor.
+     * @returns A promise that resolves to a {@link CounterfactResponseObject}.
+     */
+    async request({ auth, body, headers = {}, method, path, query, rawBody, req, }) {
         debug(`request: ${method} ${path}`);
         debug(`headers: ${JSON.stringify(headers)}`);
         debug(`body: ${JSON.stringify(body)}`);
@@ -177,12 +224,9 @@ export class Dispatcher {
             cookie: parseCookies(headers.cookie ?? headers.Cookie ?? ""),
             headers,
             proxy: async (url) => {
-                if (body !== undefined && headers.contentType !== "application/json") {
-                    throw new Error(`$.proxy() is currently limited to application/json requests. You tried to proxy to ${url} with a Content-Type of ${headers.contentType ?? "[unknown]"}. Please open an issue at https://github.com/pmcelhaney/counterfact/issues and prod me to fix this limitation.`);
-                }
                 delete headers.host;
                 const fetchResponse = await this.fetch(`${url}${req.path ?? ""}`, {
-                    body: body === undefined ? undefined : JSON.stringify(body),
+                    body: body === undefined ? undefined : rawBody,
                     headers: new Headers(headers),
                     method,
                 });
@@ -213,6 +257,21 @@ export class Dispatcher {
                 status: 406,
             };
         }
+        if (this.config?.validateResponses !== false) {
+            const validation = validateResponse(operation, normalizedResponse);
+            if (!validation.valid) {
+                return {
+                    ...normalizedResponse,
+                    appendedHeaders: [
+                        ...(normalizedResponse.appendedHeaders ?? []),
+                        ...validation.errors.map((error) => [
+                            "response-type-error",
+                            error,
+                        ]),
+                    ],
+                };
+            }
+        }
         return normalizedResponse;
     }
 }

package/dist/server/file-discovery.js

@@ -1,32 +1,43 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import nodePath from "node:path";
+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"]);
+/**
+ * Recursively discovers JavaScript/TypeScript source files under a base
+ * directory.
+ *
+ * Only files with one of the following extensions are returned:
+ * `js`, `mjs`, `cjs`, `ts`, `mts`, `cts`.
+ */
 export class FileDiscovery {
     basePath;
     constructor(basePath) {
-        this.basePath = basePath.replaceAll("\\", "/");
+        this.basePath = toForwardSlashPath(basePath);
     }
+    /**
+     * Returns an array of absolute file paths for all JS/TS files found
+     * recursively under `basePath/directory`.
+     *
+     * @param directory - Sub-directory relative to `basePath` to start from.
+     *   Defaults to `""` (the base path itself).
+     * @throws When `basePath/directory` does not exist.
+     */
     async findFiles(directory = "") {
-        const fullDir = nodePath
-            .join(this.basePath, directory)
-            .replaceAll("\\", "/");
+        const fullDir = pathJoin(this.basePath, directory);
         if (!existsSync(fullDir)) {
             throw new Error(`Directory does not exist ${fullDir}`);
         }
         const entries = await fs.readdir(fullDir, { withFileTypes: true });
         const results = await Promise.all(entries.map(async (entry) => {
             if (entry.isDirectory()) {
-                return this.findFiles(nodePath.join(directory, entry.name).replaceAll("\\", "/"));
+                return this.findFiles(pathJoin(directory, entry.name));
             }
             const extension = entry.name.split(".").at(-1);
             if (!JS_EXTENSIONS.has(extension ?? "")) {
                 return [];
             }
-            const fullPath = nodePath
-                .join(this.basePath, directory, entry.name)
-                .replaceAll("\\", "/");
+            const fullPath = pathJoin(this.basePath, directory, entry.name);
             return [escapePathForWindows(fullPath)];
         }));
         return results.flat();

package/dist/server/is-proxy-enabled-for-path.js

@@ -1,3 +1,15 @@
+/**
+ * Determines whether a given request path should be forwarded to the upstream
+ * proxy.
+ *
+ * The check walks up the path hierarchy until it either finds an explicit
+ * `proxyPaths` entry or reaches the root (in which case the proxy is
+ * considered disabled).
+ *
+ * @param path - The request path to check (e.g. `"/pets/1"`).
+ * @param config - Object containing the `proxyPaths` map.
+ * @returns `true` when the request should be proxied.
+ */
 export function isProxyEnabledForPath(path, config) {
     if (config.proxyPaths.has(path)) {
         return config.proxyPaths.get(path) ?? false;

package/dist/server/json-to-xml.js

@@ -36,6 +36,16 @@ function objectToXml(json, schema, name) {
     });
     return `<${name}${attributes.join("")}>${String(xml.join(""))}</${name}>`;
 }
+/**
+ * Converts a JSON value to an XML string using optional OpenAPI `xml` schema
+ * hints (element names, attributes, wrapping).
+ *
+ * @param json - The value to serialise.
+ * @param schema - Optional JSON Schema with an `xml` hint block.
+ * @param keyName - Fallback XML element name when the schema does not provide
+ *   one.  Defaults to `"root"`.
+ * @returns A well-formed XML string.
+ */
 export function jsonToXml(json, schema, keyName = "root") {
     const name = schema?.xml?.name ?? keyName;
     if (Array.isArray(json)) {
@@ -50,5 +60,5 @@ export function jsonToXml(json, schema, keyName = "root") {
     if (typeof json === "object" && json !== null) {
         return objectToXml(json, schema, name);
     }
-    return `<${name}>${String(json)}</${name}>`;
+    return `<${name}>${xmlEscape(String(json))}</${name}>`;
 }

package/dist/server/koa-middleware.js

@@ -40,7 +40,24 @@ function getAuthObject(ctx) {
     const [username, password] = user.split(":");
     return { password, username };
 }
-export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
+/**
+ * Builds the Koa middleware function that bridges Koa's request context with
+ * the Counterfact {@link Dispatcher}.
+ *
+ * Responsibilities:
+ * - Respects `routePrefix` — 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 dispatcher - The {@link Dispatcher} instance that handles requests.
+ * @param config - Server configuration (proxy settings, route prefix, etc.).
+ * @param proxy - Proxy factory; injectable for testing.
+ * @returns A Koa middleware function.
+ */
+export function routesMiddleware(dispatcher, config, proxy = koaProxy) {
     return async function middleware(ctx, next) {
         const { proxyUrl, routePrefix } = config;
         debug("middleware running for path: %s", ctx.request.path);
@@ -49,7 +66,7 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
             return await next();
         }
         const auth = getAuthObject(ctx);
-        const { body, headers, query } = ctx.request;
+        const { body, headers, query, rawBody } = ctx.request;
         const path = ctx.request.path.slice(routePrefix.length);
         const method = ctx.request.method;
         if (isProxyEnabledForPath(path, config) && proxyUrl) {
@@ -69,6 +86,7 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
             path,
             /* @ts-expect-error the value of a querystring item can be an array and we don't have a solution for that yet */
             query,
+            rawBody: method === "HEAD" || method === "GET" ? undefined : rawBody,
             req: { path: "", ...ctx.req },
         });
         ctx.body = response.body;
@@ -88,6 +106,11 @@ export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
                 }
             }
         }
+        if (response.appendedHeaders) {
+            for (const [key, value] of response.appendedHeaders) {
+                ctx.res.appendHeader(key, value);
+            }
+        }
         ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
         return undefined;
     };

package/dist/server/load-openapi-document.js

@@ -0,0 +1,6 @@
+import { OpenApiDocument } from "./openapi-document.js";
+export async function loadOpenApiDocument(source) {
+    const document = new OpenApiDocument(source);
+    await document.load();
+    return document;
+}

package/dist/server/module-dependency-graph.js

@@ -2,6 +2,14 @@ import { dirname, resolve } from "node:path";
 import createDebug from "debug";
 import precinct from "precinct";
 const debug = createDebug("counterfact:server:module-dependency-graph");
+/**
+ * Tracks which route files depend on shared modules so that when a shared
+ * module changes, all dependent route files can be reloaded.
+ *
+ * Dependency edges are extracted using [precinct](https://npm.im/precinct)'s
+ * static analysis and are stored as a reverse map (`dependency → Set<dependent
+ * files>`).
+ */
 export class ModuleDependencyGraph {
     dependents = new Map();
     loadDependencies(path) {
@@ -18,6 +26,14 @@ export class ModuleDependencyGraph {
             group.delete(path);
         });
     }
+    /**
+     * (Re-)indexes the dependency edges for `path`, replacing any previously
+     * recorded edges.
+     *
+     * Only relative imports are tracked; node_modules dependencies are ignored.
+     *
+     * @param path - Absolute path of the file to analyse.
+     */
     load(path) {
         this.clearDependents(path);
         for (const dependency of this.loadDependencies(path)) {
@@ -31,6 +47,15 @@ export class ModuleDependencyGraph {
             this.dependents.get(key)?.add(path);
         }
     }
+    /**
+     * Returns the transitive set of files that (directly or indirectly) import
+     * `path`.
+     *
+     * Uses a BFS traversal so each dependent is returned exactly once.
+     *
+     * @param path - Absolute path of the changed dependency.
+     * @returns A `Set` of absolute paths of all dependent files.
+     */
     dependentsOf(path) {
         const marked = new Set();
         const dependents = new Set();

package/dist/server/module-loader.js

@@ -1,6 +1,6 @@
 import { once } from "node:events";
 import fs from "node:fs/promises";
-import nodePath, { basename, dirname } from "node:path";
+import nodePath, { basename } from "node:path";
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
@@ -10,46 +10,76 @@ import { FileDiscovery } from "./file-discovery.js";
 import { isContextModule, isMiddlewareModule, } from "./middleware-detector.js";
 import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import { uncachedImport } from "./uncached-import.js";
+import { toForwardSlashPath, pathDirname, pathRelative, } from "../util/forward-slash-path.js";
 import { unescapePathForWindows } from "../util/windows-escape.js";
 const { uncachedRequire } = await import("./uncached-require.cjs");
 const debug = createDebug("counterfact:server:module-loader");
+/**
+ * Watches the compiled routes directory and dynamically loads/reloads route
+ * modules, context files, and middleware as files are added, changed, or
+ * removed.
+ *
+ * Loaded modules are registered in the {@link Registry} (route handlers) or
+ * the {@link ContextRegistry} (context files).  An optional
+ * {@link ScenarioRegistry} receives scenario modules loaded from a separate
+ * `scenarios/` directory.
+ *
+ * Emits DOM-style events (`"add"`, `"remove"`) so callers can react to module
+ * lifecycle changes.
+ */
 export class ModuleLoader extends EventTarget {
     basePath;
     registry;
     watcher;
+    scenariosWatcher;
     contextRegistry;
+    scenariosPath;
+    scenarioRegistry;
     dependencyGraph = new ModuleDependencyGraph();
     fileDiscovery;
     uncachedImport = async function (moduleName) {
         throw new Error(`uncachedImport not set up; importing ${moduleName}`);
     };
-    constructor(basePath, registry, contextRegistry = new ContextRegistry()) {
+    constructor(basePath, registry, contextRegistry = new ContextRegistry(), scenariosPath, scenarioRegistry) {
         super();
-        this.basePath = basePath.replaceAll("\\", "/");
+        this.basePath = toForwardSlashPath(basePath);
         this.registry = registry;
         this.contextRegistry = contextRegistry;
+        this.scenariosPath =
+            scenariosPath === undefined
+                ? undefined
+                : toForwardSlashPath(scenariosPath);
+        this.scenarioRegistry = scenarioRegistry;
         this.fileDiscovery = new FileDiscovery(this.basePath);
     }
+    /**
+     * Starts watching the routes directory (and optionally the scenarios
+     * directory) for file-system changes, loading or reloading modules on
+     * `"add"` and `"change"` events and deregistering them on `"unlink"`.
+     *
+     * Resolves once the initial directory scan is complete.
+     */
     async watch() {
         this.watcher = watch(this.basePath, CHOKIDAR_OPTIONS).on("all", (eventName, pathNameOriginal) => {
             const JS_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
             if (!JS_EXTENSIONS.some((extension) => pathNameOriginal.endsWith(`.${extension}`)))
                 return;
-            const pathName = pathNameOriginal.replaceAll("\\", "/");
+            const pathName = toForwardSlashPath(pathNameOriginal);
             if (pathName.includes("$.context") && eventName === "add") {
-                process.stdout.write(`\n\n!!! The file at ${pathName} needs a minor update.\n    See https://github.com/pmcelhaney/counterfact/blob/main/docs/context-change.md\n\n\n`);
+                process.stdout.write(`\n\n!!! The file at ${pathName} needs a minor update.\n    See https://github.com/pmcelhaney/counterfact/blob/main/docs/faq.md\n\n\n`);
                 return;
             }
             if (!["add", "change", "unlink"].includes(eventName)) {
                 return;
             }
             const parts = nodePath.parse(pathName.replace(this.basePath, ""));
-            const url = unescapePathForWindows(`/${parts.dir}/${parts.name}`
-                .replaceAll("\\", "/")
-                .replaceAll(/\/+/gu, "/"));
+            const url = unescapePathForWindows(toForwardSlashPath(`/${parts.dir}/${parts.name}`).replaceAll(/\/+/gu, "/"));
             if (eventName === "unlink") {
                 this.registry.remove(url);
                 this.dispatchEvent(new Event("remove"));
+                if (this.isContextFile(pathName)) {
+                    this.contextRegistry.remove(unescapePathForWindows(toForwardSlashPath(parts.dir)) || "/");
+                }
                 return;
             }
             const dependencies = this.dependencyGraph.dependentsOf(pathName);
@@ -59,20 +89,88 @@ export class ModuleLoader extends EventTarget {
             }
         });
         await once(this.watcher, "ready");
+        if (this.scenariosPath && this.scenarioRegistry) {
+            const JS_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
+            const scenariosPath = this.scenariosPath;
+            this.scenariosWatcher = watch(scenariosPath, CHOKIDAR_OPTIONS).on("all", (eventName, pathNameOriginal) => {
+                if (!JS_EXTENSIONS.some((ext) => pathNameOriginal.endsWith(`.${ext}`)))
+                    return;
+                if (!["add", "change", "unlink"].includes(eventName))
+                    return;
+                const pathName = toForwardSlashPath(pathNameOriginal);
+                if (eventName === "unlink") {
+                    const fileKey = this.scenarioFileKey(pathName);
+                    this.scenarioRegistry?.remove(fileKey);
+                    return;
+                }
+                void this.loadScenarioFile(pathName);
+            });
+            await once(this.scenariosWatcher, "ready");
+        }
     }
+    /** Closes both file-system watchers (routes and scenarios). */
     async stopWatching() {
         await this.watcher?.close();
+        await this.scenariosWatcher?.close();
+    }
+    isContextFile(pathName) {
+        return basename(pathName).startsWith("_.context.");
     }
+    /**
+     * Performs a one-shot load of all modules found under `directory` (relative
+     * to the configured base path) and all scenario files.
+     *
+     * @param directory - Sub-directory to load, defaults to the root (`""`).
+     */
     async load(directory = "") {
         const files = await this.fileDiscovery.findFiles(directory);
         await Promise.all(files.map((file) => this.loadEndpoint(file)));
+        await this.loadScenarios();
+    }
+    shouldLoadScenarioFile(pathName) {
+        return !pathName.endsWith(".d.ts") && !pathName.endsWith(".map");
+    }
+    async loadScenarios() {
+        if (!this.scenariosPath || !this.scenarioRegistry)
+            return;
+        try {
+            const fileDiscovery = new FileDiscovery(this.scenariosPath);
+            const files = await fileDiscovery.findFiles();
+            const loadableFiles = files.filter((file) => this.shouldLoadScenarioFile(file));
+            await Promise.all(loadableFiles.map((file) => this.loadScenarioFile(file)));
+        }
+        catch {
+            // Scenarios directory does not exist yet — that's fine.
+        }
+    }
+    scenarioFileKey(pathName) {
+        const normalizedScenariosPath = toForwardSlashPath(this.scenariosPath ?? "");
+        const directory = pathDirname(pathName.slice(normalizedScenariosPath.length));
+        const name = nodePath.parse(basename(pathName)).name;
+        const url = unescapePathForWindows(toForwardSlashPath(`/${nodePath.join(directory, name)}`).replaceAll(/\/+/gu, "/"));
+        return url.slice(1); // strip leading "/"
+    }
+    async loadScenarioFile(pathName) {
+        if (!this.scenariosPath || !this.scenarioRegistry)
+            return;
+        const fileKey = this.scenarioFileKey(pathName);
+        try {
+            const doImport = (await determineModuleKind(pathName)) === "commonjs"
+                ? uncachedRequire
+                : uncachedImport;
+            const module = await doImport(pathName);
+            if (module) {
+                this.scenarioRegistry.add(fileKey, module);
+            }
+        }
+        catch (error) {
+            process.stdout.write(`\nError loading scenario ${pathName}:\n${String(error)}\n`);
+        }
     }
     async loadEndpoint(pathName) {
         debug("importing module: %s", pathName);
-        const directory = dirname(pathName.slice(this.basePath.length)).replaceAll("\\", "/");
-        const url = unescapePathForWindows(`/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`
-            .replaceAll("\\", "/")
-            .replaceAll(/\/+/gu, "/"));
+        const directory = pathDirname(pathName.slice(this.basePath.length));
+        const url = unescapePathForWindows(toForwardSlashPath(`/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`).replaceAll(/\/+/gu, "/"));
         debug(`loading pathName from dependencyGraph: ${pathName}`);
         this.dependencyGraph.load(pathName);
         try {
@@ -86,9 +184,7 @@ export class ModuleLoader extends EventTarget {
             if (importError !== undefined) {
                 const isSyntaxError = importError instanceof SyntaxError ||
                     String(importError).startsWith("SyntaxError:");
-                const displayPath = nodePath
-                    .relative(process.cwd(), unescapePathForWindows(pathName))
-                    .replaceAll("\\", "/");
+                const displayPath = pathRelative(process.cwd(), unescapePathForWindows(pathName));
                 const message = isSyntaxError
                     ? `There is a syntax error in the route file: ${displayPath}`
                     : `There was an error loading the route file: ${displayPath}`;
@@ -113,8 +209,7 @@ export class ModuleLoader extends EventTarget {
                 return;
             }
             this.dispatchEvent(new Event("add"));
-            if (basename(pathName).startsWith("_.context.") &&
-                isContextModule(endpoint)) {
+            if (this.isContextFile(pathName) && isContextModule(endpoint)) {
                 const loadContext = (path) => this.contextRegistry.find(path);
                 const contextDir = nodePath.dirname(unescapePathForWindows(pathName));
                 const readJson = async (relativePath) => {