counterfact 2.1.0 → 2.2.1

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.
+
+---
+
+## Examples
 
-<details>
-<summary>Example of generated code</summary>
+### 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>
+### Typed custom responses
 
-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.
-
-<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,133 @@ export const DELETE: HTTP_DELETE = ($) => {
 };
 ```
 
-</details>
+### Returning named examples
 
-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.
+If your OpenAPI spec defines named examples, use `.example(name)` to return a specific one. The name is autocompleted and type-checked from your spec:
 
-Use `npx counterfact --help` to view CLI flags for customizing behavior (e.g. `--port`, `--proxy`, `--watch`).
+```ts
+export const GET: HTTP_GET = ($) => {
+  return $.response[200].example("successResponse");
+};
+```
 
-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.
+### State management with plain old objects
 
-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.
+Use a `_.context.ts` file to share in-memory state across routes. POST data and GET it back, just like a real API.
 
-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.
+```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];
+  }
 
-> Requires Node ≥ 17.0.0
+  getPetById(id: number) {
+    return this.pets[id];
+  }
+}
+```
 
-<div align="center" markdown="1">
+```ts
+// mock-api/routes/pet.ts
+export const POST: HTTP_POST = ($) => {
+  return $.response[200].json($.context.addPet($.body));
+};
 
-[Documentation](./docs/usage.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
+// 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);
+};
+```
 
-</div>
+You can also interact with the context object using a REPL. It's like DevTools on the server side. (See "Live REPL" below.)
 
-<br>
-<div align="center"  markdown="1">
+---
 
-![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)
+## Key Capabilities
+
+### 🔄 Hot Reload
+
+Save a route file and the server picks it up instantly — no restart, no lost state. Your in-memory context survives every reload.
+
+### 🖥 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/README.md

@@ -0,0 +1,43 @@
+# `bin/` — CLI Entry Point
+
+This directory contains the executable script that is run when a developer invokes `npx counterfact` (or `counterfact` after a global install).
+
+## Files
+
+| File | Description |
+|---|---|
+| `counterfact.js` | Parses command-line arguments with [Commander](https://github.com/tj/commander.js), validates inputs, and calls `counterfact()` from `src/app.ts` to start the server, code generator, file watcher, and/or REPL |
+
+## How It Works
+
+```
+npx counterfact openapi.yaml ./api [options]
+        │
+        ▼
+┌────────────────────────────┐
+│     counterfact.js         │
+│                            │
+│  1. Parse args (Commander) │
+│  2. Resolve paths          │
+│  3. Build Config object    │
+│  4. Run migrations if      │
+│     old layout detected    │
+│  5. Call start(config)     │
+│     from src/app.ts        │
+└────────────────────────────┘
+```
+
+### Key CLI Options
+
+| Option | Description |
+|---|---|
+| `--port <number>` | HTTP server port (default: `3100`) |
+| `-o, --open` | Open the dashboard in a browser after startup |
+| `-g, --generate` | Generate route and type files from the OpenAPI spec |
+| `-w, --watch` | Re-generate whenever the spec changes |
+| `-s, --serve` | Start the HTTP server |
+| `-r, --repl` | Start the interactive REPL |
+| `--proxy-url <url>` | Forward all unmatched requests to this upstream URL |
+| `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
+
+Run `npx counterfact --help` to see the full option list.

package/bin/counterfact.js

@@ -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");
@@ -218,7 +226,7 @@ async function main(source, destination) {
     "",
     "",
     "🔔 PLEASE READ: Feedback, Telemetry, and Privacy Discussion (10 March 2026)",
-    "   https://github.com/pmcelhaney/counterfact/discussions/1527",
+    "   https://counterfact.dev/telemetry-discussion",
     "",
     "",
     watchMessage,
@@ -302,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/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/client/README.md

@@ -0,0 +1,14 @@
+# `src/client/` — Built-in UI Templates
+
+This directory contains [Handlebars](https://handlebarsjs.com/) (`.hbs`) templates that are rendered by `page-middleware.ts` to produce the browser-facing pages bundled with Counterfact.
+
+## Files
+
+| File | Description |
+|---|---|
+| `index.html.hbs` | Template for the Counterfact dashboard (`/counterfact/`); lists registered routes and shows server status |
+| `rapi-doc.html.hbs` | Template for the interactive API documentation page (`/counterfact/swagger/`); embeds the [RapiDoc](https://rapidocweb.com/) viewer and adds VSCode "open file" links |
+
+## How It Works
+
+When a request arrives for `/counterfact/` or `/counterfact/swagger/`, `page-middleware.ts` compiles the appropriate template with runtime data (routes, port, base path, etc.) and sends the resulting HTML to the browser. No build step is required; templates are rendered on the fly.

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/counterfact-types/index.ts

@@ -37,6 +37,7 @@ type OmitValueWhenNever<Base> = Pick<
 
 interface OpenApiResponse {
   content: { [key: MediaType]: OpenApiContent };
+  examples?: { [key: string]: unknown };
   headers: { [key: string]: OpenApiHeader };
   requiredHeaders: string;
 }
@@ -105,9 +106,16 @@ type RandomFunction<Response extends OpenApiResponse> = <
   Header extends string & keyof Response["headers"],
 >() => COUNTERFACT_RESPONSE;
 
+type ExampleNames<Response extends OpenApiResponse> = Response extends {
+  examples: infer E;
+}
+  ? keyof E & string
+  : never;
+
 interface ResponseBuilder {
   [status: number | `${number} ${string}`]: ResponseBuilder;
   content?: { body: unknown; type: string }[];
+  example: (name: string) => ResponseBuilder;
   header: (name: string, value: string) => ResponseBuilder;
   headers: { [name: string]: string };
   html: (body: unknown) => ResponseBuilder;
@@ -143,6 +151,9 @@ export type GenericResponseBuilderInner<
   random: [keyof Response["content"]] extends [never]
     ? never
     : RandomFunction<Response>;
+  example: [ExampleNames<Response>] extends [never]
+    ? never
+    : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
   text: MaybeShortcut<["text/plain"], Response>;
   xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
 }>;
@@ -252,6 +263,7 @@ interface OpenApiOperation {
 }
 
 interface WideResponseBuilder {
+  example: (name: string) => WideResponseBuilder;
   header: (body: unknown) => WideResponseBuilder;
   html: (body: unknown) => WideResponseBuilder;
   json: (body: unknown) => WideResponseBuilder;
@@ -274,6 +286,7 @@ interface WideOperationArgument {
 export type { COUNTERFACT_RESPONSE };
 
 export type {
+  ExampleNames,
   HttpStatusCode,
   MaybePromise,
   MediaType,

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/dist/server/response-builder.js

@@ -63,6 +63,24 @@ export function createResponseBuilder(operation, config) {
                     ],
                 };
             },
+            example(name) {
+                if (operation.produces) {
+                    return unknownStatusCodeResponse(this.status);
+                }
+                const response = operation.responses[this.status ?? "default"] ??
+                    operation.responses.default;
+                if (response?.content === undefined) {
+                    return unknownStatusCodeResponse(this.status);
+                }
+                const { content } = response;
+                return {
+                    ...this,
+                    content: Object.keys(content).map((type) => ({
+                        body: convertToXmlIfNecessary(type, content[type]?.examples?.[name]?.value, content[type]?.schema),
+                        type,
+                    })),
+                };
+            },
             random() {
                 if (config?.alwaysFakeOptionals) {
                     JSONSchemaFaker.option("alwaysFakeOptionals", true);

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

@@ -52,6 +52,25 @@ export class ResponseTypeCoder extends TypeCoder {
             .map(({ name }) => `"${name}"`);
         return requiredHeaders.length === 0 ? "never" : requiredHeaders.join(" | ");
     }
+    buildExamplesObjectType(response) {
+        if (!response.has("content")) {
+            return "{}";
+        }
+        const exampleNames = [];
+        response.get("content").forEach((content) => {
+            if (content.has("examples")) {
+                content.get("examples").forEach((_, name) => {
+                    if (!exampleNames.includes(name)) {
+                        exampleNames.push(name);
+                    }
+                });
+            }
+        });
+        if (exampleNames.length === 0) {
+            return "{}";
+        }
+        return printObject(exampleNames.map((name) => [name, "unknown"]));
+    }
     modulePath() {
         return `types/${this.requirement.data.$ref}.ts`;
     }
@@ -60,6 +79,7 @@ export class ResponseTypeCoder extends TypeCoder {
           headers: ${this.printHeaders(script, this.requirement)};
           requiredHeaders: ${this.printRequiredHeaders(this.requirement)};
           content: ${this.printContentObjectType(script, this.requirement)};
+          examples: ${this.buildExamplesObjectType(this.requirement)};
         }`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "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",
@@ -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",