counterfact 2.0.1 → 2.2.0

package/README.md

@@ -1,69 +1,93 @@
 <div align="center" markdown="1">
 
 <img src="./counterfact.svg" alt="Counterfact" border=0>
-<br><br><br>
+
+<br>
+
+![MIT License](https://img.shields.io/badge/license-MIT-blue) [![TypeScript](./typescript-badge.png)](https://github.com/ellerbrock/typescript-badges/) [![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
+
 </div>
 
-**Spin up a mock server instantly. No config, no fuss. Try it now:**
+---
+
+**Counterfact instantly turns an [OpenAPI/Swagge](https://www.openapis.org) spec into a live, working API you can run locally.**
+
+Instead of waiting for a backend—or wiring up brittle mocks—it generates a server where every endpoint is backed by TypeScript code. Responses are valid by default, but fully customizable, and the system is stateful, interactive, and hot-reloading.
+
+It’s not just a mock server.
+
+It’s a controllable API environment you can shape in real time.
+
+> Built by Patrick McElhaney · Currently available for the right opportunity → https://patrickmcelhaney.org
 
-```sh copy
-npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json mock-api
+---
+
+## Quick Start
+
+```sh
+npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ```
 
-This command reads an OpenAPI spec (the [Swagger Petstore](https://petstore.swagger.io)), generates TypeScript code for a mock server in `mock-api`, and starts the server.
+That's it. Counterfact reads your OpenAPI spec, generates TypeScript route files in `api/`, and starts a mock server — all in one command. Point it at your own spec instead of the Petstore whenever you're ready.
+
+> **Requires Node ≥ 17.0.0**
+
+---
+
+## Features
+
+- ⚡ **Zero config** — one command to generate and start a simulated api
+- 🔒 **Type-safe by default** — route handlers are typed directly from your OpenAPI spec
+- 🔄 **Hot reload** — edit route files while the server is running; state is preserved
+- 🧠 **State management** — POST data and GET it back; share state across routes with context objects
+- 🖥 **Live REPL** — inspect and modify server state from your terminal without touching files
+- 🔀 **Hybrid proxy** — route some paths to the real API while mocking others
+- 🎲 **Smart random data** — uses OpenAPI examples and schema metadata to generate realistic responses
+- 📖 **Built-in Swagger UI** — browse and test your mock API in a browser automatically
+- 🔌 **Middleware support** — add custom middleware with `_.middleware.ts` files
+
+---
+
+## How It Works
+
+1. **Generate** — Counterfact reads your OpenAPI spec and creates a `routes/` directory with a `.ts` file for each path, plus a `types/` directory with fully typed request/response interfaces.
+2. **Customize** — Edit the route files to return exactly the data your frontend needs. The full power of TypeScript is at your disposal.
+3. **Run** — The server hot-reloads on every save. No restart, no lost state.
+
+---
 
-<details>
-<summary>Example of generated code</summary>
+## Examples
+
+### Zero effort: random responses out of the box
+
+Generated route files return random, schema-valid responses immediately — no editing required.
 
 ```ts
-// ./mock-api/routes/store/order/{orderID}.ts
+// mock-api/routes/store/order/{orderID}.ts
 import type { HTTP_GET } from "../../../types/paths/store/order/{orderId}.types.js";
-import type { HTTP_DELETE } from "../../../types/paths/store/order/{orderId}.types.js";
 
 export const GET: HTTP_GET = ($) => {
   return $.response[200].random();
 };
-
-export const DELETE: HTTP_DELETE = ($) => {
-  return $.response[200];
-};
 ```
 
-</details>
-
-Want control? Edit the generated route files (e.g. `./mock-api/routes/store/order/{orderID}.ts`) and define responses directly. A type-safe API from your spec speeds up prototyping.
+### Typed custom responses
 
-<details>
-<summary>Edit the code to define custom behavior and responses</summary>
+Replace `.random()` with `.json()` to return specific data. TypeScript (via your IDE's autocomplete) guides you to a valid response.
 
 ```ts
-// ./mock-api/routes/store/order/{orderID}.ts
-import { Order } from "../../../types/components/schemas/Order.js";
 import type { HTTP_GET } from "../../../types/paths/store/order/{orderId}.types.js";
 import type { HTTP_DELETE } from "../../../types/paths/store/order/{orderId}.types.js";
 
 export const GET: HTTP_GET = ($) => {
   const orders: Record<number, Order> = {
-    1: {
-      petId: 100,
-      status: "placed",
-    },
-    2: {
-      petId: 999,
-      status: "approved",
-    },
-    3: {
-      petId: 1234,
-      status: "delivered",
-    },
+    1: { petId: 100, status: "placed" },
+    2: { petId: 999, status: "approved" },
+    3: { petId: 1234, status: "delivered" },
   };
 
-  const order = orders[$.request.orderID];
-
-  if (order === undefined) {
-    return $.response[404];
-  }
-
+  const order = orders[$.path.orderID];
+  if (order === undefined) return $.response[404];
   return $.response[200].json(order);
 };
 
@@ -72,29 +96,123 @@ export const DELETE: HTTP_DELETE = ($) => {
 };
 ```
 
-</details>
+### State management with plain old objects
 
-You can also **proxy some paths to the real API** while mocking others — perfect when part of the backend isn’t finished or you need to simulate tricky scenarios. See [Proxying](./docs/usage.md#proxying-to-a-real-api) for details.
+Use a `_.context.ts` file to share in-memory state across routes. POST data and GET it back, just like a real API.
 
-Use `npx counterfact --help` to view CLI flags for customizing behavior (e.g. `--port`, `--proxy`, `--watch`).
+```ts
+// mock-api/routes/_.context.ts
+export class Context {
+  pets: Pet[] = [];
+
+  addPet(pet: Pet) {
+    const id = this.pets.length;
+    this.pets.push({ ...pet, id });
+    return this.pets[id];
+  }
 
-Go further with stateful mocks: POST data, then GET it back. Tweak backend data live with a REPL. Update code without restarting the server or losing state.
+  getPetById(id: number) {
+    return this.pets[id];
+  }
+}
+```
 
-We believe strongly in API-first development and the Dependency Inversion Principle. When frontend and backend implement the same API spec, they can be built and tested independently. Most of the time, it’s best to test the front end against the real API and full stack. But there's always some part of the backend that isn't finished yet, or a scenario that's cumbersome to reproduce. For this reason, Counterfact supports proxying to the real API for some paths and using mocks for others.
+```ts
+// mock-api/routes/pet.ts
+export const POST: HTTP_POST = ($) => {
+  return $.response[200].json($.context.addPet($.body));
+};
 
-Counterfact was by built an engineer who spent decades writing frontend code and got tired of being slowed down by unfinished or unwieldy backend APIs. This is the fastest way to get unblocked, prototype ideas, and remember what it feels like to enjoy creating stuff.
+// mock-api/routes/pet/{petId}.ts
+export const GET: HTTP_GET = ($) => {
+  const pet = $.context.getPetById($.path.petId);
+  if (!pet) return $.response[404].text(`Pet ${$.path.petId} not found.`);
+  return $.response[200].json(pet);
+};
+```
 
-> Requires Node ≥ 17.0.0
+You can also interact with the context object using a REPL. It's like DevTools on the server side. (See "Live REPL" below.)
 
-<div align="center" markdown="1">
+---
 
-[Documentation](./docs/usage.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
+## Key Capabilities
 
-</div>
+### 🔄 Hot Reload
 
-<br>
-<div align="center"  markdown="1">
+Save a route file and the server picks it up instantly — no restart, no lost state. Your in-memory context survives every reload.
 
-![MIT License](https://img.shields.io/badge/license-MIT-blue) [![TypeScript](./typescript-badge.png)](https://github.com/ellerbrock/typescript-badges/) [![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
+### 🖥 Live REPL
+
+The REPL gives you a JavaScript prompt connected directly to your running server. Inspect state, trigger edge cases, or adjust proxy settings without touching a file.
+
+```
+⬣> context.pets.length
+3
+⬣> context.addPet({ name: "Fluffy", photoUrls: [] })
+⬣> client.get("/pet/3")
+⬣> .proxy on /payments    # forward /payments to the real API
+⬣> .proxy off             # stop all proxying
+```
+
+### 🔀 Hybrid Proxy
+
+Mock the paths that aren't ready yet while forwarding everything else to the real backend. See [Proxying](./docs/usage.md#proxy-peek-a-boo-) for details.
+
+```sh
+npx counterfact@latest openapi.yaml mock-api --proxy-url https://api.example.com
+```
+
+### 🔒 Type Safety
+
+Every route handler is typed to match your OpenAPI spec. When the spec changes, regenerating the types surfaces any mismatches at compile time — before they become bugs.
+
+```ts
+export const GET: HTTP_GET = ($) => {
+  return $.response[200]
+    .header("x-request-id", $.headers["x-request-id"])
+    .json({
+      id: $.path.userId,
+    });
+};
+```
+
+---
+
+## CLI Reference
+
+```sh
+npx counterfact@latest [openapi.yaml] [destination] [options]
+```
+
+| Option              | Description                                 |
+| ------------------- | ------------------------------------------- |
+| `--port <number>`   | Server port (default: `3100`)               |
+| `-o, --open`        | Open browser automatically                  |
+| `-g, --generate`    | Generate route and type files               |
+| `-w, --watch`       | Generate and watch for spec changes         |
+| `-s, --serve`       | Start the mock server                       |
+| `-r, --repl`        | Start the interactive REPL                  |
+| `--proxy-url <url>` | Forward all requests to this URL by default |
+| `--prefix <path>`   | Base path prefix (e.g. `/api/v1`)           |
+
+Run `npx counterfact --help` for the full list of options.
+
+---
+
+## About the Author
+
+Counterfact came out of a pattern I kept seeing: teams are slowed down more by coordination than by code.
+
+I’ve spent 25+ years building software and improving how engineering organizations operate across large enterprises, regulated industries, and complex systems. Most of that time, the real constraint wasn’t technology—it was dependency and coordination.
+
+Counterfact is one way of removing that friction.
+
+I’m currently available — not for long.
+
+→ https://patrickmcelhaney.org
+
+<div align="center" markdown="1">
+
+[Documentation](./docs/usage.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
 
 </div>

package/bin/counterfact.js

@@ -51,17 +51,17 @@ function createWatchMessage(config) {
 
   switch (true) {
     case config.watch.routes && config.watch.types: {
-      watchMessage = "Watching for changes";
+      watchMessage = "   Watching for changes";
 
       break;
     }
     case config.watch.routes: {
-      watchMessage = "Watching routes for changes";
+      watchMessage = "   Watching routes for changes";
 
       break;
     }
     case config.watch.types: {
-      watchMessage = "Watching types for changes";
+      watchMessage = "   Watching types for changes";
 
       break;
     }
@@ -136,6 +136,8 @@ async function main(source, destination) {
   const swaggerUrl = `${url}/counterfact/swagger/`;
 
   const config = {
+    adminApiToken:
+      options.adminApiToken ?? process.env.COUNTERFACT_ADMIN_API_TOKEN ?? "",
     alwaysFakeOptionals: options.alwaysFakeOptionals,
     basePath,
 
@@ -160,6 +162,7 @@ async function main(source, destination) {
     proxyPaths: new Map([["", Boolean(options.proxyUrl)]]),
     proxyUrl: options.proxyUrl ?? "",
     routePrefix: options.prefix,
+    startAdminApi: options.adminApi,
     startRepl: options.repl,
     startServer: options.serve,
     buildCache: options.buildCache || false,
@@ -170,7 +173,12 @@ async function main(source, destination) {
     },
   };
 
-  debug("loading counterfact (%o)", config);
+  const configForLogging = {
+    ...config,
+    adminApiToken: config.adminApiToken ? "[REDACTED]" : "",
+  };
+
+  debug("loading counterfact (%o)", configForLogging);
 
   let didMigrate = false;
   let didMigrateRouteTypes = false;
@@ -193,7 +201,7 @@ async function main(source, destination) {
 
   const { start } = await counterfact(config);
 
-  debug("loaded counterfact", config);
+  debug("loaded counterfact", configForLogging);
 
   // Migrate route type imports if needed
   debug("checking if route type migration is needed");
@@ -206,19 +214,26 @@ async function main(source, destination) {
   const watchMessage = createWatchMessage(config);
 
   const introduction = [
-    "____ ____ _  _ _ _ ___ ____ ____ ____ ____ ____ ___",
-    String.raw`|___ [__] |__| |\|  |  |=== |--< |--- |--| |___  | `,
-    padTagLine(taglines[Math.floor(Math.random() * taglines.length)]),
+    "   ____ ____ _  _ _ _ ___ ____ ____ ____ ____ ____ ___",
+    String.raw`   |___ [__] |__| |\|  |  |=== |--< |--- |--| |___  | `,
+    "   " + padTagLine(taglines[Math.floor(Math.random() * taglines.length)]),
+    "",
+    `   API Base URL  ${url}`,
+    source === "_" ? undefined : `   Swagger UI    ${swaggerUrl}`,
+    "",
+    "   Instructions  https://counterfact.dev/docs/usage.html",
+    "   Help/feedback https://github.com/pmcelhaney/counterfact/issues",
     "",
-    `| API Base URL  ==> ${url}`,
-    source === "_" ? undefined : `| Swagger UI    ==> ${swaggerUrl}`,
     "",
-    "| 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",
+    "",
     "",
     watchMessage,
-    config.startServer ? "Starting server" : undefined,
-    config.startRepl ? "Starting REPL, type .help for more info" : undefined,
+    config.startServer ? "   Starting server" : undefined,
+    config.startRepl
+      ? "   Starting REPL (type .help for more info)"
+      : undefined,
   ];
 
   process.stdout.write(
@@ -295,8 +310,13 @@ program
   .option("--watch-routes", "generate + watch routes for changes")
   .option("-s, --serve", "start the server")
   .option("-b, --build-cache", "builds the cache of compiled routes and types")
+  .option("--no-admin-api", "disable the admin API at /_counterfact/api/*")
   .option("-r, --repl", "start the REPL")
   .option("--proxy-url <string>", "proxy URL")
+  .option(
+    "--admin-api-token <string>",
+    "bearer token required for /_counterfact/api/* endpoints (defaults to COUNTERFACT_ADMIN_API_TOKEN)",
+  )
   .option(
     "--prefix <string>",
     "base path from which routes will be served (e.g. /api/v1)",

package/bin/taglines.txt

@@ -45,3 +45,5 @@ the cloud natives are restless
 your front-end dev flight simulator
 your front-end’s sparring partner
 your back-end's stunt double
+deterministic vibe coding
+404 tagline not found

package/dist/app.js

@@ -90,7 +90,7 @@ export async function counterfact(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);
+    const koaApp = createKoaApp(registry, middleware, config, contextRegistry);
     async function start(options) {
         const { generate, startRepl: shouldStartRepl, startServer, watch, buildCache, } = options;
         if (generate.routes || generate.types) {

package/dist/server/admin-api-middleware.js

@@ -0,0 +1,259 @@
+import createDebug from "debug";
+const debug = createDebug("counterfact:server:admin-api-middleware");
+function extractBearerToken(authorization) {
+    if (!authorization)
+        return undefined;
+    const [scheme, token] = authorization.trim().split(/\s+/, 2);
+    if (!scheme || !token || scheme.toLowerCase() !== "bearer")
+        return undefined;
+    return token;
+}
+function normalizeIp(ip) {
+    if (!ip)
+        return "";
+    if (ip.startsWith("::ffff:"))
+        return ip.slice("::ffff:".length);
+    return ip;
+}
+function isLoopbackIp(ip) {
+    const normalized = normalizeIp(ip);
+    return (normalized === "127.0.0.1" ||
+        normalized === "::1" ||
+        normalized === "0:0:0:0:0:0:0:1");
+}
+/**
+ * Admin API middleware for programmatic access to Counterfact internals.
+ * Exposes context management, proxy configuration, and route discovery
+ * through HTTP endpoints at /_counterfact/api/*
+ *
+ * This enables AI agents and external tools to interact with the mock server
+ * in the same way the REPL does, but via HTTP requests.
+ */
+export function adminApiMiddleware(registry, contextRegistry, config) {
+    return async (ctx, next) => {
+        const { pathname } = ctx.URL;
+        // Only handle admin API routes
+        if (!pathname.startsWith("/_counterfact/api/")) {
+            return await next();
+        }
+        // ===== Admin API Access Guard =====
+        // If an admin API token is configured, require Authorization: Bearer <token>.
+        // If not set, only allow loopback access.
+        const configuredToken = (config.adminApiToken ??
+            process.env.COUNTERFACT_ADMIN_API_TOKEN ??
+            "").trim();
+        const authHeader = typeof ctx.get === "function"
+            ? ctx.get("authorization")
+            : ctx.request.headers.authorization;
+        const providedToken = extractBearerToken(authHeader);
+        if (configuredToken) {
+            if (!providedToken || providedToken !== configuredToken) {
+                debug("Admin API unauthorized request: missing/invalid bearer token");
+                ctx.status = 401;
+                ctx.body = {
+                    success: false,
+                    error: "Unauthorized",
+                    message: "Admin API requires a valid bearer token.",
+                };
+                return;
+            }
+        }
+        else {
+            const requestIp = normalizeIp(ctx.ip || ctx.request.ip || ctx.req.socket.remoteAddress);
+            if (!isLoopbackIp(requestIp)) {
+                debug("Admin API forbidden request from non-loopback IP: %s", requestIp);
+                ctx.status = 403;
+                ctx.body = {
+                    success: false,
+                    error: "Forbidden",
+                    message: "Admin API is restricted to localhost unless an admin token is configured.",
+                };
+                return;
+            }
+        }
+        debug("Admin API request: %s %s", ctx.method, pathname);
+        // Extract route components: ["_counterfact", "api", "resource", ...rest]
+        const parts = pathname.split("/").filter(Boolean);
+        const [, , resource, ...rest] = parts;
+        try {
+            // ===== Health Check =====
+            if (resource === "health" && ctx.method === "GET") {
+                ctx.body = {
+                    status: "ok",
+                    port: config.port,
+                    uptime: process.uptime(),
+                    basePath: config.basePath,
+                    routePrefix: config.routePrefix,
+                };
+                return;
+            }
+            // ===== List All Contexts =====
+            if (resource === "contexts" &&
+                rest.length === 0 &&
+                ctx.method === "GET") {
+                const paths = contextRegistry.getAllPaths();
+                const contexts = contextRegistry.getAllContexts();
+                ctx.body = {
+                    success: true,
+                    data: {
+                        paths,
+                        contexts,
+                    },
+                };
+                return;
+            }
+            // ===== Get Specific Context =====
+            if (resource === "contexts" && rest.length > 0 && ctx.method === "GET") {
+                const path = "/" + rest.join("/");
+                const context = contextRegistry.find(path);
+                ctx.body = {
+                    success: true,
+                    data: {
+                        path,
+                        context,
+                    },
+                };
+                return;
+            }
+            // ===== Update Context =====
+            if (resource === "contexts" && rest.length > 0 && ctx.method === "POST") {
+                const path = "/" + rest.join("/");
+                const newContext = ctx.request.body;
+                if (!newContext ||
+                    typeof newContext !== "object" ||
+                    Array.isArray(newContext)) {
+                    ctx.status = 400;
+                    ctx.body = {
+                        success: false,
+                        error: "Request body must be a valid, non-array JSON object",
+                    };
+                    return;
+                }
+                // Update the context using the registry's smart diffing
+                contextRegistry.update(path, newContext);
+                ctx.body = {
+                    success: true,
+                    message: `Context updated for path: ${path}`,
+                    data: {
+                        path,
+                        context: contextRegistry.find(path),
+                    },
+                };
+                return;
+            }
+            // ===== Get Full Config =====
+            if (resource === "config" && rest.length === 0 && ctx.method === "GET") {
+                ctx.body = {
+                    success: true,
+                    data: {
+                        alwaysFakeOptionals: config.alwaysFakeOptionals,
+                        adminApiTokenConfigured: Boolean(configuredToken),
+                        basePath: config.basePath,
+                        buildCache: config.buildCache,
+                        generate: config.generate,
+                        openApiPath: config.openApiPath,
+                        port: config.port,
+                        proxyUrl: config.proxyUrl,
+                        routePrefix: config.routePrefix,
+                        startAdminApi: config.startAdminApi,
+                        startRepl: config.startRepl,
+                        startServer: config.startServer,
+                        watch: config.watch,
+                        // Don't expose proxyPaths Map directly, convert to array
+                        proxyPaths: Array.from(config.proxyPaths.entries()),
+                    },
+                };
+                return;
+            }
+            // ===== Get Proxy Configuration =====
+            if (resource === "config" &&
+                rest[0] === "proxy" &&
+                ctx.method === "GET") {
+                ctx.body = {
+                    success: true,
+                    data: {
+                        proxyUrl: config.proxyUrl,
+                        proxyPaths: Array.from(config.proxyPaths.entries()),
+                    },
+                };
+                return;
+            }
+            // ===== Update Proxy Configuration =====
+            if (resource === "config" &&
+                rest[0] === "proxy" &&
+                ctx.method === "PATCH") {
+                const body = ctx.request.body;
+                if (!body || typeof body !== "object") {
+                    ctx.status = 400;
+                    ctx.body = {
+                        success: false,
+                        error: "Request body must be a valid JSON object",
+                    };
+                    return;
+                }
+                // Update proxy URL if provided
+                if (body.proxyUrl !== undefined) {
+                    if (typeof body.proxyUrl !== "string") {
+                        ctx.status = 400;
+                        ctx.body = {
+                            success: false,
+                            error: "proxyUrl must be a string",
+                        };
+                        return;
+                    }
+                    const proxyUrl = body.proxyUrl.trim();
+                    config.proxyUrl = proxyUrl;
+                    debug("Updated proxy URL to: %s", config.proxyUrl);
+                }
+                // Update proxy paths if provided
+                if (Array.isArray(body.proxyPaths)) {
+                    for (const [path, enabled] of body.proxyPaths) {
+                        if (typeof path === "string" && typeof enabled === "boolean") {
+                            config.proxyPaths.set(path, enabled);
+                            debug("Set proxy for %s to %s", path, enabled);
+                        }
+                    }
+                }
+                ctx.body = {
+                    success: true,
+                    message: "Proxy configuration updated",
+                    data: {
+                        proxyUrl: config.proxyUrl,
+                        proxyPaths: Array.from(config.proxyPaths.entries()),
+                    },
+                };
+                return;
+            }
+            // ===== List All Routes =====
+            if (resource === "routes" && ctx.method === "GET") {
+                ctx.body = {
+                    success: true,
+                    data: {
+                        routes: registry.routes,
+                    },
+                };
+                return;
+            }
+            // ===== 404 for Unknown Endpoints =====
+            ctx.status = 404;
+            ctx.body = {
+                success: false,
+                error: "Not found",
+                path: pathname,
+                message: `Unknown admin API endpoint: ${pathname}`,
+            };
+        }
+        catch (error) {
+            // ===== 500 for Server Errors =====
+            debug("Admin API error: %O", error);
+            ctx.status = 500;
+            ctx.body = {
+                success: false,
+                error: error instanceof Error ? error.message : "Unknown error",
+                stack: error instanceof Error && process.env.NODE_ENV !== "production"
+                    ? error.stack
+                    : undefined,
+            };
+        }
+    };
+}

package/dist/server/context-registry.js

@@ -47,4 +47,14 @@ export class ContextRegistry {
         Object.setPrototypeOf(context, Object.getPrototypeOf(updatedContext));
         this.cache.set(path, cloneDeep(updatedContext));
     }
+    getAllPaths() {
+        return Array.from(this.entries.keys());
+    }
+    getAllContexts() {
+        const result = {};
+        for (const [path, context] of this.entries.entries()) {
+            result[path] = context;
+        }
+        return result;
+    }
 }

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

@@ -3,10 +3,11 @@ 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 { 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) {
+export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
     const app = new Koa();
     app.use(openapiMiddleware(config.openApiPath, `//localhost:${config.port}${config.routePrefix}`));
     app.use(koaSwagger({
@@ -15,6 +16,9 @@ export function createKoaApp(registry, koaMiddleware, config) {
             url: "/counterfact/openapi",
         },
     }));
+    if (config.startAdminApi) {
+        app.use(adminApiMiddleware(registry, contextRegistry, config));
+    }
     debug("basePath: %s", config.basePath);
     debug("routes", registry.routes);
     app.use(pageMiddleware("/counterfact/", "index", {
@@ -42,6 +46,16 @@ export function createKoaApp(registry, koaMiddleware, config) {
         },
     }));
     app.use(bodyParser());
+    app.use(async (ctx, next) => {
+        await next();
+        if (ctx.body !== null &&
+            ctx.body !== undefined &&
+            typeof ctx.body === "object" &&
+            !Buffer.isBuffer(ctx.body)) {
+            ctx.body = JSON.stringify(ctx.body, null, 2);
+            ctx.type = "application/json";
+        }
+    });
     app.use(koaMiddleware);
     return app;
 }

package/dist/server/dispatcher.js

@@ -120,6 +120,15 @@ export class Dispatcher {
             path = path.replace(new RegExp(this.openApiDocument.basePath, "iu"), "");
         }
         const { matchedPath } = this.registry.handler(path, method);
+        if (!this.registry.exists(method, path) &&
+            this.registry.pathExistsWithAnyMethod(path, method)) {
+            return {
+                body: `The ${method} method is not allowed for ${path}\n`,
+                contentType: "text/plain",
+                headers: { allow: this.registry.allowedMethods(path) },
+                status: 405,
+            };
+        }
         const operation = this.operationForPathAndMethod(matchedPath, method);
         const continuousDistribution = (min, max) => {
             return min + Math.random() * (max - min);

package/dist/server/registry.js

@@ -1,6 +1,16 @@
 import createDebugger from "debug";
 import { ModuleTree } from "./module-tree.js";
 const debug = createDebugger("counterfact:server:registry");
+const ALL_HTTP_METHODS = [
+    "DELETE",
+    "GET",
+    "HEAD",
+    "OPTIONS",
+    "PATCH",
+    "POST",
+    "PUT",
+    "TRACE",
+];
 function castParameter(value, type) {
     if (typeof value !== "string") {
         return value;
@@ -52,6 +62,12 @@ export class Registry {
             path: match?.pathVariables ?? {},
         };
     }
+    pathExistsWithAnyMethod(url, excludeMethod) {
+        return ALL_HTTP_METHODS.filter((method) => method !== excludeMethod).some((method) => this.moduleTree.match(url, method) !== undefined);
+    }
+    allowedMethods(url) {
+        return ALL_HTTP_METHODS.filter((method) => Boolean(this.moduleTree.match(url, method)?.module?.[method])).join(", ");
+    }
     endpoint(httpRequestMethod, url, parameterTypes = {}) {
         const handler = this.handler(url, httpRequestMethod);
         debug("handler for %s: %o", url, handler);
@@ -97,7 +113,9 @@ export class Registry {
             function recurse(path, respondTo) {
                 if (path === null)
                     return respondTo;
-                const nextPath = path === "" ? null : path.slice(0, path.lastIndexOf("/"));
+                const nextPath = path === "/" || path === ""
+                    ? null
+                    : path.slice(0, path.lastIndexOf("/")) || "/";
                 const middleware = middlewares.get(path);
                 if (middleware !== undefined) {
                     return recurse(nextPath, ($) => middleware($, respondTo));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Generate a TypeScript-based mock server from an OpenAPI spec in seconds — with stateful routes, hot reload, and REPL support.",
   "type": "module",
   "main": "./dist/app.js",
@@ -77,11 +77,11 @@
     "postinstall": "patch-package"
   },
   "devDependencies": {
-    "@changesets/cli": "2.29.8",
-    "@stryker-mutator/core": "9.5.1",
-    "@stryker-mutator/jest-runner": "9.5.1",
-    "@stryker-mutator/typescript-checker": "9.5.1",
-    "@swc/core": "1.15.17",
+    "@changesets/cli": "2.30.0",
+    "@stryker-mutator/core": "9.6.0",
+    "@stryker-mutator/jest-runner": "9.6.0",
+    "@stryker-mutator/typescript-checker": "9.6.0",
+    "@swc/core": "1.15.18",
     "@swc/jest": "0.2.39",
     "@testing-library/dom": "10.4.1",
     "@types/debug": "^4.1.12",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^8.53.0",
     "@typescript-eslint/parser": "^8.53.0",
     "copyfiles": "2.4.1",
-    "eslint": "9.39.3",
+    "eslint": "9.39.4",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-etc": "2.0.3",
@@ -111,7 +111,7 @@
     "eslint-plugin-security": "^4.0.0",
     "eslint-plugin-unused-imports": "4.4.1",
     "husky": "9.1.7",
-    "jest": "30.2.0",
+    "jest": "30.3.0",
     "jest-retries": "1.0.1",
     "node-mocks-http": "1.17.2",
     "rimraf": "6.1.3",
@@ -128,7 +128,7 @@
     "commander": "14.0.3",
     "debug": "4.4.3",
     "fetch": "1.1.0",
-    "fs-extra": "11.3.3",
+    "fs-extra": "11.3.4",
     "handlebars": "4.7.8",
     "http-terminator": "3.2.0",
     "js-yaml": "4.1.1",