@databehave/server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `@databehave/server` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-03
+
+Initial public release of `@databehave/server`.
+
+### Added
+
+- JSON / JSONC config-driven mock HTTP server with hand-written and
+  OpenAPI-derived routes.
+- OpenAPI walker with auto-schema mode (optional `@databehave/schema` peer)
+  for realistic, deterministic response data.
+- Per-route override panel via opt-in admin UI; deterministic seeding
+  knobs (fixed / `stable` / `random`).
+- Per-request hooks (`onRequest`, `onResponse`, `onError`,
+  `onServerError`), CORS, opt-in inbound request validation, opt-in
+  access logs.
+- Public API renamed to drop the `DataBehaveKit` prefix; request /
+  response facades exposed as `MockRequest` / `MockResponse` to avoid
+  shadowing `globalThis.Request` / `Response`.
+- `seedFor` / `SeedInput` exported for callers deriving their own seeds.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ochairo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<div align="center">
+
+# @databehave/server
+
+<b>A JSON file config-driven mock server</b>
+
+[![npm version](https://img.shields.io/npm/v/@databehave/server.svg)](https://www.npmjs.com/package/@databehave/server)
+[![CI](https://github.com/ochairo/databehave/actions/workflows/ci.yml/badge.svg)](https://github.com/ochairo/databehave/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A520.19-brightgreen)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+</div>
+
+## Install
+
+You can install `@databehave/server` alone but to get full functionality, the recommended companion is `@databehave/schema`.
+
+```bash
+npm install @databehave/schema @databehave/server
+# or: pnpm add @databehave/schema @databehave/server
+# or: yarn add @databehave/schema @databehave/server
+```
+
+> `@databehave/schema` is declared as an optional peer dependency. Install it alongside `@databehave/server` whenever you enable auto-schema mode.
+
+## A 60-second tour
+
+**1. OpenAPI specs driven data** — realistic mock data derived from your OpenAPI document, with zero config. See [docs/openapi.md](docs/openapi.md) for the `openapi` field reference.
+
+**2. Auto-schema mode (`@databehave/schema`)** — realistic distributions, referential integrity, and deterministic seeding. See [docs/openapi/auto-schema.md](docs/openapi/auto-schema.md) for the `schema` field reference (knobs, defaults, install hint).
+
+**3. Full custom data** — hand-write response generators as modules, and point routes to them. The module exports a function that receives the request and returns a response shape. You can use `@databehave/schema` or any other data source.
+
+**4. Admin UI** You have a UI to override any route's response, with the override "sticking" until you remove it. No code change required for error injection.
+
+```jsonc
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": "8000"
+  },
+  // 1. OpenAPI specs driven data
+  "openapi": "./openapi.json",
+  // 2. Auto-schema mode (Adds @databehave/schema data generation engine to OpenAPI specs)
+  "schema": { "enabled": true },
+  // 3. Full custom data
+  "endpoints": {
+    "GET /health": { "response": { "status": 200, "json": { "ok": true } } },
+    "GET /products/list": "./src/routes/products/list.js",
+    "POST /products/bulk-update": "./src/routes/products/bulk-update.js"
+  },
+  // 4. Admin UI: http://[server.host]:[server.port]/[admin.path]
+  "admin": { "enabled": true, "path": "/databehave" },
+}
+```
+
+## Documentation
+
+### Start here
+
+- [Index](docs/index.md) — package TOC and reading order.
+- [Getting Started](docs/getting-started.md) — 5-step tutorial from install to a custom route.
+- [Troubleshooting](docs/troubleshooting.md) — symptom → cause → fix.
+
+### Reference
+
+- [Config](docs/config/index.md) — every `databehave.json` field.
+- [Config Validation](docs/config/validation.md) — opt-in inbound request validation (RFC 7807).
+- [Admin](docs/admin/index.md) — admin UI, REST endpoints, matchers, ErrorMode, `x-mock-*` headers, scenarios, security notes.
+- [OpenAPI](docs/openapi/fallback.md) — OAS fallback walker, [Auto-schema](docs/openapi/auto-schema.md), keyword parity.
+- [CLI](docs/cli.md) — `@databehave/server` CLI reference.
+- [Errors](docs/errors.md) — every user-visible error message, source-cited.
+
+### Deeper
+
+- [Design](docs/design.md) — architecture, dispatch pipeline, why the HTTP framework is hidden.
+- [Stability](docs/stability.md) — public-surface lock, SemVer triggers, contract surfaces.
+- [Recipes](docs/recipes.md) — error injection, static responses, programmatic hooks, in-process tests with `fetch()`.
+
+<br /><br />
+<div align="center">
+
+© 2026-present ochairo. See [LICENSE](LICENSE)
+
+</div>

package/dist/admin/admin-routes.d.ts

@@ -0,0 +1,42 @@
+import type { Handler, RouteKey } from '../types.js';
+import type { OverridesStore } from './overrides-store.js';
+import type { ScenariosStore } from './scenarios-store.js';
+export interface AdminListedRoute {
+    method: string;
+    path: string;
+    summary?: string;
+    /**
+     * Where this entry came from:
+     *   - 'openapi' — derived from the configured OAS document
+     *   - 'handler' — a hand-written route registered with the dispatcher
+     *                 (config.routes / `endpoints`) that has no OAS entry.
+     * OAS wins on duplicates so schema-rich rows take precedence in the UI.
+     */
+    source: 'openapi' | 'handler';
+}
+export interface AdminRoutesOptions {
+    readonly store: OverridesStore;
+    /** Mount point. Default '/databehave'. Must start with '/'. */
+    readonly basePath?: string;
+    /** Serve the UI HTML page. Default true. */
+    readonly ui?: boolean;
+    /** CORS headers added to every admin response. Empty = same-origin. */
+    readonly corsHeaders?: Readonly<Record<string, string>>;
+    /** Raw OpenAPI document text — used to populate the route picker. */
+    readonly openapiBody?: string;
+    /**
+     * Route keys registered on the dispatcher (hand-written `endpoints` /
+     * `config.routes`). Merged with the OAS-derived list so the admin UI
+     * surfaces handler-only routes that aren't in the OpenAPI document.
+     * OAS entries win on `(method, path)` collisions. Entries under
+     * `basePath` are filtered to avoid self-listing the admin routes.
+     */
+    readonly handlerRoutes?: ReadonlyArray<{
+        method: string;
+        path: string;
+    }>;
+    /** Optional scenarios store. When omitted, scenarios endpoints are not mounted. */
+    readonly scenarios?: ScenariosStore;
+}
+export declare const createAdminRoutes: (opts: AdminRoutesOptions) => Partial<Record<RouteKey, Handler>>;
+//# sourceMappingURL=admin-routes.d.ts.map

package/dist/admin/admin-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-routes.d.ts","sourceRoot":"","sources":["../../src/admin/admin-routes.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,OAAO,EAGP,QAAQ,EACT,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAwK1D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAC9B;AA2DD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAA;IACrB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACvD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxE,mFAAmF;IACnF,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;CACpC;AAED,eAAO,MAAM,iBAAiB,GAC5B,MAAM,kBAAkB,KACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CA6QnC,CAAA"}

package/dist/admin/admin-routes.js

@@ -0,0 +1,472 @@
+/**
+ * Admin REST + UI routes. Mounted under a configurable `basePath`
+ * (default `/databehave`).
+ *
+ *   GET    {basePath}                       — admin HTML page (UI shell)
+ *   GET    {basePath}/                      — same (trailing-slash equivalent)
+ *   GET    {basePath}/ui.js                 — admin UI script bundle
+ *   GET    {basePath}/ui.css                — admin UI stylesheet
+ *   GET    {basePath}/openapi-routes        — `{method, path, summary}[]`
+ *   GET    {basePath}/openapi.json          — raw OpenAPI document (404 when not configured)
+ *   GET    {basePath}/overrides             — list active sticky overrides
+ *   POST   {basePath}/overrides             — add a sticky override (201)
+ *   DELETE {basePath}/overrides             — clear all
+ *   DELETE {basePath}/overrides/:id         — remove by id (404 if missing)
+ *   GET    {basePath}/scenarios             — list saved scenarios
+ *   POST   {basePath}/scenarios             — save current overrides as a scenario
+ *   GET    {basePath}/scenarios/:name       — fetch a saved scenario
+ *   DELETE {basePath}/scenarios/:name       — delete a saved scenario
+ *   POST   {basePath}/scenarios/:name/load  — replace active overrides with the scenario
+ *
+ * CORS for these routes is controlled by `admin.cors`; the kit's
+ * server integration injects the resolved header bag here via
+ * {@link AdminRoutesOptions.corsHeaders}.
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isValidScenarioName } from './scenarios-store.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const UI_HTML_PATH = resolve(HERE, 'ui.html');
+const UI_JS_PATH = resolve(HERE, 'ui.js');
+const UI_CSS_PATH = resolve(HERE, 'ui.css');
+// Cached on first read — the admin bundle is static for the process lifetime.
+// HTML is cached per basePath because the served body is templated with the
+// base so the UI bundle and the asset <script>/<link> tags know where to
+// fetch from when the UI is mounted at a non-default path.
+const uiHtmlCacheByBase = new Map();
+let uiJsCache;
+let uiCssCache;
+/**
+ * Inject the resolved `basePath` into the prebuilt UI shell HTML so
+ * the `<script>` / `<link>` tags resolve correctly when the UI is
+ * mounted at the bare base path (browsers resolve `./ui.js` against
+ * the parent of the current URL, which is wrong when the URL has no
+ * trailing slash) and so the UI bundle can read
+ * `window.__DATABEHAVE_BASE__` to build its fetch URLs.
+ */
+const templateHtml = (raw, basePath) => {
+    const baseJson = JSON.stringify(basePath);
+    return raw
+        .replace(/src="\.\/ui\.js"/g, `src="${basePath}/ui.js"`)
+        .replace(/href="\.\/ui\.css"/g, `href="${basePath}/ui.css"`)
+        .replace(/<script type="module"/, `<script>window.__DATABEHAVE_BASE__=${baseJson};</script>\n  <script type="module"`);
+};
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const validateMode = (raw) => {
+    if (!isPlainObject(raw) || typeof raw.kind !== 'string') {
+        return [null, 'mode.kind must be a string'];
+    }
+    switch (raw.kind) {
+        case 'http-status':
+            if (typeof raw.status !== 'number')
+                return [null, 'http-status.status must be number'];
+            return [{ kind: 'http-status', status: raw.status }, null];
+        case 'business-failure': {
+            if (typeof raw.message !== 'string')
+                return [null, 'business-failure.message must be string'];
+            const mode = { kind: 'business-failure', message: raw.message };
+            if (raw.extra !== undefined) {
+                if (!isPlainObject(raw.extra))
+                    return [null, 'business-failure.extra must be a plain object'];
+                mode.extra = raw.extra;
+            }
+            return [mode, null];
+        }
+        case 'custom-body': {
+            if (!('body' in raw))
+                return [null, 'custom-body.body is required'];
+            const mode = { kind: 'custom-body', body: raw.body };
+            if (raw.status !== undefined) {
+                if (typeof raw.status !== 'number')
+                    return [null, 'custom-body.status must be number'];
+                mode.status = raw.status;
+            }
+            if (raw.contentType !== undefined) {
+                if (typeof raw.contentType !== 'string')
+                    return [null, 'custom-body.contentType must be string'];
+                mode.contentType = raw.contentType;
+            }
+            return [mode, null];
+        }
+        case 'empty-body': {
+            const mode = { kind: 'empty-body' };
+            if (raw.status !== undefined) {
+                if (typeof raw.status !== 'number')
+                    return [null, 'empty-body.status must be number'];
+                mode.status = raw.status;
+            }
+            return [mode, null];
+        }
+        case 'malformed-json': {
+            const mode = { kind: 'malformed-json' };
+            if (raw.status !== undefined) {
+                if (typeof raw.status !== 'number')
+                    return [null, 'malformed-json.status must be number'];
+                mode.status = raw.status;
+            }
+            return [mode, null];
+        }
+        case 'delay': {
+            if (typeof raw.ms !== 'number' || raw.ms < 0)
+                return [null, 'delay.ms must be a non-negative number'];
+            if (raw.then === undefined)
+                return [{ kind: 'delay', ms: raw.ms }, null];
+            const [inner, err] = validateMode(raw.then);
+            if (err)
+                return [null, `delay.then: ${err}`];
+            if (inner.kind === 'delay' ||
+                inner.kind === 'hang' ||
+                inner.kind === 'destroy') {
+                return [null, `delay.then cannot be ${inner.kind}`];
+            }
+            return [
+                {
+                    kind: 'delay',
+                    ms: raw.ms,
+                    then: inner,
+                },
+                null,
+            ];
+        }
+        case 'hang':
+            return [{ kind: 'hang' }, null];
+        case 'destroy':
+            return [{ kind: 'destroy' }, null];
+        default:
+            return [null, `unknown mode.kind: ${String(raw.kind)}`];
+    }
+};
+const validateMatcher = (raw) => {
+    if (!isPlainObject(raw) || typeof raw.kind !== 'string') {
+        return [null, 'matcher.kind must be a string'];
+    }
+    switch (raw.kind) {
+        case 'exact':
+            if (typeof raw.method !== 'string')
+                return [null, 'matcher.method must be string'];
+            if (typeof raw.path !== 'string' || !raw.path.startsWith('/'))
+                return [null, 'matcher.path must start with "/"'];
+            return [{ kind: 'exact', method: raw.method, path: raw.path }, null];
+        case 'path':
+            if (typeof raw.path !== 'string' || !raw.path.startsWith('/'))
+                return [null, 'matcher.path must start with "/"'];
+            return [{ kind: 'path', path: raw.path }, null];
+        case 'global': {
+            if (raw.methods === undefined)
+                return [{ kind: 'global' }, null];
+            if (!Array.isArray(raw.methods))
+                return [null, 'matcher.methods must be an array of strings'];
+            const methods = [];
+            for (const m of raw.methods) {
+                if (typeof m !== 'string')
+                    return [null, 'matcher.methods must be an array of strings'];
+                const trimmed = m.trim();
+                if (trimmed.length === 0)
+                    return [null, 'matcher.methods entries must be non-empty'];
+                methods.push(trimmed.toUpperCase());
+            }
+            if (methods.length === 0)
+                return [{ kind: 'global' }, null];
+            return [{ kind: 'global', methods }, null];
+        }
+        default:
+            return [null, `unknown matcher.kind: ${String(raw.kind)}`];
+    }
+};
+const buildAdminRoutesList = (openapiBody, handlerRoutes, basePath) => {
+    const out = [];
+    const seen = new Set();
+    if (openapiBody !== undefined) {
+        try {
+            const doc = JSON.parse(openapiBody);
+            const paths = doc.paths ?? {};
+            for (const [p, ops] of Object.entries(paths)) {
+                for (const method of [
+                    'get',
+                    'post',
+                    'put',
+                    'delete',
+                    'patch',
+                ]) {
+                    const op = ops[method];
+                    if (op !== undefined) {
+                        const upper = method.toUpperCase();
+                        seen.add(`${upper} ${p}`);
+                        out.push({
+                            method: upper,
+                            path: p,
+                            ...(typeof op.summary === 'string'
+                                ? { summary: op.summary }
+                                : {}),
+                            source: 'openapi',
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore parse errors — UI will simply show an empty list.
+        }
+    }
+    if (handlerRoutes) {
+        for (const r of handlerRoutes) {
+            const upper = r.method.toUpperCase();
+            // Hide admin routes from the UI list — they would self-list otherwise.
+            if (r.path === basePath || r.path.startsWith(`${basePath}/`))
+                continue;
+            const key = `${upper} ${r.path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ method: upper, path: r.path, source: 'handler' });
+        }
+    }
+    out.sort((a, b) => a.path === b.path
+        ? a.method.localeCompare(b.method)
+        : a.path.localeCompare(b.path));
+    return { routes: out, discoveredAt: new Date().toISOString() };
+};
+export const createAdminRoutes = (opts) => {
+    const { store, openapiBody } = opts;
+    const basePath = opts.basePath ?? '/databehave';
+    const ui = opts.ui !== false;
+    const corsHeaders = opts.corsHeaders ?? {};
+    const routesCache = buildAdminRoutesList(openapiBody, opts.handlerRoutes, basePath);
+    if (!basePath.startsWith('/')) {
+        throw new Error(`@databehave/server: admin.path must start with "/" (got ${JSON.stringify(basePath)})`);
+    }
+    const json = (status, body) => ({
+        status,
+        json: body,
+        headers: { ...corsHeaders },
+    });
+    const uiHandler = async () => {
+        try {
+            let html = uiHtmlCacheByBase.get(basePath);
+            if (html === undefined) {
+                const raw = await readFile(UI_HTML_PATH, 'utf8');
+                html = templateHtml(raw, basePath);
+                uiHtmlCacheByBase.set(basePath, html);
+            }
+            return { status: 200, html, headers: { ...corsHeaders } };
+            /* v8 ignore start -- ui.html ships with the package; missing only on a broken install */
+        }
+        catch (err) {
+            return json(500, {
+                error: 'failed to read ui.html',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        /* v8 ignore stop */
+    };
+    const uiJsHandler = async () => {
+        try {
+            if (uiJsCache === undefined) {
+                uiJsCache = await readFile(UI_JS_PATH, 'utf8');
+            }
+            return {
+                status: 200,
+                text: uiJsCache,
+                headers: {
+                    ...corsHeaders,
+                    'Content-Type': 'application/javascript; charset=utf-8',
+                },
+            };
+            /* v8 ignore start -- ui.js ships with the package; missing only on a broken install */
+        }
+        catch (err) {
+            return json(500, {
+                error: 'failed to read ui.js',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        /* v8 ignore stop */
+    };
+    const uiCssHandler = async () => {
+        try {
+            if (uiCssCache === undefined) {
+                uiCssCache = await readFile(UI_CSS_PATH, 'utf8');
+            }
+            return {
+                status: 200,
+                text: uiCssCache,
+                headers: {
+                    ...corsHeaders,
+                    'Content-Type': 'text/css; charset=utf-8',
+                },
+            };
+            /* v8 ignore start -- ui.css ships with the package; missing only on a broken install */
+        }
+        catch (err) {
+            return json(500, {
+                error: 'failed to read ui.css',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        /* v8 ignore stop */
+    };
+    const listRoutesHandler = () => json(200, routesCache);
+    const openApiDocHandler = () => {
+        if (openapiBody === undefined) {
+            return json(404, { error: 'no openapi document configured' });
+        }
+        return {
+            status: 200,
+            text: openapiBody,
+            headers: {
+                ...corsHeaders,
+                'Content-Type': 'application/json',
+                'Cache-Control': 'no-store',
+            },
+        };
+    };
+    const listOverridesHandler = () => json(200, { overrides: store.list() });
+    const addOverrideHandler = async (req) => {
+        let body;
+        try {
+            body = await req.json();
+        }
+        catch (err) {
+            return json(400, {
+                error: 'invalid JSON body',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        if (!isPlainObject(body))
+            return json(400, { error: 'body must be a JSON object' });
+        const [matcher, mErr] = validateMatcher(body.matcher);
+        if (mErr)
+            return json(400, { error: `matcher invalid: ${mErr}` });
+        const [mode, modeErr] = validateMode(body.mode);
+        if (modeErr)
+            return json(400, { error: `mode invalid: ${modeErr}` });
+        const description = typeof body.description === 'string' ? body.description : undefined;
+        const override = store.add({
+            matcher: matcher,
+            mode: mode,
+            ...(description !== undefined ? { description } : {}),
+        });
+        return {
+            status: 201,
+            json: { id: override.id, override },
+            headers: { ...corsHeaders },
+        };
+    };
+    const removeByIdHandler = (req) => {
+        const id = req.params.id;
+        if (!id)
+            return json(400, { error: 'missing :id' });
+        const ok = store.remove(id);
+        if (!ok)
+            return json(404, { error: 'override not found', id });
+        return json(200, { deleted: true, id });
+    };
+    const clearAllHandler = () => {
+        const n = store.clear();
+        return json(200, { cleared: n });
+    };
+    const routes = {
+        [`GET ${basePath}/openapi-routes`]: listRoutesHandler,
+        [`GET ${basePath}/openapi.json`]: openApiDocHandler,
+        [`GET ${basePath}/overrides`]: listOverridesHandler,
+        [`POST ${basePath}/overrides`]: addOverrideHandler,
+        [`DELETE ${basePath}/overrides`]: clearAllHandler,
+        [`DELETE ${basePath}/overrides/:id`]: removeByIdHandler,
+    };
+    if (ui) {
+        // Serve the HTML shell at the bare base path AND its trailing-slash
+        // variant so both `/databehave` and `/databehave/` work in a browser.
+        routes[`GET ${basePath}`] = uiHandler;
+        if (!basePath.endsWith('/')) {
+            routes[`GET ${basePath}/`] = uiHandler;
+        }
+        routes[`GET ${basePath}/ui.js`] = uiJsHandler;
+        routes[`GET ${basePath}/ui.css`] = uiCssHandler;
+    }
+    // Scenarios (file-backed snapshots of override sets). Mounted only
+    // when a scenarios store is provided — pure REST CRUD plus a
+    // `:name/load` action that atomically replaces the active overrides.
+    const scenarios = opts.scenarios;
+    if (scenarios) {
+        const listScenariosHandler = async () => json(200, { scenarios: await scenarios.list() });
+        const getScenarioHandler = async (req) => {
+            const name = req.params.name ?? '';
+            if (!isValidScenarioName(name))
+                return json(400, { error: 'invalid scenario name' });
+            const s = await scenarios.get(name);
+            if (!s)
+                return json(404, { error: 'scenario not found', name });
+            return json(200, s);
+        };
+        const createScenarioHandler = async (req) => {
+            let body;
+            try {
+                body = await req.json();
+            }
+            catch (err) {
+                return json(400, {
+                    error: 'invalid JSON body',
+                    detail: err instanceof Error ? err.message : String(err),
+                });
+            }
+            if (!isPlainObject(body))
+                return json(400, { error: 'body must be a JSON object' });
+            const name = typeof body.name === 'string' ? body.name : '';
+            if (!isValidScenarioName(name))
+                return json(400, {
+                    error: 'invalid scenario name (only [A-Za-z0-9_-], max 64 chars)',
+                });
+            const explicit = body.overrides;
+            const overrides = Array.isArray(explicit)
+                ? explicit
+                : store.list();
+            const saved = await scenarios.save(name, overrides);
+            return {
+                status: 201,
+                json: saved,
+                headers: { ...corsHeaders },
+            };
+        };
+        const deleteScenarioHandler = async (req) => {
+            const name = req.params.name ?? '';
+            if (!isValidScenarioName(name))
+                return json(400, { error: 'invalid scenario name' });
+            const ok = await scenarios.remove(name);
+            if (!ok)
+                return json(404, { error: 'scenario not found', name });
+            return json(200, { deleted: true, name });
+        };
+        const loadScenarioHandler = async (req) => {
+            const name = req.params.name ?? '';
+            if (!isValidScenarioName(name))
+                return json(400, { error: 'invalid scenario name' });
+            const s = await scenarios.get(name);
+            if (!s)
+                return json(404, { error: 'scenario not found', name });
+            store.clear();
+            const loaded = [];
+            for (const o of s.overrides) {
+                const added = store.add({
+                    matcher: o.matcher,
+                    mode: o.mode,
+                    ...(o.description !== undefined
+                        ? { description: o.description }
+                        : {}),
+                });
+                loaded.push(added.id);
+            }
+            return json(200, { loaded: loaded.length, name });
+        };
+        routes[`GET ${basePath}/scenarios`] =
+            listScenariosHandler;
+        routes[`GET ${basePath}/scenarios/:name`] =
+            getScenarioHandler;
+        routes[`POST ${basePath}/scenarios`] =
+            createScenarioHandler;
+        routes[`DELETE ${basePath}/scenarios/:name`] = deleteScenarioHandler;
+        routes[`POST ${basePath}/scenarios/:name/load`] = loadScenarioHandler;
+    }
+    return routes;
+};
+//# sourceMappingURL=admin-routes.js.map