@event4u/agent-config 2.26.0 → 3.1.0

package/dist/server/io/yamlIO.js

@@ -0,0 +1,162 @@
+/**
+ * YAML round-trip helpers for `.agent-settings.yml`.
+ *
+ * Important contract: the template ships with comments that explain
+ * every key — we MUST NOT discard them when the wizard writes back.
+ * `js-yaml.dump` cannot preserve comments, so we use a key-level
+ * replace strategy that mirrors `scripts/install.py::_replace_template_value`:
+ * scan the rendered template line-by-line, replace only the scalar
+ * value at each dotted path, leave comments and indentation alone.
+ *
+ * For arrays and nested objects we fall back to re-serializing the
+ * subtree (`js-yaml.dump`) because line-level replace can't safely
+ * splice multi-line blocks. The form renderer keeps depth ≤ 2, so
+ * the subtree footprint is small.
+ */
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
+export function parseYaml(raw) {
+    const parsed = yamlLoad(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('settings file did not parse to an object');
+    }
+    return parsed;
+}
+function formatScalar(value) {
+    if (typeof value === 'string') {
+        // js-yaml safely quotes strings that need it; trim the trailing newline.
+        return yamlDump(value, { lineWidth: -1 }).replace(/\n$/, '').trim();
+    }
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value === null || value === undefined)
+        return '""';
+    // Arrays / nested objects: dump inline. Form keeps depth ≤ 2 so this is rare.
+    return yamlDump(value, { lineWidth: -1, flowLevel: 0 }).replace(/\n$/, '').trim();
+}
+function flatten(value, prefix = []) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return [{ path: prefix, value }];
+    }
+    const entries = [];
+    for (const [k, v] of Object.entries(value)) {
+        entries.push(...flatten(v, [...prefix, k]));
+    }
+    return entries;
+}
+/**
+ * Replace the scalar at `dottedPath` in `template` with `value`.
+ * Comments and unrelated keys are preserved verbatim. Returns the
+ * template unchanged when the path cannot be located (matches the
+ * Python installer's tolerant behaviour).
+ */
+export function replaceScalar(template, dottedPath, value) {
+    if (dottedPath.length === 0)
+        return template;
+    const sections = dottedPath.slice(0, -1);
+    const key = dottedPath[dottedPath.length - 1];
+    const targetIndent = '  '.repeat(sections.length);
+    const lines = template.split('\n');
+    const currentPath = new Array(sections.length).fill(null);
+    const formatted = formatScalar(value);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const stripped = line.trim();
+        if (stripped === '' || stripped.startsWith('#'))
+            continue;
+        const indentLen = line.length - line.trimStart().length;
+        if (indentLen % 2 !== 0)
+            continue;
+        const level = indentLen / 2;
+        if (level > sections.length)
+            continue;
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:/.exec(stripped);
+        if (!m)
+            continue;
+        const lineKey = m[1];
+        if (lineKey === undefined)
+            continue;
+        if (level < sections.length) {
+            if (lineKey === sections[level]) {
+                currentPath[level] = lineKey;
+                for (let j = level + 1; j < currentPath.length; j++)
+                    currentPath[j] = null;
+            }
+            else if (currentPath[level] !== null && lineKey !== currentPath[level]) {
+                currentPath[level] = null;
+            }
+            continue;
+        }
+        // level === sections.length → leaf candidate
+        const parentsMatch = sections.every((s, idx) => currentPath[idx] === s);
+        if (!parentsMatch)
+            continue;
+        if (lineKey !== key)
+            continue;
+        lines[i] = `${targetIndent}${key}: ${formatted}`;
+        return lines.join('\n');
+    }
+    return template;
+}
+/**
+ * Apply every leaf change from `newValues` to `templateBody`. Paths that
+ * are not present in the template are appended at the end. Comments are
+ * preserved for every key that already exists in the template.
+ */
+export function mergeIntoTemplate(templateBody, newValues) {
+    let body = templateBody;
+    const appended = [];
+    for (const entry of flatten(newValues)) {
+        const before = body;
+        body = replaceScalar(body, entry.path, entry.value);
+        if (body === before) {
+            // Path is not in the template — append a flat key=value at EOF.
+            // Form coverage is asserted by parity test, so this branch only
+            // fires on hand-edited templates.
+            appended.push(`${entry.path.join('.')}: ${formatScalar(entry.value)}`);
+        }
+    }
+    if (appended.length > 0) {
+        if (!body.endsWith('\n'))
+            body += '\n';
+        body += `\n# Wizard-added keys (no template entry)\n${appended.join('\n')}\n`;
+    }
+    return body;
+}
+export function diffValues(before, after) {
+    const out = [];
+    const bMap = new Map(flatten(before).map((e) => [e.path.join('.'), e.value]));
+    const aMap = new Map(flatten(after).map((e) => [e.path.join('.'), e.value]));
+    const paths = new Set([...bMap.keys(), ...aMap.keys()]);
+    for (const path of paths) {
+        const fromV = bMap.get(path);
+        const toV = aMap.get(path);
+        if (JSON.stringify(fromV) !== JSON.stringify(toV))
+            out.push({ path, from: fromV, to: toV });
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Recursive dict merge — overlay wins, nested dicts are merged, lists
+ * are replaced (not concatenated). Mirrors `scripts/install.py::deep_merge`
+ * so the Python installer and the Fastify server produce the same
+ * three-layer settings tree (`defaults < global < project`).
+ */
+export function deepMerge(base, overlay) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const existing = result[key];
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            result[key] = deepMerge(existing, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=yamlIO.js.map

package/dist/server/io/yamlIO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yamlIO.js","sourceRoot":"","sources":["../../../src/server/io/yamlIO.ts"],"names":[],"mappings":"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"}

package/dist/server/port.js

@@ -0,0 +1,97 @@
+/**
+ * Free-port picker for the local server.
+ *
+ * Per ADR-012 the local server binds to the reserved range
+ * 41000–41999 on 127.0.0.1. The picker shuffles the range to avoid
+ * predictable port collisions between concurrent invocations and
+ * probes each candidate by attempting a real `net.createServer().listen`,
+ * which is the only reliable way to know a port is available on the
+ * host OS (no race window between "is free" and "bind").
+ *
+ * The picker refuses any range that overlaps the privileged ports
+ * `[0, 1024]` or strays outside the documented contract range. Both
+ * checks are anti-regression — see
+ * `docs/contracts/local-server-ports.md`.
+ */
+import net from 'node:net';
+export class NoFreePortError extends Error {
+    min;
+    max;
+    constructor(min, max) {
+        super(`No free port available in range ${min}-${max}`);
+        this.min = min;
+        this.max = max;
+        this.name = 'NoFreePortError';
+    }
+}
+export class InvalidPortRangeError extends Error {
+    constructor(reason) {
+        super(`Invalid port range: ${reason}`);
+        this.name = 'InvalidPortRangeError';
+    }
+}
+export const DEFAULT_PORT_RANGE = Object.freeze({
+    min: 41000,
+    max: 41999,
+});
+function validateRange(range) {
+    if (!Number.isInteger(range.min) || !Number.isInteger(range.max)) {
+        throw new InvalidPortRangeError('min and max must be integers');
+    }
+    if (range.min > range.max) {
+        throw new InvalidPortRangeError('min must be <= max');
+    }
+    if (range.min <= 1024) {
+        throw new InvalidPortRangeError('privileged ports (≤ 1024) are forbidden');
+    }
+    if (range.max > 65535) {
+        throw new InvalidPortRangeError('max must be <= 65535');
+    }
+}
+function shuffle(arr) {
+    const out = arr.slice();
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const a = out[i];
+        const b = out[j];
+        out[i] = b;
+        out[j] = a;
+    }
+    return out;
+}
+function tryBind(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref();
+        const cleanup = (ok) => {
+            server.removeAllListeners();
+            server.close(() => resolve(ok));
+        };
+        server.once('error', () => cleanup(false));
+        server.once('listening', () => cleanup(true));
+        try {
+            server.listen(port, '127.0.0.1');
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * Pick a free TCP port in `range` (default 41000–41999) bound to
+ * 127.0.0.1. Returns the port number. Throws `NoFreePortError` once
+ * the entire range is exhausted.
+ */
+export async function pickFreePort(range = DEFAULT_PORT_RANGE) {
+    validateRange(range);
+    const candidates = [];
+    for (let p = range.min; p <= range.max; p++)
+        candidates.push(p);
+    const shuffled = shuffle(candidates);
+    for (const port of shuffled) {
+        if (await tryBind(port))
+            return port;
+    }
+    throw new NoFreePortError(range.min, range.max);
+}
+//# sourceMappingURL=port.js.map

package/dist/server/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/server/port.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/discovery.js

@@ -0,0 +1,72 @@
+/**
+ * `GET /api/v1/discovery/manifest` — release-time discovery manifest.
+ *
+ * Returns the parsed manifest (verbatim) or a single slice when the
+ * `?slice=` query parameter is set. Slices: `workspaces`, `packs`,
+ * `artefacts`, `unassigned`.
+ *
+ * Behaviour when the manifest is missing on disk:
+ *   - HTTP 503 + `{ error: 'discovery manifest not available' }`.
+ *
+ * The route never crashes the server — absence is operator error
+ * (PR working tree, dev install) rather than a runtime bug. See ADR-013
+ * and the R3 roadmap for the broader contract.
+ */
+import { z } from 'zod';
+import { loadManifest, ManifestNotFoundError, ManifestParseError, } from '../../cli/discovery/loadManifest.js';
+export const DiscoverySliceSchema = z.enum(['workspaces', 'packs', 'artefacts', 'unassigned']);
+function pickSlice(manifest, slice) {
+    switch (slice) {
+        case 'workspaces':
+            return { workspaces: manifest.workspaces };
+        case 'packs':
+            return { packs: manifest.packs };
+        case 'artefacts':
+            return { artefacts: manifest.artefacts };
+        case 'unassigned':
+            return { unassigned: manifest.unassigned };
+    }
+}
+export function discoveryRoute(opts = {}) {
+    const plugin = async (app) => {
+        app.get('/api/v1/discovery/manifest', async (request, reply) => {
+            let manifest;
+            try {
+                manifest = loadManifest(opts.manifestPath ? { path: opts.manifestPath } : {});
+            }
+            catch (err) {
+                if (err instanceof ManifestNotFoundError) {
+                    await reply.code(503).send({
+                        error: 'discovery manifest not available',
+                        detail: `expected at ${err.path}`,
+                    });
+                    return reply;
+                }
+                if (err instanceof ManifestParseError) {
+                    await reply.code(500).send({
+                        error: 'discovery manifest is malformed',
+                        detail: err.message,
+                    });
+                    return reply;
+                }
+                throw err;
+            }
+            const query = request.query;
+            const sliceRaw = typeof query?.['slice'] === 'string' ? query['slice'] : undefined;
+            if (sliceRaw !== undefined) {
+                const parsed = DiscoverySliceSchema.safeParse(sliceRaw);
+                if (!parsed.success) {
+                    await reply.code(400).send({
+                        error: 'invalid slice parameter',
+                        detail: `slice must be one of: workspaces, packs, artefacts, unassigned`,
+                    });
+                    return reply;
+                }
+                return pickSlice(manifest, parsed.data);
+            }
+            return manifest;
+        });
+    };
+    return plugin;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/server/routes/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/server/routes/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACH,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GAErB,MAAM,qCAAqC,CAAC;AAE7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;AAQ/F,SAAS,SAAS,CACd,QAA2B,EAC3B,KAAqB;IAErB,QAAQ,KAAK,EAAE,CAAC;QACZ,KAAK,YAAY;YACb,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC/C,KAAK,OAAO;YACR,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;QACrC,KAAK,WAAW;YACZ,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC7C,KAAK,YAAY;YACb,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC;IACnD,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAA8B,EAAE;IAC3D,MAAM,MAAM,GAAuB,KAAK,EAAE,GAAoB,EAAE,EAAE;QAC9D,GAAG,CAAC,GAAG,CAAC,4BAA4B,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;YAC3D,IAAI,QAA2B,CAAC;YAChC,IAAI,CAAC;gBACD,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClF,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACvC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACvB,KAAK,EAAE,kCAAkC;wBACzC,MAAM,EAAE,eAAe,GAAG,CAAC,IAAI,EAAE;qBACpC,CAAC,CAAC;oBACH,OAAO,KAAK,CAAC;gBACjB,CAAC;gBACD,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;oBACpC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACvB,KAAK,EAAE,iCAAiC;wBACxC,MAAM,EAAE,GAAG,CAAC,OAAO;qBACtB,CAAC,CAAC;oBACH,OAAO,KAAK,CAAC;gBACjB,CAAC;gBACD,MAAM,GAAG,CAAC;YACd,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAA4C,CAAC;YACnE,MAAM,QAAQ,GAAG,OAAO,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAK,CAAC,OAAO,CAAY,CAAC,CAAC,CAAC,SAAS,CAAC;YAC/F,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBAClB,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACvB,KAAK,EAAE,yBAAyB;wBAChC,MAAM,EAAE,gEAAgE;qBAC3E,CAAC,CAAC;oBACH,OAAO,KAAK,CAAC;gBACjB,CAAC;gBACD,OAAO,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5C,CAAC;YAED,OAAO,QAAQ,CAAC;QACpB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IACF,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/server/routes/ping.js

@@ -0,0 +1,57 @@
+/**
+ * `GET /api/v1/ping` — server liveness probe.
+ *
+ * Returns the package version + projectRoot so consumers (the UI
+ * bundle, future Roadmap-2 wizard, CI smoke tests) can verify they
+ * are connected to the right process. The zod schema is exported so
+ * tests assert against the same source of truth as the handler.
+ */
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { PACKAGE_JSON } from '../../cli/paths.js';
+export const PingResponseSchema = z.object({
+    ok: z.literal(true),
+    version: z.string().min(1),
+    /**
+     * @deprecated mirrors `writeRoot` — retained so existing UI bundles
+     * and integration tests keep parsing. Remove after one release cycle.
+     */
+    projectRoot: z.string().min(1),
+    writeRoot: z.string().min(1),
+    mode: z.enum(['package-sandbox', 'global']),
+    dryRun: z.boolean(),
+    /**
+     * `true` when the wizard may offer the "scope to this project only"
+     * checkbox in Review (road-to-global-only-install § Phase 2.3). The
+     * server hides the checkbox in package-sandbox mode and when the
+     * operator pinned `writeRoot` via `--project`.
+     */
+    projectScopeAvailable: z.boolean(),
+});
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(PACKAGE_JSON, 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function pingRoute(opts) {
+    const plugin = async (app) => {
+        app.get('/api/v1/ping', async () => {
+            const response = {
+                ok: true,
+                version: readPackageVersion(),
+                projectRoot: opts.writeRoot,
+                writeRoot: opts.writeRoot,
+                mode: opts.mode,
+                dryRun: opts.dryRun === true,
+                projectScopeAvailable: opts.projectScopeRoot !== undefined && opts.projectScopeRoot !== null,
+            };
+            return response;
+        });
+    };
+    return plugin;
+}
+//# sourceMappingURL=ping.js.map

package/dist/server/routes/ping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.js","sourceRoot":"","sources":["../../../src/server/routes/ping.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B;;;OAGG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACnB;;;;;OAKG;IACH,qBAAqB,EAAE,CAAC,CAAC,OAAO,EAAE;CACrC,CAAC,CAAC;AAIH,SAAS,kBAAkB;IACvB,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAA0B,CAAC;QACpF,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,OAAO,CAAC;IACnB,CAAC;AACL,CAAC;AAcD,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC5C,MAAM,MAAM,GAAuB,KAAK,EAAE,GAAoB,EAAE,EAAE;QAC9D,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,IAAI,EAAE;YAC/B,MAAM,QAAQ,GAAiB;gBAC3B,EAAE,EAAE,IAAI;gBACR,OAAO,EAAE,kBAAkB,EAAE;gBAC7B,WAAW,EAAE,IAAI,CAAC,SAAS;gBAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,MAAM,EAAE,IAAI,CAAC,MAAM,KAAK,IAAI;gBAC5B,qBAAqB,EAAE,IAAI,CAAC,gBAAgB,KAAK,SAAS,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI;aAC/F,CAAC;YACF,OAAO,QAAQ,CAAC;QACpB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IACF,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/server/routes/schema.js

@@ -0,0 +1,41 @@
+/**
+ * `GET /api/v1/schema` — JSON-Schema export of the wizard / settings forms.
+ *
+ * The SPA bundle does not ship Zod (council security-engineer mandate:
+ * client and server cannot drift). Instead it fetches JSON-Schema once at
+ * mount and feeds it to the form renderer. `zod-to-json-schema` does the
+ * conversion in-process; the response is cached for the lifetime of the
+ * server process because the schemas are compile-time constants.
+ *
+ * Returns the documented shape from `docs/contracts/settings-api.md`:
+ *   {
+ *     settings:    JSONSchema,
+ *     userMd:      JSONSchema,
+ *     generatedAt: ISO-8601 string,
+ *   }
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { settingsSchema } from '../schemas/settings.js';
+import { userIdentitySchema } from '../../shared/userMd/schema.js';
+let cached = null;
+function build() {
+    if (cached !== null)
+        return cached;
+    cached = {
+        settings: zodToJsonSchema(settingsSchema, { name: 'Settings', target: 'jsonSchema7' }),
+        userIdentity: zodToJsonSchema(userIdentitySchema, { name: 'UserIdentity', target: 'jsonSchema7' }),
+        generatedAt: new Date().toISOString(),
+    };
+    return cached;
+}
+/** Reset cache — test-only seam so vitest does not leak state across files. */
+export function _resetSchemaCache() {
+    cached = null;
+}
+export function schemaRoute() {
+    const plugin = async (app) => {
+        app.get('/api/v1/schema', async () => build());
+    };
+    return plugin;
+}
+//# sourceMappingURL=schema.js.map

package/dist/server/routes/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/server/routes/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AASnE,IAAI,MAAM,GAA0B,IAAI,CAAC;AAEzC,SAAS,KAAK;IACV,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACnC,MAAM,GAAG;QACL,QAAQ,EAAE,eAAe,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QACtF,YAAY,EAAE,eAAe,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QAClG,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACxC,CAAC;IACF,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB;IAC7B,MAAM,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,WAAW;IACvB,MAAM,MAAM,GAAuB,KAAK,EAAE,GAAoB,EAAE,EAAE;QAC9D,GAAG,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC,CAAC;IACF,OAAO,MAAM,CAAC;AAClB,CAAC"}