@databehave/server 0.1.4 → 0.2.0

package/dist/json-config.js

@@ -1,684 +0,0 @@
-/**
- * JSON / JSONC config loader for @databehave/server.
- *
- * Reads a `databehave.json` (or `.jsonc`) file from disk, validates
- * its shape, resolves the OpenAPI document, dynamically imports every
- * handler referenced by `endpoints`, and wires the built-in mock-mode
- * middleware. The returned value is a regular `Config` ready
- * for `createServer`.
- *
- * JSONC features (`//` comments, `/* block * /` comments, trailing
- * commas) are accepted in any config file regardless of extension.
- *
- * All paths inside the JSON are resolved relative to the JSON file's
- * directory. Handlers must be ESM modules whose `default` export is
- * a `Handler`.
- */
-import { readFile, stat } from 'node:fs/promises';
-import { dirname, isAbsolute, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { buildMockModeHooks, } from './mock-mode.js';
-import { _deepFreezeForDev } from './define.js';
-import { stripJsonc } from './jsonc.js';
-import { buildAutoSchemaRoutes, loadSchemaModule, normaliseSchemaConfig, } from './openapi/auto-schema.js';
-import { parseOpenApi } from './openapi/loader.js';
-import { buildOpenApiResponseGenerators } from './openapi/register.js';
-import { matchPattern, parseRouteKey, parseRoutePattern } from './route-key.js';
-const DEFAULT_PORT = 3000;
-const DEFAULT_HOST = '127.0.0.1';
-const resolvePath = (baseDir, p) => isAbsolute(p) ? p : resolve(baseDir, p);
-/**
- * Resolve `${VAR}` / `${VAR:default}` placeholders inside any string
- * value of the JSON tree. Walks recursively; non-string nodes are
- * returned as-is. Missing env var without default → empty string.
- */
-const interpolateEnv = (value, env = process.env) => {
-    if (typeof value === 'string') {
-        // Accept the conventional `[A-Z0-9_]+` shell-style names AND
-        // lowercase / mixed-case names (e.g. `${path}`, `${myVar}`).
-        // The leading char must still be a letter or underscore so we
-        // don't accidentally interpolate `${1abc}` template fragments.
-        return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::([^}]*))?\}/g, (_, name, dflt) => {
-            const v = env[name];
-            if (v !== undefined && v !== '')
-                return v;
-            return dflt ?? '';
-        });
-    }
-    if (Array.isArray(value))
-        return value.map((v) => interpolateEnv(v, env));
-    if (value !== null && typeof value === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            out[k] = interpolateEnv(v, env);
-        }
-        return out;
-    }
-    return value;
-};
-/**
- * Coerce a port value that may have come from a `${VAR}` placeholder
- * (i.e. is now a numeric string).
- */
-const coercePort = (value, fallback) => {
-    if (typeof value === 'number' && Number.isFinite(value))
-        return value;
-    if (typeof value === 'string' && value.trim() !== '') {
-        const n = Number.parseInt(value, 10);
-        if (Number.isFinite(n))
-            return n;
-    }
-    return fallback;
-};
-const fileExists = async (path) => {
-    try {
-        const s = await stat(path);
-        return s.isFile();
-    }
-    catch (err) {
-        // Only swallow “does not exist”. Permission errors (EACCES, EPERM)
-        // are real misconfigurations — surface them instead of pretending
-        // the file is missing and falling through to a confusing
-        // ERR_MODULE_NOT_FOUND.
-        const code = err.code;
-        if (code === 'ENOENT' || code === 'ENOTDIR')
-            return false;
-        throw err;
-    }
-};
-/**
- * Normalize a handler module path so override-map lookups tolerate
- * trivial spelling differences between the JSONC value and the key
- * the caller built (typically from `import.meta.glob`).
- *
- * Strips a single leading `./`, collapses repeated `/`, and drops a
- * trailing `.js` / `.mjs` / `.cjs` / `.ts` / `.tsx` / `.mts` / `.cts`
- * so `./src/routes/x.js`, `src/routes/x`, and `./src/routes/x.ts` all
- * collapse to the same canonical form.
- */
-const canonicalizeHandlerKey = (modulePath) => modulePath
-    .replace(/^\.\//, '')
-    .replace(/\/{2,}/g, '/')
-    .replace(/\.(?:js|mjs|cjs|ts|tsx|mts|cts)$/, '');
-/**
- * Resolve a handler module path to a URL that `import()` can load.
- *
- * Config files reference handlers by their compiled `.js` path
- * (e.g. `./src/routes/health.js`) so they stay valid for production
- * `tsc`-built deployments. In dev/test scenarios where only the
- * TypeScript source exists, fall back to the same path with a `.ts`
- * (or `.tsx`, `.mjs`, `.cjs`) extension so test runners that register
- * a TS loader (vitest, tsx, ts-node) can still resolve it.
- *
- * Set `DATABEHAVE_PREFER_TS=1` to prefer `.ts` siblings over the
- * declared `.js` even when both exist on disk (handy in dev when an
- * outdated `dist/` is still around and would otherwise win).
- */
-const resolveHandlerUrl = async (absolute) => {
-    const preferTs = process.env.DATABEHAVE_PREFER_TS === '1';
-    const m = absolute.match(/\.(js|mjs|cjs)$/);
-    if (preferTs && m) {
-        const stem = absolute.slice(0, -m[0].length);
-        for (const ext of ['.ts', '.tsx', '.mts', '.cts']) {
-            const candidate = `${stem}${ext}`;
-            if (await fileExists(candidate))
-                return pathToFileURL(candidate).href;
-        }
-    }
-    if (await fileExists(absolute))
-        return pathToFileURL(absolute).href;
-    if (m) {
-        const stem = absolute.slice(0, -m[0].length);
-        for (const ext of ['.ts', '.tsx', '.mts', '.cts']) {
-            const candidate = `${stem}${ext}`;
-            if (await fileExists(candidate))
-                return pathToFileURL(candidate).href;
-        }
-    }
-    // No fallback hit — return the original URL so `import()` raises the
-    // canonical ERR_MODULE_NOT_FOUND with the requested path.
-    return pathToFileURL(absolute).href;
-};
-const importHandler = async (baseDir, modulePath, routeKey, handlerOverrides) => {
-    // 1. Pre-resolved override map wins. The caller-supplied object is
-    //    flattened into a `Map` keyed by `canonicalizeHandlerKey` once at
-    //    load time (see `buildHandlerOverrideMap`), so lookup is O(1)
-    //    regardless of the number of overrides.
-    if (handlerOverrides) {
-        const candidate = handlerOverrides.get(canonicalizeHandlerKey(modulePath));
-        if (candidate !== undefined) {
-            if (typeof candidate !== 'function') {
-                throw new Error(`@databehave/server/config: handlers override for ${JSON.stringify(modulePath)} (mapped to ${routeKey}) is not a function (got ${typeof candidate})`);
-            }
-            return candidate;
-        }
-    }
-    // 2. Dynamic import from disk, with `.js` → `.ts/.tsx/.mts/.cts`
-    //    sibling fallback for TS-loader environments (tsx, ts-node).
-    const absolute = resolvePath(baseDir, modulePath);
-    const url = await resolveHandlerUrl(absolute);
-    const mod = (await import(/* @vite-ignore */ url));
-    const handler = mod.default;
-    if (typeof handler !== 'function') {
-        throw new Error(`@databehave/server/config: ${modulePath} (mapped to ${routeKey}) has no default-exported handler function`);
-    }
-    return handler;
-};
-/**
- * Convert an `EndpointResponse` (JSON-safe DTO) into a `MockResponse`
- * (discriminated union: either body OR empty).
- */
-const toResponse = (r) => {
-    if (r.empty) {
-        return {
-            status: r.status,
-            empty: true,
-            ...(r.headers ? { headers: r.headers } : {}),
-        };
-    }
-    return {
-        status: r.status,
-        json: r.json ?? null,
-        ...(r.headers ? { headers: r.headers } : {}),
-    };
-};
-const synthesizeResponseHandler = (r) => {
-    const frozen = toResponse(r);
-    return () => frozen;
-};
-const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
-const validateEndpointResponse = (v, routeKey) => {
-    if (!isPlainObject(v)) {
-        throw new Error(`@databehave/server/config: endpoints["${routeKey}"].response must be an object`);
-    }
-    if (typeof v.status !== 'number' || !Number.isFinite(v.status)) {
-        throw new Error(`@databehave/server/config: endpoints["${routeKey}"].response.status must be a number`);
-    }
-    const out = { status: v.status };
-    if (v.json !== undefined)
-        out.json = v.json;
-    if (v.empty !== undefined) {
-        if (typeof v.empty !== 'boolean') {
-            throw new Error(`@databehave/server/config: endpoints["${routeKey}"].response.empty must be a boolean`);
-        }
-        out.empty = v.empty;
-    }
-    if (v.headers !== undefined) {
-        if (!isPlainObject(v.headers)) {
-            throw new Error(`@databehave/server/config: endpoints["${routeKey}"].response.headers must be an object`);
-        }
-        const h = {};
-        for (const [k, val] of Object.entries(v.headers)) {
-            if (typeof val !== 'string') {
-                throw new Error(`@databehave/server/config: endpoints["${routeKey}"].response.headers["${k}"] must be a string`);
-            }
-            h[k] = val;
-        }
-        out.headers = h;
-    }
-    return out;
-};
-const validateEndpointSpec = (raw, routeKey) => {
-    if (typeof raw === 'string')
-        return raw;
-    if (!isPlainObject(raw)) {
-        throw new Error(`@databehave/server/config: endpoints["${routeKey}"] must be a string or object`);
-    }
-    const hasHandler = raw.handler !== undefined;
-    const hasResponse = raw.response !== undefined;
-    if (hasHandler && hasResponse) {
-        throw new Error(`@databehave/server/config: endpoints["${routeKey}"] cannot have both "handler" and "response"`);
-    }
-    if (!hasHandler && !hasResponse) {
-        throw new Error(`@databehave/server/config: endpoints["${routeKey}"] must have either "handler" or "response"`);
-    }
-    if (hasHandler) {
-        if (typeof raw.handler !== 'string') {
-            throw new Error(`@databehave/server/config: endpoints["${routeKey}"].handler must be a string`);
-        }
-        if (raw.status !== undefined) {
-            if (typeof raw.status !== 'number' || !Number.isFinite(raw.status)) {
-                throw new Error(`@databehave/server/config: endpoints["${routeKey}"].status must be a number`);
-            }
-            return { handler: raw.handler, status: raw.status };
-        }
-        return { handler: raw.handler };
-    }
-    // hasResponse
-    if (raw.status !== undefined) {
-        throw new Error(`@databehave/server/config: endpoints["${routeKey}"].status cannot be combined with "response" (put status inside response)`);
-    }
-    return { response: validateEndpointResponse(raw.response, routeKey) };
-};
-const validate = (raw) => {
-    if (raw === null || typeof raw !== 'object') {
-        throw new Error('@databehave/server/config: JSON root must be an object');
-    }
-    const obj = raw;
-    const out = {};
-    if (obj.openapi !== undefined) {
-        if (typeof obj.openapi !== 'string') {
-            throw new Error('@databehave/server/config: "openapi" must be a string path');
-        }
-        out.openapi = obj.openapi;
-    }
-    if (obj.server !== undefined) {
-        if (typeof obj.server !== 'object' || obj.server === null) {
-            throw new Error('@databehave/server/config: "server" must be an object');
-        }
-        out.server = obj.server;
-    }
-    if (obj.basePath !== undefined) {
-        if (typeof obj.basePath !== 'string') {
-            throw new Error('@databehave/server/config: "basePath" must be a string');
-        }
-        if (!obj.basePath.startsWith('/')) {
-            throw new Error('@databehave/server/config: "basePath" must start with "/"');
-        }
-        if (obj.basePath.length > 1 && obj.basePath.endsWith('/')) {
-            throw new Error('@databehave/server/config: "basePath" must not end with "/"');
-        }
-        out.basePath = obj.basePath;
-    }
-    if (obj.cors !== undefined) {
-        if (typeof obj.cors !== 'object' || obj.cors === null) {
-            throw new Error('@databehave/server/config: "cors" must be an object');
-        }
-        out.cors = obj.cors;
-    }
-    if (obj.mockMode !== undefined) {
-        if (typeof obj.mockMode !== 'object' || obj.mockMode === null) {
-            throw new Error('@databehave/server/config: "mockMode" must be an object');
-        }
-        const mm = obj.mockMode;
-        if (mm.pathOverrides !== undefined) {
-            if (typeof mm.pathOverrides !== 'object' ||
-                mm.pathOverrides === null ||
-                Array.isArray(mm.pathOverrides)) {
-                throw new Error('@databehave/server/config: "mockMode.pathOverrides" must be an object');
-            }
-            // Keys must be either `<METHOD> <absolute-path>` or `<absolute-path>`.
-            // Anything else silently never matches at runtime, which is the
-            // exact class of typo that this validation exists to catch.
-            const KEY_RE = /^(?:(?:GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+)?\/[^\s]*$/i;
-            // The mock-mode matcher uppercases the request method before
-            // lookup (see `mock-mode.ts`), so a lowercase config key
-            // (e.g. `"get /api/x"`) would never match. Normalize the method
-            // portion here so the validator stays case-insensitive while the
-            // stored map keys remain canonical.
-            const normalized = {};
-            for (const [k, v] of Object.entries(mm.pathOverrides)) {
-                if (!KEY_RE.test(k)) {
-                    throw new Error(`@databehave/server/config: "mockMode.pathOverrides" key ${JSON.stringify(k)} must be "<METHOD> /path" or "/path" (path must start with "/")`);
-                }
-                if (typeof v !== 'number' || !Number.isFinite(v)) {
-                    throw new Error(`@databehave/server/config: "mockMode.pathOverrides[${JSON.stringify(k)}]" must be a number (HTTP status code)`);
-                }
-                const spaceIdx = k.indexOf(' ');
-                const canonical = spaceIdx > 0
-                    ? `${k.slice(0, spaceIdx).toUpperCase()}${k.slice(spaceIdx)}`
-                    : k;
-                normalized[canonical] = v;
-            }
-            mm.pathOverrides = normalized;
-        }
-        out.mockMode = mm;
-    }
-    if (obj.endpoints !== undefined) {
-        if (typeof obj.endpoints !== 'object' || obj.endpoints === null) {
-            throw new Error('@databehave/server/config: "endpoints" must be an object');
-        }
-        const map = {};
-        for (const [k, v] of Object.entries(obj.endpoints)) {
-            map[k] = validateEndpointSpec(v, k);
-        }
-        out.endpoints = map;
-    }
-    if (obj.admin !== undefined) {
-        if (typeof obj.admin !== 'object' || obj.admin === null) {
-            throw new Error('@databehave/server/config: "admin" must be an object');
-        }
-        // Pass-through; createServer validates the shape.
-        out.admin = obj.admin;
-    }
-    if (obj.log !== undefined) {
-        const v = obj.log;
-        if (typeof v !== 'boolean' &&
-            (typeof v !== 'object' || v === null || Array.isArray(v))) {
-            throw new Error('@databehave/server/config: "log" must be a boolean or an object');
-        }
-        out.log = v;
-    }
-    if (obj.validation !== undefined) {
-        if (typeof obj.validation !== 'object' || obj.validation === null || Array.isArray(obj.validation)) {
-            throw new Error('@databehave/server/config: "validation" must be an object');
-        }
-        out.validation = obj.validation;
-    }
-    if (obj.schema !== undefined) {
-        // Re-validate via `normaliseSchemaConfig` at load time; here we
-        // just pass-through the raw shape so the loader can call the
-        // normaliser once and reuse the resolved object. Reject the
-        // removed boolean shorthand fail-fast at validation time so
-        // the migration error surfaces with the same wording the
-        // normaliser would emit.
-        if (typeof obj.schema === 'boolean') {
-            throw new Error('@databehave/server/config: "schema" must be an object like ' +
-                '{ "enabled": true }; the boolean shorthand was removed (got ' +
-                JSON.stringify(obj.schema) +
-                ')');
-        }
-        out.schema = obj.schema;
-    }
-    return out;
-};
-/**
- * Rewrite an endpoint key by prepending `basePath` to its path
- * segment. Convention:
- *   - Keys whose path starts with `/` are absolute and left untouched
- *     (use this for cross-cutting endpoints like `/health`).
- *   - Keys whose path does NOT start with `/` are treated as
- *     relative to `basePath` and rewritten to `${basePath}/${path}`.
- * When `basePath` is empty or `/`, every key is forced to absolute
- * form by prepending a single `/` if missing.
- */
-const applyBasePath = (key, basePath) => {
-    const sp = key.indexOf(' ');
-    if (sp <= 0)
-        return key;
-    const method = key.slice(0, sp);
-    const path = key.slice(sp + 1);
-    if (path.startsWith('/'))
-        return key;
-    if (basePath === '' || basePath === '/')
-        return `${method} /${path}`;
-    return `${method} ${basePath}/${path}`;
-};
-/**
- * Load and fully resolve a `databehave.json`.
- *
- * Returns a ready-to-run `Config` plus the listen options the
- * CLI should bind to. Errors are thrown synchronously after parsing
- * to fail fast on bad configs.
- */
-export const loadConfig = async (configPath, options) => {
-    const absoluteConfigPath = isAbsolute(configPath)
-        ? configPath
-        : resolve(process.cwd(), configPath);
-    const baseDir = dirname(absoluteConfigPath);
-    const raw = JSON.parse(stripJsonc(await readFile(absoluteConfigPath, 'utf8')));
-    const json = validate(interpolateEnv(raw));
-    // 0. Canonicalise the handler-override map once. Lookup inside
-    //    `importHandler` is then O(1) per route instead of scanning the
-    //    entire map for every endpoint that doesn't hit a direct key.
-    const handlerOverrides = options?.handlers
-        ? (() => {
-            const m = new Map();
-            for (const [key, fn] of Object.entries(options.handlers)) {
-                m.set(canonicalizeHandlerKey(key), fn);
-            }
-            return m;
-        })()
-        : undefined;
-    // 1. OpenAPI body (loaded from disk into a string). JSON only;
-    //    convert YAML up-front with `yq -o=json`. The raw file bytes
-    //    flow through unchanged so callers see the same source-mapped
-    //    error positions a standalone tool would report.
-    let openapiBody;
-    if (json.openapi !== undefined) {
-        const specPath = resolvePath(baseDir, json.openapi);
-        openapiBody = await readFile(specPath, 'utf8');
-    }
-    // 2. endpoints → routes map + per-endpoint status overrides.
-    const routes = {};
-    const endpointStatusOverrides = {};
-    if (json.endpoints) {
-        const basePath = json.basePath ?? '';
-        const entries = Object.entries(json.endpoints);
-        // Detect collisions where two endpoint keys collapse to the same
-        // `METHOD path` after applying `basePath` — silent overwrite would
-        // mask a real configuration bug.
-        const seenKeys = new Map();
-        for (const [rawKey] of entries) {
-            const finalKey = applyBasePath(rawKey, basePath);
-            const prior = seenKeys.get(finalKey);
-            if (prior !== undefined && prior !== rawKey) {
-                throw new Error(`@databehave/server/config: endpoints keys "${prior}" and "${rawKey}" both resolve to "${finalKey}" after applying basePath`);
-            }
-            seenKeys.set(finalKey, rawKey);
-        }
-        // Resolve every endpoint concurrently. `allSettled` collects all
-        // failures so one bad path doesn't hide the rest — a misconfigured
-        // config surfaces every broken handler at once instead of forcing
-        // an iterative trial-and-error loop.
-        const settled = await Promise.allSettled(entries.map(async ([rawKey, spec]) => {
-            const key = applyBasePath(rawKey, basePath);
-            parseRouteKey(key); // validate after prefixing
-            if (typeof spec === 'string') {
-                routes[key] = await importHandler(baseDir, spec, key, handlerOverrides);
-                return;
-            }
-            if (spec.handler !== undefined) {
-                routes[key] = await importHandler(baseDir, spec.handler, key, handlerOverrides);
-                if (spec.status !== undefined) {
-                    endpointStatusOverrides[key] = spec.status;
-                }
-                return;
-            }
-            routes[key] = synthesizeResponseHandler(spec.response);
-        }));
-        const failures = settled.flatMap((r, i) => r.status === 'rejected'
-            ? [{ reason: r.reason, rawKey: entries[i][0] }]
-            : []);
-        if (failures.length > 0) {
-            const errors = failures.map((f) => f.reason instanceof Error ? f.reason : new Error(String(f.reason)));
-            const messages = failures.map((f, i) => `${f.rawKey}: ${errors[i].message}`);
-            // Node ≥ 18.17 always has AggregateError.
-            throw new AggregateError(errors, `@databehave/server/config: ${failures.length} endpoint(s) failed to load:\n  - ${messages.join('\n  - ')}`);
-        }
-    }
-    const warn = options?.logger?.warn ?? ((m) => {
-        // eslint-disable-next-line no-console
-        console.warn(m);
-    });
-    // 3. Built-in mock-mode hooks (with OAS-backed body resolver when
-    //    an OpenAPI document is present). Per-endpoint `status`
-    //    overrides are merged on top of any user-supplied
-    //    `mockMode.pathOverrides` (user values take precedence to keep
-    //    explicit JSON authoritative).
-    let hooks;
-    if (json.mockMode) {
-        const resolvedLogger = options?.logger ?? json.mockMode.logger;
-        const mergedConfig = {
-            ...json.mockMode,
-            pathOverrides: {
-                ...endpointStatusOverrides,
-                ...(json.mockMode.pathOverrides ?? {}),
-            },
-            // Thread the caller-supplied logger so mock-mode warnings
-            // (e.g. out-of-range x-mock-status header overrides) flow
-            // through the same channel as JSON/OAS warnings instead of
-            // leaking to stdout. Only set the key when defined so
-            // `exactOptionalPropertyTypes` is honoured.
-            ...(resolvedLogger ? { logger: resolvedLogger } : {}),
-        };
-        let bodyResolver;
-        if (openapiBody !== undefined) {
-            try {
-                const doc = parseOpenApi(openapiBody);
-                const generators = buildOpenApiResponseGenerators(doc, {
-                    onWalkError: (method, path, err) => {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        warn(`[@databehave/server] mock-mode body resolver: openapi walk failed for ${method.toUpperCase()} ${path}: ${msg}`);
-                    },
-                });
-                // Build a single pattern index, sorted so the dispatch
-                // result does not depend on OAS declaration order:
-                //   1. Static patterns first (exact paths beat parametric).
-                //   2. Within the same kind, longer paths first (more
-                //      specific routes shadow shorter wildcards — e.g.
-                //      `/users/me` is preferred over `/users/:id`).
-                //   3. Stable fallback on the raw path string for ties.
-                // Without this sort, two OAS paths that could both match a
-                // request resolve in `paths` insertion order — i.e. the
-                // schema author's typing order silently picks the winner.
-                const patternIndex = [];
-                for (const [key, perStatus] of generators) {
-                    const { method, path } = parseRouteKey(key);
-                    patternIndex.push({
-                        method: method.toUpperCase(),
-                        pattern: parseRoutePattern(path),
-                        perStatus,
-                    });
-                }
-                patternIndex.sort((a, b) => {
-                    if (a.pattern.isStatic !== b.pattern.isStatic) {
-                        return a.pattern.isStatic ? -1 : 1;
-                    }
-                    if (a.pattern.segments.length !== b.pattern.segments.length) {
-                        return b.pattern.segments.length - a.pattern.segments.length;
-                    }
-                    return a.pattern.path.localeCompare(b.pattern.path);
-                });
-                bodyResolver = (method, path, status) => {
-                    const upper = method.toUpperCase();
-                    for (const entry of patternIndex) {
-                        if (entry.method !== upper)
-                            continue;
-                        if (entry.pattern.isStatic) {
-                            if (entry.pattern.path !== path)
-                                continue;
-                        }
-                        else if (matchPattern(entry.pattern, path) === null) {
-                            continue;
-                        }
-                        const gen = entry.perStatus.get(status);
-                        if (gen !== undefined)
-                            return gen();
-                    }
-                    return undefined;
-                };
-            }
-            catch {
-                // If OAS parsing fails, mock-mode still works with fallback envelope.
-                bodyResolver = undefined;
-            }
-        }
-        hooks = buildMockModeHooks(mergedConfig, bodyResolver);
-    }
-    // 4. Build a `cors` value with a sensible default `origin` so the
-    //    JSON config never has to declare a function. When `cors.origin`
-    //    is declared in JSON it may be either a single allowed origin
-    //    string or an allowlist of strings — anything not on the
-    //    allowlist returns an empty value so the runtime omits the
-    //    `Access-Control-Allow-Origin` header entirely (the de-facto
-    //    “reject” signal). Allowlist comparison is case-insensitive on
-    //    the scheme/host portion so trivial typos don't silently lock
-    //    callers out.
-    let cors;
-    if (json.cors) {
-        const rawOrigin = json.cors.origin;
-        const allowlist = typeof rawOrigin === 'string'
-            ? [rawOrigin]
-            : Array.isArray(rawOrigin) && rawOrigin.every((v) => typeof v === 'string')
-                ? rawOrigin
-                : undefined;
-        const normalisedAllowlist = allowlist?.map((o) => o.toLowerCase());
-        const { origin: _origin, ...rest } = json.cors;
-        cors = {
-            ...rest,
-            origin: (o) => {
-                if (normalisedAllowlist) {
-                    // With a declared allowlist: only echo back exact matches.
-                    // No request Origin and `credentials: true` is the canonical
-                    // "don't send ACAO" case per CORS §3.2.1 — returning empty
-                    // lets the response builder omit the header entirely instead
-                    // of echoing some arbitrary allowlist entry.
-                    if (o && normalisedAllowlist.includes(o.toLowerCase()))
-                        return o;
-                    return '';
-                }
-                return o ? o : '*';
-            },
-        };
-    }
-    // admin: pass through; the CLI loader supplements openapiBody
-    // from the resolved OpenAPI document so the UI route picker is
-    // populated without the consumer having to wire it manually.
-    let admin;
-    if (json.admin !== undefined) {
-        admin = {
-            ...json.admin,
-            ...(openapiBody !== undefined && json.admin.openapiBody === undefined
-                ? { openapiBody }
-                : {}),
-        };
-    }
-    // 5. Auto-schema dispatch (Phase 2C / brief #11). When the JSONC
-    //    config sets a top-level `schema:` field, dynamic-import
-    //    `@databehave/schema` (suppressing the native "Cannot find
-    //    module" with the friendly install hint), pre-translate every
-    //    OAS path/method whose 200 response carries a JSON schema, and
-    //    inject synthesized handlers into `routes`. Hand-written
-    //    `endpoints` always win (auto-mode skips routes already in
-    //    `routes`). When `schema:` is absent everything below this
-    //    block is a no-op and the OAS-fallback walker in `server.ts`
-    //    keeps using `generateFromOasSchema` (the zero-dep
-    //    placeholder generator) — byte-identical legacy behaviour.
-    // 5. Auto-schema dispatch (Phase 2C / brief #11). When the JSONC
-    //    config sets `"schema": { "enabled": true }`, dynamic-import
-    //    `@databehave/schema` (suppressing the native "Cannot find
-    //    module" with the friendly install hint), pre-translate every
-    //    OAS path/method whose 200 response carries a JSON schema, and
-    //    inject synthesized handlers into `routes`. Hand-written
-    //    `endpoints` always win (auto-mode skips routes already in
-    //    `routes`). When `schema.enabled` is `false` (or the field is
-    //    absent) everything below this block is a no-op and the
-    //    OAS-fallback walker in `server.ts` keeps using
-    //    `generateFromOasSchema` (the zero-dep placeholder generator)
-    //    — byte-identical legacy behaviour.
-    if (json.schema !== undefined) {
-        const schemaCfg = normaliseSchemaConfig(json.schema);
-        if (schemaCfg !== null) {
-            // Cache the imported module on the loaded-config closure for
-            // later use; throws fail-fast (with the friendly install-hint
-            // template) if the optional peer is not installed. Native
-            // "Cannot find module" stack traces never reach the consumer.
-            const schemaModule = await loadSchemaModule();
-            if (openapiBody !== undefined) {
-                const doc = parseOpenApi(openapiBody);
-                const declaredKeys = new Set(Object.keys(routes).filter((k) => routes[k] !== undefined));
-                const autoRoutes = await buildAutoSchemaRoutes(doc, schemaCfg, schemaModule, declaredKeys);
-                for (const [key, handler] of autoRoutes) {
-                    routes[key] = handler;
-                }
-            }
-        }
-    }
-    const config = {
-        routes,
-        ...(openapiBody !== undefined ? { openapi: openapiBody } : {}),
-        ...(hooks !== undefined ? { hooks } : {}),
-        ...(cors !== undefined ? { cors } : {}),
-        ...(admin !== undefined ? { admin } : {}),
-        ...(json.log !== undefined ? { log: json.log } : {}),
-        ...(json.validation !== undefined ? { validation: json.validation } : {}),
-        onOpenApiWalkError: (method, path, err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            warn(`[@databehave/server] openapi walk failed for ${method.toUpperCase()} ${path}: ${msg}`);
-        },
-        onOpenApiEmptySchema: (method, path, status) => {
-            warn(`[@databehave/server] OAS response schema is empty for ${method.toUpperCase()} ${path} (status ${status}) — serving stub. Consider filling the schema in your OpenAPI document.`);
-        },
-    };
-    const server = {
-        host: json.server?.host ?? DEFAULT_HOST,
-        port: coercePort(json.server?.port, DEFAULT_PORT),
-    };
-    // Deep-freeze in dev so the resolved config behaves identically to
-    // one returned by `defineConfig()` — accidental late mutation
-    // throws loudly instead of corrupting the running server.
-    _deepFreezeForDev(config);
-    return { config, server };
-};
-//# sourceMappingURL=json-config.js.map