loom-spec 0.2.0 → 0.4.0

package/dist/cli/exportHtml.d.ts

@@ -0,0 +1,25 @@
+export interface ExportHtmlArgs {
+    /** Output file path. Default: "loom.html" in cwd. */
+    out: string;
+    /** Working directory root (walked up to find .loom/). */
+    root: string;
+    /** If set, only this diagram (plus any timelines that reference it). */
+    diagram?: string;
+    /** Skip all timelines. Useful for manuals where the static topology is
+     *  the whole story. */
+    noTimelines: boolean;
+    /** Only export nodes carrying at least one of these tags. */
+    includeTags?: string[];
+    /** Drop nodes carrying any of these tags. */
+    excludeTags?: string[];
+    /** Named bundle from .loom/exports.json. Settings from the bundle become
+     *  defaults; explicit CLI flags override. */
+    bundle?: string;
+}
+/**
+ * Used by the bundle-merge logic to tell "user passed --out" from "we are
+ * using the default". Exported so the CLI dispatcher can default-init the
+ * field once and stay consistent with this module's notion of "default".
+ */
+export declare const DEFAULT_OUT = "loom.html";
+export declare function runExportHtml(args: ExportHtmlArgs): Promise<void>;

package/dist/cli/exportHtml.js

@@ -0,0 +1,201 @@
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findLoomRoot } from "../server/findLoomRoot.js";
+import { listDiagrams, readDiagram, listTimelines, readTimeline, readNodeTypes, } from "../server/fileOps.js";
+import { applyFilter } from "../server/exportFilter.js";
+import { loadExportsConfig } from "../server/exportConfig.js";
+const here = dirname(fileURLToPath(import.meta.url));
+async function fileExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locate the export-mode view bundle. Tries both layouts:
+ *   - Production: alongside cli/ in dist/ → ../view-export/
+ *   - Dev (tsx running from src/cli/): ../../dist/view-export/
+ */
+async function findExportBundle() {
+    const candidates = [
+        resolve(here, "../view-export"),
+        resolve(here, "../../dist/view-export"),
+    ];
+    for (const c of candidates) {
+        if (await fileExists(resolve(c, "index.html")))
+            return c;
+    }
+    throw new Error(`Could not find the export view bundle. Looked in:\n  - ${candidates.join("\n  - ")}\n` +
+        `Did you run 'pnpm build' (or 'pnpm build:export') to produce dist/view-export?`);
+}
+/**
+ * Used by the bundle-merge logic to tell "user passed --out" from "we are
+ * using the default". Exported so the CLI dispatcher can default-init the
+ * field once and stay consistent with this module's notion of "default".
+ */
+export const DEFAULT_OUT = "loom.html";
+async function loadAllData(args) {
+    const loomRoot = await findLoomRoot(args.root);
+    const nodeTypes = await readNodeTypes(loomRoot.loomPath);
+    // Diagrams — either one specific or all
+    const diagrams = {};
+    if (args.diagram) {
+        diagrams[args.diagram] = await readDiagram(loomRoot.loomPath, args.diagram);
+    }
+    else {
+        const summaries = await listDiagrams(loomRoot.loomPath);
+        for (const s of summaries) {
+            diagrams[s.id] = await readDiagram(loomRoot.loomPath, s.id);
+        }
+    }
+    // Timelines — include those that reference at least one diagram we exported
+    const timelines = {};
+    if (!args.noTimelines) {
+        const summaries = await listTimelines(loomRoot.loomPath);
+        for (const s of summaries) {
+            if (!(s.diagram in diagrams))
+                continue;
+            timelines[s.id] = await readTimeline(loomRoot.loomPath, s.id);
+        }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        diagrams,
+        timelines,
+        nodeTypes,
+    };
+}
+/**
+ * Inline the view bundle (HTML + CSS + JS) and the exported data into a
+ * single self-contained HTML string.
+ *
+ * The export bundle's index.html looks roughly like:
+ *   <html><head><link rel="stylesheet" href="/assets/bundle.css">
+ *     <script type="module" crossorigin src="/assets/bundle.js"></script>
+ *   </head><body><div id="root"></div></body></html>
+ *
+ * We rewrite the link/script tags to inline contents and inject a
+ * <script>window.__LOOM_DATA__ = {...}</script> before the bundle.
+ */
+function buildHtml(bundleHtml, bundleCss, bundleJs, data, meta) {
+    // Sanitize the JSON for inlining inside a <script> tag.
+    // Replace </script> sequences and <!-- inside string values so they can't
+    // close the surrounding script element or confuse parsers.
+    const safeJson = JSON.stringify(data)
+        .replace(/<\/script/gi, "<\\/script")
+        .replace(/<!--/g, "<\\!--");
+    const inlineDataTag = `<script>window.__LOOM_DATA__ = ${safeJson};</script>`;
+    const inlineCssTag = `<style>${bundleCss}</style>`;
+    const inlineJsTag = `<script type="module">${bundleJs}</script>`;
+    let out = bundleHtml;
+    // CRITICAL: pass replacement as a function rather than a string. With a
+    // string second arg, JS treats `$$` as a literal `$`, which mangles any
+    // `$$typeof` / `$&` / `$'` in the JS bundle (React's reconciler uses
+    // `$$typeof` heavily). Function form bypasses the pattern processing.
+    out = out.replace(/<link\s+rel=["']stylesheet["'][^>]*>/i, () => inlineCssTag);
+    out = out.replace(/<script\s+type=["']module["'][^>]*><\/script>/i, () => inlineDataTag + inlineJsTag);
+    out = out.replace(/<title>[^<]*<\/title>/i, () => `<title>loom-spec export · ${escapeHtml(meta.sourceRoot)}</title>`);
+    return out;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export async function runExportHtml(args) {
+    // If a bundle name was given, resolve its settings from .loom/exports.json
+    // first. Explicit CLI args take precedence (for ad-hoc overrides).
+    let effective = args;
+    if (args.bundle) {
+        const loomRoot = await findLoomRoot(args.root);
+        const config = await loadExportsConfig(loomRoot.loomPath);
+        if (!config) {
+            console.error(`export-html: no .loom/exports.json found, but '${args.bundle}' looks like a named bundle.\n` +
+                `  Create .loom/exports.json with an 'exports.${args.bundle}' entry, or pass ad-hoc flags instead.`);
+            process.exit(1);
+        }
+        const bundle = config.exports[args.bundle];
+        if (!bundle) {
+            const available = Object.keys(config.exports).sort().join(", ") || "(none)";
+            console.error(`export-html: bundle '${args.bundle}' not found in .loom/exports.json. ` +
+                `Available: ${available}.`);
+            process.exit(1);
+        }
+        // Merge: explicit CLI args (in `args`) override config-supplied values.
+        effective = {
+            ...args,
+            out: args.out !== DEFAULT_OUT ? args.out : bundle.out ?? args.out,
+            diagram: args.diagram ?? bundle.diagram,
+            noTimelines: args.noTimelines || (bundle.noTimelines ?? false),
+            includeTags: args.includeTags ?? bundle.includeTags,
+            excludeTags: args.excludeTags ?? bundle.excludeTags,
+        };
+    }
+    const bundleDir = await findExportBundle();
+    const [bundleHtml, bundleCss, bundleJs] = await Promise.all([
+        readFile(resolve(bundleDir, "index.html"), "utf8"),
+        readFile(resolve(bundleDir, "assets/bundle.css"), "utf8"),
+        readFile(resolve(bundleDir, "assets/bundle.js"), "utf8"),
+    ]);
+    const data = await loadAllData(effective);
+    if (Object.keys(data.diagrams).length === 0) {
+        console.error("export-html: no diagrams found — refusing to write an empty export.");
+        process.exit(1);
+    }
+    const filterSpec = {
+        includeTags: effective.includeTags,
+        excludeTags: effective.excludeTags,
+    };
+    const { payload: filtered, summary } = applyFilter(data, filterSpec);
+    // After filtering, if everything's gone, bail. Better to fail loud than
+    // silently emit a blank HTML the user will wonder about.
+    const survivingNodes = Object.values(filtered.diagrams).reduce((n, d) => n + d.nodes.length, 0);
+    if (survivingNodes === 0) {
+        console.error("export-html: filter matched 0 nodes — refusing to write an empty export.");
+        if (filterSpec.includeTags?.length || filterSpec.excludeTags?.length) {
+            console.error(`  filter was: include=[${(filterSpec.includeTags ?? []).join(", ")}], ` +
+                `exclude=[${(filterSpec.excludeTags ?? []).join(", ")}]`);
+        }
+        process.exit(1);
+    }
+    const finalData = {
+        ...data,
+        diagrams: filtered.diagrams,
+        timelines: filtered.timelines,
+    };
+    const html = buildHtml(bundleHtml, bundleCss, bundleJs, finalData, {
+        sourceRoot: effective.root,
+    });
+    const outPath = resolve(effective.out);
+    await writeFile(outPath, html, "utf8");
+    const sizeKb = Math.round(Buffer.byteLength(html, "utf8") / 1024);
+    const diagramCount = Object.keys(finalData.diagrams).length;
+    const timelineCount = Object.keys(finalData.timelines).length;
+    console.log(`Wrote ${outPath} (${sizeKb} kB): ` +
+        `${diagramCount} diagram${diagramCount === 1 ? "" : "s"}, ` +
+        `${timelineCount} timeline${timelineCount === 1 ? "" : "s"}.`);
+    const droppedParts = [];
+    if (summary.nodesDropped > 0)
+        droppedParts.push(`${summary.nodesDropped} nodes`);
+    if (summary.edgesDropped > 0)
+        droppedParts.push(`${summary.edgesDropped} edges`);
+    if (summary.groupsDropped > 0)
+        droppedParts.push(`${summary.groupsDropped} groups`);
+    if (summary.eventsDropped > 0)
+        droppedParts.push(`${summary.eventsDropped} events`);
+    if (summary.timelinesDropped > 0)
+        droppedParts.push(`${summary.timelinesDropped} timelines`);
+    if (summary.drillDownsCleared > 0)
+        droppedParts.push(`${summary.drillDownsCleared} drill-down refs`);
+    if (droppedParts.length > 0) {
+        console.log(`Filter dropped: ${droppedParts.join(", ")}.`);
+    }
+    console.log(`Open it directly in a browser, or drop it into any docs / wiki / GitHub-Pages site.`);
+}
+//# sourceMappingURL=exportHtml.js.map

package/dist/cli/exportHtml.js.map

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

package/dist/cli/importTrace.d.ts

@@ -0,0 +1,15 @@
+export interface ImportTraceArgs {
+    /** Path to the OTLP JSON trace file. */
+    trace: string;
+    /** Timeline id to create or append into. */
+    asId: string;
+    /** Diagram id the new timeline overlays. */
+    diagramId: string;
+    /** Optional path to a mapping file (see MappingFile shape below). */
+    map?: string;
+    /** Append to an existing timeline instead of overwriting. */
+    append: boolean;
+    /** Working directory root (walked up to find .loom/). */
+    root: string;
+}
+export declare function runImportTrace(args: ImportTraceArgs): Promise<void>;

package/dist/cli/importTrace.js

@@ -0,0 +1,188 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { findLoomRoot } from "../server/findLoomRoot.js";
+import { readDiagram, readTimeline, writeTimeline } from "../server/fileOps.js";
+import { parseOtlpJson } from "../server/otel.js";
+import { validateTimeline } from "../validate.js";
+const KIND_TO_EVENT_KIND = {
+    internal: "compute",
+    server: "io",
+    client: "io",
+    producer: "io",
+    consumer: "io",
+    unknown: undefined,
+};
+async function loadMapping(path) {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        serviceMap: new Map(Object.entries(parsed.services ?? {})),
+        spanMap: new Map(Object.entries(parsed.spans ?? {})),
+    };
+}
+/**
+ * Decide which node a span belongs to.
+ * Precedence: explicit span map > explicit service map > heuristic match.
+ */
+function resolveNode(span, mapping, nodes) {
+    if (mapping) {
+        const direct = mapping.spanMap.get(span.name);
+        if (direct)
+            return direct;
+        if (span.serviceName) {
+            const svc = mapping.serviceMap.get(span.serviceName);
+            if (svc)
+                return svc;
+        }
+    }
+    // Heuristic: try matching span.name first (it's most specific — for
+    // CLIENT/PRODUCER spans it names the *downstream* target, which is the
+    // node we want), then fall back to service.name.
+    const candidates = [];
+    candidates.push(span.name.toLowerCase());
+    if (span.serviceName)
+        candidates.push(span.serviceName.toLowerCase());
+    for (const c of candidates) {
+        // 1. exact id match
+        const idHit = nodes.find((n) => n.id.toLowerCase() === c);
+        if (idHit)
+            return idHit.id;
+        // 2. node id appears as a token inside the candidate
+        //    (e.g. "todo-store update" → finds id "todo-store")
+        const idInCandidate = nodes.find((n) => c.includes(n.id.toLowerCase()));
+        if (idInCandidate)
+            return idInCandidate.id;
+        // 3. candidate appears in a node label
+        //    (e.g. "todo-api" → finds label "Todo API")
+        const labelHit = nodes.find((n) => n.label.toLowerCase().includes(c));
+        if (labelHit)
+            return labelHit.id;
+        // 4. code-ref path includes the candidate
+        const refHit = nodes.find((n) => (n.code_refs ?? []).some((r) => r.path.toLowerCase().includes(c)));
+        if (refHit)
+            return refHit.id;
+    }
+    return null;
+}
+function eventIdFor(spanId, existingIds) {
+    // Stable: take the first 8 hex chars of the span id, prefix with "ev".
+    // Fall back to a sequence if collision (shouldn't happen in practice).
+    const base = `ev-${spanId.slice(0, 8) || "span"}`.toLowerCase();
+    if (!existingIds.has(base))
+        return base;
+    let i = 2;
+    while (existingIds.has(`${base}-${i}`))
+        i++;
+    return `${base}-${i}`;
+}
+export async function runImportTrace(args) {
+    // 1. Locate the .loom/ root and load the diagram we're overlaying.
+    const loomRoot = await findLoomRoot(args.root);
+    const diagram = await readDiagram(loomRoot.loomPath, args.diagramId);
+    // 2. Load and parse the trace.
+    const traceRaw = await readFile(resolve(args.trace), "utf8");
+    const traceJson = JSON.parse(traceRaw);
+    const spans = parseOtlpJson(traceJson);
+    if (spans.length === 0) {
+        console.error("Trace contained 0 spans — nothing to import.");
+        process.exit(1);
+    }
+    // 3. Optional mapping file.
+    const mapping = args.map ? await loadMapping(resolve(args.map)) : null;
+    // 4. Compute t=0 (earliest span start) so the timeline is repo-portable.
+    const minStartNs = spans.reduce((m, s) => (s.startNs < m ? s.startNs : m), spans[0].startNs);
+    // 5. If appending, load existing timeline; otherwise start fresh.
+    let existing = null;
+    if (args.append) {
+        try {
+            existing = await readTimeline(loomRoot.loomPath, args.asId);
+            if (existing.diagram !== args.diagramId) {
+                console.error(`Refusing to append: existing timeline '${args.asId}' references diagram ` +
+                    `'${existing.diagram}', not '${args.diagramId}'.`);
+                process.exit(1);
+            }
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+            // Fall through: --append on a missing file behaves like create.
+        }
+    }
+    const existingIds = new Set(existing?.events.map((e) => e.id) ?? []);
+    const spanIdToEventId = new Map();
+    const events = [];
+    const skipped = [];
+    // 6. First pass: pick node + event id for each span.
+    for (const s of spans) {
+        const node = resolveNode(s, mapping, diagram.nodes);
+        if (!node) {
+            skipped.push({ span: s, reason: "no matching node" });
+            continue;
+        }
+        const id = eventIdFor(s.spanId, existingIds);
+        existingIds.add(id);
+        spanIdToEventId.set(s.spanId, id);
+        const start_ms = Number((s.startNs - minStartNs) / 1000000n);
+        const duration_ms = Number((s.endNs - s.startNs) / 1000000n);
+        events.push({
+            id,
+            node,
+            start_ms: Math.max(0, start_ms),
+            duration_ms: Math.max(0, duration_ms),
+            label: s.name.length > 60 ? s.name.slice(0, 57) + "…" : s.name,
+            kind: KIND_TO_EVENT_KIND[s.kind] ?? "compute",
+            track: s.serviceName ?? undefined,
+            tags: [`otel-import`, `kind:${s.kind}`],
+        });
+    }
+    // 7. Second pass: wire triggered_by from span parent.
+    for (let i = 0; i < spans.length; i++) {
+        const s = spans[i];
+        const ev = events.find((e) => e.id === spanIdToEventId.get(s.spanId));
+        if (!ev)
+            continue;
+        if (s.parentSpanId) {
+            const parentEventId = spanIdToEventId.get(s.parentSpanId);
+            if (parentEventId)
+                ev.triggered_by = parentEventId;
+        }
+    }
+    // 8. Build the timeline. Auto-derive tracks from distinct services.
+    const trackIds = new Set((existing?.tracks?.map((t) => t.id) ?? []).concat(events.map((e) => e.track).filter((t) => !!t)));
+    const tracks = Array.from(trackIds).map((id) => ({ id, label: id }));
+    const timeline = {
+        version: "1",
+        id: args.asId,
+        title: existing?.title ?? `Imported: ${args.asId}`,
+        description: existing?.description ??
+            `Generated by 'loom-spec import-trace' from ${args.trace}.`,
+        diagram: args.diagramId,
+        events: existing ? [...existing.events, ...events] : events,
+        tracks,
+    };
+    // 9. Validate before writing.
+    const v = await validateTimeline(timeline);
+    if (!v.ok) {
+        console.error("Generated timeline failed schema validation:");
+        for (const e of v.errors)
+            console.error(`  - ${e}`);
+        process.exit(1);
+    }
+    await writeTimeline(loomRoot.loomPath, args.asId, timeline);
+    // 10. Report.
+    console.log(`Wrote ${events.length} event${events.length === 1 ? "" : "s"} to ` +
+        `${loomRoot.loomPath}/timelines/${args.asId}.timeline.json` +
+        (existing ? ` (appended; total ${timeline.events.length})` : ""));
+    if (skipped.length > 0) {
+        console.log(`Skipped ${skipped.length} span${skipped.length === 1 ? "" : "s"} ` +
+            `with no matching node. Pass --map mapping.json to override.`);
+        const sample = skipped.slice(0, 5);
+        for (const { span, reason } of sample) {
+            console.log(`  • ${span.name}  (service=${span.serviceName ?? "—"})  ${reason}`);
+        }
+        if (skipped.length > sample.length) {
+            console.log(`  … and ${skipped.length - sample.length} more.`);
+        }
+    }
+}
+//# sourceMappingURL=importTrace.js.map

package/dist/cli/importTrace.js.map

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

package/dist/cli/index.js

@@ -4,6 +4,8 @@ import { runView } from "./view.js";
 import { runValidate } from "./validate.js";
 import { runMcp } from "./mcp.js";
 import { runInstallMcp } from "./installMcp.js";
+import { runImportTrace } from "./importTrace.js";
+import { runExportHtml, DEFAULT_OUT as EXPORT_DEFAULT_OUT } from "./exportHtml.js";
 const HELP = `loom-spec — node-based architecture spec for your repo
 
 Usage:
@@ -27,17 +29,42 @@ Usage:
       pre-commit hook.
 
   loom-spec mcp [--root <dir>]
-      Start a Model Context Protocol server on stdio. Exposes
-      loom_list_diagrams, loom_read_diagram, loom_add_node,
-      loom_update_node, loom_mark_stale, loom_delete_node,
-      loom_add_edge, loom_delete_edge, loom_validate as MCP tools.
-      Wire it into Claude Code's mcp.json (or any MCP-capable client).
+      Start a Model Context Protocol server on stdio. Exposes 15 tools
+      for diagrams (loom_list_diagrams, loom_add_node, loom_add_edge, …)
+      and timelines (loom_list_timelines, loom_add_event, …) — wire it
+      into Claude Code's mcp.json (or any MCP-capable client).
+
+  loom-spec export-html [<bundle-name>] [--out <path>] [--diagram <id>]
+                        [--no-timelines]
+                        [--include-tag <comma-list>] [--exclude-tag <comma-list>]
+                        [--root <dir>]
+      Build a standalone interactive HTML file from the spec — pan/zoom,
+      drill-down, switch diagrams, play timelines. Single self-contained
+      file, no server needed. Drop it into a manual, wiki, GitHub Pages
+      site, anywhere. Output defaults to ./loom.html. With --diagram, only
+      that diagram (and timelines referencing it) ship. With
+      --include-tag / --exclude-tag, only nodes whose 'tags' match
+      survive — edges, groups, drill-down chevrons, timeline events that
+      point at dropped nodes are cleaned up automatically.
+
+      Pass a <bundle-name> as the first positional arg to read settings
+      from a named bundle in .loom/exports.json. Explicit flags override
+      the bundle's values.
+
+  loom-spec import-trace <trace.json> --as <timeline-id> --diagram <diagram-id>
+                        [--map <mapping.json>] [--append] [--root <dir>]
+      Read an OpenTelemetry OTLP-JSON trace and generate a timeline that
+      mirrors the actual spans on the named diagram. Each span becomes
+      an event; parent/child relationships preserve as triggered_by;
+      service.name becomes the track. Spans whose service or name can't
+      be matched to a node are skipped — pass --map to override.
 
   loom-spec --help
       Print this help.
 `;
 function parseFlags(argv) {
     const flags = {};
+    const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (!a)
@@ -53,12 +80,15 @@ function parseFlags(argv) {
                 flags[key] = true;
             }
         }
+        else {
+            positional.push(a);
+        }
     }
-    return flags;
+    return { flags, positional };
 }
 async function main() {
     const [, , subcommand, ...rest] = process.argv;
-    const flags = parseFlags(rest);
+    const { flags, positional } = parseFlags(rest);
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
         console.log(HELP);
         return;
@@ -98,6 +128,50 @@ async function main() {
         });
         return;
     }
+    if (subcommand === "export-html") {
+        const splitTags = (v) => {
+            if (typeof v !== "string" || !v.trim())
+                return undefined;
+            return v.split(",").map((s) => s.trim()).filter(Boolean);
+        };
+        // First positional arg, if any, is a named-bundle key from
+        // .loom/exports.json (e.g. `loom-spec export-html user-manual`).
+        const bundle = positional[0];
+        await runExportHtml({
+            out: flags.out ?? EXPORT_DEFAULT_OUT,
+            root: flags.root ?? process.cwd(),
+            diagram: typeof flags.diagram === "string" ? flags.diagram : undefined,
+            noTimelines: Boolean(flags["no-timelines"]),
+            includeTags: splitTags(flags["include-tag"]),
+            excludeTags: splitTags(flags["exclude-tag"]),
+            bundle,
+        });
+        return;
+    }
+    if (subcommand === "import-trace") {
+        // Positional arg: the trace file path.
+        const trace = positional[0];
+        if (!trace) {
+            console.error("import-trace: missing trace file path");
+            console.log(HELP);
+            process.exit(1);
+        }
+        const asId = flags.as;
+        const diagramId = flags.diagram;
+        if (!asId || !diagramId) {
+            console.error("import-trace: --as <timeline-id> and --diagram <diagram-id> are required");
+            process.exit(1);
+        }
+        await runImportTrace({
+            trace,
+            asId,
+            diagramId,
+            map: typeof flags.map === "string" ? flags.map : undefined,
+            append: Boolean(flags.append),
+            root: flags.root ?? process.cwd(),
+        });
+        return;
+    }
     console.error(`unknown subcommand: ${subcommand}\n`);
     console.log(HELP);
     process.exit(1);

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BZ,CAAC;AAEF,SAAS,UAAU,CAAC,IAAc;IAChC,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACzB,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBAClB,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAE,AAAD,EAAG,UAAU,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAE/B,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,OAAO,CAAC;YACZ,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;YAC7C,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;YAC3B,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;SACxB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QACjC,MAAM,aAAa,CAAC;YAClB,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;SAC9C,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,OAAO,CAAC;YACZ,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;YAC7C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;YAC5C,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;SACxB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9B,MAAM,WAAW,CAAC;YAChB,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;YAC7C,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,CAAC;YACX,IAAI,EAAG,KAAK,CAAC,IAAe,IAAI,OAAO,CAAC,GAAG,EAAE;SAC9C,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,uBAAuB,UAAU,IAAI,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/server/exportConfig.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Optional `.loom/exports.json` config — defines named export bundles so
+ * teams can keep export settings versioned in the repo instead of in shell
+ * commands. A new contributor runs `loom-spec export-html user-manual`
+ * and gets the same output as everyone else without having to remember
+ * which flags to pass.
+ *
+ * Shape:
+ *
+ *   {
+ *     "exports": {
+ *       "user-manual": {
+ *         "include-tags": ["public"],
+ *         "exclude-tags": ["wip"],
+ *         "diagram": "overview",       // optional, single-diagram mode
+ *         "no-timelines": true,        // default false
+ *         "out": "docs/architecture.html"  // optional, default loom.html
+ *       },
+ *       "ops-runbook": {
+ *         "include-tags": ["ops"]
+ *       }
+ *     }
+ *   }
+ *
+ * All fields are optional. Unknown keys are tolerated (forward-compat).
+ * CLI flags override config values when both are present.
+ */
+export interface NamedExport {
+    includeTags?: string[];
+    excludeTags?: string[];
+    diagram?: string;
+    noTimelines?: boolean;
+    out?: string;
+}
+export interface ExportsFile {
+    exports: Record<string, NamedExport>;
+}
+/**
+ * Try to read `.loom/exports.json`. Returns null when the file is missing
+ * (that's a normal, non-error state — exports config is opt-in).
+ */
+export declare function loadExportsConfig(loomPath: string): Promise<ExportsFile | null>;