counterfact 2.6.0 → 2.8.1

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

@@ -51,6 +51,16 @@ function stringifyBody(body) {
     }
     return JSON.stringify(body);
 }
+/**
+ * A minimal HTTP/1.1 client that communicates over a raw TCP socket.
+ *
+ * Used in the Counterfact REPL (`client.*`) to send requests to the local mock
+ * server and pretty-print the request and response to `stdout` with ANSI
+ * colours.
+ *
+ * Unlike `fetch` or Axios, `RawHttpClient` does not buffer or parse the
+ * response — the raw HTTP response string is returned from every method.
+ */
 export class RawHttpClient {
     host;
     port;
@@ -59,30 +69,39 @@ export class RawHttpClient {
         this.host = host;
         this.port = port;
     }
+    /** Sends a `GET` request and returns the raw HTTP response string. */
     get(path, headers = {}) {
         return this.#send("GET", path, "", headers);
     }
+    /** Sends a `HEAD` request and returns the raw HTTP response string. */
     head(path, headers = {}) {
         return this.#send("HEAD", path, "", headers);
     }
+    /** Sends a `POST` request with `body` and returns the raw HTTP response string. */
     post(path, body = "", headers = {}) {
         return this.#send("POST", path, body, headers);
     }
+    /** Sends a `PUT` request with `body` and returns the raw HTTP response string. */
     put(path, body = "", headers = {}) {
         return this.#send("PUT", path, body, headers);
     }
+    /** Sends a `DELETE` request and returns the raw HTTP response string. */
     delete(path, headers = {}) {
         return this.#send("DELETE", path, "", headers);
     }
+    /** Sends a `CONNECT` request and returns the raw HTTP response string. */
     connect(path, headers = {}) {
         return this.#send("CONNECT", path, "", headers);
     }
+    /** Sends an `OPTIONS` request and returns the raw HTTP response string. */
     options(path, headers = {}) {
         return this.#send("OPTIONS", path, "", headers);
     }
+    /** Sends a `TRACE` request and returns the raw HTTP response string. */
     trace(path, headers = {}) {
         return this.#send("TRACE", path, "", headers);
     }
+    /** Sends a `PATCH` request with `body` and returns the raw HTTP response string. */
     patch(path, body = "", headers = {}) {
         return this.#send("PATCH", path, body, headers);
     }

package/dist/repl/repl.js

@@ -15,8 +15,51 @@ const ROUTE_BUILDER_METHODS = [
     "ready(",
     "send(",
 ];
-export function createCompleter(registry, fallback) {
+/**
+ * Creates a tab-completion function for the REPL.
+ *
+ * @param registry - The route registry used to complete path arguments for `route()` and `client.*()` calls.
+ * @param fallback - Optional fallback completer (e.g. the Node.js built-in completer) invoked when no custom completion matches.
+ * @param scenarioRegistry - When provided, enables tab completion for `.scenario` commands by enumerating
+ *   exported function names and file-key prefixes from the loaded scenario modules.
+ */
+export function createCompleter(registry, fallback, scenarioRegistry) {
     return (line, callback) => {
+        // Check for .scenario completion: .scenario <partial>
+        const applyMatch = line.match(/^\.scenario\s+(?<partial>\S*)$/u);
+        if (applyMatch) {
+            const partial = applyMatch.groups?.["partial"] ?? "";
+            if (scenarioRegistry !== undefined) {
+                const slashIdx = partial.lastIndexOf("/");
+                if (slashIdx === -1) {
+                    // No slash: complete exports from "index" key + top-level file prefixes
+                    const indexFunctions = scenarioRegistry.getExportedFunctionNames("index");
+                    const fileKeys = scenarioRegistry
+                        .getFileKeys()
+                        .filter((k) => k !== "index");
+                    const topLevelPrefixes = [
+                        ...new Set(fileKeys.map((k) => k.split("/")[0] + "/")),
+                    ];
+                    const allOptions = [...indexFunctions, ...topLevelPrefixes];
+                    const matches = allOptions.filter((c) => c.startsWith(partial));
+                    callback(null, [matches, partial]);
+                }
+                else {
+                    // Has slash: complete exports from the named file key
+                    const fileKey = partial.slice(0, slashIdx);
+                    const funcPartial = partial.slice(slashIdx + 1);
+                    const functions = scenarioRegistry.getExportedFunctionNames(fileKey);
+                    const matches = functions
+                        .filter((e) => e.startsWith(funcPartial))
+                        .map((e) => `${fileKey}/${e}`);
+                    callback(null, [matches, partial]);
+                }
+            }
+            else {
+                callback(null, [[], partial]);
+            }
+            return;
+        }
         // Check for RouteBuilder method completion: route("..."). or chained calls
         const builderMatch = line.match(/route\(.*\)\.(?<partial>[a-zA-Z]*)$/u);
         if (builderMatch) {
@@ -41,7 +84,26 @@ export function createCompleter(registry, fallback) {
         callback(null, [matches, partial]);
     };
 }
-export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument) {
+/**
+ * Launches the interactive Counterfact REPL.
+ *
+ * The REPL is a standard Node.js REPL augmented with:
+ * - `context` / `loadContext(path)` globals wired to the {@link ContextRegistry}.
+ * - `client` — a {@link RawHttpClient} pre-configured for `localhost`.
+ * - `route(path)` — creates a {@link RouteBuilder} for the given path.
+ * - `.counterfact` — help command.
+ * - `.proxy` — proxy configuration command.
+ * - `.scenario` — runs a named scenario function from the scenarios directory.
+ *
+ * @param contextRegistry - The live context registry.
+ * @param registry - The route registry (used for tab completion).
+ * @param config - Server configuration.
+ * @param print - Output function; defaults to writing to `stdout`.
+ * @param openApiDocument - Optional OpenAPI document for tab completion.
+ * @param scenarioRegistry - Optional scenario registry for `.scenario` support.
+ * @returns The configured Node.js REPL server instance.
+ */
+export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry) {
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -80,12 +142,12 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         }
     }
     const replServer = repl.start({
-        prompt: "⬣> ",
+        prompt: "\x1b[38;2;0;113;181m⬣> \x1b[0m",
     });
     const builtinCompleter = replServer.completer;
     // completer is typed as readonly in @types/node but is writable at runtime
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    replServer.completer = createCompleter(registry, builtinCompleter);
+    replServer.completer = createCompleter(registry, builtinCompleter, scenarioRegistry);
     replServer.defineCommand("counterfact", {
         action() {
             print("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.");
@@ -129,5 +191,55 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     replServer.context.client = new RawHttpClient("localhost", config.port);
     replServer.context.RawHttpClient = RawHttpClient;
     replServer.context.route = createRouteFunction(config.port, "localhost", openApiDocument);
+    replServer.context.routes = {};
+    replServer.defineCommand("scenario", {
+        async action(text) {
+            const parts = text.trim().split("/").filter(Boolean);
+            if (parts.length === 0) {
+                print("usage: .scenario <path>");
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            if (parts.some((part) => part === ".." || part === ".")) {
+                print("Error: Path must not contain '.' or '..' segments");
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            const functionName = parts[parts.length - 1] ?? "";
+            const fileKey = parts.length === 1 ? "index" : parts.slice(0, -1).join("/");
+            const module = scenarioRegistry?.getModule(fileKey);
+            if (module === undefined) {
+                print(`Error: Could not find scenario file "${fileKey}"`);
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            const fn = module[functionName];
+            if (typeof fn !== "function") {
+                print(`Error: "${functionName}" is not a function exported from "${fileKey}"`);
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            try {
+                const applyContext = {
+                    context: replServer.context["context"],
+                    loadContext: replServer.context["loadContext"],
+                    route: replServer.context["route"],
+                    routes: replServer.context["routes"],
+                };
+                await fn(applyContext);
+                print(`Applied ${text.trim()}`);
+            }
+            catch (error) {
+                print(`Error: ${String(error)}`);
+            }
+            this.clearBufferedCommand();
+            this.displayPrompt();
+        },
+        help: 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
+    });
     return replServer;
 }

package/dist/repl/route-builder.js

@@ -1,4 +1,17 @@
 import { RawHttpClient } from "./raw-http-client.js";
+/**
+ * Immutable fluent builder for constructing and sending HTTP requests from the
+ * Counterfact REPL.
+ *
+ * Each builder method returns a **new** `RouteBuilder` instance with the
+ * updated field — the original is never mutated.  When all required parameters
+ * are set, call {@link send} to execute the request.
+ *
+ * ```ts
+ * // Inside the REPL:
+ * route("/pets/{petId}").method("get").path({ petId: 1 }).send();
+ * ```
+ */
 export class RouteBuilder {
     routePath;
     _body;
@@ -47,29 +60,63 @@ export class RouteBuilder {
             queryParams: overrides.queryParams ?? this._queryParams,
         });
     }
+    /**
+     * Returns a new builder with the HTTP method set.
+     *
+     * @param method - HTTP method name (case-insensitive, e.g. `"get"`, `"POST"`).
+     */
     method(method) {
         return this.clone({ method: method.toUpperCase() });
     }
+    /**
+     * Returns a new builder with additional path parameters merged in.
+     *
+     * @param params - Key/value map of path variable names to values.
+     */
     path(params) {
         return this.clone({ pathParams: { ...this._pathParams, ...params } });
     }
+    /**
+     * Returns a new builder with additional query parameters merged in.
+     *
+     * @param params - Key/value map of query parameter names to values.
+     */
     query(params) {
         return this.clone({ queryParams: { ...this._queryParams, ...params } });
     }
+    /**
+     * Returns a new builder with additional request headers merged in.
+     *
+     * @param params - Key/value map of header names to values.
+     */
     headers(params) {
         return this.clone({ headerParams: { ...this._headerParams, ...params } });
     }
+    /**
+     * Returns a new builder with the request body set.
+     *
+     * @param body - The request body (will be serialised to JSON or sent as-is).
+     */
     body(body) {
         return this.clone({ body });
     }
     getOperation() {
         return this._operation;
     }
+    /**
+     * Returns `true` when a method is set and no required parameters are
+     * missing.
+     */
     ready() {
         if (!this._method)
             return false;
         return this.missing() === undefined;
     }
+    /**
+     * Returns a {@link MissingParams} object describing all required parameters
+     * that have not yet been set, or `undefined` when nothing is missing (or
+     * when the operation has no parameters).
+     */
     missing() {
         const operation = this.getOperation();
         if (!operation?.parameters)
@@ -98,6 +145,10 @@ export class RouteBuilder {
             return undefined;
         return missingParams;
     }
+    /**
+     * Returns a human-readable help string describing the operation, its
+     * parameters, and the expected responses.
+     */
     help() {
         const method = this._method ?? "[no method set]";
         const operation = this.getOperation();
@@ -168,6 +219,13 @@ export class RouteBuilder {
         }
         return lines.join("\n");
     }
+    /**
+     * Executes the HTTP request and returns the parsed response body.
+     *
+     * @throws When no HTTP method has been set.
+     * @throws When required parameters are missing.
+     * @throws When an unsupported HTTP method is used.
+     */
     async send() {
         if (!this._method) {
             throw new Error('No HTTP method set. Use .method("get") to set the method.');
@@ -265,6 +323,16 @@ export class RouteBuilder {
         return lines.join("\n");
     }
 }
+/**
+ * Creates a factory function that constructs a {@link RouteBuilder} for a
+ * given route path, pre-configured with the server's host, port, and OpenAPI
+ * document.
+ *
+ * @param port - The port the Counterfact server is listening on.
+ * @param host - The server hostname (default `"localhost"`).
+ * @param openApiDocument - Optional OpenAPI document for parameter introspection.
+ * @returns A function `(routePath: string) => RouteBuilder`.
+ */
 export function createRouteFunction(port, host, openApiDocument) {
     return (routePath) => new RouteBuilder(routePath, { host, openApiDocument, port });
 }

package/dist/server/constants.js

@@ -1,3 +1,11 @@
+/**
+ * Default options passed to every chokidar watcher in Counterfact.
+ *
+ * - `ignoreInitial: true` — suppresses the initial `"add"` events emitted for
+ *   files already present when the watcher starts.
+ * - `usePolling: true` on Windows — chokidar's native FSEvents are unreliable
+ *   on Windows; polling is more reliable there.
+ */
 export const CHOKIDAR_OPTIONS = {
     ignoreInitial: true,
     usePolling: process.platform === "win32",

package/dist/server/context-registry.js

@@ -1,6 +1,19 @@
+/**
+ * A context object that lives at a specific route path and is shared across
+ * all requests to that path (and its descendants).
+ *
+ * Route handlers receive this object as `$.context` and may freely add or
+ * modify properties to maintain state between requests.
+ */
 export class Context {
     constructor() { }
 }
+/**
+ * Returns the parent path of a route path by stripping the last segment.
+ *
+ * @param path - A route path such as `"/pets/1"`.
+ * @returns The parent path (e.g. `"/pets"`), or `"/"` for top-level paths.
+ */
 export function parentPath(path) {
     return String(path.split("/").slice(0, -1).join("/")) || "/";
 }
@@ -29,11 +42,25 @@ function cloneForCache(value) {
     }
     return clone;
 }
-export class ContextRegistry {
+/**
+ * Registry of per-path {@link Context} objects that persist state across
+ * requests.
+ *
+ * The registry is case-insensitive for path lookups and uses a write-through
+ * cache to detect which context properties have changed between hot-reloads.
+ * It extends {@link EventTarget} so that listeners can react to structural
+ * changes (e.g. to regenerate type files):
+ *
+ * ```ts
+ * contextRegistry.addEventListener("context-changed", () => { ... });
+ * ```
+ */
+export class ContextRegistry extends EventTarget {
     entries = new Map();
     cache = new Map();
     seen = new Set();
     constructor() {
+        super();
         this.add("/", {});
     }
     getContextIgnoreCase(map, key) {
@@ -45,14 +72,54 @@ export class ContextRegistry {
         }
         return undefined;
     }
+    /**
+     * Registers a new context for `path`, replacing any existing one, and
+     * dispatches a `"context-changed"` event so listeners can react.
+     *
+     * @param path - The route path (e.g. `"/pets"`).
+     * @param context - The context object to store.
+     */
     add(path, context) {
         this.entries.set(path, context);
         this.cache.set(path, cloneForCache(context));
+        this.dispatchEvent(new Event("context-changed"));
+    }
+    /**
+     * Removes the context entry for the given path and dispatches a
+     * "context-changed" event so that listeners (e.g. the _.context type
+     * generator) can regenerate type files in response to the removal.
+     *
+     * @param path - The route path whose context entry should be deleted
+     *   (e.g. "/pets").
+     */
+    remove(path) {
+        this.entries.delete(path);
+        this.cache.delete(path);
+        this.seen.delete(path);
+        this.dispatchEvent(new Event("context-changed"));
     }
+    /**
+     * Finds the context for `path`, walking up the path hierarchy until a
+     * context is found.  Falls back to `"/"` which always has a context.
+     *
+     * @param path - The route path to look up.
+     * @returns The nearest ancestor context (or the root context).
+     */
     find(path) {
         return (this.getContextIgnoreCase(this.entries, path) ??
             this.find(parentPath(path)));
     }
+    /**
+     * Merges `updatedContext` into the existing context for `path`.
+     *
+     * On the first call for a path the context is added directly.  On subsequent
+     * calls only properties whose values differ from the cached snapshot are
+     * applied, preserving live mutations made by route handlers between reloads.
+     *
+     * @param path - The route path (e.g. `"/pets"`).
+     * @param updatedContext - The new context instance (typically freshly
+     *   constructed from the reloaded `_.context.ts` file).
+     */
     update(path, updatedContext) {
         if (updatedContext === undefined) {
             return;
@@ -71,9 +138,11 @@ export class ContextRegistry {
         Object.setPrototypeOf(context, Object.getPrototypeOf(updatedContext));
         this.cache.set(path, cloneForCache(updatedContext));
     }
+    /** Returns all registered route paths as an array. */
     getAllPaths() {
         return Array.from(this.entries.keys());
     }
+    /** Returns a plain object mapping every registered path to its context. */
     getAllContexts() {
         const result = {};
         for (const [path, context] of this.entries.entries()) {

package/dist/server/counterfact-types/cookie-options.ts

@@ -0,0 +1,14 @@
+/**
+ * Options for setting an HTTP cookie on a response.
+ * These correspond to standard `Set-Cookie` attributes and are passed to the
+ * `.cookie()` method on the response builder.
+ */
+export interface CookieOptions {
+  domain?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "lax" | "none" | "strict";
+  secure?: boolean;
+}

package/dist/server/counterfact-types/counterfact-response.ts

@@ -0,0 +1,15 @@
+/**
+ * A unique symbol used as a brand for the `COUNTERFACT_RESPONSE` type.
+ * This prevents arbitrary objects from being accidentally treated as a
+ * completed response value.
+ */
+const counterfactResponse = Symbol("Counterfact Response");
+
+/**
+ * The terminal value type returned by the fluent response builder once all
+ * required fields (body, headers, etc.) have been provided. When a route
+ * handler returns this type, Counterfact treats the response as complete.
+ */
+export type COUNTERFACT_RESPONSE = {
+  [counterfactResponse]: typeof counterfactResponse;
+};

package/dist/server/counterfact-types/example-names.ts

@@ -0,0 +1,13 @@
+import type { OpenApiResponse } from "./open-api-response.js";
+
+/**
+ * Extracts the union of named example keys defined on an OpenAPI response.
+ * Resolves to `never` when the response has no named examples.
+ * Used to constrain the argument to the `.example(name)` method on the
+ * response builder.
+ */
+export type ExampleNames<Response extends OpenApiResponse> = Response extends {
+  examples: infer E;
+}
+  ? keyof E & string
+  : never;

package/dist/server/counterfact-types/example.ts

@@ -0,0 +1,10 @@
+/**
+ * Represents a named example defined in an OpenAPI document.
+ * Examples can be referenced by route handlers via the `.example(name)` method
+ * on the response builder.
+ */
+export interface Example {
+  description: string;
+  summary: string;
+  value: unknown;
+}

package/dist/server/counterfact-types/generic-response-builder.ts

@@ -0,0 +1,164 @@
+import type { COUNTERFACT_RESPONSE } from "./counterfact-response.js";
+import type { CookieOptions } from "./cookie-options.js";
+import type { ExampleNames } from "./example-names.js";
+import type { IfHasKey } from "./if-has-key.js";
+import type { MediaType } from "./media-type.js";
+import type { OmitAll } from "./omit-all.js";
+import type { OmitValueWhenNever } from "./omit-value-when-never.js";
+import type { OpenApiResponse } from "./open-api-response.js";
+import type { RandomFunction } from "./random-function.js";
+
+/**
+ * Returns `never` when `Record` is an empty object type (`{}`), signalling
+ * that there are no remaining choices available on the response builder.
+ */
+type NeverIfEmpty<Record> = object extends Record ? never : Record;
+
+/**
+ * Extracts the union of schema types from a map of media-type content entries.
+ * Used to type the body argument of shortcut methods like `.json()` or `.html()`.
+ */
+type SchemasOf<T extends { [key: string]: { schema: unknown } }> = {
+  [K in keyof T]: T[K]["schema"];
+}[keyof T];
+
+/**
+ * Produces a builder method for a shortcut (e.g. `.json()`, `.html()`) when
+ * the response contains at least one of the given `ContentTypes`, and `never`
+ * otherwise. Calling the method narrows the builder by removing those content
+ * types from the remaining options.
+ */
+type MaybeShortcut<
+  ContentTypes extends MediaType[],
+  Response extends OpenApiResponse,
+> = IfHasKey<
+  Response["content"],
+  ContentTypes,
+  (body: SchemasOf<Response["content"]>) => GenericResponseBuilder<{
+    content: NeverIfEmpty<OmitAll<Response["content"], ContentTypes>>;
+    headers: Response["headers"];
+    requiredHeaders: Response["requiredHeaders"];
+  }>,
+  never
+>;
+
+/**
+ * The type of the `.match(contentType, body)` method on the generic response
+ * builder. Calling it narrows the builder by removing the chosen content type
+ * from the remaining options.
+ */
+type MatchFunction<Response extends OpenApiResponse> = <
+  ContentType extends MediaType & keyof Response["content"],
+>(
+  contentType: ContentType,
+  body: Response["content"][ContentType]["schema"],
+) => GenericResponseBuilder<{
+  content: NeverIfEmpty<Omit<Response["content"], ContentType>>;
+  headers: Response["headers"];
+  requiredHeaders: Response["requiredHeaders"];
+}>;
+
+/**
+ * The type of the `.header(name, value)` method on the generic response
+ * builder. Calling it narrows the builder by removing the satisfied header
+ * from the set of required headers.
+ */
+type HeaderFunction<Response extends OpenApiResponse> = <
+  Header extends string & keyof Response["headers"],
+>(
+  header: Header,
+  value: Response["headers"][Header]["schema"],
+) => GenericResponseBuilder<{
+  content: NeverIfEmpty<Response["content"]>;
+  headers: NeverIfEmpty<Omit<Response["headers"], Header>>;
+  requiredHeaders: Exclude<Response["requiredHeaders"], Header>;
+}>;
+
+/**
+ * The inner shape of the generic response builder, listing all methods that
+ * are currently available given the remaining response constraints.
+ * Methods whose type resolves to `never` are stripped by `OmitValueWhenNever`.
+ *
+ * Note: `[T] extends [never]` (non-distributive tuple wrapping) is used
+ * alongside `[keyof T] extends [never]` to correctly handle both `T = never`
+ * (spec-generated no-body) and `T = {}` (all content types consumed) cases.
+ * TypeScript evaluates `keyof never` as `string | number | symbol`, so a
+ * direct `[keyof never] extends [never]` check would incorrectly return false.
+ */
+export type GenericResponseBuilderInner<
+  Response extends OpenApiResponse = OpenApiResponse,
+> = OmitValueWhenNever<{
+  binary: MaybeShortcut<["application/octet-stream"], Response>;
+  cookie: (
+    name: string,
+    value: string,
+    options?: CookieOptions,
+  ) => GenericResponseBuilder<Response>;
+  empty: [Response["content"]] extends [never]
+    ? () => COUNTERFACT_RESPONSE
+    : [keyof Response["content"]] extends [never]
+      ? () => COUNTERFACT_RESPONSE
+      : never;
+  header: [Response["headers"]] extends [never]
+    ? never
+    : [keyof Response["headers"]] extends [never]
+      ? never
+      : HeaderFunction<Response>;
+  html: MaybeShortcut<["text/html"], Response>;
+  json: MaybeShortcut<
+    [
+      "application/json",
+      "text/json",
+      "text/x-json",
+      "application/xml",
+      "text/xml",
+    ],
+    Response
+  >;
+  match: [Response["content"]] extends [never]
+    ? never
+    : [keyof Response["content"]] extends [never]
+      ? never
+      : MatchFunction<Response>;
+  random: [Response["content"]] extends [never]
+    ? never
+    : [keyof Response["content"]] extends [never]
+      ? never
+      : RandomFunction;
+  example: [ExampleNames<Response>] extends [never]
+    ? never
+    : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
+  text: MaybeShortcut<["text/plain"], Response>;
+  xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
+}>;
+
+/**
+ * The strongly-typed, fluent response builder generated for each operation in
+ * a route handler. Its available methods are derived from the OpenAPI response
+ * schema: as methods are called, the builder type narrows until all required
+ * content and headers have been provided, at which point it resolves to
+ * `COUNTERFACT_RESPONSE`.
+ *
+ * When a Response type carries an `examples` key it is a spec-generated
+ * response (either the initial no-body builder or a builder that still has
+ * content/headers to satisfy). Those always go through
+ * `GenericResponseBuilderInner`, which exposes `empty()` when `content` is
+ * `never`.
+ *
+ * When a Response type has no `examples` key it is a narrowed type produced
+ * by a method call (e.g. `.json()` sets the body and returns a type without
+ * `examples`). Those go through the existing collapse logic so that
+ * fully-satisfied responses resolve directly to `COUNTERFACT_RESPONSE`.
+ */
+export type GenericResponseBuilder<
+  Response extends OpenApiResponse = OpenApiResponse,
+> = "examples" extends keyof Response
+  ? GenericResponseBuilderInner<Response>
+  : object extends OmitValueWhenNever<Omit<Response, "examples">>
+    ? COUNTERFACT_RESPONSE
+    : keyof OmitValueWhenNever<Omit<Response, "examples">> extends "headers"
+      ? {
+          ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE;
+          header: HeaderFunction<Response>;
+        }
+      : GenericResponseBuilderInner<Response>;