counterfact 2.7.0 → 2.9.0

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

@@ -1,6 +1,16 @@
-import nodePath from "node:path";
+import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
 import { OperationTypeCoder, } from "./operation-type-coder.js";
+/**
+ * Generates the default route handler stub for a single OpenAPI operation.
+ *
+ * The generated stub calls `$.response[statusCode].random()` (or `.empty()`)
+ * for the first response defined in the spec.  It is only written when no
+ * handler file exists yet — users are expected to replace it with real logic.
+ *
+ * The corresponding TypeScript type is emitted by {@link OperationTypeCoder}
+ * into the `types/paths/…` tree.
+ */
 export class OperationCoder extends Coder {
     requestMethod;
     securitySchemes;
@@ -38,8 +48,6 @@ export class OperationCoder extends Coder {
             .split("/")
             .at(-2)
             .replaceAll("~1", "/");
-        return `${nodePath
-            .join("routes", pathString)
-            .replaceAll("\\", "/")}.types.ts`;
+        return `${pathJoin("routes", pathString)}.types.ts`;
     }
 }

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

@@ -1,4 +1,4 @@
-import nodePath from "node:path";
+import { pathJoin } from "../util/forward-slash-path.js";
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
 import { buildJsDoc } from "./jsdoc.js";
 import { ParameterExportTypeCoder } from "./parameter-export-type-coder.js";
@@ -24,6 +24,15 @@ function sanitizeIdentifier(value) {
     }
     return result || "_";
 }
+/**
+ * Generates the TypeScript type for a single OpenAPI operation.
+ *
+ * The emitted type describes the function signature that a Counterfact route
+ * handler must satisfy, including strongly-typed `query`, `path`, `headers`,
+ * `cookie`, `body`, `context`, `response`, and `user` arguments.
+ *
+ * Output is written to `types/paths/<route>.types.ts`.
+ */
 export class OperationTypeCoder extends TypeCoder {
     requestMethod;
     securitySchemes;
@@ -35,6 +44,10 @@ export class OperationTypeCoder extends TypeCoder {
         this.requestMethod = requestMethod;
         this.securitySchemes = securitySchemes;
     }
+    /**
+     * Returns the base identifier for this operation, derived from its
+     * `operationId` (sanitised) or falling back to `HTTP_<METHOD>`.
+     */
     getOperationBaseName() {
         const operationId = this.requirement.get("operationId")?.data;
         return operationId
@@ -47,6 +60,19 @@ export class OperationTypeCoder extends TypeCoder {
     names() {
         return super.names(this.getOperationBaseName());
     }
+    /**
+     * Generates and exports a named parameter type (e.g. `ListPets_Query`) from
+     * `modulePath` and returns the exported type name.
+     *
+     * Returns `"never"` without creating an export when `inlineType` is
+     * `"never"`.
+     *
+     * @param script - The script being assembled.
+     * @param parameterKind - `"query"`, `"path"`, `"headers"`, or `"cookie"`.
+     * @param inlineType - The inline TypeScript type string to export.
+     * @param baseName - The base identifier prefix for the exported type name.
+     * @param modulePath - The repository-relative path of the type file.
+     */
     exportParameterType(script, parameterKind, inlineType, baseName, modulePath) {
         if (inlineType === "never") {
             return "never";
@@ -57,6 +83,11 @@ export class OperationTypeCoder extends TypeCoder {
         coder._modulePath = modulePath;
         return script.export(coder, true);
     }
+    /**
+     * Returns the union of all possible response type shapes for this operation.
+     *
+     * @param script - The script being assembled (used to resolve imports).
+     */
     responseTypes(script) {
         return this.requirement
             .get("responses")
@@ -96,10 +127,14 @@ export class OperationTypeCoder extends TypeCoder {
             .split("/")
             .at(-2)
             .replaceAll("~1", "/");
-        return `${nodePath
-            .join("types/paths", pathString === "/" ? "/index" : pathString)
-            .replaceAll("\\", "/")}.types.ts`;
+        return `${pathJoin("types/paths", pathString === "/" ? "/index" : pathString)}.types.ts`;
     }
+    /**
+     * Returns the TypeScript type for the `user` argument.
+     *
+     * When the operation is protected by HTTP Basic auth, the type is
+     * `{username?: string, password?: string}`.  Otherwise it is `"never"`.
+     */
     userType() {
         if (this.securitySchemes.some(({ scheme, type }) => type === "http" && scheme === "basic")) {
             return "{username?: string, password?: string}";

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

@@ -1,4 +1,4 @@
-import nodePath from "node:path";
+import { pathJoin } from "../util/forward-slash-path.js";
 import { buildJsDoc } from "./jsdoc.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
@@ -39,8 +39,6 @@ export class ParametersTypeCoder extends TypeCoder {
             .split("/")
             .at(-2)
             .replaceAll("~1", "/");
-        return `${nodePath
-            .join("parameters", pathString)
-            .replaceAll("\\", "/")}.types.ts`;
+        return `${pathJoin("parameters", pathString)}.types.ts`;
     }
 }

package/dist/typescript-generator/prune.js

@@ -1,6 +1,8 @@
 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");
 /**
  * Collects all .ts route files in a directory recursively.
@@ -87,7 +89,7 @@ export async function pruneRoutes(destination, openApiPaths) {
     debug("actual route files: %o", actualFiles);
     let prunedCount = 0;
     for (const file of actualFiles) {
-        const normalizedFile = file.replaceAll("\\", "/");
+        const normalizedFile = toForwardSlashPath(file);
         if (!expectedFiles.has(normalizedFile)) {
             const fullPath = nodePath.join(routesDir, file);
             debug("pruning %s", fullPath);

package/dist/typescript-generator/repository.js

@@ -2,19 +2,36 @@ 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";
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
 import { Script } from "./script.js";
 import { escapePathForWindows } from "../util/windows-escape.js";
 const debug = createDebug("counterfact:server:repository");
-const __dirname = dirname(fileURLToPath(import.meta.url)).replaceAll("\\", "/");
+const __dirname = toForwardSlashPath(dirname(fileURLToPath(import.meta.url)));
 debug("dirname is %s", __dirname);
+/**
+ * Collection of {@link Script} objects keyed by their repository-relative
+ * path.
+ *
+ * Coders call {@link get} to obtain (or create) the script where they should
+ * export their generated TypeScript.  After all coders have been registered,
+ * {@link writeFiles} waits for every script to finish and writes the output to
+ * disk.
+ */
 export class Repository {
     scripts;
     constructor() {
         this.scripts = new Map();
     }
+    /**
+     * Returns the {@link Script} for `path`, creating it if it does not yet
+     * exist.
+     *
+     * @param path - Repository-relative path (e.g. `"routes/pets.ts"`).
+     */
     get(path) {
         debug("getting script at %s", path);
         if (this.scripts.has(path)) {
@@ -26,12 +43,22 @@ export class Repository {
         this.scripts.set(path, script);
         return script;
     }
+    /** Waits until all scripts have resolved all of their pending export promises. */
     async finished() {
         while (Array.from(this.scripts.values()).some((script) => script.isInProgress())) {
             debug("waiting for %i scripts to finish", this.scripts.size);
             await Promise.all(Array.from(this.scripts.values(), (script) => script.finished()));
         }
     }
+    /**
+     * Copies the compiled `counterfact-types` directory from the Counterfact
+     * distribution into the generated output tree.
+     *
+     * Returns `false` when the source directory does not exist (e.g. running
+     * from source without a prior build).
+     *
+     * @param destination - The root of the generated output tree.
+     */
     async copyCoreFiles(destination) {
         const sourcePath = nodePath.join(__dirname, "../../dist/server/counterfact-types");
         const destinationPath = nodePath.join(destination, "counterfact-types");
@@ -40,13 +67,23 @@ export class Repository {
         }
         return fs.cp(sourcePath, destinationPath, { recursive: true });
     }
+    /**
+     * Waits for all scripts to finish, then writes each one to disk.
+     *
+     * Route files (`routes/…`) are never overwritten if they already exist on
+     * disk, preserving user edits.  Type files (`types/…`) are always
+     * overwritten.
+     *
+     * @param destination - Absolute path to the output root directory.
+     * @param options - Controls which artefacts are written.
+     */
     async writeFiles(destination, { routes, types }) {
         debug("waiting for %i or more scripts to finish before writing files", this.scripts.size);
         await this.finished();
         debug("all %i scripts are finished", this.scripts.size);
         const writeFiles = Array.from(this.scripts.entries(), async ([path, script]) => {
             const contents = await script.contents();
-            const fullPath = escapePathForWindows(nodePath.join(destination, path).replaceAll("\\", "/"));
+            const fullPath = escapePathForWindows(pathJoin(destination, path));
             await ensureDirectoryExists(fullPath);
             const shouldWriteRoutes = routes && path.startsWith("routes");
             const shouldWriteTypes = types && !path.startsWith("routes");
@@ -70,37 +107,57 @@ export class Repository {
             await this.createDefaultContextFile(destination);
         }
     }
+    /**
+     * Creates the default `routes/_.context.ts` file if it does not already
+     * exist.
+     *
+     * @param destination - Absolute path to the output root directory.
+     */
     async createDefaultContextFile(destination) {
         const contextFilePath = nodePath.join(destination, "routes", "_.context.ts");
         if (existsSync(contextFilePath)) {
             return;
         }
         await ensureDirectoryExists(contextFilePath);
-        await fs.writeFile(contextFilePath, `/**
-* This is the default context for Counterfact.
-*
-* It defines the context object in the REPL 
-* and the $.context object in the code.
-*
-* Add properties and methods to suit your needs.
-* 
-* See https://counterfact.dev/docs/usage.html#working-with-state-the-codecontextcode-object-and-codecontexttscode
-*/
-export class Context {
+        await fs.writeFile(contextFilePath, `import type { Context$ } from "../types/_.context.js";
+
+/**
+ * This is the default context for Counterfact.
+ *
+ * It defines the context object in the REPL
+ * and the $.context object in the code.
+ *
+ * Add properties and methods to suit your needs.
+ *
+ * See https://github.com/counterfact/api-simulator/blob/main/docs/features/state.md
+ */
 
+export class Context {
+  constructor($: Context$) {
+    void $;
+  }
 }
 `);
     }
+    /**
+     * Returns the path of the `_.context.ts` file that is nearest to `path` in
+     * the directory hierarchy, relative to the script's output directory.
+     *
+     * @param destination - Output root directory.
+     * @param path - Repository-relative path of the script being generated.
+     */
     findContextPath(destination, path) {
-        return nodePath
-            .relative(nodePath.join(destination, nodePath.dirname(path)), this.nearestContextFile(destination, path))
-            .replaceAll("\\", "/");
+        return pathRelative(nodePath.join(destination, nodePath.dirname(path)), this.nearestContextFile(destination, path));
     }
+    /**
+     * Walks up the directory tree from `path` to find the nearest
+     * `_.context.ts` file, falling back to `routes/_.context.ts` at the root.
+     *
+     * @param destination - Output root directory.
+     * @param path - Repository-relative path to start from.
+     */
     nearestContextFile(destination, path) {
-        const directory = nodePath
-            .dirname(path)
-            .replaceAll("\\", "/")
-            .replace("types/paths", "routes");
+        const directory = pathDirname(path).replace("types/paths", "routes");
         const candidate = nodePath.join(destination, directory, "_.context.ts");
         if (directory.length <= 1) {
             // No _context.ts was found so import the one that should be in the root

package/dist/typescript-generator/requirement.js

@@ -1,3 +1,11 @@
+/**
+ * A node in the dereferenced OpenAPI spec tree.
+ *
+ * A `Requirement` wraps a raw JSON object (`data`) together with its location
+ * (`url`, a JSON Pointer) and a back-reference to the owning
+ * {@link Specification}.  Navigation methods (`get`, `select`, `find`, …)
+ * transparently follow `$ref` pointers.
+ */
 export class Requirement {
     data;
     url;
@@ -7,18 +15,36 @@ export class Requirement {
         this.url = url;
         this.specification = specification;
     }
+    /** `true` when this node is a JSON Reference (`$ref`) rather than inline data. */
     get isReference() {
         return this.data["$ref"] !== undefined;
     }
+    /**
+     * Resolves the `$ref` and returns the target {@link Requirement}.
+     *
+     * @throws When `isReference` is `false` or the specification is not set.
+     */
     reference() {
         return this.specification.getRequirement(this.data["$ref"]);
     }
+    /**
+     * Returns `true` when this node has a child property named `item`.
+     *
+     * Transparently follows `$ref` references.
+     *
+     * @param item - The property key to check.
+     */
     has(item) {
         if (this.isReference) {
             return this.reference().has(item);
         }
         return item in this.data;
     }
+    /**
+     * Returns the child {@link Requirement} for `item`, or `undefined`.
+     *
+     * @param item - The property key (string) or array index (number).
+     */
     get(item) {
         if (this.isReference) {
             return this.reference().get(item);
@@ -29,6 +55,16 @@ export class Requirement {
         }
         return new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
     }
+    /**
+     * Navigates to a descendant node using a slash-delimited JSON Pointer path.
+     *
+     * Tilde-escaped characters (`~0` → `~`, `~1` → `/`) and percent-encoded
+     * characters are unescaped during traversal.
+     *
+     * @param path - A slash-delimited path (e.g. `"responses/200/content"`).
+     * @returns The target {@link Requirement}, or `undefined` if the path does
+     *   not exist.
+     */
     select(path) {
         const parts = path
             .split("/")
@@ -54,19 +90,42 @@ export class Requirement {
         }
         return result;
     }
+    /**
+     * Iterates over all child properties and calls `callback` with each child
+     * requirement and its key.
+     *
+     * @param callback - Called for each child with `(child, key)`.
+     */
     forEach(callback) {
         Object.keys(this.data).forEach((key) => {
             callback(this.select(this.escapeJsonPointer(key)), key);
         });
     }
+    /**
+     * Maps over all child properties and returns the collected results.
+     *
+     * @param callback - Transformation function called with `(child, key)`.
+     */
     map(callback) {
         const result = [];
         this.forEach((value, key) => result.push(callback(value, key)));
         return result;
     }
+    /**
+     * Maps and flattens over all child properties.
+     *
+     * @param callback - Transformation function that may return a value or an
+     *   array of values.
+     */
     flatMap(callback) {
         return this.map(callback).flat();
     }
+    /**
+     * Returns the first child for which `callback` returns `true`, or
+     * `undefined` when nothing matches.
+     *
+     * @param callback - Predicate called with `(child, key)`.
+     */
     find(callback) {
         let result;
         this.forEach((value, key) => {
@@ -76,11 +135,21 @@ export class Requirement {
         });
         return result;
     }
+    /**
+     * Escapes a JSON Pointer token: `~` → `~0`, `/` → `~1`.
+     *
+     * @param value - The token to escape.
+     */
     escapeJsonPointer(value) {
         if (typeof value !== "string")
             return value;
         return value.replaceAll("~", "~0").replaceAll("/", "~1");
     }
+    /**
+     * Unescapes a JSON Pointer token: `~1` → `/`, `~0` → `~`.
+     *
+     * @param pointer - The token to unescape.
+     */
     unescapeJsonPointer(pointer) {
         if (typeof pointer !== "string")
             return pointer;

package/dist/typescript-generator/{generate.js → scenario-file-generator.js}

@@ -1,70 +1,11 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
-import createDebug from "debug";
-import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
-import { OperationCoder } from "./operation-coder.js";
-import { pruneRoutes } from "./prune.js";
-import { Repository } from "./repository.js";
-import { Specification } from "./specification.js";
-const debug = createDebug("counterfact:typescript-generator:generate");
-async function buildCacheDirectory(destination) {
-    const gitignorePath = nodePath.join(destination, ".gitignore");
-    const cacheReadmePath = nodePath.join(destination, ".cache", "README.md");
-    debug("ensuring the directory containing .gitgnore exists");
-    await ensureDirectoryExists(gitignorePath);
-    debug("creating the .gitignore file if it doesn't already exist");
-    if (!existsSync(gitignorePath)) {
-        await fs.writeFile(gitignorePath, ".cache\n", "utf8");
-    }
-    debug("creating the .cache/README.md file");
-    ensureDirectoryExists(cacheReadmePath);
-    await fs.writeFile(cacheReadmePath, "This directory contains compiled JS files from the paths directory. Do not edit these files directly.\n", "utf8");
-}
-async function getPathsFromSpecification(specification) {
-    try {
-        return specification.getRequirement("#/paths") ?? new Set();
-    }
-    catch (error) {
-        process.stderr.write(`Could not find #/paths in the specification.\n${error}\n`);
-        return undefined;
-    }
-}
-export async function generate(source, destination, generateOptions, repository = new Repository()) {
-    debug("generating code from %s to %s", source, destination);
-    debug("initializing the .cache directory");
-    await buildCacheDirectory(destination);
-    debug("done initializing the .cache directory");
-    debug("creating specification from %s", source);
-    const specification = await Specification.fromFile(source);
-    debug("created specification: $o", specification);
-    debug("reading the #/paths from the specification");
-    const paths = await getPathsFromSpecification(specification);
-    debug("got %i paths", paths?.map?.length ?? 0);
-    if (generateOptions.prune && generateOptions.routes) {
-        debug("pruning defunct route files");
-        await pruneRoutes(destination, paths.map((_v, key) => key));
-        debug("done pruning");
-    }
-    const securityRequirement = specification.getRequirement("#/components/securitySchemes");
-    const securitySchemes = Object.values(securityRequirement?.data ?? {});
-    paths.forEach((pathDefinition, key) => {
-        debug("processing path %s", key);
-        const path = key === "/" ? "/index" : key;
-        pathDefinition.forEach((operation, requestMethod) => {
-            repository
-                .get(`routes${path}.ts`)
-                .export(new OperationCoder(operation, requestMethod, securitySchemes));
-        });
-    });
-    debug("telling the repository to write the files to %s", destination);
-    await repository.writeFiles(destination, generateOptions);
-    debug("finished writing the files");
-    if (generateOptions.types) {
-        await writeApplyContextType(destination);
-        await writeDefaultScenariosIndex(destination);
-    }
-}
+/* 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";
+import { waitForEvent } from "../util/wait-for-event.js";
 async function collectContextFiles(destination) {
     const routesDir = nodePath.join(destination, "routes");
     const results = [];
@@ -88,9 +29,7 @@ async function walkForContextFiles(routesDir, currentDir, results) {
             await walkForContextFiles(routesDir, nodePath.join(currentDir, entry.name), results);
         }
         else if (entry.name === "_.context.ts") {
-            const relDir = nodePath
-                .relative(routesDir, currentDir)
-                .replaceAll("\\", "/");
+            const relDir = pathRelative(routesDir, currentDir);
             const routePath = relDir === "" ? "/" : `/${relDir}`;
             const depth = relDir === "" ? 0 : relDir.split("/").length;
             const importPath = relDir === "" ? "../routes/_.context" : `../routes/${relDir}/_.context`;
@@ -128,7 +67,7 @@ function buildLoadContextOverload(routePath, alias) {
         .join("/")}`;
     return `  loadContext(path: \`${templatePath}\`): ${alias};`;
 }
-function buildApplyContextContent(contextFiles) {
+function buildScenarioContextContent(contextFiles) {
     const rootContext = contextFiles.find((f) => f.routePath === "/");
     const contextType = rootContext
         ? rootContext.alias
@@ -141,38 +80,60 @@ function buildApplyContextContent(contextFiles) {
         "// This file is generated by Counterfact. Do not edit manually.",
         ...importLines,
         "",
-        "export interface ApplyContext {",
-        '  /** Root context, same as loadContext("/") */',
-        `  context: ${contextType};`,
-        "  /** Load a context object for a specific path */",
+        "interface LoadContextDefinitions {",
+        "  /* code generator adds additional signatures here */",
         ...overloadLines,
         "  loadContext(path: string): Record<string, unknown>;",
+        "}",
+        "",
+        "export interface Scenario$ {",
+        '  /** Root context, same as loadContext("/") */',
+        `  readonly context: ${contextType};`,
+        '  readonly loadContext: LoadContextDefinitions["loadContext"];',
         "  /** Named route builders stored in the REPL execution context */",
-        "  routes: Record<string, unknown>;",
+        "  readonly routes: Record<string, unknown>;",
         "  /** Create a new route builder for a given path */",
-        "  route: (path: string) => unknown;",
+        "  readonly route: (path: string) => unknown;",
         "}",
         "",
         "/** A scenario function that receives the live REPL environment */",
-        "export type Scenario = ($: ApplyContext) => Promise<void> | void;",
+        "export type Scenario = ($: Scenario$) => Promise<void> | void;",
+        "",
+        "/** Interface for Context objects defined in _.context.ts files */",
+        "export interface Context$ {",
+        "  /** Load a context object for a specific path */",
+        '  readonly loadContext: LoadContextDefinitions["loadContext"];',
+        "  /** Load a JSON file relative to this file's path */",
+        "  readonly readJson: (relativePath: string) => Promise<unknown>;",
+        "}",
         "",
     ];
     return parts.join("\n");
 }
-export async function writeApplyContextType(destination) {
+/**
+ * Writes the `types/_.context.ts` file, which exports the
+ * `Scenario$` interface used to type scenario functions.
+ *
+ * The interface is generated from all `_.context.ts` files found under the
+ * `routes/` directory, providing strongly typed `loadContext()` overloads for
+ * every route path that has a context file.
+ *
+ * @param destination - Root output directory.
+ */
+async function writeScenarioContextType(destination) {
     const typesDir = nodePath.join(destination, "types");
-    const filePath = nodePath.join(typesDir, "scenario-context.ts");
+    const filePath = nodePath.join(typesDir, "_.context.ts");
     const contextFiles = await collectContextFiles(destination);
-    const content = buildApplyContextContent(contextFiles);
+    const content = buildScenarioContextContent(contextFiles);
     await fs.mkdir(typesDir, { recursive: true });
     await fs.writeFile(filePath, content, "utf8");
 }
-const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/scenario-context.js";
+const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/_.context.js";
 
 /**
  * Scenario scripts are plain TypeScript functions that receive the live REPL
  * environment and can read or mutate server state. Run them from the REPL with:
- *   .apply <functionName>
+ *   .scenario <functionName>
  */
 
 /**
@@ -186,9 +147,24 @@ const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/scenari
  *   $.routes.myRequest = $.route("/pets").method("get");
  */
 
+/**
+ * startup() runs automatically when the server initializes, right before the
+ * REPL starts. Use it to seed dummy data so the server is ready to use
+ * immediately. It receives the same $ argument as all other scenario functions.
+ *
+ * Tip: delegate to other scenario functions and pass $ along so each function
+ * stays focused on a single concern. You can also pass additional arguments to
+ * configure them, e.g. addPets($, 20, "dog").
+ *
+ * If you don't need a startup scenario, delete this function or leave it empty.
+ */
+export const startup: Scenario = ($) => {
+  void $;
+};
+
 /**
  * An example scenario. To use it in the REPL, type:
- *   .apply help
+ *   .scenario help
  */
 export const help: Scenario = ($) => {
   void $;
@@ -216,3 +192,45 @@ async function writeDefaultScenariosIndex(destination) {
     await fs.mkdir(scenariosDir, { recursive: true });
     await fs.writeFile(filePath, DEFAULT_SCENARIOS_INDEX, "utf8");
 }
+/**
+ * Encapsulates the generation of scenario-related files:
+ * - `types/_.context.ts` — the typed `Scenario$` interface derived from all
+ *   `_.context.ts` files found under `routes/`.
+ * - `scenarios/index.ts` — the default scenarios entry-point (created only if
+ *   it does not already exist).
+ *
+ * When {@link watch} is called, a file-system watcher monitors the `routes/`
+ * directory for changes to `_.context.ts` files and automatically regenerates
+ * `types/_.context.ts`.
+ */
+export class ScenarioFileGenerator {
+    destination;
+    watcher;
+    constructor(destination) {
+        this.destination = destination;
+    }
+    /** Generates both scenario-related files once and resolves when complete. */
+    async generate() {
+        await writeScenarioContextType(this.destination);
+        await writeDefaultScenariosIndex(this.destination);
+    }
+    /**
+     * Starts watching the `routes/` directory for `_.context.ts` changes and
+     * regenerates `types/_.context.ts` on every change.
+     *
+     * Resolves once the watcher is ready.
+     */
+    async watch() {
+        const routesDir = nodePath.join(this.destination, "routes");
+        this.watcher = watch(routesDir, CHOKIDAR_OPTIONS).on("all", (_event, filePath) => {
+            if (filePath.endsWith("_.context.ts")) {
+                void writeScenarioContextType(this.destination);
+            }
+        });
+        await waitForEvent(this.watcher, "ready");
+    }
+    /** Closes the file-system watcher. */
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+}