@databehave/server 0.1.1 → 0.1.3

package/docs/admin/overrides.md

@@ -1,23 +0,0 @@
-# Overrides
-
-## Matchers
-
-```jsonc
-{ "kind": "exact",  "method": "POST", "path": "/api/v1/example" }  // METHOD + path
-{ "kind": "path",   "path":   "/api/v1/example" }                  // any method
-{ "kind": "global" }                                                // every route
-```
-
-Resolution priority (first match wins): `exact` → `path` → `global`.
-
-## Sticky override resolution
-
-For each request, the dispatcher consults sources in this order — first
-hit wins:
-
-1. `x-mock-*` request headers (per-request, never stored).
-2. Sticky `exact` override (METHOD + path).
-3. Sticky `path` override (any method).
-4. Sticky `global` override.
-5. Existing `mockMode` resolution (see [../config/mock-mode.md](../config/mock-mode.md)).
-6. Passthrough — the real handler runs.

package/docs/admin/rest-api.md

@@ -1,90 +0,0 @@
-# REST endpoints
-
-All paths are relative to `${admin.path}` (default `/databehave`).
-Successful POSTs return `201`; missing scenarios return `404`.
-
-| Method   | Path                              | Body                              | Response                                |
-| -------- | --------------------------------- | --------------------------------- | --------------------------------------- |
-| `GET`    | `{path}`                          | —                                 | UI HTML (also `{path}/`)                |
-| `GET`    | `{path}/ui.js`                    | —                                 | UI script bundle                        |
-| `GET`    | `{path}/ui.css`                   | —                                 | UI stylesheet                           |
-| `GET`    | `{path}/openapi-routes`           | —                                 | `{ routes: {method,path,summary?,source}[], discoveredAt }` (merged: OAS + hand-written handlers; OAS wins on duplicates; `source` is `'openapi'` or `'handler'`) |
-| `GET`    | `{path}/openapi.json`             | —                                 | Raw OpenAPI JSON document (only when configured; `404` otherwise) |
-| `GET`    | `{path}/overrides`                | —                                 | `{ overrides: StickyOverride[] }`       |
-| `POST`   | `{path}/overrides`                | `{ matcher, mode, description? }` | `201 { id, override }`                  |
-| `DELETE` | `{path}/overrides`                | —                                 | `{ cleared: N }`                        |
-| `DELETE` | `{path}/overrides/:id`            | —                                 | `200` or `404`                          |
-| `GET`    | `{path}/scenarios`                | —                                 | `{ scenarios: [{ name, count, created }] }` |
-| `POST`   | `{path}/scenarios`                | `{ name, overrides? }`            | `201 { scenario }` (snapshots current if `overrides` omitted) |
-| `GET`    | `{path}/scenarios/:name`          | —                                 | `{ scenario: { name, overrides[] } }` or `404` |
-| `DELETE` | `{path}/scenarios/:name`          | —                                 | `200` or `404`                          |
-| `POST`   | `{path}/scenarios/:name/load`     | —                                 | `{ loaded: N }` or `404`                |
-
-Curl examples:
-
-```sh
-# add a sticky 500 to one route
-curl -sS -X POST http://127.0.0.1:8000/databehave/overrides \
-  -H 'content-type: application/json' \
-  -d '{"matcher":{"kind":"exact","method":"GET","path":"/api/v1/health"},"mode":{"kind":"http-status","status":500}}'
-
-# list active overrides
-curl -sS http://127.0.0.1:8000/databehave/overrides
-
-# clear everything
-curl -sS -X DELETE http://127.0.0.1:8000/databehave/overrides
-
-# save the current overrides as a scenario, then load it
-curl -sS -X POST http://127.0.0.1:8000/databehave/scenarios \
-  -H 'content-type: application/json' -d '{"name":"all-500"}'
-curl -sS -X POST http://127.0.0.1:8000/databehave/scenarios/all-500/load
-```
-
-## Caching
-
-`GET {path}/openapi.json` is served with `Cache-Control: no-store`.
-The OpenAPI document is the contract the admin UI's route picker
-displays — caching is incorrect when the JSONC config is reloaded
-between requests in dev.
-
-`GET {path}/openapi-routes` (the merged OAS + hand-written list) is
-freshly assembled per request and unconditionally non-cacheable;
-no caching headers are emitted.
-
-## Error envelope
-
-Admin REST responses use a single error shape:
-
-```jsonc
-{ "error": "<machine code>", "detail": "<human-readable, optional>" }
-```
-
-| Status | Example body | When |
-| ------ | ------------ | --- |
-| `400`  | `{"error":"invalid_json"}` | POST body could not be parsed as JSON. |
-| `400`  | `{"error":"validation_failed","detail":"matcher.kind must be 'exact'"}` | Body parsed but failed schema validation. |
-| `404`  | `{"error":"not_found"}` | Scenario name / override id missing. |
-| `405`  | `{"error":"method_not_allowed"}` | Path matched but method is not registered. |
-| `500`  | `{"error":"internal_error","detail":"<message>"}` | Unhandled exception in admin code (the message is the underlying `Error.message`). |
-
-The envelope is identical to the [non-admin error envelope](../errors.md)
-so a single client-side handler can decode both kinds of responses.
-
-## `400 invalid x-mock-* header`
-
-When admin-mode is enabled with `headers: true` (the default) and a
-request carries an `x-mock-*` header that fails parsing, the inject
-hook returns `400` **before** the underlying route runs:
-
-```text
-HTTP/1.1 400 Bad Request
-content-type: application/json
-x-mock-injected: header-error
-
-{"error":"invalid x-mock-* header","detail":"<parse error>"}
-```
-
-The `x-mock-injected: header-error` response header is the
-observability signal that the rejection came from header parsing
-rather than the user's handler returning a 400 of its own — see
-[headers.md#x-mock-injected-response-header](./headers.md#x-mock-injected-response-header).

package/docs/admin/scenarios.md

@@ -1,28 +0,0 @@
-# Scenarios
-
-A scenario is a named snapshot of the current sticky overrides set, stored
-as JSON under `admin.scenariosDir` (default `${cwd}/mock-scenarios`).
-
-- Names are restricted to `[A-Za-z0-9_-]{1,64}`.
-- Writes are atomic (`tmp` + `rename`).
-- A missing directory is treated as "no scenarios", not an error; the
-  directory is created on first write.
-- `POST {path}/scenarios/:name/load` clears the active overrides and
-  re-adds the snapshot in one step.
-
-File format:
-
-```json
-{
-  "name": "all-500",
-  "created": "2026-05-28T10:00:00.000Z",
-  "overrides": [
-    {
-      "id": "ovr_…",
-      "matcher": { "kind": "global" },
-      "mode":    { "kind": "http-status", "status": 500 },
-      "createdAt": "2026-05-28T10:00:00.000Z"
-    }
-  ]
-}
-```

package/docs/cli.md

@@ -1,76 +0,0 @@
-# CLI
-
-```sh
-databehave-server databehave.jsonc      # explicit path (required)
-databehave-server --open databehave.jsonc
-databehave-server --help
-```
-
-The positional `<config>` argument is **required**. The CLI does not
-fall back to a default file — invoking `databehave-server` with no
-argument prints the usage text to `stderr` and exits with code **2**
-(bad usage). The same exit code is used for unknown flags, which
-additionally print:
-
-```txt
-[@databehave/server] unknown option(s): <flag>
-```
-
-Flags:
-
-| Flag | Effect |
-| --- | --- |
-| `--open` | After the server is listening, open the admin UI in the default browser. No-op (with a log line) when `admin` is absent or `admin.enabled !== true`. |
-| `-h`, `--help` | Print usage and exit `0`. |
-
-Exit codes:
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Clean shutdown (SIGINT / SIGTERM). |
-| `1` | Bootstrap failure (config load, listen, etc.). |
-| `2` | Bad usage (missing `<config>`, unknown flag). |
-
-On successful boot the CLI loads the file, builds the config, calls
-`listen()` using the `server` section, and prints exactly:
-
-```text
-[@databehave/server] listening on http://${host}:${port}
-```
-
-via `console.info` (so it lands on stdout, not stderr). When
-`admin.enabled` is also true, a second line follows on the same
-stream:
-
-```text
-[@databehave/server] admin panel ready at http://${host}:${port}${admin.path} (dev mock — disable in production)
-```
-
-Walk errors and empty-schema reports print to `stderr` via
-`console.warn`. `SIGINT` and `SIGTERM` trigger a graceful shutdown
-via `RunHandle.close()`.
-
-Set `MOCK_SERVER_HOST` / `MOCK_SERVER_PORT` to override `server.host`
-/ `server.port` when the config uses `${VAR}` interpolation.
-
-## `--open` browser launcher
-
-`--open` and `admin.openBrowserOnStart: true` (in the JSONC
-config) both trigger the same launcher — they are ORed. With
-`admin.enabled: false`, the flag prints a log line and is a
-no-op:
-
-```text
-[@databehave/server] --open requested but admin.enabled is false; skipping
-```
-
-The launcher spawns a platform command, never a network request:
-
-| Platform        | Command |
-| --------------- | --- |
-| `darwin` (macOS) | `open <url>` |
-| `win32`          | `cmd /c start "" <url>` |
-| `linux` / other  | `xdg-open <url>` |
-
-Spawn failures (missing `xdg-open`, headless CI) are caught and
-printed as a warn line; the server keeps running.

package/docs/config/admin.md

@@ -1,62 +0,0 @@
-# `admin`
-
-Opt-in admin panel + REST API for sticky error overrides and per-request
-`x-mock-*` header injection. Default **off** — when absent or
-`enabled: false` the kit serves nothing under the mount path and ignores
-`x-mock-*` headers (zero behaviour change for existing consumers). When
-enabled the kit writes a one-line stdout banner on boot (see
-[admin/index.md#security-notes](../admin/index.md#security-notes) for the
-canonical banner format) and mounts the UI + REST routes under `path`.
-
-```jsonc
-"admin": {
-  "enabled":      true,
-  "path":         "/databehave",
-  "bind":         "loopback-only",
-  "allowDestroy": true,
-  "cors":         "auto",
-  "scenariosDir": "./mock-scenarios"
-}
-```
-
-| Field          | Default                          | Meaning |
-| -------------- | -------------------------------- | --- |
-| `enabled`      | `false`                          | Master switch. Absent or `false` = feature off. |
-| `path`         | `'/databehave'`                  | Mount point for UI + REST. Must start with `/`. |
-| `ui`           | `true`                           | Serve the admin HTML / `ui.js` / `ui.css` at `${path}`. Set `false` for a REST-only deployment (no static assets). |
-| `headers`      | `true`                           | Honour `x-mock-*` request headers. Set `false` to keep the sticky-override REST API enabled while ignoring per-request header overrides. |
-| `bind`         | `'loopback-only'`                | Refuse to enable when the server host is not loopback. Set `'any'` to opt out (CLI exits 1 if the policy is violated). |
-| `allowDestroy` | `true`                           | Honour `x-mock-destroy` / `destroy` ErrorMode. `false` → reject with HTTP 503. |
-| `cors`         | `'auto'`                         | `'auto'` \| `'any'` \| `'same-origin'` \| `{ origin }`. `'auto'` resolves to `*` on loopback, `'same-origin'` when `bind: 'any'`. |
-| `scenariosDir` | `${cwd}/mock-scenarios`          | Directory used by the file-backed scenarios endpoints. |
-| `openBrowserOnStart` | `false`                    | When `true`, spawn the platform browser opener on the admin URL after `listening`. Default off — the URL is logged but no browser is launched. ORed with the CLI's `--open` flag. |
-| `openapiBody`  | undefined                        | **Programmatic only.** Override the OpenAPI document the admin route picker advertises at `GET ${path}/openapi-routes` and `GET ${path}/openapi.json`. Accepts the raw JSON text. When omitted, the kit reuses the same OAS bytes the dispatcher loaded from `openapi:`. Useful when the admin UI should expose a different surface than the dispatcher (e.g. an internal-only spec). |
-
-> **Security.** `bind: 'loopback-only'` is the default. Setting
-> `bind: 'any'` exposes the overrides REST API and the per-request
-> `x-mock-*` headers to the network — only do this in trusted
-> environments. See [../admin/index.md#security-notes](../admin/index.md#security-notes).
-
-> **Route list.** The admin UI lists OAS routes and hand-written
-> `endpoints` together. Routes registered only via programmatic
-> `routes` are also included; OAS wins on duplicates.
-
-Full REST surface, matcher / ErrorMode reference, `x-mock-*` header
-table, sticky-override resolution priority, scenarios file format — see
-[../admin/](../admin/index.md).
-
-## Route collision detection
-
-Admin routes are mounted under `${path}` (`/openapi-routes`,
-`/overrides`, `/scenarios`, …). When a hand-written `endpoints` key
-collides with one of those admin routes, the kit refuses to boot
-rather than silently shadowing one with the other:
-
-```text
-@databehave/server: admin route GET /databehave/overrides collides with a user-declared route. Move admin.path to a free prefix or rename the user route.
-```
-
-Fix: change `admin.path` to a free prefix (`/_admin`, `/__mock`,
-…) or rename the user route. The collision check fires on every
-admin sub-route, including the static UI assets at `${path}/ui.js`
-and `${path}/ui.css`.

package/docs/config/cors.md

@@ -1,72 +0,0 @@
-# `cors`
-
-```jsonc
-"cors": {
-  "origin": ["https://app.example.com", "https://admin.example.com"],
-  "credentials": true,
-  "exposeHeaders": ["x-mock-status"],
-  "allowMethods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
-  "allowHeaders": ["content-type", "authorization"],
-  "maxAge": 86400
-}
-```
-
-All fields optional. When the `cors` section is present, @databehave/server
-handles `OPTIONS` preflight for every declared route and attaches
-CORS headers on every response.
-
-## `cors.origin`
-
-`origin` accepts:
-
-- **omitted** — the loader installs a reflector that echoes the
-  request `Origin` back (or `*` when the request has none).
-- **`string`** — single allowed origin. Treated as a one-entry
-  allowlist.
-- **`string[]`** — explicit allowlist. The request `Origin` is matched
-  case-insensitively against the list; only an exact match is echoed
-  back. Off-allowlist requests get an empty `Access-Control-Allow-Origin`
-  value, which the response builder omits entirely (the de-facto
-  reject signal — no header is sent).
-
-```jsonc
-"cors": {
-  "origin": "https://app.example.com",        // single origin
-  "credentials": true
-}
-```
-
-```jsonc
-"cors": {
-  "origin": ["https://app.example.com", "https://staging.example.com"],
-  "credentials": true
-}
-```
-
-For a fully custom reflector (e.g. regex matching), use the
-programmatic API — `cors.origin` there accepts a `(o: string) => string`
-function.
-
-## `Vary: Origin`
-
-Whenever the `cors` section is present, the response decorator adds
-`Vary: Origin` to every response (preflight included). This prevents
-reverse proxies and CDNs from caching one origin's response and serving
-it to another after the body diverges on the request `Origin`.
-
-When a handler also sets `Vary` (e.g. `Vary: Accept-Encoding`), the two
-values are **merged additively**, not replaced. Tokens are deduplicated
-case-insensitively, the first occurrence's casing is preserved, and a
-literal `*` short-circuits to just `*` (HTTP semantic: "varies on every
-possible header").
-
-```ts
-// Handler returns Vary: Accept-Encoding
-// CORS adds      Vary: Origin
-// On the wire    Vary: Accept-Encoding, Origin
-```
-
-Other CORS response headers (`Access-Control-Allow-Origin`,
-`Access-Control-Allow-Credentials`, `Access-Control-Expose-Headers`)
-follow the standard "handler wins" merge rule — only `Vary` is
-additive.

package/docs/config/endpoints.md

@@ -1,162 +0,0 @@
-# `endpoints`
-
-The route table. Keys are `"METHOD <path>"`. Values pick one of three
-forms:
-
-## 1. String (handler module path)
-
-```jsonc
-"GET products/list": "./src/routes/products/get/list.js"
-```
-
-Shorthand for `{ "handler": "..." }`. The module must:
-
-- be loadable via the runtime's native ESM `import()`,
-- `export default` a `Handler` (a function returning a
-  `MockResponse` POJO, sync or async).
-
-CommonJS modules are not supported by the JSONC loader's resolver —
-its dynamic-import path runs through `pathToFileURL()` and assumes
-ESM. If the module's default export is missing or is not a function,
-boot fails with:
-
-```text
-@databehave/server/config: ./src/routes/products/get/list.js (mapped to GET /api/v1/products/list) has no default-exported handler function
-```
-
-### Handler resolution
-
-Config files reference handlers by their compiled `.js` path so they
-stay valid for production `tsc`-built deployments. In dev / test
-scenarios where only the TypeScript source exists on disk, the
-resolver falls back to a sibling extension automatically — `.js`
-becomes `.ts`, `.tsx`, `.mts`, or `.cts` (in that order) — so test
-runners that register a TS loader (`vitest`, `tsx`, `ts-node`) pick
-the right file without any config change.
-
-Set `DATABEHAVE_PREFER_TS=1` to **prefer** `.ts` siblings over the
-declared `.js` even when both exist on disk. Useful in dev when an
-outdated `dist/` is still around and would otherwise win. The
-variable accepts only the literal string `"1"`; any other value
-(including `true`) is treated as off.
-
-## 2. Handler object
-
-```jsonc
-"POST products/bulk-update": {
-  "handler": "./src/routes/products/update/bulk-update.js",
-  "status": 500
-}
-```
-
-The optional `status` field is a shortcut that registers an entry in
-`mockMode.pathOverrides` for this route. Use it to force an error
-status without editing the handler.
-
-## 3. Static response
-
-```jsonc
-"GET /health": {
-  "response": {
-    "status": 200,
-    "json":   { "ok": true },
-    "headers": { "cache-control": "no-store" }
-  }
-}
-```
-
-No handler module is loaded; the response is returned verbatim. Use
-`"empty": true` instead of `"json"` for an empty body.
-
-### `EndpointResponse` fields
-
-| Field     | Required | Meaning |
-| --------- | -------- | --- |
-| `status`  | yes      | HTTP status integer. Boot fails with `endpoints["KEY"].response.status must be a number` if missing or non-numeric — there is no implicit `200`. |
-| `json`    | no       | JSON body. Mutually exclusive with `empty`. May be any JSON value (`null`, `[]`, `{}` are all valid). When omitted on a non-`empty` response the body is `null`. |
-| `empty`   | no       | When `true`, the response carries no body. Boot fails with `endpoints["KEY"].response.empty must be a boolean` if the value is non-boolean. |
-| `headers` | no       | Plain `Record<string, string>` merged into the response. Non-string values raise `endpoints["KEY"].response.headers["H"] must be a string` at boot. Header keys are case-preserved as written. |
-
-`handler` and `response` are mutually exclusive. Setting both raises:
-
-```text
-@databehave/server/config: endpoints["KEY"] cannot have both "handler" and "response"
-```
-
-An empty `{}` value is also rejected:
-
-```text
-@databehave/server/config: endpoints["KEY"] must have either "handler" or "response"
-```
-
-A `status` field next to `response` (instead of inside it) is rejected
-with a hint pointing at the correct location:
-
-```text
-@databehave/server/config: endpoints["KEY"].status cannot be combined with "response" (put status inside response)
-```
-
-## Programmatic `handlers` override
-
-`loadConfig(path, { handlers })` accepts an explicit
-module-path → function map that short-circuits the dynamic `import()`
-for matching keys. Use case: test environments (vitest under plain
-Node 18) that cannot load `.ts` source files through native
-`import()`. Construct the map via static imports or
-`import.meta.glob('eager')`, then pass it in.
-
-```ts
-import { loadConfig } from '@databehave/server'
-import healthHandler from './src/routes/health.ts'
-
-await loadConfig('./databehave.jsonc', {
-  handlers: {
-    './src/routes/health.js': healthHandler,
-  },
-})
-```
-
-Keys are canonicalised before lookup: a leading `./` is stripped,
-repeated `/` are collapsed, and the trailing
-`.js` / `.mjs` / `.cjs` / `.ts` / `.tsx` / `.mts` / `.cts` is dropped
-— so `./src/routes/health.js`, `src/routes/health`, and
-`./src/routes/health.ts` all collapse to the same lookup key.
-Handlers not present in the map fall back to dynamic import. Values
-that are not functions raise at boot:
-
-```text
-@databehave/server/config: handlers override for "./src/routes/health.js" (mapped to GET /health) is not a function (got TYPE)
-```
-
-## Programmatic `logger` injection
-
-`loadConfig(path, { logger })` redirects non-fatal
-warnings (OAS walker errors, empty schemas, mock-mode header
-diagnostics) to a custom sink. Defaults to `console.warn`. Inject a
-no-op logger from tests to silence the output, or a structured logger
-in production:
-
-```ts
-await loadConfig('./databehave.jsonc', {
-  logger: { warn: (m) => myLogger.warn({ src: 'databehave', m }) },
-})
-```
-
-The injected logger only catches warnings emitted while loading the
-config and wiring the OpenAPI / mock-mode adapters — it does not
-intercept access logs (those go through the [`log`](./log.md)
-config) or per-request `console.warn` calls from user handlers.
-
-## `basePath` collisions
-
-When the JSONC config sets `basePath`, every relative endpoint key
-(e.g. `"GET products/list"`) is rewritten to absolute
-(`"GET /api/v1/products/list"`). If two distinct keys collide after
-rewriting — typically because one was already absolute and the other
-relative to the same final path — the loader fails fast at boot:
-
-```text
-@databehave/server/config: endpoints keys "GET /api/v1/products/list" and "GET products/list" both resolve to "GET /api/v1/products/list" after applying basePath
-```
-
-There is no last-write-wins fallback. Pick one form per route.

package/docs/config/index.md

@@ -1,107 +0,0 @@
-# Configuration reference
-
-`@databehave/server` is configured by one file (`databehave.jsonc`) or one
-`Config` object passed to `createServer`. This page covers
-the file form; the programmatic form mirrors it field-for-field.
-
-## File format
-
-- Extension can be `.json` or `.jsonc`. Either way, JSONC features are
-  accepted:
-  - `// line` comments
-  - `/* block */` comments
-  - trailing commas
-- Every string value supports `${VAR}` and `${VAR:default}` env
-  interpolation. Missing env without default → empty string.
-- Variable names accept ASCII letters, digits, and `_`, with the
-  leading character restricted to a letter or `_`. Lowercase and
-  mixed-case names are allowed (`${path}`, `${myVar}`); the loader
-  does not require ALL_CAPS shell convention.
-- Every relative path is resolved against the **directory of the
-  config file**.
-
-## Environment variables (process-level)
-
-Two env vars influence boot behaviour beyond `${VAR}` interpolation:
-
-| Variable | Effect |
-| --- | --- |
-| `NODE_ENV` | When **not** equal to `'production'`, both `defineConfig` and the JSONC loader deep-freeze the resolved config so accidental mutation throws in tests. Production skips the freeze so callers may legitimately patch the object after construction. |
-| `DATABEHAVE_PREFER_TS=1` | Prefer a `.ts` / `.tsx` / `.mts` / `.cts` sibling over the declared `.js` for handler resolution, even when the `.js` exists on disk. Useful in dev when an outdated `dist/` is still around. Default off. |
-
-## Top-level shape
-
-```jsonc
-{
-  "openapi":   "./openapi.json",        // optional, JSON only
-  "server":    { "host": "...", "port": 8000 },
-  "basePath":  "/api/v1",               // optional
-  "cors":      { /* ... */ },           // optional
-  "mockMode":  { /* ... */ },           // optional
-  "admin": { /* ... */ },           // optional, default off
-  "log":       false,                   // optional, default off
-  "endpoints": { /* ... */ }            // route → handler / response
-}
-```
-
-## Field reference
-
-- [openapi.md](./openapi.md) — `openapi:` (path to the OAS document).
-- [server.md](./server.md) — `server:` host / port and `basePath:`.
-- [endpoints.md](./endpoints.md) — `endpoints:` route table and handler shorthand forms.
-- [cors.md](./cors.md) — `cors:` block.
-- [mock-mode.md](./mock-mode.md) — `mockMode:` block.
-- [admin.md](./admin.md) — `admin:` block (config knobs only — admin behaviour is in [../admin/](../admin/index.md)).
-- [log.md](./log.md) — `log:` block.
-- [schema.md](./schema.md) — `schema:` (auto-schema config knobs — auto-mode behaviour is in [../openapi/auto-schema.md](../openapi/auto-schema.md)).
-- [validation.md](./validation.md) — `validation:` block.
-
-For the CLI that consumes the `server` section, see [../cli.md](../cli.md).
-
-## Programmatic `Config`
-
-```ts
-import { createServer, defineConfig } from '@databehave/server'
-
-const config = defineConfig({
-  routes: {
-    'GET /api/v1/ping': () => ({ json: { ok: true } }),
-  },
-  hooks: {
-    onRequest:  (req) => { /* short-circuit by returning a MockResponse */ },
-    onResponse: (req, res) => res,
-    onError:    (req, err) => ({ status: 500, json: { error: true } }),
-  },
-  cors: { origin: (o) => o || '*', credentials: true },
-  openapi: undefined,                   // pass JSON OAS text here to enable
-  onOpenApiWalkError:   (m, p, err) => console.warn(`walk failed: ${m} ${p}`, err),
-  onOpenApiEmptySchema: (m, p, s) => console.warn(`empty schema: ${m} ${p} ${s}`),
-})
-
-const server = createServer(config)
-```
-
-`defineConfig` is an identity function — present for IDE support, it
-gives you the strict `Config` type inline. When `NODE_ENV !==
-'production'` it also deep-freezes the returned config so accidental
-mutation (e.g. `config.routes['GET /x'] = …`, pushing into
-`cors.allowMethods`) throws in tests instead of silently corrupting the
-running server. Handler functions are intentionally left mutable — freeze
-stops at function boundaries. Production skips the freeze so callers may
-legitimately patch the object for env-specific wiring.
-
-## Programmatic API surface
-
-Everything reachable from the package entry point. Every field above
-maps to a typed member of `Config` (see the source
-declaration in `src/types.ts`).
-
-| Export | What it is |
-| --- | --- |
-| `createServer(config)` | Build a `Server` from an in-memory config. Returns `{ fetch, listen }`. The HTTP runtime is `node:http` ↔ Web Fetch under the hood. |
-| `defineConfig(config)` | Identity helper for IDE intellisense + dev-mode deep-freeze (see above). |
-| `loadConfig(path, opts?)` | Read a JSONC file from disk and resolve every handler module. `opts.handlers` short-circuits dynamic `import()` (test-friendly bypass — see [endpoints.md](./endpoints.md#programmatic-handlers-override)); `opts.logger` redirects walker / mock-mode warnings to your sink (defaults to `console.warn`). |
-| `run({ config, open? })` / `RunHandle` | One-call boot: load JSONC, build the server, bind the listen port, optionally open the admin URL. `RunHandle.close()` is idempotent. Used by both the CLI and direct library consumers so log lines and error model match exactly. |
-| `seedFor({ endpoint, from?, dayOffset?, extra? })` | Pure helper for building deterministic databehave seed strings (`<endpoint>|<key>=<val>|date=<YYYY-MM-DD>|day=<n>`). Re-exported so consumers can derive their own seeds without reimplementing the format. |
-| `resolveStatus` / `MockModeConfig` / `MockModeLogger` | `resolveStatus(method, path, config)` is exported for unit tests. `MockModeConfig` (and its `logger` sink `MockModeLogger`) is the type of `JsonConfig.mockMode`. The wiring (`buildMockModeHooks`, `BodyResolver`, `MockModeHooks`) is internal — set `mockMode.enabled: true` in JSONC. |
-| `Config` and sibling types (`Method`, `MockRequest`, `MockResponse`, `Cors`, `Handler`, `ListenOptions`, `Server`, `AdminModeConfig`, `ErrorMode`, …) | Strict type declarations exported from `src/types.ts` / `src/admin/admin-types.ts`. |

package/docs/config/log.md

@@ -1,43 +0,0 @@
-# `log`
-
-Opt-in per-request access log written to **stdout**. Off by default —
-no output and no per-request overhead.
-
-```jsonc
-"log": true                                // shorthand: { access: true }
-```
-
-Or as an object:
-
-```jsonc
-"log": {
-  "access":       true,                    // default true when object given
-  "includeAdmin": false,                   // log admin-panel hits too
-  "colors":       "auto",                  // 'auto' | 'always' | 'never'
-  "format":       "pretty"                 // 'pretty' | 'json'
-}
-```
-
-| Field          | Default     | Meaning |
-| -------------- | ----------- | --- |
-| `access`       | `true`      | One line per request when `true`. |
-| `includeAdmin` | `false`     | When `true`, log hits to `admin.path/*`. |
-| `colors`       | `'auto'`    | `'auto'` honours `process.stdout.isTTY`. No effect on `json` format. |
-| `format`       | `'pretty'`  | `'pretty'` (ANSI one-liner) or `'json'` (newline-terminated object). |
-
-Sticky / header-driven overrides are flagged with
-`[override:<mode.kind>]` (pretty) or `"override":"<kind>"` (json).
-
-Pretty (colours stripped):
-
-```txt
-GET /api/v1/health → 200 4 ms · 56
-POST /api/v1/widgets/copy → 500 2 ms · 78 [override:http-status]
-```
-
-JSON:
-
-```json
-{"t":"2026-05-28T10:00:00.000Z","method":"GET","path":"/api/v1/health","status":200,"ms":4,"bytes":"56"}
-{"t":"2026-05-28T10:00:00.000Z","method":"POST","path":"/api/v1/widgets/copy","status":500,"ms":2,"bytes":"78","override":"http-status"}
-```