@databehave/server 0.1.1 → 0.1.2

package/package.json

@@ -1,19 +1,12 @@
 {
   "name": "@databehave/server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A JSON file config-driven mock server",
-  "keywords": [
-    "mock",
-    "mock-server",
-    "openapi",
-    "databehave",
-    "testing",
-    "http",
-    "json",
-    "jsonc"
-  ],
-  "license": "MIT",
+  "type": "module",
   "author": "ochairo",
+  "license": "MIT",
+  "homepage": "https://github.com/ochairo/databehave/tree/main/packages/server#readme",
+  "readme": "README.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ochairo/databehave.git",
@@ -22,8 +15,18 @@
   "bugs": {
     "url": "https://github.com/ochairo/databehave/issues"
   },
-  "homepage": "https://github.com/ochairo/databehave/tree/main/packages/server#readme",
-  "type": "module",
+  "keywords": [
+    "mock-server",
+    "api-mock",
+    "openapi-mock",
+    "http-mock",
+    "schema-driven",
+    "test-server",
+    "json",
+    "jsonc",
+    "typescript",
+    "databehave"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -37,10 +40,9 @@
   },
   "files": [
     "dist",
-    "docs",
     "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"
@@ -60,7 +62,7 @@
     "typescript": "^6.0.3",
     "vite": "^6.4.3",
     "vitest": "^3.2.6",
-    "@databehave/schema": "0.1.1"
+    "@databehave/schema": "0.1.2"
   },
   "publishConfig": {
     "access": "public",
@@ -69,12 +71,12 @@
   "scripts": {
     "build:admin": "vite build --config vite.admin.config.ts && mv dist/admin/ui-shell.html dist/admin/ui.html",
     "build": "pnpm run build:admin && tsc -p tsconfig.build.json && chmod +x dist/bin.js",
-    "clean": "rm -rf dist coverage dist-test",
-    "bench": "vitest bench --run",
-    "pretypecheck": "pnpm --filter @databehave/schema build",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.ui.json --noEmit",
     "test": "vitest run --coverage",
     "test:watch": "vitest",
-    "test:no-coverage": "vitest run"
+    "test:no-coverage": "vitest run",
+    "bench": "vitest bench --run",
+    "clean": "rm -rf dist coverage dist-test",
+    "pretypecheck": "pnpm --filter @databehave/schema build"
   }
 }

package/docs/admin/error-mode.md

@@ -1,14 +0,0 @@
-# `ErrorMode` reference
-
-| Kind | Minimal body | Description |
-| - | - | - |
-| `http-status` | `{"kind":"http-status","status":500}` | Force the response status. Body from OAS schema if any. |
-| `business-failure` | `{"kind":"business-failure","message":"…","extra":{ }}` | 2xx envelope `{success:false, message, …extra}`. |
-| `custom-body` | `{"kind":"custom-body","body":{…},"status":200,"contentType":"application/json"}` | Arbitrary body / status / content-type.` |
-| `empty-body` | `{"kind":"empty-body","status":204}` | Empty response body. |
-| `malformed-json` | `{"kind":"malformed-json","status":200}` | Body is literally `{` — clients see `JSON.parse` failure. |
-| `delay` | `{"kind":"delay","ms":2000,"then":{"kind":"http-status","status":500}}` | Sleep `ms`, then run `then` (or passthrough if omitted). |
-| `hang` | `{"kind":"hang"}` | Never resolve — exercises client timeout / hang detection. |
-| `destroy` | `{"kind":"destroy"}` | Drop the socket. Gated by `allowDestroy: true`. |
-
-`delay.then` cannot itself be `delay`, `hang`, or `destroy`.

package/docs/admin/headers.md

@@ -1,63 +0,0 @@
-# `x-mock-*` header reference
-
-Per-request overrides. A header beats every sticky override and is
-discarded after the request. Conflicting terminal headers, an invalid
-base64 payload, or invalid JSON return **HTTP 400** with
-`{error: "invalid …: <reason>"}` so the typo is loud.
-
-| Header                                           | ErrorMode kind         | Example value                          |
-| ------------------------------------------------ | ---------------------- | -------------------------------------- |
-| `x-mock-status`                                  | `http-status`          | `500`                                  |
-| `x-mock-business-failure`                        | `business-failure`     | `update conflict`                      |
-| `x-mock-business-failure-b64`                    | `business-failure`     | `5pON5L2c44GM…` (base64 of UTF-8)      |
-| `x-mock-business-failure-extra`                  | merged into `extra`    | base64-of-JSON object                  |
-| `x-mock-body` (+ `-status`, `-content-type`)     | `custom-body`          | base64 JSON                            |
-| `x-mock-empty` (+ `-status`)                     | `empty-body`           | `1`                                    |
-| `x-mock-malformed` (+ `-status`)                 | `malformed-json`       | `1`                                    |
-| `x-mock-delay`                                   | `delay` (wraps others) | `2000`                                 |
-| `x-mock-hang`                                    | `hang`                 | `1`                                    |
-| `x-mock-destroy`                                 | `destroy`              | `1` (rejected with 503 if `allowDestroy:false`) |
-
-Base64 is standard (not URL-safe). Non-ASCII messages must use the
-`-b64` variant — HTTP headers reject byte values > 255.
-
-```sh
-# unicode business-failure
-MSG_B64=$(printf 'cannot copy: record was modified during operation — café' | base64)
-curl -sS -X POST http://127.0.0.1:8000/api/v1/widgets/copy \
-  -H "x-mock-business-failure-b64: $MSG_B64" \
-  -H 'content-type: application/json' -d '{}'
-```
-
-## `x-mock-injected` response header
-
-Whenever the admin inject hook overrides a response — whether from
-an `x-mock-*` request header or a sticky override — the response is
-tagged with `x-mock-injected: <kind>:<source>`:
-
-| `kind` | Where it came from |
-| ------ | --- |
-| `http-status`, `business-failure`, `custom-body`, `empty-body`, `malformed-json`, `delay`, `hang`, `destroy` | The ErrorMode that fired. |
-| `header-error` | Header parsing failed; the request was rejected with 400. |
-
-| `source` | Meaning |
-| -------- | --- |
-| `header` | The override came from an `x-mock-*` request header. |
-| `sticky` | The override came from a `POST /overrides` sticky entry. |
-
-Examples:
-
-```text
-x-mock-injected: http-status:header
-x-mock-injected: business-failure:sticky
-x-mock-injected: header-error
-```
-
-This is the single observability signal that proves an override
-fired — without it, a 500 from the mock server is indistinguishable
-from a 500 the real handler would have produced. Tests assert on
-this header to verify a mock pathway, and dashboards filter by it
-to separate injected failures from organic ones.
-
-`header-error` carries no `:source` suffix because the rejection
-happens before the override taxonomy applies.

package/docs/admin/index.md

@@ -1,111 +0,0 @@
-# Admin mode
-
-Opt-in error-injection panel + REST API + per-request `x-mock-*` headers,
-mounted under a configurable base path (default `/databehave`). All routes,
-headers, and behaviours below are served **only** when
-`admin.enabled: true`. With the flag off, the kit behaves exactly as
-the pre-`admin` versions did — no admin routes, no header parsing, no
-overrides store.
-
-For the `admin` config schema (`enabled`, `path`, `bind`, `cors`,
-`allowDestroy`, `scenariosDir`) see
-[../config/admin.md](../config/admin.md).
-
-## Sub-pages
-
-- [rest-api.md](./rest-api.md) — every `__databehave/*` endpoint.
-- [headers.md](./headers.md) — every `x-mock-*` request header.
-- [overrides.md](./overrides.md) — sticky overrides, matchers, resolution priority.
-- [scenarios.md](./scenarios.md) — scenario file format and lifecycle.
-- [error-mode.md](./error-mode.md) — `ErrorMode` reference.
-
-## Quick start
-
-```jsonc
-// databehave.jsonc
-{
-  "openapi":   "./openapi.json",
-  "basePath":  "/api/v1",
-  "endpoints": { /* ... */ },
-  "admin": { "enabled": true }
-}
-```
-
-```sh
-npx @databehave/server databehave.jsonc
-# stdout: [@databehave/server] admin panel ready at http://127.0.0.1:8000/databehave (dev mock — disable in production)
-```
-
-Point a browser at `http://127.0.0.1:8000/databehave`.
-
-Programmatic equivalent:
-
-```ts
-import { createServer } from '@databehave/server'
-
-const server = createServer({
-  routes: { 'GET /api/v1/ping': () => ({ json: { ok: true } }) },
-  admin: { enabled: true },
-})
-await server.listen({ port: 8000, host: '127.0.0.1' })
-```
-
-## UI overview
-
-The UI is shipped as `dist/admin/{ui.html, ui.js, ui.css}` and rendered
-with native Web Components — zero runtime framework, no CDN dependency.
-English-only.
-
-- **Endpoint list** — populated from `GET {path}/openapi-routes`, grouped by
-  OpenAPI tag, filterable. Each row opens an inject panel that pre-fills
-  from any existing sticky override targeting the same route.
-- **Global override modal** — top-bar button. Owns `kind: 'global'`
-  overrides (the per-endpoint inject panel only offers `exact` and `path`
-  scopes).
-- **Active overrides side panel** — right side. Global rows are tagged
-  `GLOBAL` and float above `path` / `exact` rows. A floating bottom-right
-  pill shows the active count.
-- **Try-it-out** — runs the live request through the dispatcher so the
-  injected override actually applies. The response viewer renders the
-  body as a collapsible **schema tree** for JSON responses (each
-  property is a fold-able row) and falls back to a raw text panel for
-  non-JSON bodies.
-- **Scenarios menu** — list, save (snapshot of the current overrides),
-  load, and delete named scenarios from disk.
-- **Toasts** — successful saves, deletes, and override-create actions
-  fire a top-right toast (`success` / `error` / `info` variants);
-  failures show the REST [error envelope](./rest-api.md#error-envelope)
-  detail verbatim.
-- **Keyboard** — `/` and `Cmd/Ctrl+K` focus the route filter, `Esc`
-  closes modals, `?` shows the help overlay.
-
-### Non-default `admin.path`
-
-The UI is path-agnostic. When `admin.path` is set to anything
-other than the default `/databehave`, the boot-time HTML injects a
-`window.__DATABEHAVE_BASE__ = '<path>'` shim before `ui.js` runs.
-The UI reads that constant for every REST call so the panel works
-unchanged behind a reverse proxy or a custom mount point.
-
-If you load the panel through a build of your own (rare), set
-`window.__DATABEHAVE_BASE__` yourself before importing
-`ui.js` — the script falls back to `/databehave` only when the
-constant is absent.
-
-## Security notes
-
-`admin` is a developer tool — not a hardened endpoint. Do not expose
-the admin panel to untrusted networks.
-
-- **Startup notice.** Every enabled boot writes
-  `admin panel ready at http://…/databehave (dev mock — disable in production)` to stdout. Misconfiguration is visible.
-- **`bind: 'loopback-only'` (default).** The CLI exits 1 (and
-  `server.listen()` rejects) when the configured host is not a loopback
-  address. Set `bind: 'any'` to opt out — only in trusted environments.
-- **`cors: 'auto'` (default).** Returns `Access-Control-Allow-Origin: *`
-  on loopback (so a localhost bookmarklet works) and switches to
-  `same-origin` (no CORS headers added) when `bind: 'any'`. Override with
-  `'any'`, `'same-origin'`, or `{ origin }`.
-- **`allowDestroy: true` (default).** Honours `x-mock-destroy` and the
-  matching `destroy` ErrorMode. Set `false` to reject those requests with
-  HTTP 503 instead.

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.