Merge branch 'main' into copilot/make-applycontext-type-available

Author: pmcelhaney

.changeset/add-internal-jsdocs.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Add JSDoc comments throughout the codebase, covering all major classes, functions, and interfaces in `src/server/`, `src/typescript-generator/`, `src/repl/`, and `src/util/`.

.changeset/blue-hexagon-repl-prompt.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Make the hexagon in the REPL prompt the same shade of blue as the logo (#0071b5).

.changeset/move-openapi-example-to-fixtures.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Moved `openapi-example.yaml` from the repository root into `test/fixtures/openapi-example.yaml` and expanded it with many OpenAPI edge cases: CRUD operations on `/users` and `/users/{userId}`, polymorphic events via `oneOf`/`allOf`/`discriminator`, nullable fields, enum types, integer formats, file upload via `multipart/form-data`, cookie parameters, deprecated endpoints, multiple response content types, a no-body `204` health-check endpoint, and free-form `additionalProperties` objects.

.changeset/refine-readme.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Replaced the five-minute walkthrough README with a concise, confident two-paragraph introduction. Added ten README variants under `docs/readme-variants/` for the team to review and choose from.

.changeset/rename-apply-to-scenario.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Rename the `.apply` REPL command to `.scenario`. Update all references in code, tests, and documentation.

README.md

@@ -4,174 +4,19 @@
 
 <br>
 
-**Your backend isn't ready. Your frontend can't wait.**
-
-**Counterfact turns your OpenAPI spec into a live, stateful API you can program in TypeScript.**
-
-<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>
 
-This is a five-minute walkthrough. By the end, you’ll have a **stateful, type-safe, hot-reloading API simulator** running locally—and you’ll understand why it’s different from traditional mock servers.
-
-Built for frontend developers, test engineers, and AI agents that need a predictable API to work against.
+You've used mock servers. You know where they stop being useful: static responses, no shared state, no way to inject a failure mid-run, no control without restarting. Counterfact picks up where they leave off.
 
-
-
-## Minute 1 — Start the server
+Point it at an OpenAPI spec and it generates TypeScript handlers for every endpoint—type-safe, hot-reloading, sharing state across routes. A built-in REPL gives you a live control surface: seed data, trigger error conditions, proxy individual routes to a real backend, all on a running server. Whether you're a frontend developer waiting on a backend, a test engineer who needs clean reproducible state, or an AI agent that needs a stable API to work against, Counterfact is the simulator that doesn't plateau.
 
 ```sh
 npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ```
 
-> **Requires Node ≥ 22.0.0**
-
-That’s it.
-
-Counterfact reads your spec, generates a TypeScript handler for every endpoint, and starts a server at `http://localhost:3100`.
-
-Open `http://localhost:3100/counterfact/swagger/`.
-
-Every endpoint is already live, returning random, schema-valid responses. No code written yet.
-
-
-
-## Minute 2 — Make a route return real data
-
-Open the generated file for `GET /pet/{petId}`:
-
-```ts
-import type { HTTP_GET } from "../../types/paths/pet/{petId}.types.js";
-
-export const GET: HTTP_GET = ($) => $.response[200].random();
-```
-
-Replace `.random()` with your own logic:
-
-```ts
-export const GET: HTTP_GET = ($) => {
-  if ($.path.petId === 99) {
-    return $.response[404].text("Pet not found");
-  }
-  return $.response[200].json({
-    id: $.path.petId,
-    name: "Fluffy",
-    status: "available",
-    photoUrls: []
-  });
-};
-```
-
-Save the file. The server reloads instantly—no restart, no lost state.
-
-TypeScript enforces the contract. If your response doesn’t match the spec, you’ll know before you make the request. 
-
-## Minute 3 — Add state that survives across requests
-
-Real APIs have memory. Yours should too.
-
-Create `api/routes/_.context.ts`:
-
-```ts
-import type { Pet } from "../types/components/pet.types.js";
-
-export class Context {
-  private pets = new Map<number, Pet>();
-  private nextId = 1;
-
-  add(data: Omit<Pet, "id">): Pet {
-    const pet = { ...data, id: this.nextId++ };
-    this.pets.set(pet.id, pet);
-    return pet;
-  }
-
-  get(id: number): Pet | undefined { return this.pets.get(id); }
-  list(): Pet[] { return [...this.pets.values()]; }
-  remove(id: number): void { this.pets.delete(id); }
-}
-```
-
-Use it in your routes:
-
-```ts
-export const GET: HTTP_GET = ($) => $.response[200].json($.context.list());
-export const POST: HTTP_POST = ($) => $.response[200].json($.context.add($.body));
-```
-
-Now your API behaves like a real system:
-- POST creates data
-- GET returns it
-- DELETE removes it
-
-State survives hot reloads. Restarting resets everything—perfect for clean test runs.
-
-
-
-## Minute 4 — Control the system at runtime (REPL)
-
-This is where Counterfact becomes more than a mock.
-
-The built-in REPL lets you inspect and control the system while it’s running.
-
-Seed data:
-
-```
-⬣> context.add({ name: "Fluffy", status: "available", photoUrls: [] })
-⬣> context.add({ name: "Rex", status: "pending", photoUrls: [] })
-```
-
-Make requests:
-
-```
-⬣> client.get("/pet/1")
-```
-
-Simulate failures instantly:
-
-```
-⬣> context.rateLimitExceeded = true
-⬣> client.get("/pet/1")
-{ status: 429, body: "Too Many Requests" }
-```
-
-No HTTP scripts. No restarts. Just direct control.
-
-
-
-## Minute 5 — Proxy to the real backend
-
-When parts of your backend are ready, forward them through.
-
-Everything else stays simulated.
-
-```sh
-npx counterfact@latest openapi.yaml api --proxy-url https://api.example.com
-```
-
-Toggle paths live:
-
-```
-⬣> .proxy on /payments
-⬣> .proxy on /auth
-⬣> .proxy off
-```
-
-
-
-## What you just built
-
-In five minutes, you turned a static spec into a working system:
-
-- **Schema-valid responses** from the moment it starts
-- **Type-safe handlers** generated from your spec
-- **Shared state** across all routes
-- **Hot reloading** without losing that state
-- A **live control surface (REPL)** for runtime behavior
-- **Selective proxying** to real services
-
-
+> Requires Node ≥ 22.0.0
 
 ## Go deeper
 
@@ -189,4 +34,4 @@ In five minutes, you turned a static spec into a working system:
 
 [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
-</div>
+</div>

docs/adr/001-apply-command-with-function-injection.md

@@ -1,4 +1,4 @@
-# ADR 001: .apply Command Design — Minimalist Function Injection
+# ADR 001: .scenario Command Design — Minimalist Function Injection
 
 ## Status
 
@@ -8,7 +8,7 @@ Accepted
 
 Counterfact's REPL lets developers interact with the running mock server from the terminal. A common need is to transition the server into a specific state (e.g. "all pets sold", "service unavailable") in a reproducible, shareable way. Today, operators must manually call REPL commands one by one; there is no mechanism to save and replay a named scenario.
 
-The `.apply` command is proposed to address this: given a path argument, it loads and executes a user-authored script that mutates REPL context and routes, then reports what changed.
+The `.scenario` command is proposed to address this: given a path argument, it loads and executes a user-authored script that mutates REPL context and routes, then reports what changed.
 
 Three designs were proposed as working documents in `.github/issue-proposals/`:
 
@@ -27,7 +27,7 @@ Three designs were proposed as working documents in `.github/issue-proposals/`:
 
 **Solution 1 (Minimalist Function Injection) is selected.**
 
-An apply script is a TypeScript file with one or more named function exports. When `.apply <path>` is run, Counterfact splits the argument on `/`, uses the last segment as the function name and the rest as the file path (relative to `<basePath>/repl/`), dynamically imports the module, and calls the named function with a live `ApplyContext` (`$`) object:
+A scenario script is a TypeScript file with one or more named function exports. When `.scenario <path>` is run, Counterfact splits the argument on `/`, uses the last segment as the function name and the rest as the file path (relative to `<basePath>/repl/`), dynamically imports the module, and calls the named function with a live `ApplyContext` (`$`) object:
 
 ```ts
 // repl/sold-pets.ts
@@ -55,7 +55,7 @@ Scripts export named functions that receive `$: ApplyContext`. Counterfact resol
 
 ### Solution 2: Scenario Class with Lifecycle Hooks
 
-Scripts export a named class that implements a `Scenario` interface with `setup()` and optional `teardown()` methods. Counterfact instantiates the class, calls `setup()`, and tracks applied instances in a map for later `.unapply`. A static `dependencies` array enables ordered composition.
+Scripts export a named class that implements a `Scenario` interface with `setup()` and optional `teardown()` methods. Counterfact instantiates the class, calls `setup()`, and tracks applied instances in a map for later `.unscenario`. A static `dependencies` array enables ordered composition.
 
 **Why not chosen:** Class syntax and lifecycle coupling add complexity that is not justified until the need for teardown and dependency ordering is proven in practice. These concerns can be layered on top of Solution 1 once the basic command exists.
 
@@ -81,7 +81,7 @@ Identical surface syntax to Solution 1, but Counterfact wraps `context` and `rou
 
 ### Risks and downsides
 
-- Without lifecycle hooks, accumulated state across many `.apply` calls may be difficult to reason about.
+- Without lifecycle hooks, accumulated state across many `.scenario` calls may be difficult to reason about.
 - If teardown proves to be a common need, adding it later will require extending the API in a backward-compatible way.
 - Proxy-based auto-diffing (Solution 3) remains attractive for DX; deferring it means script authors will need to be disciplined about documenting context changes in the short term.
 

docs/features/repl.md

@@ -56,21 +56,21 @@ await req.send()
 
 See the [Route Builder guide](./route-builder.md) for full documentation.
 
-## Scenario scripts with `.apply`
+## Scenario scripts with `.scenario`
 
-For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.apply`:
+For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.scenario`:
 
 ```
-⬣> .apply soldPets
+⬣> .scenario soldPets
 ```
 
-**Path resolution:** the argument to `.apply` is a slash-separated path. The last segment is the function name; everything before it is the file path, resolved relative to `<basePath>/scenarios/` (with `index.ts` as the default file).
+**Path resolution:** the argument to `.scenario` is a slash-separated path. The last segment is the function name; everything before it is the file path, resolved relative to `<basePath>/scenarios/` (with `index.ts` as the default file).
 
 | Command | File | Function |
 |---|---|---|
-| `.apply foo` | `scenarios/index.ts` | `foo` |
-| `.apply foo/bar` | `scenarios/foo.ts` | `bar` |
-| `.apply foo/bar/baz` | `scenarios/foo/bar.ts` | `baz` |
+| `.scenario soldPets` | `scenarios/index.ts` | `soldPets` |
+| `.scenario pets/resetAll` | `scenarios/pets.ts` | `resetAll` |
+| `.scenario pets/orders/pending` | `scenarios/pets/orders.ts` | `pending` |
 
 A scenario function receives a single argument with `{ context, loadContext, routes, route }`:
 

docs/readme-variants/variant-1.md

@@ -0,0 +1,37 @@
+<div align="center" markdown="1">
+
+<img src="../../counterfact.svg" alt="Counterfact" border=0>
+
+<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>
+
+Counterfact turns an OpenAPI spec into a live, stateful API server you can program in TypeScript. Point it at a spec and every endpoint is immediately live—returning schema-valid responses, sharing state across routes, and hot-reloading when you edit a handler.
+
+That's where traditional mock servers stop. Counterfact keeps going. A built-in REPL lets you inspect and manipulate the running server: seed data, trigger failure modes, flip a proxy on or off—without restarting. It's a direct control surface for a running API. It works for frontend developers who can't wait on a backend, for test engineers who need reproducible states, and for AI coding agents that need a programmable, predictable sandbox to iterate in.
+
+```sh
+npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
+```
+
+> Requires Node ≥ 22.0.0
+
+## Go deeper
+
+| | |
+|---|---|
+| [Getting started](../getting-started.md) | Detailed walkthrough with state, REPL, and proxy |
+| [Usage](../usage.md) | Feature index: routes, context, REPL, proxy, middleware, and more |
+| [Patterns](../patterns/index.md) | Failures, latency, AI sandboxes, integration tests |
+| [Reference](../reference.md) | `$` API, CLI flags, architecture |
+| [How it compares](../comparison.md) | json-server, WireMock, Prism, Microcks, MSW |
+| [FAQ](../faq.md) | State, types, regeneration |
+| [Petstore example](https://github.com/counterfact/example-petstore) | Full working example |
+
+<div align="center" markdown="1">
+
+[Changelog](../../CHANGELOG.md) · [Contributing](../../CONTRIBUTING.md)
+
+</div>

docs/readme-variants/variant-10.md

@@ -0,0 +1,37 @@
+<div align="center" markdown="1">
+
+<img src="../../counterfact.svg" alt="Counterfact" border=0>
+
+<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>
+
+The shift toward AI-assisted development changes what a mock server needs to be. Agents iterate fast, depend on state carrying over between requests, and need to simulate failures and edge cases on demand. Static mocks—fixed responses, no memory, no runtime control—aren't enough anymore.
+
+Counterfact is a programmable API simulator built for this moment. It reads an OpenAPI spec and starts a stateful TypeScript server in one command. A built-in REPL lets you—or an agent—control the running system: seed data, trigger failures, proxy individual routes to a real backend. The handlers it generates are type-safe, hot-reloading, and share state across routes. It works equally well for human developers who can't wait on a backend and for AI agents that need a reliable sandbox to reason about.
+
+```sh
+npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
+```
+
+> Requires Node ≥ 22.0.0
+
+## Go deeper
+
+| | |
+|---|---|
+| [Getting started](../getting-started.md) | Detailed walkthrough with state, REPL, and proxy |
+| [Usage](../usage.md) | Feature index: routes, context, REPL, proxy, middleware, and more |
+| [Patterns](../patterns/index.md) | Failures, latency, AI sandboxes, integration tests |
+| [Reference](../reference.md) | `$` API, CLI flags, architecture |
+| [How it compares](../comparison.md) | json-server, WireMock, Prism, Microcks, MSW |
+| [FAQ](../faq.md) | State, types, regeneration |
+| [Petstore example](https://github.com/counterfact/example-petstore) | Full working example |
+
+<div align="center" markdown="1">
+
+[Changelog](../../CHANGELOG.md) · [Contributing](../../CONTRIBUTING.md)
+
+</div>