Merge branch 'main' into copilot/fix-response-type-errors

Author: pmcelhaney

.changeset/afraid-pens-remain.md

@@ -0,0 +1,5 @@
+---
+"counterfact": minor
+---
+
+Add .empty() method to response builder for responses with no body

.changeset/document-usage-patterns.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+add docs/usage-patterns.md documenting seven usage patterns: explore a new API, simulate failures and edge cases, mock APIs with dummy data, fast sandbox for agentic coding, hybrid proxy, API reference implementation, and executable spec

.changeset/more-usage-patterns.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+add two new usage pattern docs: Automated Integration Tests (programmatic API in test suites) and Custom Middleware (_.middleware.ts for cross-cutting concerns); propose three future patterns as GitHub issues: Record and Replay, Webhook Simulation, and Persistent State

.changeset/revise-documentation-coherence.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Revised documentation for coherence: added table of contents to usage, reference, and FAQ pages; added "See also" sections to pages that were missing them; moved the usage guide link from the README footer into the "Go deeper" table.

.github/issue-proposals/docs-pattern-persistent-state.md

@@ -0,0 +1,43 @@
+---
+title: "docs: add Persistent State usage pattern"
+parentIssue: 1805
+labels:
+  - documentation
+  - enhancement
+assignees: []
+milestone:
+---
+
+Add a usage pattern for persisting Counterfact context state to disk so that it survives server restarts.
+
+## Context
+
+Counterfact's in-memory state resets to its initial values every time the server restarts. This is intentional and usually desirable during development — it provides a clean slate. However, some workflows need state to survive restarts:
+
+- **Shared demo environments**: a team seeds realistic data and then shares the mock across a demo session that spans multiple days. Restarting the server to pick up a new version of a handler file should not wipe the demo data.
+- **Long-running integration environments**: a staging or QA environment runs the mock for days or weeks; testers build up test data over multiple sessions.
+- **Seeded fixtures**: a project ships a `seed.json` file with canonical test data that is loaded at startup rather than recreated by hand after every restart.
+
+Counterfact currently has no built-in persistence mechanism. Workarounds involve writing a startup script that calls context methods to re-seed data, or serializing context state to a file manually and loading it back in a custom startup hook.
+
+## Proposed feature
+
+Add a `--persist-state <path>` CLI flag (or a `persist` option in `counterfact.yaml`) that:
+1. At shutdown, serializes the context's state to a JSON file at the specified path.
+2. At startup, loads the JSON file and hydrates the context before the server begins accepting requests.
+
+Context classes would opt in by implementing `toJSON()` and `fromJSON(data)` methods (or a similar convention). This keeps the persistence mechanism decoupled from the context class interface.
+
+A `Persistent State` pattern document would describe:
+- When to use it: shared demo environments, long-running QA mocks, or fixture-based seeding
+- How to enable persistence with `--persist-state`
+- How to implement `toJSON` / `fromJSON` in a context class
+- Consequences: state files can drift from the spec; schema migrations are the author's responsibility; not suitable for high-concurrency scenarios
+
+## Acceptance criteria
+
+- [ ] `--persist-state <path>` CLI flag (or equivalent) is implemented
+- [ ] Context classes can opt in to persistence by implementing a documented interface
+- [ ] `docs/patterns/persistent-state.md` is added following the established pattern format
+- [ ] The new pattern is linked in `docs/usage-patterns.md`
+- [ ] The reference doc is updated to describe the new CLI flag and context interface

.github/issue-proposals/docs-pattern-record-and-replay.md

@@ -0,0 +1,34 @@
+---
+title: "docs: add Record and Replay usage pattern"
+parentIssue: 1805
+labels:
+  - documentation
+  - enhancement
+assignees: []
+milestone:
+---
+
+Add a usage pattern documenting a record-and-replay workflow where real API traffic is captured and replayed by Counterfact as a mock.
+
+## Context
+
+Record-and-replay is a common mock strategy supported by tools like WireMock, VCR (Ruby), Polly.js, and others. The idea is: point a proxy at the real API once, record all the responses, then replay those exact responses from the mock without hitting the real API again.
+
+Counterfact currently has no built-in record-and-replay feature. The proxy (`--proxy-url`) forwards requests to the real backend but does not persist the responses. Users who want to bootstrap a mock from real traffic must manually inspect responses and write handlers by hand.
+
+## Proposed feature
+
+Add a `--record` CLI flag (or similar) that, when combined with `--proxy-url`, captures every request-response pair and writes it to the handler files under the output directory. Each captured response is stored as a named example in the handler, so subsequent requests are served from the recorded data without proxying.
+
+A `Record and Replay` usage pattern document would describe:
+- When to use it: you want realistic responses without writing handlers by hand, and the real API is available at least once
+- How to record: start Counterfact with `--proxy-url` and `--record`, then exercise the relevant API paths
+- How to replay: restart without `--proxy-url`; all recorded responses are served from the generated handlers
+- Consequences: recorded responses go stale when the real API changes; good for bootstrapping, not for long-lived mocks
+
+## Acceptance criteria
+
+- [ ] A `--record` (or equivalent) CLI flag is implemented that writes captured responses to handler files
+- [ ] `docs/patterns/record-and-replay.md` is added following the established pattern format (Context, Problem, Solution, Example, Consequences, Related Patterns)
+- [ ] The new pattern is linked in `docs/usage-patterns.md`
+- [ ] The reference doc is updated to describe the new CLI flag

.github/issue-proposals/docs-pattern-webhook-simulation.md

@@ -0,0 +1,38 @@
+---
+title: "docs: add Webhook Simulation usage pattern"
+parentIssue: 1805
+labels:
+  - documentation
+  - enhancement
+assignees: []
+milestone:
+---
+
+Add a usage pattern documenting how to simulate webhooks and push events from a Counterfact mock to a client application.
+
+## Context
+
+Many modern APIs are not purely request/response. They also push data to clients via webhooks (HTTP callbacks), Server-Sent Events (SSE), or WebSocket messages. Examples include Stripe's payment webhooks, GitHub's repository event hooks, and Slack's event subscriptions.
+
+Counterfact currently has no built-in mechanism to initiate outbound HTTP calls or push events to a client. Developers building or testing webhook consumers have to either hit the real API or write a separate one-off script to send fake webhook payloads.
+
+## Proposed feature
+
+Add a way to trigger outbound HTTP calls from a Counterfact mock — for example, a `$.webhook(url, payload)` helper available in handlers or via the REPL. Combined with the existing REPL, this would allow developers to simulate the full webhook lifecycle interactively:
+
+1. Client subscribes to a webhook by calling `POST /webhooks` on the mock
+2. Developer triggers the event from the REPL: `client.post("/webhooks/trigger", { event: "payment.succeeded", ... })`
+3. Counterfact sends an HTTP POST to the registered callback URL with the event payload
+
+A `Webhook Simulation` pattern document would describe:
+- When to use it: you are building a webhook consumer and need to test it locally without a real event source
+- How to register a callback URL in the mock's context on subscription
+- How to trigger an outbound call from the REPL or a handler
+- Consequences and limitations: the callback URL must be reachable from the mock's process; production webhook signatures are not simulated unless explicitly added to the handler
+
+## Acceptance criteria
+
+- [ ] An outbound-call mechanism (e.g., `$.webhook()` or `$.emit()`) is implemented and documented
+- [ ] `docs/patterns/webhook-simulation.md` is added following the established pattern format
+- [ ] The new pattern is linked in `docs/usage-patterns.md`
+- [ ] The reference doc is updated to describe the new API