swaggerizer 0.0.0-stage → 1.0.1

package/dist/cli.js

@@ -0,0 +1,2977 @@
+#!/usr/bin/env node
+
+'use strict';
+
+var path = require('node:path');
+var readline = require('node:readline/promises');
+var yargs = require('yargs');
+var helpers = require('yargs/helpers');
+var fs = require('node:fs');
+var os = require('node:os');
+var SwaggerParser = require('@apidevtools/swagger-parser');
+var http = require('node:http');
+var node_url = require('node:url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/*
+ * JSON-pointer resolution and deterministic sample generation for OpenAPI 3 schemas.
+ * Specs are bundled (not dereferenced), so internal `$ref`s are followed lazily here with cycle
+ * protection — that keeps documents JSON-serialisable even when schemas are recursive.
+ */
+function decodePointerSegment(segment) {
+    return decodeURIComponent(segment).replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/** Resolves an internal `#/a/b` reference against `doc`. Returns undefined for anything else. */
+function resolvePointer(doc, ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#"))
+        return undefined;
+    const parts = ref.replace(/^#\/?/, "").split("/").filter(p => p !== "");
+    let node = doc;
+    for (const part of parts) {
+        if (node === null || typeof node !== "object")
+            return undefined;
+        node = node[decodePointerSegment(part)];
+    }
+    return node;
+}
+/** Follows `$ref` chains on `node`, returning the target and the last ref name seen. */
+function deref(doc, node, seen = new Set()) {
+    let current = node;
+    let lastRef;
+    while (current && typeof current === "object" && typeof current.$ref === "string") {
+        const ref = current.$ref;
+        if (seen.has(ref))
+            return { node: current, ref };
+        seen.add(ref);
+        lastRef = ref;
+        current = resolvePointer(doc, ref);
+    }
+    return { node: current, ref: lastRef };
+}
+function refName(ref) {
+    if (!ref)
+        return undefined;
+    const parts = ref.split("/");
+    return decodePointerSegment(parts[parts.length - 1]);
+}
+const FORMAT_SAMPLES = {
+    "date-time": "2024-01-01T12:00:00Z",
+    date: "2024-01-01",
+    time: "12:00:00",
+    email: "user@example.com",
+    uuid: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    uri: "https://example.com",
+    url: "https://example.com",
+    hostname: "example.com",
+    ipv4: "192.168.0.1",
+    ipv6: "::1",
+    byte: "U3dhZ2dlcml6ZXI=",
+    binary: "",
+    password: "********"
+};
+function primaryType(schema) {
+    const t = schema?.type;
+    if (Array.isArray(t))
+        return t.find((x) => x !== "null") ?? t[0];
+    if (typeof t === "string")
+        return t;
+    if (schema?.properties || schema?.additionalProperties)
+        return "object";
+    if (schema?.items)
+        return "array";
+    return undefined;
+}
+const MAX_DEPTH$1 = 8;
+function sample(schemaIn, ctx) {
+    if (schemaIn === true || schemaIn === undefined || schemaIn === null)
+        return {};
+    if (ctx.depth > MAX_DEPTH$1)
+        return undefined;
+    let schema = schemaIn;
+    let pushed;
+    if (schema && typeof schema.$ref === "string") {
+        if (ctx.stack.includes(schema.$ref))
+            return undefined; // recursive schema: stop here
+        const ref = schema.$ref;
+        pushed = ref;
+        ctx.stack.push(ref);
+        schema = resolvePointer(ctx.doc, ref) ?? {};
+    }
+    try {
+        if (schema.example !== undefined)
+            return schema.example;
+        if (Array.isArray(schema.examples) && schema.examples.length > 0)
+            return schema.examples[0];
+        if (schema.const !== undefined)
+            return schema.const;
+        if (schema.default !== undefined)
+            return schema.default;
+        if (Array.isArray(schema.enum) && schema.enum.length > 0)
+            return schema.enum[0];
+        const next = { ...ctx, depth: ctx.depth + 1 };
+        if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+            let merged = undefined;
+            for (const part of schema.allOf) {
+                const value = sample(part, next);
+                if (value && typeof value === "object" && !Array.isArray(value)) {
+                    merged = { ...(merged || {}), ...value };
+                }
+                else if (merged === undefined) {
+                    merged = value;
+                }
+            }
+            if (schema.properties) {
+                merged = { ...(merged || {}), ...sampleObject(schema, next) };
+            }
+            return merged;
+        }
+        const variants = schema.oneOf || schema.anyOf;
+        if (Array.isArray(variants) && variants.length > 0) {
+            const base = schema.properties ? sampleObject(schema, next) : undefined;
+            const chosen = sample(variants[0], next);
+            return base && chosen && typeof chosen === "object" ? { ...base, ...chosen } : chosen ?? base;
+        }
+        switch (primaryType(schema)) {
+            case "object":
+                return sampleObject(schema, next);
+            case "array": {
+                const item = sample(schema.items, next);
+                if (item === undefined)
+                    return [];
+                const count = Math.max(1, Math.min(Number(schema.minItems) || 1, 3));
+                return Array.from({ length: count }, () => item);
+            }
+            case "string": {
+                if (schema.format && schema.format in FORMAT_SAMPLES)
+                    return FORMAT_SAMPLES[schema.format];
+                const min = Number(schema.minLength) || 0;
+                const base = "string";
+                return min > base.length ? base.padEnd(min, "x") : base;
+            }
+            case "integer":
+                return clampNumber(schema, 1, true);
+            case "number":
+                return clampNumber(schema, 1.5, false);
+            case "boolean":
+                return true;
+            case "null":
+                return null;
+            default:
+                return schema.properties ? sampleObject(schema, next) : {};
+        }
+    }
+    finally {
+        if (pushed)
+            ctx.stack.pop();
+    }
+}
+function clampNumber(schema, fallback, integer) {
+    let value = fallback;
+    if (typeof schema.minimum === "number")
+        value = Math.max(value, schema.minimum);
+    if (typeof schema.exclusiveMinimum === "number")
+        value = Math.max(value, schema.exclusiveMinimum + 1);
+    if (typeof schema.maximum === "number")
+        value = Math.min(value, schema.maximum);
+    if (typeof schema.exclusiveMaximum === "number")
+        value = Math.min(value, schema.exclusiveMaximum - 1);
+    return integer ? Math.round(value) : value;
+}
+function sampleObject(schema, ctx) {
+    const out = {};
+    for (const [name, prop] of Object.entries(schema.properties || {})) {
+        if (prop && (prop.writeOnly === true || prop.readOnly === "never"))
+            continue;
+        const value = sample(prop, ctx);
+        if (value !== undefined)
+            out[name] = value;
+    }
+    if (Object.keys(out).length === 0 && schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        const value = sample(schema.additionalProperties, ctx);
+        if (value !== undefined)
+            out.key = value;
+    }
+    return out;
+}
+/** Builds a deterministic, schema-valid-ish example payload for `schema`. */
+function sampleFromSchema(schema, doc = {}) {
+    const value = sample(schema, { doc, stack: [], depth: 0 });
+    return value === undefined ? {} : value;
+}
+
+/*
+ * Shared types. This file must stay free of Node imports: it is used by the server, the MSW
+ * runtime (browser + node) and the in-page debug menu.
+ */
+const HTTP_METHODS = [
+    "get",
+    "put",
+    "post",
+    "delete",
+    "options",
+    "head",
+    "patch",
+    "trace"
+];
+/** Variant name used for a response that has a body but no explicit examples in the spec. */
+const GENERATED = "generated";
+/** Variant name used for a response that declares no body at all. */
+const EMPTY = "empty";
+
+/*
+ * Contract snapshots and change detection.
+ *
+ * A contract is a normalised, acyclic summary of an OpenAPI document: every operation with its
+ * parameters, request body and response schemas. Swaggerizer saves one next to the generated code
+ * and compares new specs against it, so you are warned about new, removed and changed APIs —
+ * and which of those changes break the generated client — before you regenerate.
+ */
+/* ------------------------------------------------------------------ normalisation */
+const MAX_DEPTH = 12;
+function normaliseSchema(doc, raw, stack = [], depth = 0) {
+    if (raw === undefined || raw === null || raw === true)
+        return undefined;
+    if (depth > MAX_DEPTH)
+        return { circular: "max-depth" };
+    let schema = raw;
+    let pushed;
+    if (typeof raw.$ref === "string") {
+        if (stack.includes(raw.$ref))
+            return { circular: refName(raw.$ref) ?? raw.$ref };
+        const ref = raw.$ref;
+        pushed = ref;
+        stack.push(ref);
+        schema = deref(doc, raw).node ?? {};
+    }
+    try {
+        const next = (s) => normaliseSchema(doc, s, stack, depth + 1);
+        const out = {};
+        let type;
+        let nullable = schema.nullable === true;
+        if (Array.isArray(schema.type)) {
+            nullable = nullable || schema.type.includes("null");
+            const nonNull = schema.type.filter((t) => t !== "null");
+            type = nonNull.length === 1 ? nonNull[0] : nonNull.sort().join("|") || undefined;
+        }
+        else if (typeof schema.type === "string") {
+            type = schema.type;
+        }
+        // allOf: merge into a single object shape.
+        if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+            const merged = { type: "object", properties: {}, required: [] };
+            for (const part of schema.allOf) {
+                const p = next(part);
+                if (!p)
+                    continue;
+                if (p.properties)
+                    Object.assign(merged.properties, p.properties);
+                if (p.required)
+                    merged.required.push(...p.required);
+                if (p.type && p.type !== "object")
+                    merged.type = p.type;
+                if (p.nullable)
+                    merged.nullable = true;
+            }
+            const own = schema.properties ? next({ ...schema, allOf: undefined }) : undefined;
+            if (own?.properties)
+                Object.assign(merged.properties, own.properties);
+            if (own?.required)
+                merged.required.push(...own.required);
+            merged.required = [...new Set(merged.required)].sort();
+            if (nullable)
+                merged.nullable = true;
+            return tidy(merged);
+        }
+        const variants = schema.oneOf || schema.anyOf;
+        if (Array.isArray(variants) && variants.length > 0) {
+            out.oneOf = variants.map((v) => next(v) ?? {});
+            if (variants.some((v) => v?.type === "null"))
+                nullable = true;
+        }
+        if (!type) {
+            if (schema.properties || schema.additionalProperties)
+                type = "object";
+            else if (schema.items)
+                type = "array";
+        }
+        if (type)
+            out.type = type;
+        if (typeof schema.format === "string")
+            out.format = schema.format;
+        if (nullable)
+            out.nullable = true;
+        if (Array.isArray(schema.enum))
+            out.enum = [...schema.enum].filter(v => v !== null);
+        if (type === "array" && schema.items)
+            out.items = next(schema.items) ?? {};
+        if (schema.properties && typeof schema.properties === "object") {
+            out.properties = {};
+            for (const [name, prop] of Object.entries(schema.properties)) {
+                out.properties[name] = next(prop) ?? {};
+            }
+            out.required = Array.isArray(schema.required) ? [...schema.required].sort() : [];
+        }
+        if (schema.additionalProperties !== undefined) {
+            out.additionalProperties =
+                typeof schema.additionalProperties === "object"
+                    ? next(schema.additionalProperties) ?? true
+                    : Boolean(schema.additionalProperties);
+        }
+        return tidy(out);
+    }
+    finally {
+        if (pushed)
+            stack.pop();
+    }
+}
+function tidy(schema) {
+    if (schema.required && schema.required.length === 0)
+        delete schema.required;
+    if (schema.properties && Object.keys(schema.properties).length === 0 && schema.type !== "object") {
+        delete schema.properties;
+    }
+    return schema;
+}
+function preferredMedia(content) {
+    const types = Object.keys(content || {}).sort();
+    const preferred = types.find(t => /json/i.test(t)) || types[0];
+    return { types, media: preferred ? content[preferred] : undefined };
+}
+/** Normalises route templates so renaming `{id}` to `{petId}` is not reported as remove + add. */
+function contractKey(method, route) {
+    return `${method.toUpperCase()} ${route.replace(/\{[^}]+\}/g, "{}")}`;
+}
+function buildContract(doc, specId) {
+    const operations = {};
+    for (const [route, rawItem] of Object.entries(doc?.paths || {})) {
+        const item = deref(doc, rawItem).node;
+        if (!item || typeof item !== "object")
+            continue;
+        const pathParams = Array.isArray(item.parameters) ? item.parameters : [];
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (!op || typeof op !== "object")
+                continue;
+            const parameters = {};
+            const routeParamNames = [...route.matchAll(/\{([^}]+)\}/g)].map(m => m[1]);
+            for (const rawParam of [...pathParams, ...(Array.isArray(op.parameters) ? op.parameters : [])]) {
+                const p = deref(doc, rawParam).node;
+                if (!p || typeof p !== "object" || !p.name || !p.in)
+                    continue;
+                // Path parameters are positional: key them by position so renames are not changes.
+                const index = p.in === "path" ? routeParamNames.indexOf(p.name) : -1;
+                const id = p.in === "path" && index >= 0 ? `path:#${index}` : `${p.in}:${p.name}`;
+                parameters[id] = {
+                    name: p.name,
+                    in: p.in,
+                    required: p.in === "path" ? true : Boolean(p.required),
+                    schema: normaliseSchema(doc, p.schema ?? (p.content ? preferredMedia(p.content).media?.schema : undefined))
+                };
+            }
+            let requestBody;
+            if (op.requestBody) {
+                const body = deref(doc, op.requestBody).node;
+                const { types, media } = preferredMedia(body?.content);
+                requestBody = {
+                    required: Boolean(body?.required),
+                    contentTypes: types,
+                    schema: normaliseSchema(doc, media?.schema)
+                };
+            }
+            const responses = {};
+            for (const [code, rawResponse] of Object.entries(op.responses || {})) {
+                const response = deref(doc, rawResponse).node;
+                const { types, media } = preferredMedia(response?.content);
+                responses[code] = { contentTypes: types, schema: normaliseSchema(doc, media?.schema) };
+            }
+            operations[contractKey(method, route)] = {
+                method: method.toUpperCase(),
+                route,
+                ...(typeof op.operationId === "string" ? { operationId: op.operationId } : {}),
+                ...(op.deprecated ? { deprecated: true } : {}),
+                parameters,
+                ...(requestBody ? { requestBody } : {}),
+                responses
+            };
+        }
+    }
+    return {
+        swaggerizer: 1,
+        specId,
+        title: typeof doc?.info?.title === "string" ? doc.info.title : undefined,
+        version: doc?.info?.version !== undefined ? String(doc.info.version) : undefined,
+        operations
+    };
+}
+class Collector {
+    operation;
+    changes = [];
+    constructor(operation) {
+        this.operation = operation;
+    }
+    add(severity, kind, message, location) {
+        this.changes.push({ severity, kind, operation: this.operation, ...(location ? { location } : {}), message });
+    }
+}
+function describeType(s) {
+    if (!s)
+        return "any";
+    if (s.circular)
+        return s.circular;
+    if (s.oneOf)
+        return `oneOf(${s.oneOf.length})`;
+    const base = s.type === "array" ? `${describeType(s.items)}[]` : s.type || "any";
+    return s.nullable ? `${base} | null` : base;
+}
+function compareSchema(a, b, dir, location, out, kind) {
+    if (!a && !b)
+        return;
+    if (!a || !b) {
+        if (!a)
+            out.add(dir === "response" ? "info" : "warning", kind, `Schema added`, location);
+        else
+            out.add("breaking", kind, `Schema removed`, location);
+        return;
+    }
+    if (a.circular || b.circular) {
+        if (a.circular !== b.circular)
+            out.add("warning", kind, `Recursive type changed from ${describeType(a)} to ${describeType(b)}`, location);
+        return;
+    }
+    if ((a.type || "any") !== (b.type || "any")) {
+        out.add("breaking", kind, `Type changed from ${describeType(a)} to ${describeType(b)}`, location);
+        return;
+    }
+    if ((a.format || "") !== (b.format || "")) {
+        out.add("warning", kind, `Format changed from '${a.format ?? "none"}' to '${b.format ?? "none"}'`, location);
+    }
+    if (!a.nullable && b.nullable) {
+        out.add(dir === "response" ? "breaking" : "info", kind, `Can now be null`, location);
+    }
+    else if (a.nullable && !b.nullable) {
+        out.add(dir === "request" ? "breaking" : "info", kind, `Can no longer be null`, location);
+    }
+    if (a.enum || b.enum) {
+        const before = new Set((a.enum || []).map(v => JSON.stringify(v)));
+        const after = new Set((b.enum || []).map(v => JSON.stringify(v)));
+        const removed = [...before].filter(v => !after.has(v));
+        const added = [...after].filter(v => !before.has(v));
+        if (!a.enum && b.enum) {
+            out.add(dir === "request" ? "breaking" : "info", kind, `Now restricted to ${[...after].join(", ")}`, location);
+        }
+        else if (a.enum && !b.enum) {
+            out.add(dir === "response" ? "warning" : "info", kind, `No longer restricted to a fixed set of values`, location);
+        }
+        else {
+            if (removed.length) {
+                out.add(dir === "request" ? "breaking" : "info", kind, `Enum value(s) removed: ${removed.join(", ")}`, location);
+            }
+            if (added.length) {
+                out.add(dir === "response" ? "warning" : "info", kind, `Enum value(s) added: ${added.join(", ")}`, location);
+            }
+        }
+    }
+    if (a.oneOf || b.oneOf) {
+        const la = a.oneOf?.length ?? 0;
+        const lb = b.oneOf?.length ?? 0;
+        if (la !== lb) {
+            out.add(lb > la && dir === "response" ? "warning" : lb < la && dir === "request" ? "breaking" : "info", kind, `Number of oneOf/anyOf variants changed from ${la} to ${lb}`, location);
+        }
+        const n = Math.min(la, lb);
+        for (let i = 0; i < n; i++)
+            compareSchema(a.oneOf[i], b.oneOf[i], dir, `${location}<${i}>`, out, kind);
+    }
+    if (a.type === "array" || b.type === "array") {
+        compareSchema(a.items, b.items, dir, `${location}[]`, out, kind);
+    }
+    if (a.properties || b.properties) {
+        const pa = a.properties || {};
+        const pb = b.properties || {};
+        const ra = new Set(a.required || []);
+        const rb = new Set(b.required || []);
+        for (const name of Object.keys(pa)) {
+            const where = `${location}.${name}`;
+            if (!(name in pb)) {
+                out.add(dir === "response" ? "breaking" : "warning", kind, `Property '${name}' removed`, where);
+                continue;
+            }
+            if (ra.has(name) && !rb.has(name)) {
+                out.add(dir === "response" ? "breaking" : "info", kind, `Property '${name}' is no longer required`, where);
+            }
+            else if (!ra.has(name) && rb.has(name)) {
+                out.add(dir === "request" ? "breaking" : "info", kind, `Property '${name}' is now required`, where);
+            }
+            compareSchema(pa[name], pb[name], dir, where, out, kind);
+        }
+        for (const name of Object.keys(pb)) {
+            if (name in pa)
+                continue;
+            const required = rb.has(name);
+            out.add(dir === "request" && required ? "breaking" : "info", kind, `${required ? "Required" : "Optional"} property '${name}' added`, `${location}.${name}`);
+        }
+    }
+}
+function isSuccess(code) {
+    return /^2/.test(code);
+}
+function compareOperation(key, a, b) {
+    const label = `${b.method} ${b.route}`;
+    const out = new Collector(label);
+    if ((a.operationId || "") !== (b.operationId || "")) {
+        out.add("breaking", "operation-renamed", `operationId changed from '${a.operationId ?? "none"}' to '${b.operationId ?? "none"}' — generated function names will change`);
+    }
+    if (!a.deprecated && b.deprecated)
+        out.add("warning", "operation-deprecated", "Operation is now deprecated");
+    for (const [id, pa] of Object.entries(a.parameters)) {
+        const pb = b.parameters[id];
+        const where = `${pa.in} parameter '${pa.name}'`;
+        if (!pb) {
+            out.add(pa.in === "path" ? "breaking" : "warning", "parameter-removed", `Parameter removed`, where);
+            continue;
+        }
+        if (!pa.required && pb.required)
+            out.add("breaking", "parameter-changed", "Parameter is now required", where);
+        if (pa.required && !pb.required)
+            out.add("info", "parameter-changed", "Parameter is now optional", where);
+        compareSchema(pa.schema, pb.schema, "request", where, out, "parameter-changed");
+    }
+    for (const [id, pb] of Object.entries(b.parameters)) {
+        if (a.parameters[id])
+            continue;
+        out.add(pb.required ? "breaking" : "info", "parameter-added", `${pb.required ? "Required" : "Optional"} parameter added`, `${pb.in} parameter '${pb.name}'`);
+    }
+    if (!a.requestBody && b.requestBody) {
+        out.add(b.requestBody.required ? "breaking" : "info", "request-body-added", `${b.requestBody.required ? "Required" : "Optional"} request body added`, "request body");
+    }
+    else if (a.requestBody && !b.requestBody) {
+        out.add("warning", "request-body-removed", "Request body removed", "request body");
+    }
+    else if (a.requestBody && b.requestBody) {
+        if (!a.requestBody.required && b.requestBody.required) {
+            out.add("breaking", "request-body-changed", "Request body is now required", "request body");
+        }
+        const lost = a.requestBody.contentTypes.filter(t => !b.requestBody.contentTypes.includes(t));
+        if (lost.length)
+            out.add("breaking", "request-body-changed", `Content type(s) no longer accepted: ${lost.join(", ")}`, "request body");
+        compareSchema(a.requestBody.schema, b.requestBody.schema, "request", "request body", out, "request-body-changed");
+    }
+    for (const [code, ra] of Object.entries(a.responses)) {
+        const rb = b.responses[code];
+        if (!rb) {
+            out.add(isSuccess(code) ? "breaking" : "warning", "response-removed", `Response ${code} removed`, `response ${code}`);
+            continue;
+        }
+        const lost = ra.contentTypes.filter(t => !rb.contentTypes.includes(t));
+        if (lost.length)
+            out.add("breaking", "response-changed", `Content type(s) no longer returned: ${lost.join(", ")}`, `response ${code}`);
+        compareSchema(ra.schema, rb.schema, "response", `response ${code} body`, out, "response-changed");
+    }
+    for (const code of Object.keys(b.responses)) {
+        if (a.responses[code])
+            continue;
+        out.add(isSuccess(code) ? "warning" : "info", "response-added", `Response ${code} added`, `response ${code}`);
+    }
+    return out.changes;
+}
+const SEVERITY_ORDER = { breaking: 0, warning: 1, info: 2 };
+/** Compares two contracts and reports added, removed and changed operations. */
+function diffContracts(before, after, baseline = "snapshot") {
+    const a = before?.operations || {};
+    const b = after.operations;
+    const changes = [];
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [key, op] of Object.entries(a)) {
+        if (!b[key]) {
+            removed.push(`${op.method} ${op.route}`);
+            changes.push({ severity: "breaking", kind: "operation-removed", operation: `${op.method} ${op.route}`, message: "Operation removed" });
+        }
+    }
+    for (const [key, op] of Object.entries(b)) {
+        const label = `${op.method} ${op.route}`;
+        if (!a[key]) {
+            if (before) {
+                added.push(label);
+                changes.push({ severity: "info", kind: "operation-added", operation: label, message: "New operation" });
+            }
+            continue;
+        }
+        const opChanges = compareOperation(key, a[key], op);
+        if (opChanges.length) {
+            changed.push(label);
+            changes.push(...opChanges);
+        }
+    }
+    changes.sort((x, y) => SEVERITY_ORDER[x.severity] - SEVERITY_ORDER[y.severity] || x.operation.localeCompare(y.operation));
+    const counts = { breaking: 0, warning: 0, info: 0 };
+    for (const c of changes)
+        counts[c.severity]++;
+    return {
+        specId: after.specId,
+        title: after.title,
+        baseline,
+        ...(before?.version !== undefined ? { fromVersion: before.version } : {}),
+        ...(after.version !== undefined ? { toVersion: after.version } : {}),
+        added,
+        removed,
+        changed,
+        changes,
+        counts
+    };
+}
+/** True when the report contains changes at or above the given threshold. */
+function exceedsThreshold(report, failOn) {
+    switch (failOn) {
+        case "none":
+            return false;
+        case "any":
+            return report.changes.length > 0;
+        case "warning":
+            return report.counts.breaking + report.counts.warning > 0;
+        default:
+            return report.counts.breaking > 0;
+    }
+}
+/** Plain-text rendering of a change report, for terminals and CI logs. */
+function formatReport(report, options = {}) {
+    const c = options.color
+        ? {
+            red: (s) => `\x1b[31m${s}\x1b[0m`,
+            yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+            green: (s) => `\x1b[32m${s}\x1b[0m`,
+            dim: (s) => `\x1b[2m${s}\x1b[0m`,
+            bold: (s) => `\x1b[1m${s}\x1b[0m`
+        }
+        : { red: (s) => s, yellow: (s) => s, green: (s) => s, dim: (s) => s, bold: (s) => s };
+    const lines = [];
+    const version = report.fromVersion !== undefined && report.toVersion !== undefined && report.fromVersion !== report.toVersion
+        ? ` (${report.fromVersion} → ${report.toVersion})`
+        : "";
+    lines.push(c.bold(`${report.title ?? report.specId}${version}`));
+    if (report.changes.length === 0) {
+        lines.push(c.green("  No contract changes."));
+        return lines.join("\n");
+    }
+    lines.push(`  ${c.red(`${report.counts.breaking} breaking`)}, ${c.yellow(`${report.counts.warning} warning(s)`)}, ${report.counts.info} info · ` +
+        `${report.added.length} new, ${report.removed.length} removed, ${report.changed.length} changed operation(s)`);
+    const icon = { breaking: c.red("✖ BREAKING"), warning: c.yellow("▲ WARNING "), info: c.dim("● info    ") };
+    for (const change of report.changes) {
+        if (change.severity === "info" && !options.verbose && change.kind !== "operation-added")
+            continue;
+        const where = change.location ? c.dim(` [${change.location}]`) : "";
+        lines.push(`  ${icon[change.severity]} ${change.operation} — ${change.message}${where}`);
+    }
+    const hiddenInfo = options.verbose ? 0 : report.changes.filter(x => x.severity === "info" && x.kind !== "operation-added").length;
+    if (hiddenInfo)
+        lines.push(c.dim(`  …and ${hiddenInfo} non-breaking detail(s); use --verbose to list them.`));
+    return lines.join("\n");
+}
+
+/** File names Swaggerizer writes next to generated code. */
+const CONTRACT_FILE = "swaggerizer.contract.json";
+const WRAPPER_FILE = "swaggerizer.ts";
+const INDEX_FILE = "index.ts";
+const isUrl = (input) => /^https?:\/\//i.test(input);
+/** Folders a spec's generated code lives in: client/models/contract, and mocks. */
+function outputDirs(id, root, spec = {}) {
+    const dir = path.resolve(spec.output ?? path.join(root ?? "src/api", id));
+    return { dir, mocksDir: path.resolve(spec.mocksOutput ?? dir) };
+}
+
+/*
+ * The scenario planner: which response each operation serves. Pure and browser-safe — shared by
+ * the Node mock server, the MSW runtime and the in-page debug menu so they all behave the same.
+ */
+const SCENARIO_HEADER = "x-swaggerizer-scenario";
+const MODES = ["mock", "custom", "proxy"];
+const MAX_DELAY_MS = 120_000;
+function operationKey(method, route) {
+    return `${String(method).toLowerCase()}:${route}`;
+}
+/** Every selectable (code, example) pair for an operation. */
+function variantsOf(op) {
+    const list = [];
+    for (const response of op.responses) {
+        if (response.examples.length > 0) {
+            for (const ex of response.examples) {
+                list.push({
+                    code: response.code,
+                    example: ex.name,
+                    kind: "example",
+                    value: ex.value,
+                    response,
+                    ...(ex.contentType ? { contentType: ex.contentType } : {}),
+                    ...(ex.headers ? { headers: ex.headers } : {})
+                });
+            }
+        }
+        else if (response.hasBody) {
+            list.push({ code: response.code, example: GENERATED, kind: "generated", value: response.generated, response });
+        }
+        else {
+            list.push({ code: response.code, example: EMPTY, kind: "empty", value: undefined, response });
+        }
+    }
+    return list;
+}
+function findResponse(op, code) {
+    return (op.responses.find(r => r.code === code) ||
+        op.responses.find(r => String(r.status) === code) ||
+        op.responses.find(r => r.code.toUpperCase() === code.toUpperCase()));
+}
+/** The variant that will actually be served for a code + requested example name. */
+function effectiveExample(op, code, requested) {
+    const variants = variantsOf(op).filter(v => v.code === code);
+    if (variants.length === 0)
+        return EMPTY;
+    return (variants.find(v => v.example === requested) || variants[0]).example;
+}
+function buildOperationStates(specs, scenarios, options = {}) {
+    const servedBy = new Map();
+    const states = [];
+    for (const spec of specs) {
+        for (const op of spec.operations) {
+            let active = spec.enabled && !spec.error;
+            let shadowedBy;
+            if (active) {
+                const owner = servedBy.get(op.key);
+                if (owner) {
+                    active = false;
+                    shadowedBy = owner;
+                }
+                else {
+                    servedBy.set(op.key, spec.id);
+                }
+            }
+            states.push({ ...stateOf(op, scenarios[op.key], options), active, ...(shadowedBy ? { shadowedBy } : {}) });
+        }
+    }
+    return states;
+}
+function stateOf(op, scenario = {}, options = {}) {
+    const response = scenario.code ? findResponse(op, scenario.code) : undefined;
+    const selectedCode = response ? response.code : op.defaultCode;
+    const selectedExample = effectiveExample(op, selectedCode, scenario.example);
+    const mode = scenario.mode && MODES.includes(scenario.mode) ? scenario.mode : "mock";
+    const defaultDelay = Math.max(0, Number(options.defaultDelay) || 0);
+    const delay = scenario.delay === undefined ? defaultDelay : Math.max(0, Number(scenario.delay) || 0);
+    const modified = mode !== "mock" ||
+        delay !== defaultDelay ||
+        selectedCode !== op.defaultCode ||
+        selectedExample !== effectiveExample(op, op.defaultCode, op.defaultExample);
+    return {
+        ...op,
+        mode,
+        selectedCode,
+        selectedExample,
+        delay,
+        ...(scenario.custom ? { custom: scenario.custom } : {}),
+        modified,
+        active: true
+    };
+}
+function isSet(value) {
+    return value !== undefined && value !== null && value !== "";
+}
+function normaliseCustom(raw, label) {
+    if (!raw || typeof raw !== "object")
+        throw new Error(`${label}: custom must be an object with a status.`);
+    const status = Number(raw.status);
+    if (!Number.isInteger(status) || status < 100 || status > 599) {
+        throw new Error(`${label}: custom.status must be an HTTP status between 100 and 599.`);
+    }
+    let body = raw.body;
+    let contentType = isSet(raw.contentType) ? String(raw.contentType) : undefined;
+    // Bodies typed into a form arrive as strings: keep JSON as data so it is re-serialised cleanly.
+    if (typeof body === "string" && (!contentType || /json/i.test(contentType))) {
+        const trimmed = body.trim();
+        if (trimmed === "")
+            body = undefined;
+        else {
+            try {
+                body = JSON.parse(trimmed);
+            }
+            catch {
+                if (contentType)
+                    throw new Error(`${label}: custom.body is not valid JSON.`);
+                // Not JSON and no content type given: send it exactly as typed.
+                contentType = "text/plain";
+            }
+        }
+    }
+    const headers = {};
+    if (raw.headers && typeof raw.headers === "object") {
+        for (const [k, v] of Object.entries(raw.headers))
+            headers[k] = String(v);
+    }
+    return {
+        status,
+        ...(body !== undefined ? { body } : {}),
+        ...(contentType ? { contentType } : {}),
+        ...(Object.keys(headers).length ? { headers } : {})
+    };
+}
+/**
+ * Validates a selection against an operation and returns the complete scenario to store. Throws a
+ * readable error for unknown codes, examples or modes. Unset fields keep their current value.
+ */
+function applySelection(op, selection, current = {}) {
+    const label = `${op.method.toUpperCase()} ${op.route}`;
+    const next = { ...current };
+    if (isSet(selection.mode)) {
+        const mode = String(selection.mode);
+        if (!MODES.includes(mode))
+            throw new Error(`${label}: mode must be one of ${MODES.join(", ")}.`);
+        next.mode = mode;
+    }
+    let code = isSet(selection.code) ? String(selection.code) : undefined;
+    const example = isSet(selection.example) ? String(selection.example) : undefined;
+    if (!code && example) {
+        // Allow `?example=notFound` on its own: find the response that declares it.
+        const owner = variantsOf(op).find(v => v.example === example);
+        if (!owner)
+            throw new Error(`${label} has no example named '${example}'.`);
+        code = owner.code;
+    }
+    if (code) {
+        const response = findResponse(op, code);
+        if (!response)
+            throw new Error(`${label} does not declare a ${code} response.`);
+        code = response.code;
+        if (example) {
+            const known = variantsOf(op).some(v => v.code === code && v.example === example);
+            if (!known)
+                throw new Error(`The ${code} response of ${label} has no example named '${example}'.`);
+        }
+        next.code = code;
+        next.example = example ?? effectiveExample(op, code);
+        if (!isSet(selection.mode))
+            next.mode = "mock";
+    }
+    if (selection.custom !== undefined && selection.custom !== null) {
+        next.custom = normaliseCustom(selection.custom, label);
+        if (!isSet(selection.mode))
+            next.mode = "custom";
+    }
+    if (next.mode === "custom" && !next.custom) {
+        // Start the editor from whatever is currently being served.
+        const state = stateOf(op, current);
+        const variant = variantsOf(op).find(v => v.code === state.selectedCode && v.example === state.selectedExample);
+        next.custom = {
+            status: variant?.response.status ?? 200,
+            ...(variant?.value !== undefined ? { body: variant.value } : {})
+        };
+    }
+    if (isSet(selection.delay)) {
+        const delay = Number(selection.delay);
+        if (!Number.isFinite(delay) || delay < 0 || delay > MAX_DELAY_MS) {
+            throw new Error(`${label}: delay must be between 0 and ${MAX_DELAY_MS} ms.`);
+        }
+        next.delay = Math.round(delay);
+    }
+    if (next.mode === "mock")
+        delete next.mode;
+    // An explicit 0 is kept: it overrides a server-wide default delay.
+    if (next.delay === undefined)
+        delete next.delay;
+    return next;
+}
+/** Parses the per-request override header: `404`, `404:notFound`, `notFound`, `proxy`, `custom`. */
+function parseScenarioHeader(value) {
+    if (!value)
+        return undefined;
+    const raw = String(value).trim();
+    if (!raw)
+        return undefined;
+    if (MODES.includes(raw))
+        return { mode: raw };
+    const [first, ...rest] = raw.split(":");
+    if (/^(\d{3}|[1-5]XX|default)$/i.test(first)) {
+        return { code: first, ...(rest.length ? { example: rest.join(":") } : {}), mode: "mock" };
+    }
+    return { example: raw, mode: "mock" };
+}
+/** Decides what to send for one request to an operation. */
+function resolveResponse(op, override) {
+    let state = op;
+    if (override) {
+        try {
+            const scenario = applySelection(op, override, scenarioFromState(op));
+            state = { ...op, ...stateOf(op, { delay: op.delay, ...scenario }) };
+        }
+        catch {
+            // An override that does not fit this operation is ignored rather than failing the request.
+        }
+    }
+    if (state.mode === "proxy")
+        return { kind: "proxy", delay: state.delay };
+    if (state.mode === "custom" && state.custom) {
+        return {
+            kind: "respond",
+            status: state.custom.status,
+            contentType: state.custom.contentType ?? (state.custom.body !== undefined ? "application/json" : undefined),
+            headers: state.custom.headers,
+            body: state.custom.body,
+            variant: "custom",
+            code: String(state.custom.status),
+            delay: state.delay
+        };
+    }
+    const variant = variantsOf(state).find(v => v.code === state.selectedCode && v.example === state.selectedExample);
+    if (!variant) {
+        return { kind: "respond", status: 200, body: {}, contentType: "application/json", variant: EMPTY, code: "200", delay: state.delay };
+    }
+    const contentType = variant.contentType || variant.response.contentTypes.find(t => /json/i.test(t)) || variant.response.contentTypes[0];
+    return {
+        kind: "respond",
+        status: variant.response.status,
+        contentType,
+        ...(variant.headers ? { headers: variant.headers } : {}),
+        body: variant.kind === "empty" ? undefined : variant.value,
+        variant: variant.example,
+        code: variant.code,
+        delay: state.delay
+    };
+}
+function scenarioFromState(op) {
+    return {
+        code: op.selectedCode,
+        example: op.selectedExample,
+        ...(op.mode !== "mock" ? { mode: op.mode } : {}),
+        ...(op.custom ? { custom: op.custom } : {}),
+        delay: op.delay
+    };
+}
+/** Serialises a resolved body for the wire. */
+function encodeBody(body, contentType) {
+    if (body === undefined)
+        return undefined;
+    if (typeof body === "string" && contentType && !/json/i.test(contentType))
+        return body;
+    return JSON.stringify(body);
+}
+const routeCache = new Map();
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function compileRoute(route) {
+    const cached = routeCache.get(route);
+    if (cached)
+        return cached;
+    let statics = 0;
+    let params = 0;
+    const pattern = route
+        .split("/")
+        .map(segment => {
+        if (!segment)
+            return "";
+        if (/\{[^}]+\}/.test(segment)) {
+            params++;
+            return segment
+                .split(/(\{[^}]+\})/)
+                .map(part => (/^\{[^}]+\}$/.test(part) ? "([^/]+)" : escapeRegex(part)))
+                .join("");
+        }
+        statics++;
+        return escapeRegex(segment);
+    })
+        .join("/");
+    const compiled = { regex: new RegExp(`^${pattern || "/"}/?$`), statics, params };
+    routeCache.set(route, compiled);
+    return compiled;
+}
+/** Static segments beat templated ones, so `/pets/mine` wins over `/pets/{petId}`. */
+function routeSpecificity(a, b) {
+    const ra = compileRoute(a.route);
+    const rb = compileRoute(b.route);
+    return rb.statics - ra.statics || ra.params - rb.params || a.route.localeCompare(b.route);
+}
+/**
+ * Finds the active operation that serves `method` + `pathname`, trying the path as-is and with
+ * each known base path (from `servers`) stripped.
+ */
+function matchOperation(operations, method, pathname, basePaths = [], aliases = {}) {
+    const m = method.toLowerCase();
+    const candidates = operations.filter(op => op.active && op.method === m).sort(routeSpecificity);
+    return candidatePaths(pathname, basePaths, aliases)
+        .map(path => candidates.find(op => compileRoute(op.route).regex.test(path)))
+        .find(Boolean);
+}
+/** Replaces a matching alias prefix: `/online-banking/bff/v4/x` with `{ "/online-banking/bff/v4/": "/v4/online-banking/" }` → `/v4/online-banking/x`. */
+function applyAliases(pathname, aliases = {}) {
+    const out = [];
+    for (const [from, to] of Object.entries(aliases)) {
+        if (from && pathname.startsWith(from))
+            out.push(to + pathname.slice(from.length));
+    }
+    return out;
+}
+/** Every spelling of a request path worth matching: as-is, de-aliased, and with base paths stripped. */
+function candidatePaths(pathname, basePaths = [], aliases = {}) {
+    const paths = [pathname, ...applyAliases(pathname, aliases)];
+    for (const path of [...paths]) {
+        for (const base of basePaths) {
+            if (base && (path === base || path.startsWith(base + "/")))
+                paths.push(path.slice(base.length) || "/");
+        }
+    }
+    return [...new Set(paths)];
+}
+/** The base path that prefixes `pathname` (after aliases), and the path relative to it. */
+function relativeToBase(pathname, basePaths = [], aliases = {}) {
+    const [aliased = pathname] = applyAliases(pathname, aliases);
+    const base = basePaths.find(b => aliased === b || aliased.startsWith(b + "/"));
+    return base ? aliased.slice(base.length) || "/" : aliased;
+}
+
+/*
+ * Flattens an OpenAPI 3 document into one entry per method + route, recording every response code
+ * and named example so they can be listed and switched from the admin page and debug menu.
+ */
+function text(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+/** HTTP status to send for a response key: "404" → 404, "2XX" → 200, "default" → 500. */
+function statusForCode(code) {
+    if (/^\d{3}$/.test(code))
+        return Number(code);
+    const range = /^([1-5])XX$/i.exec(code);
+    if (range)
+        return Number(range[1]) * 100;
+    return 500;
+}
+function preferredContentType(types) {
+    return (types.find(t => /^application\/json/i.test(t)) ||
+        types.find(t => /\+json/i.test(t)) ||
+        types.find(t => /json/i.test(t)) ||
+        types[0]);
+}
+function extractExamples(media, doc) {
+    if (!media || typeof media !== "object")
+        return [];
+    const examples = [];
+    if (media.examples && typeof media.examples === "object") {
+        for (const [name, raw] of Object.entries(media.examples)) {
+            const { node } = deref(doc, raw);
+            if (node && typeof node === "object" && "value" in node) {
+                examples.push({ name, summary: text(node.summary), value: node.value });
+            }
+            else if (node && typeof node === "object" && node.externalValue) {
+                examples.push({ name, summary: text(node.summary) ?? `external: ${node.externalValue}`, value: null });
+            }
+        }
+    }
+    if (examples.length === 0 && media.example !== undefined) {
+        examples.push({ name: "example", value: media.example });
+    }
+    if (examples.length === 0 && media.schema) {
+        const { node: schema } = deref(doc, media.schema);
+        if (schema && schema.example !== undefined) {
+            examples.push({ name: "example", value: schema.example });
+        }
+        else if (schema && Array.isArray(schema.examples) && schema.examples.length > 0) {
+            schema.examples.forEach((value, i) => examples.push({ name: i === 0 ? "example" : `example${i + 1}`, value }));
+        }
+    }
+    return examples;
+}
+/**
+ * Media types as they are served. springdoc writes `*\/*` for JSON responses; serving that as a
+ * Content-Type confuses clients, so wildcards become `application/json`.
+ */
+function normaliseMediaType(type) {
+    const t = type.trim().toLowerCase();
+    return t === "*/*" || t === "*" || t === "application/*" ? "application/json" : type;
+}
+function buildResponse(code, raw, doc) {
+    const { node: response } = deref(doc, raw);
+    const content = response?.content && typeof response.content === "object" ? response.content : {};
+    const contentTypes = [...new Set(Object.keys(content).map(normaliseMediaType))];
+    const keys = Object.keys(content);
+    const preferred = preferredContentType(keys) ?? keys[0];
+    const media = preferred ? content[preferred] : keys.length ? content[keys[0]] : undefined;
+    const examples = extractExamples(media, doc);
+    const result = {
+        code,
+        status: statusForCode(code),
+        description: text(response?.description),
+        contentTypes,
+        hasBody: contentTypes.length > 0,
+        examples
+    };
+    if (media && examples.length === 0) {
+        result.generated = media.schema ? sampleFromSchema(media.schema, doc) : {};
+    }
+    return result;
+}
+function sortCodes(a, b) {
+    return statusForCode(a) - statusForCode(b) || a.localeCompare(b);
+}
+function defaultVariant(responses) {
+    const sorted = [...responses].sort((a, b) => sortCodes(a.code, b.code));
+    const response = sorted.find(r => r.status >= 200 && r.status < 300) || sorted[0];
+    if (!response)
+        return { code: "200", example: EMPTY };
+    return { code: response.code, example: firstVariantName(response) };
+}
+function firstVariantName(response) {
+    if (response.examples.length > 0)
+        return response.examples[0].name;
+    return response.hasBody ? GENERATED : EMPTY;
+}
+function buildCatalogue(doc, specId) {
+    const operations = [];
+    for (const [route, rawItem] of Object.entries(doc?.paths || {})) {
+        const { node: item } = deref(doc, rawItem);
+        if (!item || typeof item !== "object")
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (!op || typeof op !== "object")
+                continue;
+            const responses = Object.entries(op.responses || {})
+                .sort(([a], [b]) => sortCodes(a, b))
+                .map(([code, raw]) => buildResponse(code, raw, doc));
+            const def = defaultVariant(responses);
+            operations.push({
+                key: operationKey(method, route),
+                method,
+                route,
+                specId,
+                operationId: text(op.operationId),
+                summary: text(op.summary),
+                description: text(op.description) ?? text(item.description),
+                tags: Array.isArray(op.tags) ? op.tags.map(String) : [],
+                ...(op.deprecated ? { deprecated: true } : {}),
+                responses,
+                defaultCode: def.code,
+                defaultExample: def.example
+            });
+        }
+    }
+    return operations;
+}
+/** Path prefixes from `servers`, e.g. `https://api.example.com/v1` → `/v1`. */
+function basePathsOf(doc) {
+    const out = new Set();
+    for (const server of Array.isArray(doc?.servers) ? doc.servers : []) {
+        const url = typeof server?.url === "string" ? server.url : "";
+        // Substitute server variables with their defaults.
+        const resolved = url.replace(/\{([^}]+)\}/g, (_m, name) => {
+            const value = server?.variables?.[name]?.default;
+            return value !== undefined ? String(value) : "";
+        });
+        let pathname;
+        try {
+            pathname = new URL(resolved, "http://localhost").pathname;
+        }
+        catch {
+            continue;
+        }
+        pathname = pathname.replace(/\/+$/, "");
+        if (pathname && pathname !== "/")
+            out.add(pathname);
+    }
+    return [...out];
+}
+/** The first absolute http(s) server URL, used as the default proxy target. */
+function serverUrlOf(doc) {
+    for (const server of Array.isArray(doc?.servers) ? doc.servers : []) {
+        const url = typeof server?.url === "string" ? server.url : "";
+        const resolved = url.replace(/\{([^}]+)\}/g, (_m, name) => String(server?.variables?.[name]?.default ?? ""));
+        if (/^https?:\/\//i.test(resolved))
+            return resolved.replace(/\/+$/, "");
+    }
+    return undefined;
+}
+
+/* Loading Swagger 2.0 / OpenAPI 3.x files into a bundled OpenAPI 3 document (Node only). */
+const SPEC_FILE_PATTERN = /\.(ya?ml|json)$/i;
+/**
+ * Reads spec URLs (and relative $refs on the same origin) with fetch. The parser's own HTTP
+ * resolver refuses localhost and private addresses, which is where api-docs usually live
+ * (`http://localhost:8080/v3/api-docs`, internal gateways), and cannot send auth headers.
+ * $refs to any other origin still go through the parser's guarded resolver.
+ */
+function specUrlResolver(root, options) {
+    const origin = new URL(root).origin;
+    return {
+        order: 1,
+        canRead: (file) => {
+            try {
+                return /^https?:/i.test(file.url) && new URL(file.url).origin === origin;
+            }
+            catch {
+                return false;
+            }
+        },
+        read: async (file) => {
+            const url = file.url.split("#")[0];
+            let response;
+            try {
+                response = await fetch(url, {
+                    headers: { Accept: "application/json, application/yaml;q=0.9, */*;q=0.5", ...(options.headers || {}) },
+                    signal: AbortSignal.timeout(options.timeout ?? 30000)
+                });
+            }
+            catch (err) {
+                const reason = err?.name === "TimeoutError" ? "timed out" : err?.cause?.code || err?.message || String(err);
+                throw new Error(`Could not fetch ${url}: ${reason}`);
+            }
+            if (!response.ok)
+                throw new Error(`${url} answered ${response.status} ${response.statusText}`.trim());
+            return response.text();
+        }
+    };
+}
+async function convertSwagger2(api) {
+    const mod = await import('swagger2openapi');
+    const converter = mod.convertObj ? mod : mod.default;
+    const options = { patch: true, warnOnly: true, resolve: false };
+    const result = await converter.convertObj(api, options);
+    const warnings = (options.warnings || result?.warnings || []).map((w) => (w?.message ? String(w.message) : String(w)));
+    renameSwagger2Examples(result.openapi);
+    return { doc: result.openapi, warnings };
+}
+/** swagger2openapi names a Swagger 2 response example "response"; call it "example" like OAS3's singular form. */
+function renameSwagger2Examples(doc) {
+    const visitResponses = (responses) => {
+        for (const response of Object.values(responses || {})) {
+            for (const media of Object.values(response?.content || {})) {
+                const keys = media?.examples ? Object.keys(media.examples) : [];
+                if (keys.length === 1 && keys[0] === "response") {
+                    media.examples = { example: media.examples.response };
+                }
+            }
+        }
+    };
+    for (const item of Object.values(doc?.paths || {})) {
+        for (const op of Object.values(item || {})) {
+            if (op && typeof op === "object" && op.responses)
+                visitResponses(op.responses);
+        }
+    }
+    visitResponses(doc?.components?.responses);
+}
+/** Quick check used when scanning folders: is this YAML/JSON file an OpenAPI or Swagger document? */
+async function looksLikeSpec(file) {
+    try {
+        const head = (await fs.promises.readFile(file, "utf8")).slice(0, 4096);
+        return /["']?(openapi|swagger)["']?\s*:/.test(head);
+    }
+    catch {
+        return false;
+    }
+}
+async function listSpecFiles(folder) {
+    const absolute = path.resolve(folder);
+    const entries = await fs.promises.readdir(absolute, { withFileTypes: true });
+    const files = entries
+        .filter(e => e.isFile() && SPEC_FILE_PATTERN.test(e.name) && !e.name.startsWith("."))
+        .map(e => path.join(absolute, e.name))
+        .sort();
+    const specs = [];
+    for (const file of files)
+        if (await looksLikeSpec(file))
+            specs.push(file);
+    return specs;
+}
+async function loadSpecFile(file, options = {}) {
+    const remote = isUrl(file);
+    const absolute = remote ? file : path.resolve(file);
+    // bundle() resolves external $refs into internal ones but keeps the document acyclic.
+    const bundled = remote
+        ? await SwaggerParser.bundle(absolute, { resolve: { swaggerizer: specUrlResolver(absolute, options) } })
+        : await SwaggerParser.bundle(absolute);
+    const raw = remote ? structuredClone(bundled) : undefined;
+    const warnings = [];
+    let doc = bundled;
+    let specVersion;
+    if (typeof bundled?.swagger === "string") {
+        specVersion = bundled.swagger;
+        const converted = await convertSwagger2(bundled);
+        doc = converted.doc;
+        warnings.push(...converted.warnings);
+    }
+    else if (typeof bundled?.openapi === "string") {
+        specVersion = bundled.openapi;
+    }
+    else {
+        throw new Error("Not an OpenAPI or Swagger document (missing `openapi` / `swagger` field).");
+    }
+    try {
+        // Validate a copy: validation dereferences in place.
+        await SwaggerParser.validate(structuredClone(bundled));
+    }
+    catch (err) {
+        const details = Array.isArray(err?.details) ? err.details : [];
+        if (details.length) {
+            warnings.push(...details.slice(0, 10).map(d => `${d.message ?? d}${d.path ? ` at ${[].concat(d.path).join(".")}` : ""}`));
+        }
+        else {
+            warnings.push(String(err?.message ?? err).split("\n")[0]);
+        }
+    }
+    return { file: absolute, specVersion, doc, ...(raw ? { raw } : {}), warnings: warnings.slice(0, 20) };
+}
+/** Stable id for a spec file: its basename without extensions (`users.swagger.json` → `users`). */
+function specIdFor(file) {
+    const name = isUrl(file) ? new URL(file).pathname.split("/").filter(Boolean).pop() || new URL(file).hostname : file;
+    return path
+        .basename(name)
+        .replace(SPEC_FILE_PATTERN, "")
+        .replace(/\.(swagger|openapi|oas|spec)$/i, "")
+        .replace(/[^A-Za-z0-9_-]+/g, "-");
+}
+async function analyseSpecFile(file, id = specIdFor(file), options = {}) {
+    const loaded = await loadSpecFile(file, options);
+    return {
+        ...loaded,
+        id,
+        operations: buildCatalogue(loaded.doc, id),
+        contract: buildContract(loaded.doc, id),
+        basePaths: basePathsOf(loaded.doc),
+        serverUrl: serverUrlOf(loaded.doc)
+    };
+}
+/** Accepts a mix of spec files and folders and returns every spec file, folder contents sorted. */
+async function resolveSpecInputs(inputs) {
+    const out = [];
+    for (const input of inputs) {
+        if (isUrl(input)) {
+            out.push(input);
+            continue;
+        }
+        const absolute = path.resolve(input);
+        const stat = await fs.promises.stat(absolute);
+        if (stat.isDirectory())
+            out.push(...(await listSpecFiles(absolute)));
+        else
+            out.push(absolute);
+    }
+    return [...new Set(out)];
+}
+
+/*
+ * swaggerizer/config — the `swaggerizer.config.ts` shape, scenario overlays and custom handlers.
+ * Browser-safe: a config file (and the fixtures it imports) can be shared with the MSW runtime.
+ */
+function result(body, status = 200, headers, contentType) {
+    return {
+        __swaggerizer: "result",
+        status,
+        ...(body !== undefined ? { body } : {}),
+        ...(headers ? { headers } : {}),
+        ...({})
+    };
+}
+function isHandlerResult(value) {
+    return Boolean(value && typeof value === "object" && value.__swaggerizer === "result");
+}
+/** Finds the entry for an operation in a map keyed by operationId or `"METHOD /route"`. */
+function lookupByOperation(map, op) {
+    if (!map)
+        return undefined;
+    if (op.operationId && map[op.operationId] !== undefined)
+        return map[op.operationId];
+    const spaced = `${op.method.toUpperCase()} ${op.route}`;
+    if (map[spaced] !== undefined)
+        return map[spaced];
+    return map[operationKey(op.method, op.route)];
+}
+/** Keys in an overlay or handler map that match no operation (typos, removed operations). */
+function unmatchedKeys(map, operations) {
+    if (!map)
+        return [];
+    return Object.keys(map).filter(key => !operations.some(op => op.operationId === key || `${op.method.toUpperCase()} ${op.route}` === key || op.key === key));
+}
+/**
+ * Adds overlay scenarios to the catalogue. They come first, so the first overlay of a success
+ * code becomes the default. A synthesised body stays available as "generated".
+ */
+function applyOverlays(operations, overlays) {
+    if (!overlays)
+        return operations;
+    return operations.map(op => {
+        const named = lookupByOperation(overlays, op);
+        if (!named || Object.keys(named).length === 0)
+            return op;
+        const responses = op.responses.map(r => ({ ...r, examples: [...r.examples] }));
+        const added = new Map();
+        for (const [name, overlay] of Object.entries(named)) {
+            const code = String(overlay.status);
+            let response = responses.find(r => r.code === code) ?? responses.find(r => r.status === overlay.status);
+            if (!response) {
+                response = {
+                    code,
+                    status: overlay.status,
+                    description: "Scenario overlay",
+                    contentTypes: overlay.body !== undefined ? [overlay.contentType ?? "application/json"] : [],
+                    hasBody: overlay.body !== undefined,
+                    examples: []
+                };
+                responses.push(response);
+            }
+            if (!added.has(response.code)) {
+                added.set(response.code, response);
+                // Keep the schema-generated body selectable once named examples exist.
+                if (response.examples.length === 0 && response.generated !== undefined) {
+                    response.examples.push({ name: GENERATED, value: response.generated });
+                }
+            }
+            const overlayExamples = response.examples.filter(e => e.overlay);
+            const rest = response.examples.filter(e => !e.overlay && e.name !== name);
+            response.examples = [
+                ...overlayExamples,
+                {
+                    name,
+                    value: overlay.body,
+                    overlay: true,
+                    ...(overlay.summary ? { summary: overlay.summary } : {}),
+                    ...(overlay.contentType ? { contentType: overlay.contentType } : {}),
+                    ...(overlay.headers ? { headers: overlay.headers } : {})
+                },
+                ...rest
+            ];
+            if (overlay.body !== undefined)
+                response.hasBody = true;
+        }
+        responses.sort((a, b) => a.status - b.status || a.code.localeCompare(b.code));
+        const success = responses.find(r => r.status >= 200 && r.status < 300) ?? responses[0];
+        const defaultCode = success ? success.code : op.defaultCode;
+        const defaultExample = success?.examples[0]?.name ?? op.defaultExample;
+        return { ...op, responses, defaultCode, defaultExample };
+    });
+}
+/** Path parameters of `route` in `path` (path relative to any base path). */
+function extractParams(route, path) {
+    const names = [...route.matchAll(/\{([^}]+)\}/g)].map(m => m[1]);
+    if (names.length === 0)
+        return {};
+    const pattern = route
+        .split(/(\{[^}]+\})/)
+        .map(part => (/^\{[^}]+\}$/.test(part) ? "([^/]+)" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
+        .join("");
+    const match = new RegExp(`^${pattern}/?$`).exec(path);
+    if (!match)
+        return {};
+    return Object.fromEntries(names.map((n, i) => [n, decodeURIComponent(match[i + 1])]));
+}
+function createHandlerContext(base) {
+    return {
+        ...base,
+        json: (body, status = 200, headers) => result(body, status, headers),
+        empty: (status = 204, headers) => result(undefined, status, headers)
+    };
+}
+
+/*
+ * `swaggerizer generate`: runs orval for every spec (client + typed models + MSW handlers), then
+ * writes a Swaggerizer wrapper that makes those MSW handlers follow the admin's scenario choices,
+ * plus a contract snapshot used to warn about API changes before the next regeneration.
+ */
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function pascal(text) {
+    const out = text
+        .replace(/[^A-Za-z0-9]+/g, " ")
+        .trim()
+        .split(/\s+/)
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join("");
+    return /^[0-9]/.test(out) ? `Api${out}` : out || "Api";
+}
+function camel(text) {
+    const p = pascal(text);
+    return p.charAt(0).toLowerCase() + p.slice(1);
+}
+/** Snapshots of specs that were generated before but are no longer among the inputs. */
+function orphanSnapshots(output, ids) {
+    if (!fs.existsSync(output))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(output, { withFileTypes: true })) {
+        if (!entry.isDirectory() || ids.has(entry.name))
+            continue;
+        const snapshot = readJson(path.join(output, entry.name, CONTRACT_FILE));
+        if (snapshot?.operations && Object.keys(snapshot.operations).length > 0)
+            out.push(snapshot);
+    }
+    return out;
+}
+/** Every spec to work on: those declared in the config plus any extra files, folders or URLs. */
+async function resolveTargets(specInputs, config) {
+    const targets = [];
+    for (const [id, spec] of Object.entries(config?.specs || {})) {
+        const input = spec.file && fs.existsSync(spec.file) ? spec.file : spec.source;
+        if (!input)
+            throw new Error(`Spec '${id}' needs a \`file\` that exists or a \`source\` URL (run \`swaggerizer pull\`).`);
+        targets.push({ id, input, config: spec });
+    }
+    const extra = specInputs === undefined ? [] : [].concat(specInputs);
+    if (extra.length) {
+        const files = await resolveSpecInputs(extra);
+        if (files.length === 0)
+            throw new Error(`No OpenAPI / Swagger files found in ${extra.join(", ")}.`);
+        for (const file of files) {
+            const id = specIdFor(file);
+            if (!targets.some(t => t.id === id))
+                targets.push({ id, input: file, config: config?.specs?.[id] || {} });
+        }
+    }
+    if (targets.length === 0)
+        throw new Error("No specs given: pass --folder or create swaggerizer.config.ts.");
+    return targets;
+}
+async function analyseTarget(target, headers) {
+    const spec = await analyseSpecFile(target.input, target.id, { headers: { ...(headers || {}), ...(target.config.headers || {}) } });
+    spec.operations = applyOverlays(spec.operations, target.config.scenarios);
+    for (const key of unmatchedKeys(target.config.scenarios, spec.operations)) {
+        spec.warnings.push(`Scenario overlay '${key}' matches no operation`);
+    }
+    return { ...spec, config: target.config };
+}
+/** Compares every spec with the snapshot saved at the last generation. */
+async function checkChanges(specInputs, output, config, headers = config?.headers) {
+    const targets = await resolveTargets(specInputs, config);
+    const specs = [];
+    for (const target of targets)
+        specs.push(await analyseTarget(target, headers));
+    const root = path.resolve(output ?? config?.output ?? "src/api");
+    const reports = [];
+    for (const spec of specs) {
+        const snapshot = readJson(path.join(outputDirs(spec.id, root, spec.config).dir, CONTRACT_FILE));
+        if (!snapshot) {
+            reports.push({
+                specId: spec.id,
+                title: spec.contract.title,
+                baseline: "snapshot",
+                toVersion: spec.contract.version,
+                added: Object.values(spec.contract.operations).map(o => `${o.method} ${o.route}`),
+                removed: [],
+                changed: [],
+                changes: Object.values(spec.contract.operations).map(o => ({
+                    severity: "info",
+                    kind: "operation-added",
+                    operation: `${o.method} ${o.route}`,
+                    message: "New operation (first generation)"
+                })),
+                counts: { breaking: 0, warning: 0, info: Object.keys(spec.contract.operations).length }
+            });
+            continue;
+        }
+        reports.push(diffContracts(snapshot, spec.contract, "snapshot"));
+    }
+    for (const orphan of orphanSnapshots(root, new Set(specs.map(s => s.id)))) {
+        // The spec file is gone: everything it declared will disappear from the generated code.
+        const report = diffContracts(orphan, { ...orphan, operations: {} }, "snapshot");
+        report.title = `${orphan.title ?? orphan.specId} (spec file removed)`;
+        reports.push(report);
+    }
+    return { specs, reports };
+}
+function mergeOrval(...parts) {
+    const out = {};
+    for (const part of parts) {
+        for (const [key, value] of Object.entries(part || {})) {
+            out[key] =
+                value && typeof value === "object" && !Array.isArray(value) && out[key] && typeof out[key] === "object"
+                    ? mergeOrval(out[key], value)
+                    : value;
+        }
+    }
+    return out;
+}
+async function runOrval(spec, dir, options) {
+    const mod = await import('orval');
+    const generate = mod.generate ?? mod.default;
+    const output = mergeOrval({
+        target: path.join(dir, `${spec.id}.ts`),
+        schemas: path.join(dir, "model"),
+        client: options.client || options.config?.client || "fetch",
+        mode: "split",
+        mock: options.mock !== false,
+        clean: true,
+        ...(options.baseUrl ? { baseUrl: options.baseUrl } : {})
+    }, options.orval, spec.config.orval);
+    // A spec URL is handed to orval as the copy already fetched (with any auth headers and
+    // same-origin $refs bundled in), so orval never needs network access of its own.
+    const tmp = spec.raw ? fs.mkdtempSync(path.join(os.tmpdir(), "swaggerizer-")) : undefined;
+    const input = tmp ? path.join(tmp, `${spec.id}.json`) : spec.file;
+    if (tmp)
+        fs.writeFileSync(input, JSON.stringify(spec.raw));
+    try {
+        await generate({ input: { target: input }, output }, process.cwd(), { logLevel: options.silent ? "silent" : "warn" });
+    }
+    finally {
+        if (tmp)
+            fs.rmSync(tmp, { recursive: true, force: true });
+    }
+    return output;
+}
+function relImport(fromDir, target) {
+    const rel = path.relative(fromDir, target).split(path.sep).join("/");
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+/**
+ * Moves orval's MSW + faker files into the mocks folder (Nx-style repos keep mocks apart from
+ * shipped code) and points their imports back at the models.
+ */
+function moveMocks(id, dir, mocksDir) {
+    fs.mkdirSync(mocksDir, { recursive: true });
+    const modelImport = relImport(mocksDir, path.join(dir, "model"));
+    for (const name of [`${id}.msw.ts`, `${id}.faker.ts`]) {
+        const from = path.join(dir, name);
+        if (!fs.existsSync(from))
+            continue;
+        const source = fs.readFileSync(from, "utf8").replace(/from (['"])\.\/model\1/g, `from $1${modelImport}$1`);
+        fs.writeFileSync(path.join(mocksDir, name), source);
+        fs.rmSync(from);
+    }
+}
+/** Name of orval's aggregate `get<Title>Mock()` export in the generated `.msw.ts` file. */
+function findMockAggregate(source) {
+    const match = /export const (get\w*Mock)\s*=\s*\([^)]*\)\s*=>\s*\[/.exec(source);
+    return match ? match[1] : undefined;
+}
+function renderWrapper(spec, manifest, mockModule, aggregate, runtimeImport) {
+    const name = pascal(spec.contract.title || spec.id);
+    const lines = [
+        "/**",
+        " * Generated by Swaggerizer — do not edit by hand. Re-run `swaggerizer generate` instead.",
+        ` * ${spec.contract.title ?? spec.id}${spec.contract.version ? ` v${spec.contract.version}` : ""}`,
+        " */",
+        `import { createSwaggerizerMocks, type SwaggerizerManifest, type SwaggerizerMswOptions } from "${runtimeImport}";`
+    ];
+    if (mockModule && aggregate)
+        lines.push(`import { ${aggregate} } from "./${mockModule}";`);
+    lines.push("", `export const manifest: SwaggerizerManifest = ${JSON.stringify(manifest, null, 2)};`, "", "/** orval's faker-based MSW handlers, used whenever a \"generated\" response is selected. */", mockModule && aggregate ? `export const fallbackHandlers = () => ${aggregate}();` : "export const fallbackHandlers = () => [];", "", `/** MSW handlers for ${spec.contract.title ?? spec.id} that follow the Swaggerizer scenario choices. */`, `export function create${name}Mocks(options: SwaggerizerMswOptions = {}) {`, "  return createSwaggerizerMocks({", "    ...options,", "    manifests: [manifest, ...(options.manifests ?? [])],", "    fallbackHandlers: [...fallbackHandlers(), ...(options.fallbackHandlers ?? [])]", "  });", "}", "");
+    return lines.join("\n");
+}
+function renderIndex(entries, runtimeImport) {
+    const lines = [
+        "/** Generated by Swaggerizer — do not edit by hand. Re-run `swaggerizer generate` instead. */",
+        `import { createSwaggerizerMocks, type SwaggerizerMswOptions } from "${runtimeImport}";`
+    ];
+    for (const e of entries) {
+        lines.push(`import { manifest as ${camel(e.id)}Manifest, fallbackHandlers as ${camel(e.id)}Fallback } from "./${e.id}/swaggerizer";`);
+    }
+    lines.push("");
+    for (const e of entries)
+        lines.push(`export * as ${camel(e.id)} from "./${e.id}/${e.clientModule}";`);
+    lines.push("", `export const manifests = [${entries.map(e => `${camel(e.id)}Manifest`).join(", ")}];`, "", "/**", " * One set of MSW handlers for every spec. Pass `server: \"http://localhost:8080/swaggerizer\"` to follow", " * the choices made in a running Swaggerizer admin page.", " */", "export function createMocks(options: SwaggerizerMswOptions = {}) {", "  return createSwaggerizerMocks({", "    ...options,", "    manifests: [...manifests, ...(options.manifests ?? [])],", `    fallbackHandlers: [${entries.map(e => `...${camel(e.id)}Fallback()`).join(", ")}, ...(options.fallbackHandlers ?? [])]`, "  });", "}", "");
+    return lines.join("\n");
+}
+/** Bare module names pass through; relative paths are resolved from the cwd and re-relativised per file. */
+function runtimeImportFor(runtimeImport, fromDir) {
+    if (!runtimeImport.startsWith("."))
+        return runtimeImport;
+    const rel = path.relative(fromDir, path.resolve(runtimeImport)).split(path.sep).join("/");
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function scenariosFor(spec, saved) {
+    if (!saved)
+        return undefined;
+    const keys = new Set(spec.operations.map(o => o.key));
+    const picked = Object.fromEntries(Object.entries(saved).filter(([key]) => keys.has(key)));
+    return Object.keys(picked).length ? picked : undefined;
+}
+async function generate(options) {
+    const say = (message) => {
+        if (!options.silent)
+            console.log(message);
+    };
+    const output = path.resolve(options.output ?? options.config?.output ?? "src/api");
+    const failOn = options.failOn ?? "breaking";
+    const runtimeImport = options.runtimeImport ?? options.config?.runtimeImport ?? "swaggerizer/msw";
+    const { specs, reports } = await checkChanges(options.specs, output, options.config, options.headers ?? options.config?.headers);
+    for (const report of reports)
+        say(formatReport(report, { color: options.color, verbose: options.verbose }) + "\n");
+    const blocked = reports.some(r => exceedsThreshold(r, failOn));
+    if (options.check)
+        return { reports, generated: [], skipped: true, blocked };
+    if (blocked && !options.yes) {
+        const ok = options.confirm ? await options.confirm(reports) : false;
+        if (!ok) {
+            say(`Generation cancelled: contract changes at or above '${failOn}' were not confirmed. Re-run with --yes to accept them.`);
+            return { reports, generated: [], skipped: true, blocked };
+        }
+    }
+    const saved = options.stateFile ? readJson(options.stateFile)?.scenarios : undefined;
+    const generated = [];
+    const entries = [];
+    for (const spec of specs) {
+        const { dir, mocksDir } = outputDirs(spec.id, output, spec.config);
+        for (const warning of spec.warnings.filter(w => /matches no operation/.test(w)))
+            say(`  ! ${spec.id}: ${warning}`);
+        say(`Generating ${spec.id} → ${path.relative(process.cwd(), dir) || dir}`);
+        const orvalOutput = await runOrval(spec, dir, options);
+        if (mocksDir !== dir) {
+            if (orvalOutput.mode === "split")
+                moveMocks(spec.id, dir, mocksDir);
+            else
+                say(`  ! ${spec.id}: mocksOutput only works with orval mode "split"; mocks left in ${dir}.`);
+        }
+        const mockFile = path.join(mocksDir, `${spec.id}.msw.ts`);
+        const aggregate = fs.existsSync(mockFile) ? findMockAggregate(fs.readFileSync(mockFile, "utf8")) : undefined;
+        if (options.mock !== false && !aggregate) {
+            say(`  ! Could not find orval's MSW handler list in ${mockFile}; "generated" responses will use Swaggerizer samples.`);
+        }
+        const manifest = {
+            specId: spec.id,
+            title: spec.contract.title,
+            version: spec.contract.version,
+            basePaths: spec.basePaths,
+            operations: spec.operations,
+            ...(spec.config.aliases ? { aliases: spec.config.aliases } : {})
+        };
+        const scenarios = scenariosFor(spec, saved);
+        if (scenarios)
+            manifest.scenarios = scenarios;
+        fs.mkdirSync(mocksDir, { recursive: true });
+        fs.writeFileSync(path.join(mocksDir, WRAPPER_FILE), renderWrapper(spec, manifest, aggregate ? `${spec.id}.msw` : undefined, aggregate, runtimeImportFor(runtimeImport, mocksDir)));
+        fs.writeFileSync(path.join(dir, CONTRACT_FILE), JSON.stringify({ ...spec.contract, generatedAt: new Date().toISOString() }, null, 2) + "\n");
+        generated.push(spec.id);
+        // Only specs in the default layout (<output>/<id>/) go in the aggregate index.
+        if (!spec.config.output && !spec.config.mocksOutput)
+            entries.push({ id: spec.id, clientModule: spec.id });
+    }
+    // Specs whose file was removed: the removal has now been accepted, so record it in their
+    // snapshot (it stops being reported) and leave the stale folder for the user to delete.
+    for (const orphan of orphanSnapshots(output, new Set(specs.map(s => s.id)))) {
+        const file = path.join(output, orphan.specId, CONTRACT_FILE);
+        fs.writeFileSync(file, JSON.stringify({ ...orphan, operations: {}, removedAt: new Date().toISOString() }, null, 2) + "\n");
+        say(`  ${orphan.specId}: spec file removed — ${path.join(path.relative(process.cwd(), output), orphan.specId)} is no longer used and can be deleted.`);
+    }
+    if (entries.length) {
+        fs.mkdirSync(output, { recursive: true });
+        fs.writeFileSync(path.join(output, INDEX_FILE), renderIndex(entries, runtimeImportFor(runtimeImport, output)));
+    }
+    say(entries.length === generated.length
+        ? `Done: ${generated.length} spec(s) generated in ${path.relative(process.cwd(), output) || output}`
+        : `Done: ${generated.length} spec(s) generated.`);
+    return { reports, generated, skipped: false, blocked };
+}
+
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml"
+};
+const BASE_PLACEHOLDER = /__SWAGGERIZER_BASE__/g;
+function escapeHtmlAttr(str) {
+    return str.replace(/["&'<>]/g, c => {
+        switch (c) {
+            case '"': return "&quot;";
+            case "&": return "&amp;";
+            case "'": return "&#39;";
+            case "<": return "&lt;";
+            case ">": return "&gt;";
+            default: return c;
+        }
+    });
+}
+/**
+ * The UI files live in `src/ui` during development and are copied to `dist/ui` by the build, next
+ * to the bundle that is executing (`__dirname` in CommonJS, `import.meta.url` in the ES build).
+ */
+function currentDir() {
+    if (typeof __dirname !== "undefined")
+        return __dirname;
+    try {
+        return path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.js', document.baseURI).href))));
+    }
+    catch {
+        return process.cwd();
+    }
+}
+function resolveUiDir() {
+    const here = currentDir();
+    const candidates = [
+        path.join(here, "ui"),
+        path.join(here, "..", "src", "ui"),
+        path.join(here, "..", "dist", "ui")
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(candidate, "index.html")))
+            return candidate;
+    }
+    return null;
+}
+function createUiAssetServer(basePath, uiDir = resolveUiDir()) {
+    const cache = new Map();
+    function load(asset) {
+        if (!uiDir)
+            return null;
+        const cached = cache.get(asset);
+        if (cached)
+            return cached;
+        try {
+            let content = fs.readFileSync(path.join(uiDir, asset));
+            if (asset === "index.html") {
+                const safeBase = escapeHtmlAttr(basePath === "/" ? "" : basePath);
+                content = Buffer.from(content.toString("utf8").replace(BASE_PLACEHOLDER, safeBase), "utf8");
+            }
+            cache.set(asset, content);
+            return content;
+        }
+        catch {
+            return null;
+        }
+    }
+    function serve(asset, res) {
+        const content = load(asset);
+        if (!content) {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("swaggerizer admin UI assets were not found. Rebuild with `npm run build`.");
+            return;
+        }
+        res.statusCode = 200;
+        res.setHeader("Content-Type", CONTENT_TYPES[path.extname(asset)] || "application/octet-stream");
+        res.setHeader("Content-Length", content.length);
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        if (asset === "index.html") {
+            res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'");
+        }
+        res.end(content);
+    }
+    return { available: Boolean(uiDir), serve };
+}
+
+function sendJson(res, status, payload) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Cache-Control", "no-store");
+    res.end(JSON.stringify(payload));
+}
+function blank(value) {
+    return value === undefined || value === null || value === "";
+}
+/**
+ * Turns a flat record (query string, form post or JSON) into a selection. Accepts the ramlizer
+ * names (`nextResponseCode`, `nextExampleName`) and flat custom fields (`status`, `body`, `contentType`).
+ */
+function toSelection(raw) {
+    const selection = {
+        method: raw?.method,
+        route: raw?.route,
+        code: raw?.code ?? raw?.nextResponseCode,
+        example: raw?.example ?? raw?.nextExampleName
+    };
+    if (!blank(raw?.mode))
+        selection.mode = raw.mode;
+    if (!blank(raw?.delay))
+        selection.delay = Number(raw.delay);
+    if (raw?.custom && typeof raw.custom === "object") {
+        selection.custom = raw.custom;
+    }
+    else if (!blank(raw?.status)) {
+        selection.custom = {
+            status: Number(raw.status),
+            ...(raw.body !== undefined ? { body: raw.body } : {}),
+            ...(!blank(raw.contentType) ? { contentType: raw.contentType } : {})
+        };
+    }
+    for (const key of Object.keys(selection)) {
+        if (blank(selection[key]))
+            delete selection[key];
+    }
+    return selection;
+}
+function registerAdmin(ctx) {
+    const assets = createUiAssetServer(ctx.basePath);
+    const assetFor = {
+        "/": "index.html",
+        "/index.html": "index.html",
+        "/app.js": "app.js",
+        "/app.css": "app.css"
+    };
+    async function handle(req, res) {
+        const { method, path, query } = req;
+        const isForm = Boolean(req.contentType && /x-www-form-urlencoded/i.test(req.contentType));
+        // Form posts from a plain HTML page can ask to be sent back somewhere afterwards.
+        const finish = (payload) => {
+            const redirect = (req.body && req.body.redirect) || query.get("redirect");
+            if (isForm && typeof redirect === "string" && redirect.startsWith("/")) {
+                res.statusCode = 303;
+                res.setHeader("Location", redirect);
+                res.end();
+                return;
+            }
+            sendJson(res, 200, payload);
+        };
+        try {
+            // ramlizer-compatible configuration endpoint.
+            if (method === "POST" && path === "/") {
+                const operations = ctx.select(toSelection(req.body || {}));
+                finish({ route: req.body?.route, operations });
+                return true;
+            }
+            if (method === "GET" && path === "/api/state") {
+                sendJson(res, 200, ctx.getState());
+                return true;
+            }
+            if (path === "/api/select" && (method === "GET" || method === "POST")) {
+                const source = method === "GET" ? Object.fromEntries(query) : req.body;
+                const selection = Array.isArray(source) ? source.map(toSelection) : toSelection(source || {});
+                finish({ operations: ctx.select(selection) });
+                return true;
+            }
+            if (path === "/api/reset" && (method === "GET" || method === "POST")) {
+                const source = method === "GET" ? Object.fromEntries(query) : req.body || {};
+                const reset = ctx.reset({ method: source.method || undefined, route: source.route || undefined });
+                finish({ reset, state: ctx.getState() });
+                return true;
+            }
+            if (method === "POST" && path === "/api/spec") {
+                const { id } = req.body || {};
+                const enabled = req.body?.enabled === true || req.body?.enabled === "true";
+                if (typeof id !== "string" || (req.body?.enabled === undefined)) {
+                    throw new Error('Expected a body of {"id": string, "enabled": boolean}.');
+                }
+                const spec = ctx.setSpecEnabled(id, enabled);
+                finish({ spec, state: ctx.getState() });
+                return true;
+            }
+            if (method === "POST" && path === "/api/reload") {
+                sendJson(res, 200, await ctx.reload());
+                return true;
+            }
+            if (method === "GET" && path === "/api/changes") {
+                sendJson(res, 200, { changes: ctx.getState().changes });
+                return true;
+            }
+            if (path === "/api/log") {
+                if (method === "GET") {
+                    const since = Number(query.get("since") || 0);
+                    sendJson(res, 200, { entries: ctx.getRequestLog(Number.isFinite(since) ? since : 0) });
+                    return true;
+                }
+                if (method === "POST") {
+                    // Lets the MSW runtime report requests it answered in the browser or in tests.
+                    const items = Array.isArray(req.body) ? req.body : [req.body];
+                    const entries = items.slice(0, 50).map(item => ctx.recordRequest({
+                        method: String(item?.method || "GET").toUpperCase(),
+                        path: String(item?.path || ""),
+                        ...(item?.route ? { route: String(item.route) } : {}),
+                        status: Number(item?.status) || 0,
+                        example: String(item?.example || ""),
+                        ...(item?.specId ? { specId: String(item.specId) } : {}),
+                        ...(item?.ms !== undefined ? { ms: Number(item.ms) } : {}),
+                        source: "msw"
+                    }));
+                    sendJson(res, 200, { recorded: entries.length });
+                    return true;
+                }
+            }
+            const openapi = /^\/api\/openapi\/([^/]+?)(\.json)?$/.exec(path);
+            if (method === "GET" && openapi) {
+                const doc = ctx.getSpecDocument(decodeURIComponent(openapi[1]));
+                if (!doc) {
+                    sendJson(res, 404, { error: `No spec with id '${openapi[1]}' is loaded.` });
+                }
+                else {
+                    sendJson(res, 200, doc);
+                }
+                return true;
+            }
+            if (ctx.ui && method === "GET" && assetFor[path]) {
+                assets.serve(assetFor[path], res);
+                return true;
+            }
+        }
+        catch (err) {
+            sendJson(res, 400, { error: err?.message ? String(err.message) : String(err) });
+            return true;
+        }
+        if (path.startsWith("/api/")) {
+            sendJson(res, 404, { error: `Unknown admin route ${method} ${ctx.basePath}${path}` });
+            return true;
+        }
+        return false;
+    }
+    return { handle, uiAvailable: ctx.ui && assets.available };
+}
+
+/* The Swaggerizer mock server: serves every loaded spec and exposes the admin API + page. */
+const REQUEST_LOG_LIMIT = 300;
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+function log(silent, message) {
+    if (!silent)
+        console.log(`\x1b[36m[swaggerizer]\x1b[0m ${message}`);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("Request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function parseRequestBody(raw, contentType) {
+    const text = raw.toString("utf8");
+    if (!text.trim())
+        return {};
+    if (contentType && /application\/x-www-form-urlencoded/i.test(contentType)) {
+        return Object.fromEntries(new URLSearchParams(text));
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("Request body is not valid JSON.");
+    }
+}
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function createSwaggerizer(options = {}) {
+    const silent = Boolean(options.silent);
+    const endpoint = (options.endpoint || "swaggerizer").replace(/^\/+|\/+$/g, "") || "swaggerizer";
+    const basePath = `/${endpoint}`;
+    const specs = new Map();
+    const sources = [];
+    const scenarios = {};
+    const requestLog = [];
+    const previousReports = new Map();
+    let snapshotReports = [];
+    let requestSeq = 0;
+    let lastReload;
+    let reloadChain = Promise.resolve();
+    const watchers = [];
+    const servers = new Set();
+    const specConfigs = { ...(options.specConfigs || {}) };
+    const store = new Map();
+    let configHeaders = {};
+    const configFor = (id) => specConfigs[id] || {};
+    /* ------------------------------------------------------------------ persistence */
+    function restoreState() {
+        if (!options.stateFile || !fs.existsSync(options.stateFile))
+            return;
+        try {
+            const saved = JSON.parse(fs.readFileSync(options.stateFile, "utf8"));
+            Object.assign(scenarios, saved?.scenarios || {});
+            log(silent, `Restored ${Object.keys(scenarios).length} scenario(s) from ${options.stateFile}`);
+        }
+        catch (err) {
+            log(silent, `Could not read state file ${options.stateFile}: ${err?.message ?? err}`);
+        }
+    }
+    function saveState() {
+        if (!options.stateFile)
+            return;
+        const disabled = [...specs.values()].filter(s => !s.enabled).map(s => s.id);
+        fs.mkdirSync(path.dirname(path.resolve(options.stateFile)), { recursive: true });
+        fs.writeFileSync(options.stateFile, JSON.stringify({ scenarios, disabledSpecs: disabled }, null, 2) + "\n");
+    }
+    function savedDisabledSpecs() {
+        if (!options.stateFile || !fs.existsSync(options.stateFile))
+            return new Set();
+        try {
+            return new Set(JSON.parse(fs.readFileSync(options.stateFile, "utf8"))?.disabledSpecs || []);
+        }
+        catch {
+            return new Set();
+        }
+    }
+    /* ------------------------------------------------------------------ state */
+    const ordered = () => [...specs.values()];
+    const states = () => buildOperationStates(ordered(), scenarios, { defaultDelay: options.delay });
+    function summarise(spec) {
+        return {
+            id: spec.id,
+            file: spec.file,
+            name: path.basename(spec.file),
+            title: spec.doc?.info?.title,
+            version: spec.doc?.info?.version !== undefined ? String(spec.doc.info.version) : undefined,
+            specVersion: spec.specVersion,
+            enabled: spec.enabled,
+            loadedAt: spec.loadedAt,
+            ...(spec.error ? { error: spec.error } : {}),
+            warnings: spec.warnings,
+            basePaths: spec.basePaths,
+            ...(configFor(spec.id).aliases ? { aliases: configFor(spec.id).aliases } : {}),
+            ...(isUrl(spec.file) ? { source: spec.file } : {}),
+            proxyTarget: configFor(spec.id).proxy || options.proxy || spec.serverUrl,
+            operationCount: spec.operations.length
+        };
+    }
+    function getState() {
+        const changes = [
+            ...snapshotReports,
+            ...[...previousReports.values()].filter(r => r.changes.length > 0)
+        ];
+        return {
+            endpoint,
+            ...(options.delay ? { defaultDelay: options.delay } : {}),
+            ...(options.fallback ? { fallback: options.fallback } : {}),
+            specs: ordered().map(summarise),
+            operations: states(),
+            lastReload,
+            changes
+        };
+    }
+    function servingOperation(method, route) {
+        const key = operationKey(method, route);
+        const all = states();
+        return all.find(s => s.key === key && s.active) || all.find(s => s.key === key);
+    }
+    function select(selection) {
+        const list = Array.isArray(selection) ? selection : [selection];
+        if (list.length === 0)
+            throw new Error("Selection list cannot be empty.");
+        // Validate everything before applying anything.
+        const next = [];
+        for (const item of list) {
+            if (!item || typeof item.method !== "string" || typeof item.route !== "string") {
+                throw new Error("Each selection needs a string `method` and `route`.");
+            }
+            const op = servingOperation(item.method, item.route);
+            if (!op)
+                throw new Error(`No operation ${item.method.toUpperCase()} ${item.route} is loaded.`);
+            next.push([op.key, applySelection(op, item, scenarios[op.key])]);
+        }
+        for (const [key, scenario] of next)
+            scenarios[key] = scenario;
+        saveState();
+        const after = states();
+        return next.map(([key]) => after.find(s => s.key === key && s.active) || after.find(s => s.key === key));
+    }
+    function reset(filter = {}) {
+        let count = 0;
+        for (const key of Object.keys(scenarios)) {
+            const [method, ...rest] = key.split(":");
+            const route = rest.join(":");
+            if (filter.method && method !== String(filter.method).toLowerCase())
+                continue;
+            if (filter.route && route !== filter.route)
+                continue;
+            delete scenarios[key];
+            count++;
+        }
+        // "Reset all" also empties the state custom handlers keep.
+        if (!filter.method && !filter.route)
+            store.clear();
+        saveState();
+        return count;
+    }
+    function setSpecEnabled(id, enabled) {
+        const spec = specs.get(id);
+        if (!spec)
+            throw new Error(`No spec with id '${id}' is loaded.`);
+        spec.enabled = Boolean(enabled);
+        saveState();
+        log(silent, `${spec.id} ${spec.enabled ? "enabled" : "disabled"}`);
+        return summarise(spec);
+    }
+    function recordRequest(entry) {
+        const full = { id: ++requestSeq, time: new Date().toISOString(), ...entry };
+        requestLog.push(full);
+        if (requestLog.length > REQUEST_LOG_LIMIT)
+            requestLog.splice(0, requestLog.length - REQUEST_LOG_LIMIT);
+        return full;
+    }
+    function getRequestLog(sinceId = 0) {
+        if (sinceId > 0 && requestLog.length > 0 && requestLog[requestLog.length - 1].id < sinceId)
+            return [];
+        return requestLog.filter(e => e.id > sinceId);
+    }
+    /* ------------------------------------------------------------------ loading */
+    function readSnapshot(specId) {
+        const cfg = configFor(specId);
+        if (!options.generated && !cfg.output)
+            return undefined;
+        const file = path.join(outputDirs(specId, options.generated, cfg).dir, CONTRACT_FILE);
+        if (!fs.existsSync(file))
+            return undefined;
+        try {
+            return JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function refreshSnapshotReports() {
+        snapshotReports = [];
+        for (const spec of ordered()) {
+            if (spec.error)
+                continue;
+            const snapshot = readSnapshot(spec.id);
+            if (!snapshot)
+                continue;
+            const report = diffContracts(snapshot, spec.contract, "snapshot");
+            if (report.changes.length)
+                snapshotReports.push(report);
+        }
+    }
+    async function wantedFiles() {
+        const files = [];
+        for (const source of sources) {
+            if (source.kind === "folder") {
+                try {
+                    files.push(...(await listSpecFiles(source.path)).map(file => ({ file })));
+                }
+                catch {
+                    // folder vanished
+                }
+            }
+            else if (source.kind === "url" || fs.existsSync(source.path)) {
+                files.push({ file: source.path, id: source.id });
+            }
+        }
+        const seen = new Set();
+        return files.filter(f => (seen.has(f.file) ? false : (seen.add(f.file), true)));
+    }
+    async function doReload() {
+        const previous = new Map(ordered().map(s => [s.file, s]));
+        const disabled = savedDisabledSpecs();
+        const next = new Map();
+        const usedIds = new Set();
+        for (const { file, id: configuredId } of await wantedFiles()) {
+            const before = previous.get(file);
+            let id = configuredId ?? before?.id ?? specIdFor(file);
+            for (let n = 2; usedIds.has(id); n++)
+                id = `${specIdFor(file)}-${n}`;
+            usedIds.add(id);
+            try {
+                const analysed = await analyseSpecFile(file, id, { headers: { ...configHeaders, ...(options.headers || {}), ...(configFor(id).headers || {}) } });
+                const cfg = configFor(id);
+                analysed.operations = applyOverlays(analysed.operations, cfg.scenarios);
+                for (const key of unmatchedKeys(cfg.scenarios, analysed.operations)) {
+                    analysed.warnings.push(`Scenario overlay '${key}' matches no operation`);
+                }
+                for (const key of unmatchedKeys(cfg.handlers, analysed.operations)) {
+                    analysed.warnings.push(`Custom handler '${key}' matches no operation`);
+                }
+                const enabled = before ? before.enabled : !disabled.has(id);
+                next.set(id, { ...analysed, enabled, loadedAt: new Date().toISOString() });
+                if (before && !before.error) {
+                    const report = diffContracts(before.contract, analysed.contract, "previous-load");
+                    if (report.changes.length) {
+                        previousReports.set(id, report);
+                        log(silent, `${id}: ${report.counts.breaking} breaking, ${report.counts.warning} warning(s) since last load`);
+                    }
+                }
+                log(silent, `Loaded ${isUrl(file) ? file : path.basename(file)} (${analysed.specVersion}) – ${analysed.operations.length} operation(s)`);
+            }
+            catch (err) {
+                const message = err?.message ? String(err.message).split("\n")[0] : String(err);
+                log(silent, `Could not load ${file}: ${message}`);
+                next.set(id, before
+                    ? { ...before, error: message }
+                    : {
+                        id,
+                        file,
+                        doc: {},
+                        warnings: [],
+                        operations: [],
+                        contract: { swaggerizer: 1, specId: id, operations: {} },
+                        basePaths: [],
+                        enabled: true,
+                        loadedAt: new Date().toISOString(),
+                        error: message
+                    });
+            }
+        }
+        specs.clear();
+        for (const [id, spec] of next)
+            specs.set(id, spec);
+        for (const id of previousReports.keys())
+            if (!specs.has(id))
+                previousReports.delete(id);
+        refreshSnapshotReports();
+        for (const report of snapshotReports) {
+            log(silent, `${report.specId} differs from the generated client: ${report.counts.breaking} breaking, ${report.counts.warning} warning(s), ${report.added.length} new, ${report.removed.length} removed`);
+        }
+        lastReload = new Date().toISOString();
+        return getState();
+    }
+    function reload() {
+        const run = reloadChain.then(doReload, doReload);
+        reloadChain = run.catch(() => undefined);
+        return run;
+    }
+    function watch(target) {
+        if (!options.watch)
+            return;
+        let timer;
+        try {
+            const watcher = fs.watch(target, () => {
+                clearTimeout(timer);
+                timer = setTimeout(() => {
+                    log(silent, "Spec change detected – reloading");
+                    reload().catch(() => undefined);
+                }, 200);
+            });
+            watchers.push(watcher);
+        }
+        catch {
+            // watching is best effort
+        }
+    }
+    async function load(inputs) {
+        for (const input of [].concat(inputs)) {
+            if (isUrl(input)) {
+                if (!sources.some(s => s.path === input))
+                    sources.push({ kind: "url", path: input });
+                continue;
+            }
+            const absolute = path.resolve(input);
+            const stat = await fs.promises.stat(absolute);
+            const kind = stat.isDirectory() ? "folder" : "file";
+            if (!sources.some(s => s.path === absolute)) {
+                sources.push({ kind, path: absolute });
+                watch(absolute);
+            }
+        }
+        return reload();
+    }
+    async function loadConfig(config) {
+        configHeaders = { ...(config.headers || {}) };
+        for (const [id, spec] of Object.entries(config.specs || {})) {
+            specConfigs[id] = spec;
+            const local = spec.file ? path.resolve(spec.file) : undefined;
+            if (local && fs.existsSync(local)) {
+                if (!sources.some(s => s.path === local)) {
+                    sources.push({ kind: "file", path: local, id });
+                    watch(local);
+                }
+            }
+            else if (spec.source) {
+                if (!sources.some(s => s.path === spec.source))
+                    sources.push({ kind: "url", path: spec.source, id });
+            }
+            else {
+                throw new Error(`Spec '${id}' needs a \`file\` that exists or a \`source\` URL (run \`swaggerizer pull\`).`);
+            }
+        }
+        return reload();
+    }
+    /* ------------------------------------------------------------------ mock serving */
+    async function proxy(req, res, target, relativePath, search) {
+        const upstream = target.replace(/\/+$/, "") + relativePath + search;
+        const headers = {};
+        for (const [name, value] of Object.entries(req.headers)) {
+            if (value === undefined)
+                continue;
+            if (["host", "connection", "content-length", "accept-encoding", SCENARIO_HEADER].includes(name))
+                continue;
+            headers[name] = Array.isArray(value) ? value.join(", ") : value;
+        }
+        const method = (req.method || "GET").toUpperCase();
+        const body = method === "GET" || method === "HEAD" ? undefined : await readBody(req);
+        const response = await fetch(upstream, { method, headers, body: body && body.length ? new Uint8Array(body) : undefined, redirect: "manual" });
+        const out = Buffer.from(await response.arrayBuffer());
+        res.statusCode = response.status;
+        response.headers.forEach((value, name) => {
+            if (["content-encoding", "content-length", "transfer-encoding", "connection"].includes(name))
+                return;
+            if (name.startsWith("access-control-"))
+                return;
+            res.setHeader(name, value);
+        });
+        res.setHeader("X-Swaggerizer-Proxied", upstream);
+        res.end(out);
+        return response.status;
+    }
+    async function serveMock(req, res, url) {
+        const started = Date.now();
+        const method = (req.method || "GET").toLowerCase();
+        const enabledSpecs = ordered().filter(s => s.enabled && !s.error);
+        const allBasePaths = [...new Set(enabledSpecs.flatMap(s => s.basePaths))];
+        const allAliases = Object.assign({}, ...enabledSpecs.map(s => configFor(s.id).aliases || {}));
+        const op = matchOperation(states(), method, url.pathname, allBasePaths, allAliases);
+        if (!op)
+            return false;
+        const spec = specs.get(op.specId);
+        const cfg = configFor(op.specId);
+        const override = parseScenarioHeader(req.headers[SCENARIO_HEADER]);
+        const entry = { method: method.toUpperCase(), path: url.pathname + url.search, route: op.route, specId: op.specId, source: "server" };
+        const custom = lookupByOperation(cfg.handlers, op);
+        if (custom && !override && !op.modified) {
+            const raw = method === "get" || method === "head" ? undefined : (await readBody(req)).toString("utf8");
+            let body = raw;
+            if (raw !== undefined) {
+                try {
+                    body = raw.trim() ? JSON.parse(raw) : undefined;
+                }
+                catch {
+                    body = raw;
+                }
+            }
+            const params = candidatePaths(url.pathname, spec.basePaths, cfg.aliases || {})
+                .map(p => extractParams(op.route, p))
+                .find(p => Object.keys(p).length > 0) ?? {};
+            const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : String(v ?? "")]));
+            let outcome;
+            try {
+                outcome = await custom(createHandlerContext({ operation: op, method: method.toUpperCase(), path: url.pathname, params, query: url.searchParams, headers, body, store }));
+            }
+            catch (err) {
+                sendJson(res, 500, { error: `Custom handler for ${op.operationId ?? op.key} threw: ${err?.message ?? err}` });
+                recordRequest({ ...entry, status: 500, example: "handler error", ms: Date.now() - started });
+                return true;
+            }
+            if (isHandlerResult(outcome)) {
+                if (op.delay > 0)
+                    await sleep(op.delay);
+                const contentType = outcome.contentType ?? (outcome.body !== undefined ? (typeof outcome.body === "string" ? "text/plain" : "application/json") : undefined);
+                res.statusCode = outcome.status;
+                for (const [name, value] of Object.entries(outcome.headers || {}))
+                    res.setHeader(name, value);
+                res.setHeader("X-Swaggerizer-Scenario", `${outcome.status}:handler`);
+                const payload = outcome.status === 204 || outcome.status === 304 ? undefined : encodeBody(outcome.body, contentType);
+                if (payload !== undefined && contentType)
+                    res.setHeader("Content-Type", contentType);
+                res.end(payload);
+                recordRequest({ ...entry, status: outcome.status, example: "handler", contentType, ms: Date.now() - started });
+                return true;
+            }
+        }
+        const resolved = resolveResponse(op, override);
+        if (resolved.delay > 0)
+            await sleep(resolved.delay);
+        if (resolved.kind === "proxy") {
+            const target = cfg.proxy || options.proxy || spec.serverUrl;
+            if (!target) {
+                sendJson(res, 502, { error: `No upstream for ${op.specId}: pass --proxy or declare an absolute URL in servers.` });
+                recordRequest({ ...entry, status: 502, example: "proxy", ms: Date.now() - started });
+                return true;
+            }
+            const relative = relativeToBase(url.pathname, spec.basePaths, cfg.aliases || {});
+            try {
+                const status = await proxy(req, res, target, relative, url.search);
+                recordRequest({ ...entry, status, example: "proxy", ms: Date.now() - started });
+            }
+            catch (err) {
+                sendJson(res, 502, { error: `Proxy to ${target} failed: ${err?.message ?? err}` });
+                recordRequest({ ...entry, status: 502, example: "proxy", ms: Date.now() - started });
+            }
+            return true;
+        }
+        res.statusCode = resolved.status;
+        for (const [name, value] of Object.entries(resolved.headers || {}))
+            res.setHeader(name, value);
+        res.setHeader("X-Swaggerizer-Scenario", `${resolved.code}:${resolved.variant}`);
+        const payload = resolved.status === 204 || resolved.status === 304 || method === "head"
+            ? undefined
+            : encodeBody(resolved.body, resolved.contentType);
+        if (payload !== undefined && resolved.contentType)
+            res.setHeader("Content-Type", resolved.contentType);
+        res.end(payload);
+        recordRequest({ ...entry, status: resolved.status, example: resolved.variant, contentType: resolved.contentType, ms: Date.now() - started });
+        return true;
+    }
+    function sendJson(res, status, payload) {
+        res.statusCode = status;
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Cache-Control", "no-store");
+        res.end(JSON.stringify(payload));
+    }
+    const admin = registerAdmin({
+        basePath,
+        ui: options.ui !== false,
+        getState,
+        select,
+        reset,
+        setSpecEnabled,
+        reload,
+        getRequestLog,
+        recordRequest,
+        getSpecDocument: id => specs.get(id)?.doc
+    });
+    function handler(req, res, next) {
+        if (options.cors !== false) {
+            res.setHeader("Access-Control-Allow-Origin", req.headers.origin || "*");
+            res.setHeader("Vary", "Origin");
+            res.setHeader("Access-Control-Allow-Credentials", "true");
+            res.setHeader("Access-Control-Expose-Headers", "X-Swaggerizer-Scenario, X-Swaggerizer-Proxied");
+            if (req.method === "OPTIONS" && req.headers["access-control-request-method"]) {
+                res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS");
+                res.setHeader("Access-Control-Allow-Headers", req.headers["access-control-request-headers"] || "*");
+                res.setHeader("Access-Control-Max-Age", "600");
+                res.statusCode = 204;
+                res.end();
+                return;
+            }
+        }
+        const url = new URL(req.url || "/", "http://localhost");
+        const isAdmin = url.pathname === basePath || url.pathname.startsWith(basePath + "/");
+        (async () => {
+            if (isAdmin) {
+                let body = {};
+                if (req.method === "POST" || req.method === "PUT") {
+                    body = parseRequestBody(await readBody(req), req.headers["content-type"]);
+                }
+                const request = {
+                    method: (req.method || "GET").toUpperCase(),
+                    path: url.pathname.slice(basePath.length) || "/",
+                    query: url.searchParams,
+                    body,
+                    contentType: req.headers["content-type"]
+                };
+                if (await admin.handle(request, res))
+                    return;
+            }
+            else if (await serveMock(req, res, url)) {
+                return;
+            }
+            else if (options.fallback) {
+                const started = Date.now();
+                const method = (req.method || "GET").toUpperCase();
+                try {
+                    const status = await proxy(req, res, options.fallback, url.pathname, url.search);
+                    recordRequest({ method, path: url.pathname + url.search, status, example: "fallback", source: "server", ms: Date.now() - started });
+                }
+                catch (err) {
+                    sendJson(res, 502, { error: `Fallback to ${options.fallback} failed: ${err?.message ?? err}` });
+                    recordRequest({ method, path: url.pathname + url.search, status: 502, example: "fallback", source: "server", ms: Date.now() - started });
+                }
+                return;
+            }
+            if (next)
+                return next();
+            const method = (req.method || "GET").toUpperCase();
+            sendJson(res, 404, { error: `No operation matches ${method} ${url.pathname}` });
+            if (!isAdmin)
+                recordRequest({ method, path: url.pathname + url.search, status: 404, example: "unmatched", source: "server" });
+        })().catch(err => {
+            if (!res.headersSent)
+                sendJson(res, 400, { error: err?.message ? String(err.message) : String(err) });
+            else
+                res.end();
+        });
+    }
+    function listen(port = 8080, host) {
+        return new Promise((resolve, reject) => {
+            const server = http.createServer((req, res) => handler(req, res));
+            server.once("error", reject);
+            server.listen(port, host, () => {
+                servers.add(server);
+                const address = server.address();
+                const actual = typeof address === "object" && address ? address.port : port;
+                log(silent, `Mock API on http://localhost:${actual}`);
+                if (options.ui !== false)
+                    log(silent, `Admin page at http://localhost:${actual}${basePath}/`);
+                resolve(server);
+            });
+        });
+    }
+    async function close() {
+        for (const w of watchers.splice(0))
+            w.close();
+        await Promise.all([...servers].map(s => new Promise(resolve => {
+            s.closeAllConnections?.();
+            s.close(() => resolve());
+        })));
+        servers.clear();
+    }
+    restoreState();
+    return {
+        handler,
+        load,
+        loadConfig,
+        reload,
+        getState,
+        select,
+        reset,
+        setSpecEnabled,
+        getRequestLog,
+        recordRequest,
+        getSpecDocument: id => specs.get(id)?.doc,
+        listen,
+        close,
+        endpoint,
+        scenarios
+    };
+}
+/** CLI entry point: load specs and listen. */
+async function startSwaggerizer(options) {
+    const swaggerizer = createSwaggerizer(options);
+    if (options.config)
+        await swaggerizer.loadConfig(options.config);
+    if (options.specs)
+        await swaggerizer.load(options.specs);
+    const server = await swaggerizer.listen(options.port ?? 8080, options.host);
+    return { ...swaggerizer, server };
+}
+
+/* Finding and loading swaggerizer.config.{ts,mts,js,mjs,json} (Node only). */
+const CONFIG_FILES = [
+    "swaggerizer.config.ts",
+    "swaggerizer.config.mts",
+    "swaggerizer.config.js",
+    "swaggerizer.config.mjs",
+    "swaggerizer.config.json"
+];
+function findConfigFile(cwd = process.cwd()) {
+    for (const name of CONFIG_FILES) {
+        const file = path.join(cwd, name);
+        if (fs.existsSync(file))
+            return file;
+    }
+    return undefined;
+}
+/** Strips // and /* *\/ comments and trailing commas outside strings, so tsconfig files parse as JSON. */
+function parseJsonc(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\") {
+                out += next ?? "";
+                i++;
+            }
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+        }
+        else if (c === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (c === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i++;
+        }
+        else {
+            out += c;
+        }
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+}
+/**
+ * Module aliases from a tsconfig's `compilerOptions.paths`, so a config file can import fixtures
+ * through workspace aliases such as `@online-banking/data-access/...` (Nx, path-mapped monorepos).
+ */
+function aliasesFromTsconfig(tsconfigFile) {
+    if (!fs.existsSync(tsconfigFile))
+        return {};
+    let json;
+    try {
+        json = parseJsonc(fs.readFileSync(tsconfigFile, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const options = json?.compilerOptions || {};
+    const baseDir = path.resolve(path.dirname(tsconfigFile), options.baseUrl || ".");
+    const aliases = {};
+    for (const [key, targets] of Object.entries(options.paths || {})) {
+        const target = Array.isArray(targets) ? targets[0] : undefined;
+        if (!target)
+            continue;
+        if (key.endsWith("/*") && target.endsWith("/*")) {
+            aliases[key.slice(0, -2)] = path.resolve(baseDir, target.slice(0, -2));
+        }
+        else if (!key.includes("*")) {
+            aliases[key] = path.resolve(baseDir, target);
+        }
+    }
+    return aliases;
+}
+async function loadConfig(file, cwd = process.cwd()) {
+    const configFile = file ? path.resolve(cwd, file) : findConfigFile(cwd);
+    if (!configFile)
+        return undefined;
+    if (!fs.existsSync(configFile))
+        throw new Error(`Config file not found: ${configFile}`);
+    let config;
+    if (configFile.endsWith(".json")) {
+        config = JSON.parse(fs.readFileSync(configFile, "utf8"));
+    }
+    else {
+        const dir = path.dirname(configFile);
+        const peek = fs.readFileSync(configFile, "utf8");
+        const declared = /tsconfig\s*:\s*["'`]([^"'`]+)["'`]/.exec(peek)?.[1];
+        const tsconfig = [declared && path.resolve(dir, declared), path.join(dir, "tsconfig.base.json"), path.join(dir, "tsconfig.json")]
+            .filter((f) => Boolean(f))
+            .find(f => fs.existsSync(f));
+        const { createJiti } = await import('jiti');
+        const jiti = createJiti(configFile, {
+            alias: tsconfig ? aliasesFromTsconfig(tsconfig) : {},
+            interopDefault: true,
+            moduleCache: false
+        });
+        const mod = await jiti.import(configFile);
+        config = mod?.default ?? mod;
+    }
+    if (!config || typeof config !== "object" || !config.specs || typeof config.specs !== "object") {
+        throw new Error(`${configFile} must export a config with a \`specs\` object (use defineConfig).`);
+    }
+    // Paths in the config are relative to the config file, not the shell.
+    const dir = path.dirname(configFile);
+    const rel = (p) => (p && !/^https?:\/\//i.test(p) ? path.resolve(dir, p) : p);
+    for (const spec of Object.values(config.specs)) {
+        spec.file = rel(spec.file);
+        spec.output = rel(spec.output);
+        spec.mocksOutput = rel(spec.mocksOutput);
+    }
+    config.output = rel(config.output);
+    config.stateFile = rel(config.stateFile);
+    return { config: config, file: configFile };
+}
+
+/* `swaggerizer pull`: refresh committed spec files from their source URLs (Node only). */
+/** JSON is re-indented so diffs of committed specs stay readable; YAML is kept as served. */
+function normaliseSpecText(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        return { text: JSON.stringify(JSON.parse(trimmed), null, 2) + "\n", ext: "json" };
+    }
+    return { text: trimmed + "\n", ext: "yaml" };
+}
+async function pull(options) {
+    const say = (m) => {
+        if (!options.silent)
+            console.log(m);
+    };
+    const result = { pulled: [], failed: [] };
+    const entries = Object.entries(options.config.specs).filter(([id, spec]) => spec.source && (!options.only?.length || options.only.includes(id)));
+    if (entries.length === 0) {
+        say("Nothing to pull: no spec in the config has a `source` URL.");
+        return result;
+    }
+    for (const [id, spec] of entries) {
+        try {
+            const response = await fetch(spec.source, {
+                headers: {
+                    Accept: "application/json, application/yaml;q=0.9, */*;q=0.5",
+                    ...(options.config.headers || {}),
+                    ...(spec.headers || {}),
+                    ...(options.headers || {})
+                },
+                signal: AbortSignal.timeout(30000)
+            });
+            if (!response.ok)
+                throw new Error(`${spec.source} answered ${response.status}`);
+            const { text, ext } = normaliseSpecText(await response.text());
+            const file = path.resolve(spec.file ?? path.join("specs", `${id}.${ext}`));
+            const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : undefined;
+            if (before === text) {
+                say(`${id}: unchanged`);
+                result.pulled.push({ id, file, changed: false });
+                continue;
+            }
+            // Compare contracts so a pull says what moved, not just that bytes changed.
+            // Same extension as the target so the parser picks the right format.
+            const tmp = path.join(path.dirname(file), `.pulling-${path.basename(file)}`);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(tmp, text);
+            let report;
+            try {
+                const next = await analyseSpecFile(tmp, id);
+                if (before !== undefined) {
+                    try {
+                        const previous = await analyseSpecFile(file, id);
+                        report = diffContracts(previous.contract, next.contract, "previous-load");
+                    }
+                    catch {
+                        // The old file did not parse: nothing meaningful to compare against.
+                    }
+                }
+            }
+            catch (err) {
+                // Never replace a working spec with one that does not parse.
+                fs.rmSync(tmp, { force: true });
+                throw err;
+            }
+            fs.renameSync(tmp, file);
+            say(before === undefined ? `${id}: saved ${path.relative(process.cwd(), file)}` : `${id}: updated ${path.relative(process.cwd(), file)}`);
+            if (report)
+                say(formatReport(report, { color: options.color, verbose: options.verbose }).replace(/^/gm, "  ") + "\n");
+            result.pulled.push({ id, file, changed: true, ...(report ? { report } : {}) });
+        }
+        catch (err) {
+            const error = err?.message ? String(err.message) : String(err);
+            say(`${id}: could not pull – ${error}`);
+            result.failed.push({ id, error });
+        }
+    }
+    return result;
+}
+
+const FAIL_ON = ["breaking", "warning", "any", "none"];
+const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+async function confirm(reports) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const breaking = reports.reduce((n, r) => n + r.counts.breaking, 0);
+    const warnings = reports.reduce((n, r) => n + r.counts.warning, 0);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`\nThe specs contain ${breaking} breaking change(s) and ${warnings} warning(s) compared with the generated code.\n` +
+            "Regenerate the client, models and mocks anyway? [y/N] ");
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+async function configFrom(file) {
+    const loaded = await loadConfig(file);
+    if (loaded && !process.env.SWAGGERIZER_QUIET)
+        console.log(`Using ${path.relative(process.cwd(), loaded.file) || loaded.file}`);
+    return loaded?.config;
+}
+function needSpecs(folder, config) {
+    if (!config && !(Array.isArray(folder) && folder.length)) {
+        throw new Error("Pass --folder <specs…> or create a swaggerizer.config.ts (see the README).");
+    }
+}
+const configOption = { type: "string", describe: "config file (default: ./swaggerizer.config.{ts,mts,js,mjs,json} when present)" };
+const folderOption = { alias: ["f", "specs"], type: "string", array: true, describe: "spec files, folders or URLs" };
+const headerOption = { alias: "H", type: "string", array: true, describe: "request header for spec URLs, e.g. -H 'Authorization: Bearer …'" };
+/** `-H 'Name: value'` flags merged over the config's `headers`; undefined when there are none. */
+function headersFrom(flags, config) {
+    const headers = { ...(config?.headers || {}) };
+    for (const h of flags ?? []) {
+        const i = h.indexOf(":");
+        if (i > 0)
+            headers[h.slice(0, i).trim()] = h.slice(i + 1).trim();
+    }
+    return Object.keys(headers).length ? headers : undefined;
+}
+async function run(argv = process.argv) {
+    await yargs(helpers.hideBin(argv))
+        .scriptName("swaggerizer")
+        .command(["serve", "$0"], "Serve mock APIs from OpenAPI/Swagger specs with a live admin page", y => y
+        .option("config", configOption)
+        .option("folder", folderOption)
+        .option("header", headerOption)
+        .option("port", { alias: "p", type: "number", describe: "port to listen on (default 8080)" })
+        .option("host", { type: "string", describe: "interface to bind (default: all)" })
+        .option("endpoint", { type: "string", describe: "path of the admin API and page (default swaggerizer)" })
+        .option("ui", { type: "boolean", default: true, describe: "serve the admin page (disable with --no-ui)" })
+        .option("proxy", { type: "string", describe: "upstream base URL for 'Real API' mode (default: each spec's servers URL)" })
+        .option("delay", { type: "number", describe: "default latency for every operation, in ms" })
+        .option("fallback", { type: "string", describe: "proxy requests that match no operation to this URL" })
+        .option("state-file", { type: "string", describe: "persist scenario choices to this JSON file" })
+        .option("generated", { alias: "output", type: "string", describe: "generated code folder: warn when the specs drift from it" })
+        .option("watch", { alias: "w", type: "boolean", default: false, describe: "reload specs when files change" })
+        .option("silent", { type: "boolean", default: false }), async (args) => {
+        const config = await configFrom(args.config);
+        needSpecs(args.folder, config);
+        await startSwaggerizer({
+            config,
+            specs: args.folder,
+            headers: headersFrom(args.header, config),
+            port: args.port ?? config?.port ?? 8080,
+            host: args.host ?? config?.host,
+            endpoint: args.endpoint ?? config?.endpoint,
+            ui: args.ui,
+            proxy: args.proxy,
+            delay: args.delay ?? config?.delay,
+            fallback: args.fallback ?? config?.fallback,
+            stateFile: args["state-file"] ?? config?.stateFile,
+            generated: args.generated ?? config?.output,
+            watch: args.watch,
+            silent: args.silent
+        });
+    })
+        .command("generate", "Generate a typed client, models and MSW mocks with orval — after warning about contract changes", y => y
+        .option("config", configOption)
+        .option("folder", folderOption)
+        .option("header", headerOption)
+        .option("output", { alias: "o", type: "string", describe: "folder for generated code (default src/api)" })
+        .option("client", { type: "string", describe: "orval client: fetch (default), axios, axios-functions, react-query, swr, vue-query, angular…" })
+        .option("base-url", { type: "string", describe: "base URL baked into the generated client" })
+        .option("mock", { type: "boolean", default: true, describe: "generate MSW handlers (disable with --no-mock)" })
+        .option("state-file", { type: "string", describe: "embed scenario choices saved by `serve --state-file` as mock defaults" })
+        .option("fail-on", { choices: FAIL_ON, default: "breaking", describe: "change level that needs confirmation" })
+        .option("yes", { alias: "y", type: "boolean", default: false, describe: "accept contract changes without asking" })
+        .option("runtime-import", { type: "string", describe: "module the generated wrapper imports (default swaggerizer/msw)" })
+        .option("verbose", { type: "boolean", default: false, describe: "list non-breaking details too" }), async (args) => {
+        const config = await configFrom(args.config);
+        needSpecs(args.folder, config);
+        const result = await generate({
+            config,
+            specs: args.folder,
+            output: args.output,
+            client: args.client,
+            baseUrl: args["base-url"],
+            mock: args.mock,
+            stateFile: args["state-file"] ?? config?.stateFile,
+            failOn: args["fail-on"],
+            yes: args.yes,
+            runtimeImport: args["runtime-import"],
+            headers: headersFrom(args.header, config),
+            verbose: args.verbose,
+            color: useColor,
+            confirm
+        });
+        if (result.skipped)
+            process.exitCode = 1;
+    })
+        .command(["diff", "check"], "Report new, removed and changed APIs compared with the last generated code (no files written)", y => y
+        .option("config", configOption)
+        .option("folder", folderOption)
+        .option("header", headerOption)
+        .option("output", { alias: "o", type: "string", describe: "folder holding the generated code (default src/api)" })
+        .option("fail-on", { choices: FAIL_ON, default: "breaking", describe: "exit 1 when changes reach this level" })
+        .option("json", { type: "boolean", default: false, describe: "print the reports as JSON" })
+        .option("verbose", { type: "boolean", default: false }), async (args) => {
+        if (args.json)
+            process.env.SWAGGERIZER_QUIET = "1";
+        const config = await configFrom(args.config);
+        needSpecs(args.folder, config);
+        const { reports } = await checkChanges(args.folder, args.output, config, headersFrom(args.header, config));
+        if (args.json)
+            console.log(JSON.stringify(reports, null, 2));
+        else
+            for (const r of reports)
+                console.log(formatReport(r, { color: useColor, verbose: args.verbose }) + "\n");
+        if (reports.some(r => exceedsThreshold(r, args["fail-on"])))
+            process.exitCode = 1;
+    })
+        .command("pull [ids..]", "Refresh committed spec files from the `source` URLs in swaggerizer.config.ts, showing what changed", y => y
+        .positional("ids", { type: "string", array: true, describe: "only these spec ids" })
+        .option("config", configOption)
+        .option("header", headerOption)
+        .option("verbose", { type: "boolean", default: false }), async (args) => {
+        const config = await configFrom(args.config);
+        if (!config)
+            throw new Error("`pull` needs a swaggerizer.config.ts with `source` URLs.");
+        const result = await pull({ config, only: args.ids, headers: headersFrom(args.header), color: useColor, verbose: args.verbose });
+        if (result.failed.length)
+            process.exitCode = 1;
+    })
+        .strict()
+        .showHelpOnFail(false)
+        .help()
+        .parseAsync();
+}
+run().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+
+exports.run = run;
+//# sourceMappingURL=cli.js.map