counterfact 2.5.1 → 2.6.0

package/README.md

@@ -205,6 +205,7 @@ npx counterfact@latest [openapi.yaml] [destination] [options]
 | `--spec <path>`     | Path or URL to the OpenAPI document         |
 | `--proxy-url <url>` | Forward all requests to this URL by default |
 | `--prefix <path>`   | Base path prefix (e.g. `/api/v1`)           |
+| `--no-validate-request` | Disable request validation against the OpenAPI spec |
 
 Run `npx counterfact@latest --help` for the full list of options.
 

package/bin/README.md

@@ -41,5 +41,6 @@ npx counterfact@latest openapi.yaml ./api [options]
 | `--proxy-url <url>` | Forward all unmatched requests to this upstream URL |
 | `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
 | `--no-update-check` | Disable the npm update check on startup |
+| `--no-validate-request` | Disable request validation against the OpenAPI spec |
 
 Run `npx counterfact@latest --help` to see the full option list.

package/bin/counterfact.js

@@ -1,17 +1,43 @@
 #!/usr/bin/env node
 
+/**
+ * bin/counterfact.js — CLI entry point for the `counterfact` command.
+ *
+ * Responsibilities:
+ *  1. Parse CLI arguments and build a `Config` object via Commander.
+ *  2. Run any pending migrations (paths → routes directory layout).
+ *  3. Delegate to `counterfact()` from `src/app.ts` to start the server,
+ *     code generator, transpiler, module loader, and optional REPL.
+ *  4. Print the startup banner and open the browser when requested.
+ *  5. Check for available updates against the npm registry.
+ *
+ * Architecture (high-level data flow):
+ *
+ *   CLI args  ──▶  Commander  ──▶  Config
+ *                                     │
+ *                         ┌───────────▼───────────┐
+ *                         │      counterfact()     │
+ *                         │   (src/app.ts)         │
+ *                         │                        │
+ *                         │  CodeGenerator         │  reads OpenAPI spec, emits .ts route/type files
+ *                         │  Transpiler            │  compiles .ts → .cjs and watches for changes
+ *                         │  ModuleLoader          │  loads compiled modules into Registry
+ *                         │  Dispatcher + KoaApp   │  handles HTTP requests
+ *                         │  REPL (optional)       │  interactive terminal session
+ *                         └────────────────────────┘
+ */
+
 import fs from "node:fs";
 import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import nodePath from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
 
 import { program } from "commander";
 import createDebug from "debug";
 import open from "open";
-
-import { counterfact } from "../dist/app.js";
-import { pathsToRoutes } from "../dist/migrate/paths-to-routes.js";
-import { updateRouteTypes } from "../dist/migrate/update-route-types.js";
+import { PostHog } from "posthog-node";
 
 const MIN_NODE_VERSION = 17;
 
@@ -23,28 +49,110 @@ if (Number.parseInt(process.versions.node.split("."), 10) < MIN_NODE_VERSION) {
   process.exit(1);
 }
 
+const __binDir = nodePath.dirname(fileURLToPath(import.meta.url));
+
 const packageJson = JSON.parse(
-  await readFile(
-    nodePath.join(
-      nodePath.dirname(fileURLToPath(import.meta.url)),
-      "../package.json",
-    ),
-    "utf8",
-  ),
+  await readFile(nodePath.join(__binDir, "../package.json"), "utf8"),
 );
 
 const CURRENT_VERSION = packageJson.version;
 
+// Telemetry — fire-and-forget, never blocks startup
+const POSTHOG_API_KEY = "phc_msXmBxiL8FVugNMLCx9bnPQGqfEMqmyBjnVkKhHkN3m7";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+
+const telemetryKey = process.env.POSTHOG_API_KEY ?? POSTHOG_API_KEY;
+const telemetryHost = process.env.POSTHOG_HOST ?? POSTHOG_HOST;
+
+const isCI = Boolean(process.env.CI);
+const isBeforeRollout = new Date() < new Date("2026-05-01");
+const telemetryDisabledEnv = process.env.COUNTERFACT_TELEMETRY_DISABLED;
+
+const isTelemetryDisabled =
+  isCI ||
+  telemetryDisabledEnv === "true" ||
+  (isBeforeRollout && telemetryDisabledEnv !== "false");
+
+if (!isTelemetryDisabled) {
+  try {
+    const posthog = new PostHog(telemetryKey, { host: telemetryHost });
+
+    posthog.capture({
+      distinctId: randomUUID(),
+      event: "counterfact_started",
+      properties: {
+        version: CURRENT_VERSION,
+        nodeVersion: process.version,
+        platform: process.platform,
+        arch: process.arch,
+        source: "counterfact-cli",
+      },
+    });
+
+    posthog.shutdownAsync().catch(() => {
+      // ignore errors — telemetry is best-effort
+    });
+  } catch {
+    // ignore errors — telemetry must never surface to the user
+  }
+}
+
 const taglinesFile = await readFile(
-  nodePath.join(
-    nodePath.dirname(fileURLToPath(import.meta.url)),
-    "taglines.txt",
-  ),
+  nodePath.join(__binDir, "taglines.txt"),
   "utf8",
 );
 
 const taglines = taglinesFile.split("\n").slice(0, -1);
 
+// Probe whether the current runtime can natively execute TypeScript with
+// erasable type annotations AND resolve .js imports to .ts files (tsx-style).
+async function runtimeCanExecuteErasableTs() {
+  const dir = fs.mkdtempSync(nodePath.join(tmpdir(), "ts-probe-"));
+  // helper.ts is imported via .js extension — the TypeScript convention used
+  // throughout this codebase. If the runtime resolves helper.js → helper.ts,
+  // it is fully capable of running the TypeScript source tree.
+  fs.writeFileSync(
+    nodePath.join(dir, "helper.ts"),
+    'export const value: string = "ok";\n',
+    "utf8",
+  );
+  fs.writeFileSync(
+    nodePath.join(dir, "main.ts"),
+    'import { value } from "./helper.js"; export default value;\n',
+    "utf8",
+  );
+  try {
+    const mod = await import(pathToFileURL(nodePath.join(dir, "main.ts")).href);
+    return mod?.default === "ok";
+  } catch {
+    return false;
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const nativeTs = await runtimeCanExecuteErasableTs();
+
+const resolve = (rel) => pathToFileURL(nodePath.join(__binDir, rel)).href;
+
+const { counterfact } = await import(
+  resolve(nativeTs ? "../src/app.ts" : "../dist/app.js")
+);
+const { pathsToRoutes } = await import(
+  resolve(
+    nativeTs
+      ? "../src/migrate/paths-to-routes.js"
+      : "../dist/migrate/paths-to-routes.js",
+  )
+);
+const { updateRouteTypes } = await import(
+  resolve(
+    nativeTs
+      ? "../src/migrate/update-route-types.js"
+      : "../dist/migrate/update-route-types.js",
+  )
+);
+
 const DEFAULT_PORT = 3100;
 
 const debug = createDebug("counterfact:bin:counterfact");
@@ -234,6 +342,7 @@ async function main(source, destination) {
     startRepl: options.repl,
     startServer: options.serve,
     buildCache: options.buildCache || false,
+    validateRequests: options.validateRequest !== false,
 
     watch: {
       routes: options.watch || options.watchRoutes,
@@ -248,6 +357,14 @@ async function main(source, destination) {
 
   debug("loading counterfact (%o)", configForLogging);
 
+  if (config.startAdminApi && !config.adminApiToken) {
+    process.stderr.write(
+      "⚠️  WARNING: The admin API is enabled without an authentication token.\n" +
+        "   Any process on this machine can read and modify server state via /_counterfact/api/*.\n" +
+        "   Set --admin-api-token or COUNTERFACT_ADMIN_API_TOKEN to restrict access.\n\n",
+    );
+  }
+
   let didMigrate = false;
   let didMigrateRouteTypes;
 
@@ -266,7 +383,16 @@ async function main(source, destination) {
     didMigrate = true;
   }
 
-  const { start, startRepl } = await counterfact(config);
+  let start;
+  let startRepl;
+  try {
+    ({ start, startRepl } = await counterfact(config));
+  } catch (error) {
+    process.stderr.write(
+      `\n❌ ${error instanceof Error ? error.message : String(error)}\n\n`,
+    );
+    process.exit(1);
+  }
 
   debug("loaded counterfact", configForLogging);
 
@@ -280,6 +406,14 @@ async function main(source, destination) {
 
   const watchMessage = createWatchMessage(config);
 
+  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 introduction = [
     "   ____ ____ _  _ _ _ ___ ____ ____ ____ ____ ____ ___",
     String.raw`   |___ [__] |__| |\|  |  |=== |--< |--- |--| |___  | `,
@@ -292,11 +426,7 @@ async function main(source, destination) {
     "   Instructions  https://counterfact.dev/docs/usage.html",
     "   Help/feedback https://github.com/pmcelhaney/counterfact/issues",
     "",
-    "",
-    "🔔 PLEASE READ: Feedback, Telemetry, and Privacy Discussion (10 March 2026)",
-    "   https://counterfact.dev/telemetry-discussion",
-    "",
-    "",
+    ...telemetryWarning,
     watchMessage,
     config.startServer ? "   Starting server" : undefined,
     config.startRepl
@@ -311,7 +441,14 @@ async function main(source, destination) {
   process.stdout.write("\n\n");
 
   debug("starting server");
-  await start(config);
+  try {
+    await start(config);
+  } catch (error) {
+    process.stderr.write(
+      `\n❌ ${error instanceof Error ? error.message : String(error)}\n\n`,
+    );
+    process.exit(1);
+  }
   debug("started server");
 
   await updateCheckPromise;
@@ -409,5 +546,9 @@ program
     "path or URL to OpenAPI document (alternative to the positional [openapi.yaml] argument)",
   )
   .option("--no-update-check", "disable the npm update check on startup")
+  .option(
+    "--no-validate-request",
+    "disable request validation against the OpenAPI spec",
+  )
   .action(main)
   .parse(process.argv);

package/bin/register-ts-loader.mjs

@@ -0,0 +1,17 @@
+/**
+ * Register the ts-loader hook using Node's modern module.register() API.
+ *
+ * Usage (replaces deprecated --loader flag):
+ *   node --experimental-strip-types --import ./bin/register-ts-loader.mjs bin/counterfact.js ...
+ */
+
+// module.register() was added in Node 20.6 / 22; this file is only used when
+// running counterfact under a TypeScript-capable Node runtime (22.6+).
+// eslint-disable-next-line n/no-unsupported-features/node-builtins
+import { register } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+register("./ts-loader.mjs", pathToFileURL(join(__dirname, "/")));

package/bin/ts-loader.mjs

@@ -0,0 +1,31 @@
+/**
+ * Node.js custom loader that remaps .js import specifiers to .ts when a
+ * corresponding .ts file exists alongside the importer.
+ *
+ * Usage:
+ *   node --experimental-strip-types --loader ./bin/ts-loader.mjs bin/counterfact.js ...
+ *
+ * Why: Node's built-in --experimental-strip-types handles type annotation
+ * removal, but it does not remap .js → .ts import specifiers. This codebase
+ * uses the TypeScript convention of writing .js extensions in import paths
+ * (which resolve to .ts files at authoring time). This loader bridges that gap.
+ */
+
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function resolve(specifier, context, nextResolve) {
+  if (specifier.endsWith(".js") && context.parentURL) {
+    const tsSpecifier = specifier.slice(0, -3) + ".ts";
+    try {
+      const resolved = new URL(tsSpecifier, context.parentURL);
+      if (existsSync(fileURLToPath(resolved))) {
+        return nextResolve(tsSpecifier, context);
+      }
+    } catch {
+      // If URL construction fails, fall through to default resolution
+    }
+  }
+
+  return nextResolve(specifier, context);
+}

package/dist/app.js

@@ -1,6 +1,7 @@
 import fs, { rm } from "node:fs/promises";
 import nodePath from "node:path";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
+import createDebug from "debug";
 import { createHttpTerminator } from "http-terminator";
 import { startRepl as startReplServer } from "./repl/repl.js";
 import { ContextRegistry } from "./server/context-registry.js";
@@ -11,6 +12,8 @@ import { ModuleLoader } from "./server/module-loader.js";
 import { Registry } from "./server/registry.js";
 import { Transpiler } from "./server/transpiler.js";
 import { CodeGenerator } from "./typescript-generator/code-generator.js";
+import { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
+const debug = createDebug("counterfact:app");
 const allowedMethods = [
     "all",
     "head",
@@ -25,8 +28,10 @@ export async function loadOpenApiDocument(source) {
     try {
         return (await dereference(source));
     }
-    catch {
-        return undefined;
+    catch (error) {
+        debug("could not load OpenAPI document from %s: %o", source, error);
+        const details = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not load the OpenAPI spec from "${source}".\n${details}`, { cause: error });
     }
 }
 const mswHandlers = {};
@@ -44,9 +49,6 @@ export async function createMswHandlers(config, ModuleLoaderClass = ModuleLoader
     // 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);
-    if (openApiDocument === undefined) {
-        throw new Error(`Could not load OpenAPI document from ${config.openApiPath}`);
-    }
     const modulesPath = config.basePath;
     const compiledPathsDirectory = nodePath
         .join(modulesPath, ".cache")
@@ -75,29 +77,37 @@ export async function createMswHandlers(config, ModuleLoaderClass = ModuleLoader
 }
 export async function counterfact(config) {
     const modulesPath = config.basePath;
+    const nativeTs = await runtimeCanExecuteErasableTs();
     const compiledPathsDirectory = nodePath
-        .join(modulesPath, ".cache")
+        .join(modulesPath, nativeTs ? "routes" : ".cache")
         .replaceAll("\\", "/");
-    await rm(compiledPathsDirectory, { force: true, recursive: true });
+    if (!nativeTs) {
+        await rm(compiledPathsDirectory, { force: true, recursive: true });
+    }
     const registry = new Registry();
     const contextRegistry = new ContextRegistry();
     const codeGenerator = new CodeGenerator(config.openApiPath, config.basePath, config.generate);
-    const dispatcher = new Dispatcher(registry, contextRegistry, await loadOpenApiDocument(config.openApiPath), config);
+    const openApiDocument = config.openApiPath === "_"
+        ? undefined
+        : await loadOpenApiDocument(config.openApiPath);
+    const dispatcher = new Dispatcher(registry, contextRegistry, openApiDocument, config);
     const transpiler = new Transpiler(nodePath.join(modulesPath, "routes").replaceAll("\\", "/"), compiledPathsDirectory, "commonjs");
     const moduleLoader = new ModuleLoader(compiledPathsDirectory, registry, contextRegistry);
     const middleware = koaMiddleware(dispatcher, config);
     const koaApp = createKoaApp(registry, middleware, config, contextRegistry);
     async function start(options) {
         const { generate, startServer, watch, buildCache } = options;
-        if (generate.routes || generate.types) {
+        if (config.openApiPath !== "_" && (generate.routes || generate.types)) {
             await codeGenerator.generate();
         }
-        if (watch.routes || watch.types) {
+        if (config.openApiPath !== "_" && (watch.routes || watch.types)) {
             await codeGenerator.watch();
         }
         let httpTerminator;
         if (startServer) {
-            await transpiler.watch();
+            if (!nativeTs) {
+                await transpiler.watch();
+            }
             await moduleLoader.load();
             await moduleLoader.watch();
             const server = koaApp.listen({
@@ -127,6 +137,7 @@ export async function counterfact(config) {
         koaMiddleware: middleware,
         registry,
         start,
-        startRepl: () => startReplServer(contextRegistry, registry, config),
+        startRepl: () => startReplServer(contextRegistry, registry, config, undefined, // use the default print function (stdout)
+        openApiDocument),
     };
 }

package/dist/migrate/update-route-types.js

@@ -13,6 +13,23 @@ const HTTP_METHODS = [
     "HEAD",
     "OPTIONS",
 ];
+// Pre-compile regex patterns derived from HTTP_METHODS
+const HTTP_METHOD_ALTERNATION = HTTP_METHODS.join("|");
+// eslint-disable-next-line security/detect-non-literal-regexp
+const NEEDS_MIGRATION_REGEX = new RegExp(`import\\s+type\\s+\\{[^}]*HTTP_(?:${HTTP_METHOD_ALTERNATION})[^}]*\\}`, "iu");
+// eslint-disable-next-line security/detect-non-literal-regexp
+const HTTP_TYPE_NAME_REGEX = new RegExp(`^HTTP_(?<method>${HTTP_METHOD_ALTERNATION})$`, "u");
+// Pre-build import/export replacement patterns for each HTTP method type name
+const IMPORT_REPLACE_PATTERNS = new Map(HTTP_METHODS.map((method) => [
+    `HTTP_${method}`,
+    // eslint-disable-next-line security/detect-non-literal-regexp
+    new RegExp(`(import\\s+type\\s+\\{[^}]*\\b)HTTP_${method}(\\b[^}]*\\}\\s+from)`, "g"),
+]));
+const EXPORT_REPLACE_PATTERNS = new Map(HTTP_METHODS.map((method) => [
+    `HTTP_${method}`,
+    // eslint-disable-next-line security/detect-non-literal-regexp
+    new RegExp(`(export\\s+const\\s+${method}\\s*:\\s*)HTTP_${method}(\\b)`, "g"),
+]));
 /**
  * Converts an OpenAPI path to a file system path
  * e.g., "/hello/{name}" -> "hello/{name}"
@@ -71,9 +88,7 @@ async function buildTypeNameMapping(specification) {
  * @param content - The file content
  */
 function needsMigration(content) {
-    const methodAlternation = HTTP_METHODS.map((method) => method.toUpperCase()).join("|");
-    const pattern = new RegExp(`import\\s+type\\s+\\{[^}]*HTTP_(?:${methodAlternation})[^}]*\\}`, "iu");
-    return pattern.test(content);
+    return NEEDS_MIGRATION_REGEX.test(content);
 }
 /**
  * Updates a single route file with the correct type names
@@ -102,7 +117,7 @@ async function updateRouteFile(filePath, methodToTypeName) {
             .filter((t) => t.length > 0);
         for (const importedType of importedTypes) {
             // Check if this is an HTTP_ type
-            const httpMethodMatch = importedType.match(new RegExp(`^HTTP_(?<method>${HTTP_METHODS.join("|")})$`, "u"));
+            const httpMethodMatch = importedType.match(HTTP_TYPE_NAME_REGEX);
             if (httpMethodMatch) {
                 const method = httpMethodMatch.groups?.["method"] ?? "";
                 const newTypeName = methodToTypeName.get(method);
@@ -120,15 +135,20 @@ async function updateRouteFile(filePath, methodToTypeName) {
     // Apply replacements
     for (const [oldName, newName] of replacements.entries()) {
         // Replace in import statement
-        const importPattern = new RegExp(`(import\\s+type\\s+\\{[^}]*\\b)${oldName}(\\b[^}]*\\}\\s+from)`, "g");
-        content = content.replace(importPattern, `$1${newName}$2`);
+        const importPattern = IMPORT_REPLACE_PATTERNS.get(oldName);
+        if (importPattern) {
+            importPattern.lastIndex = 0;
+            content = content.replace(importPattern, `$1${newName}$2`);
+        }
         // Replace in export statement (e.g., "export const GET: HTTP_GET")
         // Match the method from the old type name
-        const methodMatch = oldName.match(new RegExp(`^HTTP_(?<method>${HTTP_METHODS.join("|")})$`, "u"));
+        const methodMatch = oldName.match(HTTP_TYPE_NAME_REGEX);
         if (methodMatch) {
-            const method = methodMatch.groups?.["method"] ?? "";
-            const exportPattern = new RegExp(`(export\\s+const\\s+${method}\\s*:\\s*)${oldName}(\\b)`, "g");
-            content = content.replace(exportPattern, `$1${newName}$2`);
+            const exportPattern = EXPORT_REPLACE_PATTERNS.get(oldName);
+            if (exportPattern) {
+                exportPattern.lastIndex = 0;
+                content = content.replace(exportPattern, `$1${newName}$2`);
+            }
         }
         modified = true;
     }

package/dist/repl/raw-http-client.js

@@ -11,8 +11,8 @@ const colors = {
     blue: "\x1b[34m",
 };
 function isLikelyJson(headersBlock, body) {
-    const m = headersBlock.match(/^content-type:\s*([^\r\n;]+)/im);
-    const ct = (m?.[1] ?? "").toLowerCase();
+    const m = headersBlock.match(/^content-type:\s*(?<contentType>[^\r\n;]+)/im);
+    const ct = (m?.groups?.["contentType"] ?? "").toLowerCase();
     if (ct.includes("application/json") || ct.includes("+json"))
         return true;
     const s = body.trim();
@@ -30,7 +30,7 @@ function highlightJson(text) {
         return text;
     }
     const pretty = JSON.stringify(obj, null, 2);
-    return pretty.replace(/("(?:\\.|[^"\\])*")(\s*:)?|\b(true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g, (match, str, colon, boolOrNull) => {
+    return pretty.replace(/(?<str>"(?:\\.|[^"\\])*")(?<colon>\s*:)?|\b(?<boolOrNull>true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g, (match, str, colon, boolOrNull) => {
         if (str) {
             if (colon)
                 return `${colors.blue}${str}${colors.reset}${colon}`;
@@ -60,31 +60,31 @@ export class RawHttpClient {
         this.port = port;
     }
     get(path, headers = {}) {
-        this.#send("GET", path, "", headers);
+        return this.#send("GET", path, "", headers);
     }
     head(path, headers = {}) {
-        this.#send("HEAD", path, "", headers);
+        return this.#send("HEAD", path, "", headers);
     }
     post(path, body = "", headers = {}) {
-        this.#send("POST", path, body, headers);
+        return this.#send("POST", path, body, headers);
     }
     put(path, body = "", headers = {}) {
-        this.#send("PUT", path, body, headers);
+        return this.#send("PUT", path, body, headers);
     }
     delete(path, headers = {}) {
-        this.#send("DELETE", path, "", headers);
+        return this.#send("DELETE", path, "", headers);
     }
     connect(path, headers = {}) {
-        this.#send("CONNECT", path, "", headers);
+        return this.#send("CONNECT", path, "", headers);
     }
     options(path, headers = {}) {
-        this.#send("OPTIONS", path, "", headers);
+        return this.#send("OPTIONS", path, "", headers);
     }
     trace(path, headers = {}) {
-        this.#send("TRACE", path, "", headers);
+        return this.#send("TRACE", path, "", headers);
     }
     patch(path, body = "", headers = {}) {
-        this.#send("PATCH", path, body, headers);
+        return this.#send("PATCH", path, body, headers);
     }
     #send(method, path, bodyAsStringOrObject, headers) {
         const requestNumber = ++this.requestNumber;
@@ -146,9 +146,9 @@ export class RawHttpClient {
         const lines = head.split("\r\n");
         const statusLine = lines[0] ?? "";
         let statusColor = colors.green;
-        const match = statusLine.match(/HTTP\/\d+\.\d+\s+(\d+)/);
+        const match = statusLine.match(/HTTP\/\d+\.\d+\s+(?<statusCode>\d+)/);
         if (match) {
-            const code = Number(match[1]);
+            const code = Number(match.groups?.["statusCode"]);
             if (code >= 400)
                 statusColor = colors.red;
             else if (code >= 300)

package/dist/repl/repl.js

@@ -1,11 +1,31 @@
 import repl from "node:repl";
 import { RawHttpClient } from "./raw-http-client.js";
+import { createRouteFunction } from "./route-builder.js";
 function printToStdout(line) {
     process.stdout.write(`${line}\n`);
 }
+const ROUTE_BUILDER_METHODS = [
+    "body(",
+    "headers(",
+    "help(",
+    "method(",
+    "missing(",
+    "path(",
+    "query(",
+    "ready(",
+    "send(",
+];
 export function createCompleter(registry, fallback) {
     return (line, callback) => {
-        const match = line.match(/client\.(?:get|post|put|patch|delete)\("(?<partial>[^"]*)$/u);
+        // 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]);
+            return;
+        }
+        const match = line.match(/(?:client\.(?:get|post|put|patch|delete)|route)\("(?<partial>[^"]*)$/u);
         if (!match) {
             if (fallback) {
                 fallback(line, callback);
@@ -21,7 +41,7 @@ export function createCompleter(registry, fallback) {
         callback(null, [matches, partial]);
     };
 }
-export function startRepl(contextRegistry, registry, config, print = printToStdout) {
+export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -73,6 +93,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             print("");
             print("- loadContext('/some/path'): to access the context object for a given path");
             print("- context: the root context ( same as loadContext('/') )");
+            print("- route('/some/path'): create a request builder for the given path");
             print("");
             print("For more information, see https://counterfact.dev/docs/usage.html");
             print("");
@@ -107,5 +128,6 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     replServer.context.context = replServer.context.loadContext("/");
     replServer.context.client = new RawHttpClient("localhost", config.port);
     replServer.context.RawHttpClient = RawHttpClient;
+    replServer.context.route = createRouteFunction(config.port, "localhost", openApiDocument);
     return replServer;
 }