@diagc/cli 0.1.0

package/dist/api/handlers.js

@@ -0,0 +1,420 @@
+import { access, mkdir, readFile, readdir, rename, unlink } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { IMAGE_REF, composeIncludes, errMessage, isDrawings, isLayoutOverlay, validate } from '@diagc/core';
+import { writeFileAtomic } from '../atomic-write.js';
+import { EjectError, ejectDiagram } from '../eject.js';
+import { resolveInclude } from '../includes.js';
+import { snapshotSession } from '../snapshots.js';
+export function isSafeName(name) {
+    return /^[a-z0-9][a-z0-9/-]*$/.test(name) && !name.includes('..') && !name.includes('//');
+}
+// path.dirname(diagramsDir) is the .diagrams root when diagramsDir is
+// .diagrams/src — the same rootDir a locked session uses elsewhere (eject.ts).
+// 'locked' because the boot/refresh path must never fetch or vendor a remote
+// include on a viewer's behalf — that only happens at `diagc compile`.
+const lockedResolver = (diagramsDir) => snapshotSession(resolveInclude, path.dirname(diagramsDir), 'locked').resolver;
+const hasIncludes = (m) => m !== null && Array.isArray(m.nodes) && m.nodes.some((n) => n.include !== undefined);
+/** Recursively collect every file under `dir` whose name ends in `suffix`,
+ * posix-joined relative to `dir` with the suffix stripped. Missing dir → [].
+ * Shared by the diagram-source and layout-overlay walks. */
+export async function walkFiles(dir, suffix) {
+    const names = [];
+    const walk = async (d, prefix) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory())
+                await walk(path.join(d, e.name), `${prefix}${e.name}/`);
+            else if (e.name.endsWith(suffix))
+                names.push(`${prefix}${e.name.slice(0, -suffix.length)}`);
+        }
+    };
+    await walk(dir, '');
+    return names;
+}
+/** Recursively collect `<name>` for every `*.diagram.json` under `dir`
+ * (posix-joined, suffix stripped). Missing dir → []. */
+export async function walkDiagramJson(dir) {
+    return walkFiles(dir, '.diagram.json');
+}
+/** Render-ready models for the studio boot: JSON sources (editable) served from
+ * `diagramsDir`, compiled TS artifacts from `artifactsDir`. A source shadows its
+ * artifact so unsaved-compile staleness never shows. */
+export async function listDiagramModels(diagramsDir, artifactsDir) {
+    const sourceNames = new Set(await walkDiagramJson(diagramsDir));
+    const artifactNames = await walkDiagramJson(artifactsDir);
+    const all = [...new Set([...sourceNames, ...artifactNames])].sort();
+    const diagrams = [];
+    for (const name of all) {
+        const editable = sourceNames.has(name);
+        const file = editable
+            ? path.join(diagramsDir, `${name}.diagram.json`)
+            : path.join(artifactsDir, `${name}.diagram.json`);
+        let model = null;
+        const issues = [];
+        try {
+            model = JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch {
+            issues.push({ message: `Could not read model for '${name}'` });
+        }
+        if (editable && hasIncludes(model)) {
+            try {
+                const { model: composed, warnings } = await composeIncludes(model, path.resolve(file), lockedResolver(diagramsDir));
+                // compileFile refuses an invalid composed result outright (CLAUDE.md:
+                // "the renderer may assume the model is sound") — an id collision
+                // between an umbrella-declared node and a namespaced include can pass
+                // composeIncludes (which only grafts) while still being invalid, so
+                // this must be checked here too, not just on compile.
+                const validationIssues = validate(composed);
+                if (validationIssues.length > 0) {
+                    // fall back to the raw model (include nodes as placeholders); it
+                    // still renders, unlike the unsound composed result
+                    issues.push(...validationIssues);
+                }
+                else {
+                    model = composed;
+                    for (const w of warnings)
+                        issues.push({ message: w });
+                }
+            }
+            catch (e) {
+                // the raw model still renders (include nodes as placeholders); say why
+                issues.push({ message: `Includes not expanded: ${errMessage(e)}` });
+            }
+        }
+        diagrams.push({ name, model, issues, editable });
+    }
+    return { status: 200, body: { diagrams } };
+}
+/** All layout overlays under `diagramsDir`, keyed by diagram name. Corrupt
+ * overlays are skipped, never fatal. */
+export async function listLayouts(diagramsDir) {
+    const layouts = {};
+    for (const name of await walkFiles(diagramsDir, '.layout.json')) {
+        try {
+            layouts[name] = JSON.parse(await readFile(path.join(diagramsDir, `${name}.layout.json`), 'utf8'));
+        }
+        catch {
+            /* skip corrupt overlay */
+        }
+    }
+    return { status: 200, body: { layouts } };
+}
+/** All drawings sidecars under `diagramsDir`, keyed by diagram name. Corrupt
+ * files are skipped, never fatal — same contract as listLayouts. */
+export async function listDrawings(diagramsDir) {
+    const drawings = {};
+    for (const name of await walkFiles(diagramsDir, '.drawings.json')) {
+        try {
+            drawings[name] = JSON.parse(await readFile(path.join(diagramsDir, `${name}.drawings.json`), 'utf8'));
+        }
+        catch {
+            /* skip corrupt sidecar */
+        }
+    }
+    return { status: 200, body: { drawings } };
+}
+/** the JSON source (+ sibling layout and drawings) of a designer-owned diagram — the studio
+ * reads these directly so it never depends on a compile watcher for its own files */
+export async function readDiagram(diagramsDir, name) {
+    if (!isSafeName(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
+    let model;
+    try {
+        model = JSON.parse(await readFile(path.join(diagramsDir, `${name}.diagram.json`), 'utf8'));
+    }
+    catch {
+        return { status: 404, body: { issues: [{ message: `No diagram source '${name}'` }] } };
+    }
+    let layout;
+    try {
+        layout = JSON.parse(await readFile(path.join(diagramsDir, `${name}.layout.json`), 'utf8'));
+    }
+    catch {
+        layout = undefined;
+    }
+    let drawings;
+    try {
+        drawings = JSON.parse(await readFile(path.join(diagramsDir, `${name}.drawings.json`), 'utf8'));
+    }
+    catch {
+        drawings = undefined;
+    }
+    return {
+        status: 200,
+        body: {
+            model,
+            ...(layout !== undefined ? { layout } : {}),
+            ...(drawings !== undefined ? { drawings } : {}),
+        },
+    };
+}
+/** Composed read of an editable source — the studio's view-refresh after a
+ * save. Sources without includes pass through untouched. */
+export async function readComposedDiagram(diagramsDir, name) {
+    if (!isSafeName(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
+    const file = path.join(diagramsDir, `${name}.diagram.json`);
+    let model;
+    try {
+        model = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return { status: 404, body: { issues: [{ message: `No diagram source '${name}'` }] } };
+    }
+    if (!hasIncludes(model))
+        return { status: 200, body: { model } };
+    try {
+        const { model: composed, warnings } = await composeIncludes(model, path.resolve(file), lockedResolver(diagramsDir));
+        // Same soundness check as listDiagramModels: a composed model that fails
+        // validation must never reach the renderer, so refuse it like a failed
+        // compose instead of returning 200 with an unsound model.
+        const issues = validate(composed);
+        if (issues.length > 0)
+            return { status: 409, body: { issues } };
+        return { status: 200, body: { model: composed, ...(warnings.length > 0 ? { warnings } : {}) } };
+    }
+    catch (e) {
+        return { status: 409, body: { issues: [{ message: errMessage(e) }] } };
+    }
+}
+export async function saveDiagram(diagramsDir, name, payload) {
+    if (!isSafeName(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
+    const p = payload;
+    const arraysOk = p !== null &&
+        p.version === 1 &&
+        Array.isArray(p.nodes) &&
+        Array.isArray(p.containment) &&
+        Array.isArray(p.relations) &&
+        Array.isArray(p.layers) &&
+        Array.isArray(p.planes);
+    if (!arraysOk) {
+        return { status: 400, body: { issues: [{ message: 'Not a version-1 diagram model' }] } };
+    }
+    const issues = validate(payload);
+    if (issues.length > 0)
+        return { status: 400, body: { issues } };
+    const target = path.join(diagramsDir, `${name}.diagram.json`);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
+    return { status: 200, body: { ok: true } };
+}
+/** Move a designer-owned diagram (and its sibling layout, if any) to a new name,
+ * rewriting the model's internal id/name to match so the file stays self-consistent. */
+export async function renameDiagram(diagramsDir, from, to) {
+    if (!isSafeName(from) || !isSafeName(to)) {
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${isSafeName(from) ? to : from}'` }] } };
+    }
+    if (from === to)
+        return { status: 400, body: { issues: [{ message: 'New name is the same as the old' }] } };
+    const fromDiagram = path.join(diagramsDir, `${from}.diagram.json`);
+    const toDiagram = path.join(diagramsDir, `${to}.diagram.json`);
+    let raw;
+    try {
+        raw = await readFile(fromDiagram, 'utf8');
+    }
+    catch {
+        return { status: 404, body: { issues: [{ message: `No diagram source '${from}'` }] } };
+    }
+    try {
+        await access(toDiagram);
+        return { status: 409, body: { issues: [{ message: `A diagram named '${to}' already exists` }] } };
+    }
+    catch {
+        /* target free — proceed */
+    }
+    let model;
+    try {
+        model = JSON.parse(raw);
+    }
+    catch {
+        return { status: 400, body: { issues: [{ message: `Corrupt diagram source '${from}'` }] } };
+    }
+    model['id'] = to;
+    model['name'] = to;
+    await mkdir(path.dirname(toDiagram), { recursive: true });
+    await writeFileAtomic(toDiagram, `${JSON.stringify(model, null, 2)}\n`);
+    await unlink(fromDiagram);
+    // Carry the layout over when it exists; its absence is not an error.
+    try {
+        await rename(path.join(diagramsDir, `${from}.layout.json`), path.join(diagramsDir, `${to}.layout.json`));
+    }
+    catch {
+        /* no layout to move */
+    }
+    try {
+        await rename(path.join(diagramsDir, `${from}.drawings.json`), path.join(diagramsDir, `${to}.drawings.json`));
+    }
+    catch {
+        /* no drawings to move */
+    }
+    return { status: 200, body: { ok: true } };
+}
+/** Promote a JSON-owned diagram to a generated `.diagram.ts`. See `ejectDiagram`
+ * for the round-trip guarantee; this just maps its failure codes to statuses. */
+export async function ejectDiagramSource(diagramsDir, artifactsDir, name) {
+    if (!isSafeName(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
+    try {
+        await ejectDiagram(diagramsDir, artifactsDir, name);
+        return { status: 200, body: { ok: true } };
+    }
+    catch (e) {
+        if (e instanceof EjectError) {
+            const status = e.code === 'not-found' ? 404 : e.code === 'invalid' ? 400 : 409;
+            return { status, body: { issues: [{ message: e.message }] } };
+        }
+        throw e;
+    }
+}
+export async function saveLayout(diagramsDir, name, payload) {
+    if (!isSafeName(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
+    // Core's structural guard mirrors the old inline checks (version 1, nested
+    // numeric x/y planes, optional positive-finite sizes) — one source of truth
+    // shared with the client-side artifact loader.
+    if (!isLayoutOverlay(payload))
+        return { status: 400, body: { issues: [{ message: 'Not a version-1 layout overlay' }] } };
+    const target = path.join(diagramsDir, `${name}.layout.json`);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
+    return { status: 200, body: { ok: true } };
+}
+/** Persist the drawings sidecar. An overlay in which no bucket holds a stroke
+ * DELETES the file instead of writing it: a diagram that never had drawings
+ * must never grow an empty `<name>.drawings.json`, and erasing the last stroke
+ * should leave the tree as it was. */
+export async function saveDrawings(diagramsDir, name, payload) {
+    if (!isSafeName(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe name '${name}'` }] } };
+    if (!isDrawings(payload))
+        return { status: 400, body: { issues: [{ message: 'Not a version-1 drawings overlay' }] } };
+    const target = path.join(diagramsDir, `${name}.drawings.json`);
+    const hasStrokes = Object.values(payload.planes).some((bucket) => bucket.length > 0);
+    if (!hasStrokes) {
+        try {
+            await unlink(target);
+        }
+        catch (e) {
+            // ENOENT only: there was nothing to delete, which is the ordinary case for
+            // a diagram that never had ink. Anything else (EACCES, EPERM, EISDIR) means
+            // the strokes are still on disk — rethrow so dispatch turns it into a 500
+            // and useEditor.save surfaces it, instead of answering `{ ok: true }` and
+            // letting the erased strokes resurrect on the next boot.
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        return { status: 200, body: { ok: true } };
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
+    return { status: 200, body: { ok: true } };
+}
+export async function readLibrary(diagramsDir) {
+    try {
+        const raw = await readFile(path.join(diagramsDir, 'library.json'), 'utf8');
+        return { status: 200, body: JSON.parse(raw) };
+    }
+    catch {
+        return { status: 200, body: { categories: [], entries: [] } };
+    }
+}
+// Must cover every NodeTemplate presentation channel — 'shape' included, or a
+// user library holding an imported silhouette is rejected on save.
+const TEMPLATE_STRING_KEYS = new Set(['type', 'color', 'image', 'shape']);
+const TEMPLATE_NUMBER_KEYS = new Set(['width', 'height']);
+/** Persist the whole user library. Validates internal consistency only — bundled
+ * packs are merged client-side and never written here. */
+export async function saveLibrary(diagramsDir, payload) {
+    const p = payload;
+    if (p === null || !Array.isArray(p.categories) || !Array.isArray(p.entries)) {
+        return { status: 400, body: { issues: [{ message: 'Not a library { categories, entries }' }] } };
+    }
+    const catIds = new Set();
+    for (const c of p.categories) {
+        const cat = c;
+        if (typeof cat.id !== 'string' || typeof cat.name !== 'string') {
+            return { status: 400, body: { issues: [{ message: 'Category needs string id and name' }] } };
+        }
+        if (catIds.has(cat.id))
+            return { status: 400, body: { issues: [{ message: `Duplicate category '${cat.id}'` }] } };
+        catIds.add(cat.id);
+    }
+    const entryIds = new Set();
+    for (const e of p.entries) {
+        const entry = e;
+        if (typeof entry.id !== 'string' || typeof entry.name !== 'string' || typeof entry.category !== 'string') {
+            return { status: 400, body: { issues: [{ message: 'Entry needs string id, name, category' }] } };
+        }
+        if (!catIds.has(entry.category)) {
+            return { status: 400, body: { issues: [{ message: `Entry '${entry.id}' references unknown category '${entry.category}'` }] } };
+        }
+        if (entryIds.has(entry.id))
+            return { status: 400, body: { issues: [{ message: `Duplicate entry '${entry.id}'` }] } };
+        entryIds.add(entry.id);
+        const t = entry.template;
+        if (t === null || typeof t !== 'object' || Array.isArray(t)) {
+            return { status: 400, body: { issues: [{ message: `Entry '${entry.id}' missing template` }] } };
+        }
+        for (const [k, v] of Object.entries(t)) {
+            const ok = TEMPLATE_STRING_KEYS.has(k) ? typeof v === 'string' : TEMPLATE_NUMBER_KEYS.has(k) ? typeof v === 'number' : false;
+            if (!ok)
+                return { status: 400, body: { issues: [{ message: `Entry '${entry.id}' has invalid template field '${k}'` }] } };
+        }
+    }
+    const target = path.join(diagramsDir, 'library.json');
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFileAtomic(target, `${JSON.stringify(payload, null, 2)}\n`);
+    return { status: 200, body: { ok: true } };
+}
+// Keys here must stay in sync with IMAGE_REF's extension group (@diagc/core) —
+// an extension accepted by the regex but missing here would 404 on read.
+const ASSET_EXT = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/svg+xml': 'svg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+};
+const ASSET_TYPE = Object.fromEntries(Object.entries(ASSET_EXT).map(([t, e]) => [e, t]));
+export const MAX_ASSET_BYTES = 5 * 1024 * 1024;
+/** store image bytes under their content hash; identical drops dedupe to one file */
+export async function saveAsset(diagramsDir, contentType, bytes) {
+    const ext = ASSET_EXT[contentType.split(';')[0]?.trim() ?? ''];
+    if (ext === undefined) {
+        return { status: 400, body: { issues: [{ message: `Unsupported image type '${contentType}'` }] } };
+    }
+    if (bytes.length === 0 || bytes.length > MAX_ASSET_BYTES) {
+        return { status: 400, body: { issues: [{ message: `Image must be 1 byte to ${MAX_ASSET_BYTES / 1024 / 1024} MB` }] } };
+    }
+    const name = `${createHash('sha256').update(bytes).digest('hex').slice(0, 12)}.${ext}`;
+    const target = path.join(diagramsDir, 'assets', name);
+    await mkdir(path.dirname(target), { recursive: true });
+    try {
+        await access(target); // already stored — content hash guarantees same bytes
+    }
+    catch {
+        await writeFileAtomic(target, bytes);
+    }
+    return { status: 200, body: { name } };
+}
+export async function readAsset(diagramsDir, name) {
+    if (!IMAGE_REF.test(name))
+        return { status: 400, body: { issues: [{ message: `Unsafe asset name '${name}'` }] } };
+    try {
+        const bytes = await readFile(path.join(diagramsDir, 'assets', name));
+        const ext = name.split('.').at(-1) ?? '';
+        return { status: 200, body: null, bytes, contentType: ASSET_TYPE[ext === 'jpeg' ? 'jpg' : ext] ?? 'application/octet-stream' };
+    }
+    catch {
+        return { status: 404, body: { issues: [{ message: `No asset '${name}'` }] } };
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,3 @@
+export * as handlers from './handlers.js';
+export { handleApiRequest, runRoute, type ApiContext, type Handlers, type RouteRequest, type RouteResponse, } from './dispatch.js';
+export { matchRoute, ROUTES, type Route, type RouteCtx } from './routes.js';

package/dist/api/index.js

@@ -0,0 +1,7 @@
+// The studio's read/write API, shared by two hosts: the Vite dev middleware in
+// `apps/studio` (which loads this module lazily, through Vite's own pipeline)
+// and the packaged `diagc studio` server, which has no Vite at all. One route
+// table, so an added route cannot exist in only one of them.
+export * as handlers from './handlers.js';
+export { handleApiRequest, runRoute, } from './dispatch.js';
+export { matchRoute, ROUTES } from './routes.js';

package/dist/api/routes.d.ts

@@ -0,0 +1,27 @@
+type Handlers = typeof import('./handlers.js');
+/** One route handler's result: handlers' JSON envelope plus readAsset's
+ * optional `bytes`/`contentType`, which the wrapper streams raw. */
+export type RouteResult = Awaited<ReturnType<Handlers['readAsset']>>;
+/** Capture groups, already-read body, content-type, and dirs for a request. */
+export interface RouteCtx {
+    match: RegExpMatchArray;
+    body: unknown;
+    /** content-type of the raw body (only the asset-upload route reads it) */
+    contentType?: string;
+    diagramsDir: string;
+    artifactsDir: string;
+}
+export type BodyMode = 'none' | 'json' | 'raw';
+export interface Route {
+    method: string;
+    /** non-global regex against `req.url`; captures are passed to the handler */
+    pattern: RegExp;
+    /** 'json' parses the body (malformed JSON → 400), 'raw' passes bytes
+     * through, 'none' (default) leaves the body unread. */
+    bodyMode?: BodyMode;
+    handler: (h: Handlers, ctx: RouteCtx) => Promise<RouteResult>;
+}
+export declare const ROUTES: Route[];
+/** The route matching `method` + `url`, or undefined. First match wins. */
+export declare function matchRoute(method: string | undefined, url: string): Route | undefined;
+export {};

package/dist/api/routes.js

@@ -0,0 +1,43 @@
+// Route table: the first pattern a request matches wins, so entry order here
+// IS the dispatch order (the rename entry must precede the generic save entry).
+export const ROUTES = [
+    // --- assets: raw body in, raw bytes out ---
+    { method: 'POST', pattern: /^\/api\/assets$/, bodyMode: 'raw', handler: (h, c) => h.saveAsset(c.diagramsDir, c.contentType ?? '', c.body) },
+    { method: 'GET', pattern: /^\/api\/assets\/([^/]+)$/, handler: (h, c) => h.readAsset(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')) },
+    // --- library ---
+    { method: 'GET', pattern: /^\/api\/library$/, handler: (h, c) => h.readLibrary(c.diagramsDir) },
+    { method: 'PUT', pattern: /^\/api\/library$/, bodyMode: 'json', handler: (h, c) => h.saveLibrary(c.diagramsDir, c.body) },
+    // --- diagrams & layouts ---
+    { method: 'GET', pattern: /^\/api\/diagrams$/, handler: (h, c) => h.listDiagramModels(c.diagramsDir, c.artifactsDir) },
+    { method: 'GET', pattern: /^\/api\/layouts$/, handler: (h, c) => h.listLayouts(c.diagramsDir) },
+    { method: 'GET', pattern: /^\/api\/drawings$/, handler: (h, c) => h.listDrawings(c.diagramsDir) },
+    // Composed read must precede the generic read, whose `(.+)` would swallow
+    // `<name>/composed` as a filename.
+    { method: 'GET', pattern: /^\/api\/diagrams\/(.+)\/composed$/, handler: (h, c) => h.readComposedDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')) },
+    { method: 'GET', pattern: /^\/api\/diagrams\/(.+)$/, handler: (h, c) => h.readDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')) },
+    // Rename must be checked before the generic save route, whose `(.+)`
+    // would otherwise swallow `<from>/rename` as a filename.
+    { method: 'POST', pattern: /^\/api\/diagrams\/(.+)\/rename$/, bodyMode: 'json', handler: async (h, c) => {
+            const to = c.body?.to;
+            if (typeof to !== 'string')
+                return { status: 400, body: { issues: [{ message: "Missing 'to' name" }] } };
+            return h.renameDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? ''), to);
+        } },
+    // Eject must also precede the generic save route, whose `(.+)` would
+    // swallow `<name>/eject` as a filename.
+    { method: 'POST', pattern: /^\/api\/diagrams\/(.+)\/eject$/, handler: (h, c) => h.ejectDiagramSource(c.diagramsDir, c.artifactsDir, decodeURIComponent(c.match[1] ?? '')) },
+    { method: 'POST', pattern: /^\/api\/(diagrams|layouts|drawings)\/(.+)$/, bodyMode: 'json', handler: (h, c) => {
+            // decodeURIComponent throws on malformed percent-encoding — kept
+            // inside the boundary so a bad name yields 500, never a crash.
+            const name = decodeURIComponent(c.match[2] ?? '');
+            return c.match[1] === 'diagrams'
+                ? h.saveDiagram(c.diagramsDir, name, c.body)
+                : c.match[1] === 'layouts'
+                    ? h.saveLayout(c.diagramsDir, name, c.body)
+                    : h.saveDrawings(c.diagramsDir, name, c.body);
+        } },
+];
+/** The route matching `method` + `url`, or undefined. First match wins. */
+export function matchRoute(method, url) {
+    return ROUTES.find((r) => r.method === method && r.pattern.test(url));
+}

package/dist/atomic-write.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Write `data` to `target` atomically: stage it in a hidden temp file in the
+ * same directory (same filesystem, so `rename` is atomic), then rename over
+ * the target. A crash or full disk mid-write leaves the previous content
+ * intact instead of a truncated file — these are committed sources, not
+ * regenerable build output.
+ */
+export declare function writeFileAtomic(target: string, data: string | Buffer): Promise<void>;

package/dist/atomic-write.js

@@ -0,0 +1,21 @@
+import { randomBytes } from 'node:crypto';
+import { rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Write `data` to `target` atomically: stage it in a hidden temp file in the
+ * same directory (same filesystem, so `rename` is atomic), then rename over
+ * the target. A crash or full disk mid-write leaves the previous content
+ * intact instead of a truncated file — these are committed sources, not
+ * regenerable build output.
+ */
+export async function writeFileAtomic(target, data) {
+    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        await writeFile(tmp, data);
+        await rename(tmp, target);
+    }
+    catch (e) {
+        await unlink(tmp).catch(() => { });
+        throw e;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+interface Args {
+    command: string;
+    files: string[];
+    out: string;
+    images: boolean;
+    updateIncludes: boolean;
+}
+/** Parse argv into command + flags. Unknown flags (anything `--…` that is not
+ * recognized) are an error rather than being silently treated as a file path,
+ * so a typo surfaces loudly instead of quietly skewing the file set. */
+export declare function parseArgs(argv: string[]): Args;
+/** Thrown by {@link parseArgs} for `--help`/`-h`; `main` prints usage and exits 0. */
+export declare class HelpRequested extends Error {
+    constructor();
+}
+/** Thrown by {@link parseArgs} for an unrecognized flag; `main` prints the
+ * offending flag plus usage and exits 1. */
+export declare class UnknownFlagError extends Error {
+    constructor(flag: string);
+}
+export {};