@databehave/server 0.1.0 → 0.1.2

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"}
-```

package/docs/config/mock-mode.md

@@ -1,84 +0,0 @@
-# `mockMode`
-
-```jsonc
-"mockMode": {
-  "enabled":             true,
-  "header":              "x-mock-status",
-  "healthPaths":         ["/health", "/healthz", "/api/v1/health"],
-  "defaultStatus":       200,
-  "allowHeaderOverride": false,
-  "pathOverrides": {
-    "GET /api/v1/products/list": 500,
-    "/api/v1/admin/users-delete": 401
-  }
-}
-```
-
-| Field | Default | Meaning |
-| --- | --- | --- |
-| `enabled` | `false` | Master switch. `false` / absent = feature off. |
-| `header` | `'x-mock-status'` | Response header tagged with the resolved status. Also the request header consulted when `allowHeaderOverride: true`. |
-| `healthPaths` | `[]` | Paths exempt from injection (typically health probes). |
-| `defaultStatus` | undefined | Status applied when no override matches. Omit for passthrough. |
-| `allowHeaderOverride` | `false` | When `true`, an incoming request may flip the mocked status by sending the same `header` (default `x-mock-status: 500`). Disabled by default so production-style mock servers don't expose status injection to arbitrary clients. |
-| `pathOverrides` | `{}` | Per-route status overrides. Keys are `"METHOD /path"` or `"/path"` (path must start with `/`). Values are HTTP status codes. |
-| `logger` | `console` | Programmatic-only sink for non-fatal mock-mode diagnostics (e.g. out-of-range header overrides). Pass the host application's logger to keep mock-server output in one place. Not settable from JSONC. |
-
-## Resolution priority (canonical)
-
-For each request, mock-mode picks a status in this order — first hit
-wins. When `admin.enabled` is also set, the admin inject hook
-runs **before** mock-mode and can short-circuit any of the steps
-below; see [../admin/overrides.md#sticky-override-resolution](../admin/overrides.md#sticky-override-resolution)
-for the unified pipeline.
-
-1. Request `header` value (only when `allowHeaderOverride: true`).
-2. `pathOverrides["<METHOD> <path>"]` (method-scoped exact match).
-3. `pathOverrides["<path>"]` (any-method exact match).
-4. `defaultStatus`.
-5. Passthrough — the real handler runs.
-
-`healthPaths` short-circuits the entire chain: matching paths are
-served by their handler regardless of any override.
-
-## `pathOverrides` key validation
-
-Keys are validated at config load. Malformed keys raise at boot
-(via `AggregateError` so every gap surfaces at once) — there is no
-silent "this key never matches" failure mode.
-
-- Keys must match `(?:METHOD\s+)?/path`. The optional method prefix
-  is one of `GET POST PUT DELETE PATCH HEAD OPTIONS`. The path must
-  start with `/` and contain no whitespace.
-- Method names are normalised to upper-case: `"get /api/x"`,
-  `"GET /api/x"`, and `"Get /api/x"` all canonicalise to
-  `"GET /api/x"` so a lower-case key still matches.
-- Values must be finite numbers (HTTP status codes).
-
-## Body resolution
-
-When a non-passthrough status `N` fires:
-
-1. `status === 204` → empty body.
-2. The body resolver returns the OAS `responses[N]` schema mock when
-   the route is OAS-walker-backed and a response schema exists for
-   that status (see [../openapi/fallback.md#per-status-body-generators](../openapi/fallback.md#per-status-body-generators)).
-3. Fallback envelope `{ error: true, status: N }`.
-
-The configured `header` (default `x-mock-status`) is always tagged on
-the response with the resolved status code so a client can confirm
-which override fired.
-
-## `allowHeaderOverride` validation
-
-When the request header is set but the value is not a finite integer
-in `[200, 600)`, the value is **ignored** and a single `warn` line
-is emitted via `logger` (default `console`) so the typo is visible
-without breaking legitimate clients that ship the header for other
-reasons:
-
-```text
-@databehave/server/mock-mode: ignored x-mock-status="abc" (must be an integer in [200, 600))
-```
-
-A per-endpoint shortcut also exists — see [endpoints.md](./endpoints.md).

package/docs/config/openapi.md

@@ -1,8 +0,0 @@
-# `openapi`
-
-Path (relative to the config file) to an OpenAPI 3.x document.
-**JSON only** — convert YAML first via `yq -o=json openapi.yaml > openapi.json`.
-When set, the walker registers fallback handlers for every
-`paths.*.<method>` not declared in `endpoints`.
-
-See [../openapi/fallback.md](../openapi/fallback.md) for walker behaviour.

package/docs/config/schema.md

@@ -1,34 +0,0 @@
-# `schema`
-
-Top-level field that opts the server into **auto-schema mode** — every
-endpoint absent from `endpoints` is served from data generated by
-`@databehave/schema`'s `mock()` engine, derived directly from your
-OpenAPI document.
-
-**Minimal:**
-
-```jsonc
-{
-  "openapi": "./openapi.json",
-  "schema": { "enabled": true }, // "enabled" gates auto-mode; defaults equivalent to { "seed": "stable" }
-  "endpoints": {}
-}
-```
-
-**With knobs:**
-
-```jsonc
-{
-  "openapi": "./openapi.json",
-  "schema": {
-    "enabled": true,
-    "seed": 42, // number = fixed; "stable" = derive from endpoint|query|params; "random" = fresh per request; default "stable"
-    "locale": "ja",
-    "arrayCount": 20 // default array length when the OAS lacks minItems
-  }
-}
-```
-
-For the architecture, install path, missing-install error, precedence,
-and default-behaviour rules, see
-[../openapi/auto-schema.md](../openapi/auto-schema.md).