@itsthecsguy/linework 0.1.4 → 0.2.1

package/README.md

@@ -159,6 +159,8 @@ Linework sizes every box from the real width of its text in the font it renders
 
 Linework needs Node 20+ and a Chromium-based browser, which it uses headless to measure text and render. It tries Playwright's Chromium, then Chrome, then Edge. If none is found, run `linework install-browser`, or set `LINEWORK_CHROME` to a browser binary. If a browser is found but crashes on launch, an agent's sandbox is usually blocking it. Linework then retries Playwright's Chromium in single-process mode, which starts inside Codex's sandbox.
 
+The first drawing command starts a background process that keeps Chromium running, and later commands hand their work to it. A build of the checkout example takes about 1.0s the first time and 0.16s after that. The process listens on a Unix socket in a folder only you can open, exits after 5 idle minutes, and is off on Windows and in CI. `LINEWORK_NO_DAEMON=1` or `--no-daemon` turns it off, and `linework daemon stop` ends it.
+
 Linework keeps the font subsets it embeds in your cache folder (`~/Library/Caches/linework` on macOS, `~/.cache/linework` on Linux, `%LOCALAPPDATA%\linework` on Windows), so rebuilding a diagram doesn't compress the same fonts again. Set `LINEWORK_NO_CACHE=1` to turn that off.
 
 ## Connect over MCP
@@ -202,6 +204,20 @@ npx -y @itsthecsguy/linework skill install .claude/skills   # Claude Code
 npx -y @itsthecsguy/linework skill install .grok/skills     # Grok Build
 ```
 
+## Small changes
+
+Once a diagram exists, a change to it keeps everything else where it is. That holds whether a person arranged the layout in draw.io or nobody has touched it.
+
+```bash
+linework set docs/checkout.drawio.svg api.label="Checkout API v2" api.highlight=true
+linework add docs/checkout.drawio.svg "fraud: { label: Fraud check, in: vpc }" "api -> fraud: score"
+linework rm  docs/checkout.drawio.svg cache "api -> stripe"
+```
+
+A renamed box grows in place. A new box goes next to the one it connects to, and its group grows to hold it without covering boxes outside the group. A removed box takes its edges with it, and its group closes up. `linework build` with an edited spec follows the same rules. It lays out from scratch only for a new file, a changed direction or theme on a layout nobody arranged, or `--relayout`.
+
+After dragging boxes around in draw.io, `linework tidy <file>` reroutes the edges left behind and moves labels off whatever they landed on. Boxes stay where you put them.
+
 ## Editing by hand
 
 Any draw.io editor works on these files: draw.io desktop, VS Code with the Draw.io Integration extension, or app.diagrams.net. Or:
@@ -221,11 +237,14 @@ Docs can't hold an SVG, so the diagram lives in Google Drive and draw.io's Googl
 | command | does |
 |---|---|
 | `linework build <spec\|-> -o out.drawio.svg [--png p.png] [--relayout]` | layout (or merge into an existing file), write, lint |
+| `linework set <file> id.field=value...` | change a label, kind, color, theme or title in place |
+| `linework add <file> "id: {...}" "a -> b: label"...` | add boxes, groups and edges in place |
+| `linework rm <file> id "a -> b"...` | remove boxes, groups and edges in place |
 | `linework show <file> [--geometry]` | print the spec of a diagram, including hand edits |
 | `linework edit <file> [--no-open]` | edit in the bundled draw.io, in your browser; saves write the file |
 | `linework check <file>` | lint: overlaps, edges through nodes, labels that don't fit, too wide |
 | `linework render <file> -o out.png [--scale 2]` | preview image |
-| `linework tidy <file>` | reroute edges that pass through nodes, change nothing else |
+| `linework tidy <file>` | after hand edits: reroute stale edges and move colliding labels; boxes stay |
 | `linework import <file.mmd\|doc.md> [-o out.drawio.svg]` | convert a Mermaid diagram |
 | `linework publish <file...> [--to dir] [--pull]` | copy diagrams into Google Drive for the Docs add-on |
 | `linework icons <aws\|gcp\|k8s\|azure> [filter]` | list icon names |
@@ -234,11 +253,12 @@ Docs can't hold an SVG, so the diagram lives in Google Drive and draw.io's Googl
 | `linework mcp [--root dir]` | MCP server over stdio |
 | `linework kinds [type]` | node kinds per diagram type |
 | `linework schema` | JSON Schema of the spec |
+| `linework daemon [status\|stop]` | the background process that keeps the browser running between builds |
 | `linework install-browser` | download the headless Chromium build this version uses |
 
 ## Status
 
-All four phases of [PLAN.md](PLAN.md) are built. Two paths haven't been tried yet, because they need a real account or app: the Google Docs add-on round trip, and saving from the VS Code Draw.io Integration extension. Both use the same file format and protocol that the tests cover with draw.io's own editor.
+All five phases of [PLAN.md](PLAN.md) are built. Two paths haven't been tried yet, because they need a real account or app: the Google Docs add-on round trip, and saving from the VS Code Draw.io Integration extension. Both use the same file format and protocol that the tests cover with draw.io's own editor.
 
 ## Development
 
@@ -249,4 +269,20 @@ npm run build        # compile to dist/
 npm run dev -- build examples/checkout.yaml -o out/checkout.drawio.svg --png out/checkout.png
 ```
 
+Every push to `main` and every pull request runs the typecheck and the tests on Node 22 and 24 in GitHub Actions. To run the suite with a browser that isn't in one of the usual places, set `LINEWORK_CHROME=/path/to/chromium`.
+
+After a change to layout or rendering, rebuild the README gallery and look at what moved:
+
+```bash
+npm run build && node docs/gallery/build.mjs
+```
+
+### Releasing
+
+```bash
+npm run release            # patch; or: npm run release -- minor | major | 1.2.3
+```
+
+That bumps the version, commits it as `Release x.y.z`, tags `vx.y.z` and pushes both. The tag starts the release workflow, which runs the tests again, publishes to npm and opens a GitHub release with generated notes. Nobody logs in to npm: the workflow publishes through npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers), which is set up once in the package's settings on npmjs.com (GitHub Actions, repository `itsthecsguy/linework`, workflow `release.yml`).
+
 `assets/drawio` holds the parts of the draw.io web app that linework runs: the renderer it uses headless, and the editor behind `linework edit`. draw.io is Apache-2.0; see [NOTICE](NOTICE). To update it, check out a jgraph/drawio tag in `vendor/drawio` and run `npm run assets`.

package/dist/api.js

@@ -36,8 +36,13 @@ export async function build(specText, opts) {
         }
     }
     const edits = old ? manualEdits(old) : [];
-    // Once a person has touched the layout, every later build merges into it.
-    const mode = old && !opts.relayout && (old.meta.aiviz_layout === 'manual' || edits.length > 0) ? 'merge' : 'fresh';
+    // Once a person has touched the layout, every later build merges into it. A
+    // layout nobody touched is also kept when the spec changed a little: a renamed
+    // label or one new box shouldn't move the rest.
+    const touched = !!old && (old.meta.aiviz_layout === 'manual' || edits.length > 0);
+    let mode = 'fresh';
+    if (old && !opts.relayout)
+        mode = touched || opts.keepLayout || smallChange(old, diagram) ? 'merge' : 'fresh';
     return withBrowser(opts.browser, async (b) => {
         const measure = (r) => b.measure(r);
         for (const n of diagram.nodes) {
@@ -82,26 +87,45 @@ export async function build(specText, opts) {
         const l = await layout(diagram, measure);
         let xml;
         let stats;
+        let freshXml;
         if (mode === 'merge') {
-            const m = merge(diagram, old, l, { specIsCurrent: specBase(specText) === fingerprint(old) });
+            const m = merge(diagram, old, l, { specIsCurrent: specBase(specText) === fingerprint(old), touched });
             stats = m.stats;
             xml = serialize(m.scene);
             if (m.reroute.length)
                 xml = await rerouteInto(b, xml, m.reroute);
             // Kept routes can already be broken, e.g. stale waypoints after someone moved a node.
-            const broken = brokenEdges(check(await b.inspect(xml)));
+            const after = check(await b.inspect(xml));
+            const broken = brokenEdges(after);
             if (broken.length) {
                 xml = await rerouteInto(b, xml, broken);
                 stats.rerouted += broken.filter((id) => !m.reroute.includes(id)).length;
             }
+            // Nobody arranged this layout, so there is nothing to protect: when the
+            // change doesn't fit into it cleanly, lay it out again.
+            if (!touched && !opts.keepLayout) {
+                const merged = check(await b.inspect(xml));
+                const bad = (c) => c.findings.filter((f) => f.level === 'error').length;
+                let redo = bad(merged) > 0;
+                if (!redo && (stats.placed.length || merged.stats.crossings)) {
+                    freshXml = await straightenDetours(b, toMxfile(diagram, l), detourEdges(diagram, l));
+                    redo = merged.stats.crossings > check(await b.inspect(freshXml)).stats.crossings + 1;
+                }
+                if (redo) {
+                    mode = 'fresh';
+                    stats = undefined;
+                }
+            }
         }
+        if (mode === 'fresh')
+            xml = freshXml ?? (await straightenDetours(b, toMxfile(diagram, l), detourEdges(diagram, l)));
         else
-            xml = await straightenDetours(b, toMxfile(diagram, l), detourEdges(diagram, l));
+            xml = xml;
         const fixed = await fixLabels(b, xml);
         xml = fixed.xml;
         xml = stampEdgeRoutes(xml);
         // Stamping routes changes attributes, not geometry: the cells fixLabels read still hold.
-        return finish(b, xml, { mode, warnings, direction: mode === 'merge' ? (old.meta.aiviz_direction ?? l.direction) : l.direction, edits, old, stats, cells: fixed.cells });
+        return finish(b, xml, { mode, warnings, direction: mode === 'merge' ? (old.meta.aiviz_direction ?? l.direction) : l.direction, edits, old, stats, cells: fixed.cells, labelsMoved: fixed.moved });
     });
     async function finish(b, xml, r) {
         fs.mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true });
@@ -116,10 +140,33 @@ export async function build(specText, opts) {
             direction: r.direction,
             mode: r.mode,
             merge: r.stats,
+            labelsMoved: r.labelsMoved ?? 0,
             discardedLayout: !!(opts.relayout && r.old && (r.old.meta.aiviz_layout === 'manual' || r.edits.length > 0)),
         };
     }
 }
+/**
+ * Whether the new spec is close enough to an untouched file to keep its layout:
+ * same type, direction and theme, and only a few new boxes. Sequence diagrams
+ * always lay out again; their rows follow message order either way.
+ */
+function smallChange(old, d) {
+    if (d.type === 'sequence')
+        return false;
+    let prev;
+    try {
+        prev = toDiagram(old).diagram;
+    }
+    catch {
+        return false;
+    }
+    if (prev.type !== d.type || prev.direction !== d.direction || prev.theme !== d.theme)
+        return false;
+    const had = new Set(prev.nodes.map((n) => n.id));
+    const added = d.nodes.filter((n) => !had.has(n.id)).length;
+    const kept = d.nodes.length - added;
+    return kept > 0 && added <= Math.max(2, Math.ceil(d.nodes.length / 4));
+}
 /**
  * Edges whose route is far longer than the gap between their ends. Layered layout
  * draws one edge of every cycle backwards, so the reply in a call-and-callback pair
@@ -160,17 +207,27 @@ async function straightenDetours(b, xml, ids) {
 async function rerouteInto(b, xml, edgeIds) {
     return patchEdges(xml, await b.reroute(xml, edgeIds), edgeIds);
 }
-/** Reroute only the edges check flags as broken. Nothing else changes. */
+/**
+ * Repair a diagram after hand edits: reroute edges that are broken or were left
+ * behind when someone moved a box, and move labels off whatever they landed on.
+ * Boxes, groups and routes a person drew stay where they are.
+ */
 export async function tidy(file, browser) {
     const text = fs.readFileSync(file, 'utf8');
     const m = readDrawio(text);
+    if (m.meta.aiviz_type && m.meta.aiviz_type !== 'sequence') {
+        // The file's own spec merged into itself: positions stay, hand moves become
+        // part of the layout, and only stale routes and colliding labels change.
+        const res = await build(show(file).yaml, { out: file, keepLayout: true, browser });
+        return { fixed: res.merge?.rerouted ?? 0, labels: res.labelsMoved, check: res.check };
+    }
     return withBrowser(browser, async (b) => {
         const broken = brokenEdges(check(await b.inspect(m.xml)));
         if (!broken.length)
-            return { fixed: 0, check: check(await b.inspect(m.xml)) };
+            return { fixed: 0, labels: 0, check: check(await b.inspect(m.xml)) };
         const xml = stampEdgeRoutes(await rerouteInto(b, m.xml, broken));
         fs.writeFileSync(file, file.endsWith('.svg') ? await b.renderSvg(xml) : xml);
-        return { fixed: broken.length, check: check(await b.inspect(xml)) };
+        return { fixed: broken.length, labels: 0, check: check(await b.inspect(xml)) };
     });
 }
 export function show(file, opts = {}) {

package/dist/cli.js

@@ -1,320 +1,87 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
 import module from 'node:module';
-import path from 'node:path';
 import { parseArgs } from 'node:util';
-const USAGE = `linework: AI-written, hand-editable diagrams (YAML spec -> .drawio.svg)
-
-Usage:
-  linework build <spec.yaml|-> -o <out.drawio.svg> [--png preview.png] [--relayout]
-      Lay out and write the diagram, then lint it. "-" reads the spec from stdin.
-      If the file exists and someone edited it by hand, the spec is merged in:
-      existing positions stay, new nodes are placed next to their neighbours.
-      --relayout throws the existing layout away (hand edits included).
-  linework show <file.drawio.svg> [--geometry]
-      Print the spec of an existing diagram (including hand edits) as YAML.
-      --geometry appends node positions as comments.
-  linework render <file.drawio.svg> -o <out.png|out.svg> [--scale 2]
-      Render a preview image.
-  linework check <file.drawio.svg>
-      Lint layout: overlaps, edges through nodes, labels that don't fit.
-  linework tidy <file.drawio.svg>
-      Reroute edges that check flags as broken (e.g. after moving nodes by hand).
-      Nothing else in the file changes.
-  linework edit <file.drawio.svg> [--no-open] [--port N]
-      Open the diagram in draw.io (bundled, offline) in your browser. Saving in
-      the editor writes the file. Stops when you exit the editor or close the tab.
-  linework import <file.mmd|doc.md|-> [--block N] [-o out.drawio.svg] [--png p.png]
-      Convert a Mermaid diagram (flowchart, state, sequence, ER) to an linework spec.
-      Prints the spec, or builds it straight away with -o.
-  linework icons <aws|gcp|k8s|azure> [filter]
-      List icon names, for "icon: aws.lambda" on architecture nodes.
-  linework publish <file.drawio.svg...> [--to DIR] [--pull] [--force]
-      Copy diagrams into your Google Drive folder (Google Drive for desktop) so
-      draw.io's Google Docs add-on can insert them and refresh them later.
-      --pull copies back a diagram someone edited from Docs or Drive.
-  linework skill [install <dir>]
-      Print where the bundled agent skill is, or copy it to <dir>/linework
-      (e.g. .claude/skills, ~/.agents/skills).
-  linework mcp [--root DIR]
-      Run as an MCP server over stdio, for chat apps and agents without a shell.
-      Relative paths resolve against --root (default: the current folder).
-  linework git-setup
-      Make git diff show .drawio.svg changes as spec changes (this repo only).
-  linework kinds [architecture|flow|state]
-      List node kinds for each diagram type.
-  linework schema
-      Print the spec's JSON Schema.
-
-  linework install-browser
-      Download the headless Chromium build that matches this version. Needed only
-      when no Chrome or Edge is installed, or to run inside an agent's sandbox.
-`;
 // Node 22.1+ can keep compiled bytecode for linework's modules on disk, which
 // takes about a quarter off loading them on every run after the first. Older
 // Node has no such call. NODE_DISABLE_COMPILE_CACHE=1 turns it off.
 module.enableCompileCache?.();
 async function main(argv) {
+    const { OPTIONS, USAGE, needsBrowser, run, report, processIO } = await import('./commands.js');
     const [cmd, ...rest] = argv;
-    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: OPTIONS });
+    if (cmd === 'daemon')
+        return daemon(rest[0]);
+    let parsed;
+    try {
+        parsed = parseArgs({ args: rest, allowPositionals: true, options: OPTIONS });
+    }
+    catch (e) {
+        process.exitCode = report(e);
+        return;
+    }
+    const { values, positionals } = parsed;
     if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h' || values.help)
         return void process.stdout.write(USAGE);
+    const draws = needsBrowser(cmd, values);
+    // A custom render scale needs its own page, so that one runs here.
+    const shareable = draws && !(cmd === 'render' && values.scale) && !values['no-daemon'];
+    if (shareable) {
+        // Chromium, draw.io and ELK may already be warm in the background process.
+        const { viaDaemon } = await import('./daemon.js');
+        const stdin = positionals[0] === '-' && (cmd === 'build' || cmd === 'import') ? processIO.stdin() : undefined;
+        const code = await viaDaemon({ argv, cwd: process.cwd(), stdin }, processIO.out, processIO.err);
+        if (code !== undefined)
+            return exitWhenFlushed(code);
+        if (stdin !== undefined)
+            processIO.stdin = () => stdin;
+    }
     // Commands that draw start Chromium first and load the rest of linework while it
     // boots and loads draw.io: the two take about the same time, so they overlap.
-    const needsBrowser = ['build', 'render', 'check', 'tidy', 'icons'].includes(cmd) || (cmd === 'import' && !!values.out);
-    const launching = needsBrowser ? import('./render/browser.js').then((m) => m.DrawioBrowser.launch({ scale: cmd === 'render' && values.scale ? Number(values.scale) : 2 })) : undefined;
+    const launching = draws ? import('./render/browser.js').then((m) => m.DrawioBrowser.launch({ scale: cmd === 'render' && values.scale ? Number(values.scale) : 2 })) : undefined;
     // A failure here surfaces where the browser is awaited; don't report it twice.
     launching?.catch(() => { });
+    let failed = false;
     try {
         await run(cmd, values, positionals, launching);
     }
+    catch (e) {
+        failed = true;
+        process.exitCode = report(e);
+    }
     finally {
         if (launching)
             await (await launching.catch(() => undefined))?.close();
     }
+    // The next drawing command finds the browser already running.
+    if (shareable && !failed)
+        (await import('./daemon.js')).startDaemon();
     // The font subsetter's WebAssembly keeps node alive for ~100ms after the work
     // is done, with nothing left to run. A drawing command is finished here.
     if (launching)
-        await exitWhenFlushed();
+        await exitWhenFlushed(Number(process.exitCode ?? 0));
 }
-/** A small spec with a group, labels and a cycle: enough to exercise ELK's main paths. */
-const WARM_SPEC = 'type: architecture\ngroups: { g: G }\nnodes:\n  a: { in: g }\n  b: { in: g }\n  c: {}\nedges:\n  - a -> b: x\n  - b -> c: y\n  - c -> a\n';
-async function warmUp() {
-    const [{ parseSpecText }, { layout }] = await Promise.all([import('./spec/parse.js'), import('./layout/layout.js')]);
-    await layout(parseSpecText(WARM_SPEC).diagram);
+async function daemon(sub) {
+    const d = await import('./daemon.js');
+    if (sub === 'run')
+        return d.serve();
+    if (sub === 'stop')
+        return void console.log((await d.stopDaemon()) ? 'stopped' : 'not running');
+    if (sub === 'status' || !sub) {
+        const sock = d.daemonAllowed() ? d.socketPath() : undefined;
+        const fs = await import('node:fs');
+        return void console.log(!sock ? 'off (LINEWORK_NO_DAEMON, CI or Windows)' : fs.existsSync(sock) ? `running at ${sock}` : 'not running; the next build starts it');
+    }
+    console.error('usage: linework daemon [status|stop]');
+    process.exitCode = 2;
 }
-function exitWhenFlushed() {
+function exitWhenFlushed(code) {
     return new Promise(() => {
         let pending = 2;
-        const done = () => --pending === 0 && process.exit();
+        const done = () => --pending === 0 && process.exit(code);
         process.stdout.write('', done);
         process.stderr.write('', done);
     });
 }
-const OPTIONS = {
-    out: { type: 'string', short: 'o' },
-    png: { type: 'string' },
-    force: { type: 'boolean', default: false },
-    relayout: { type: 'boolean', default: false },
-    geometry: { type: 'boolean', default: false },
-    quiet: { type: 'boolean', short: 'q', default: false },
-    block: { type: 'string' },
-    scale: { type: 'string' },
-    'no-open': { type: 'boolean', default: false },
-    port: { type: 'string' },
-    root: { type: 'string' },
-    to: { type: 'string' },
-    pull: { type: 'boolean', default: false },
-    help: { type: 'boolean', short: 'h' },
-};
-async function run(cmd, values, positionals, launching) {
-    const browser = async () => {
-        // ELK compiles its code on first use. Laying out a tiny graph while Chromium
-        // is still starting takes that cost off the real layout.
-        if (launching && ['build', 'import'].includes(cmd))
-            await warmUp();
-        return launching;
-    };
-    const { buildLines } = await import('./report.js');
-    switch (cmd) {
-        case 'build': {
-            const src = positionals[0];
-            if (!src || !values.out)
-                fail('usage: linework build <spec.yaml|-> -o <out.drawio.svg>');
-            const text = src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
-            const { build } = await import('./api.js');
-            // Spec errors first: they shouldn't wait on, or hide behind, a browser problem.
-            (await import('./spec/parse.js')).parseSpecText(text);
-            const res = await build(text, { out: values.out, png: values.png, force: values.force, relayout: values.relayout, browser: await browser() });
-            for (const line of buildLines(res, values.png))
-                console.log(line);
-            return;
-        }
-        case 'show': {
-            const file = positionals[0] ?? fail('usage: linework show <file.drawio.svg>');
-            const { show } = await import('./api.js');
-            const res = show(file, { geometry: values.geometry });
-            process.stdout.write(res.yaml);
-            if (values.quiet)
-                return;
-            for (const n of res.notes)
-                console.error(`note: ${n}`);
-            if (res.edits.length) {
-                const moved = res.edits.filter((e) => e.what !== 'added').length;
-                const added = res.edits.filter((e) => e.what === 'added').length;
-                console.error(`note: edited by hand since the last build (${moved} moved/resized, ${added} added). build keeps those positions and merges your changes in.`);
-            }
-            return;
-        }
-        case 'render': {
-            const file = positionals[0];
-            if (!file || !values.out)
-                fail('usage: linework render <file.drawio.svg> -o <out.png>');
-            const { render } = await import('./api.js');
-            await render(file, values.out, await browser());
-            console.log(`wrote ${values.out}`);
-            return;
-        }
-        case 'check': {
-            const file = positionals[0] ?? fail('usage: linework check <file.drawio.svg>');
-            const { checkFile } = await import('./api.js');
-            const res = await checkFile(file, await browser());
-            await printCheck(res);
-            if (res.findings.some((f) => f.level === 'error'))
-                process.exitCode = 1;
-            return;
-        }
-        case 'tidy': {
-            const file = positionals[0] ?? fail('usage: linework tidy <file.drawio.svg>');
-            const { tidy } = await import('./api.js');
-            const res = await tidy(file, await browser());
-            console.log(res.fixed ? `rerouted ${res.fixed} edges in ${file}` : 'nothing to fix');
-            await printCheck(res.check);
-            return;
-        }
-        case 'edit': {
-            const file = positionals[0] ?? fail('usage: linework edit <file.drawio.svg>');
-            const { startEditor, openInBrowser } = await import('./edit/server.js');
-            const session = await startEditor(file, { port: values.port ? Number(values.port) : undefined });
-            const opened = !values['no-open'] && openInBrowser(session.url);
-            console.log(`${opened ? 'opened' : 'open'} ${session.url}`);
-            console.log(`editing ${file}. Save in the editor (Ctrl/Cmd+S) to write the file. Exit the editor, close the tab or press Ctrl+C to stop.`);
-            process.once('SIGINT', () => void session.close());
-            const res = await session.done;
-            console.log(res.saves ? `saved ${file} ${res.saves - res.conflicts.length} time(s)` : 'closed without saving');
-            for (const c of res.conflicts)
-                console.log(`note: ${file} changed on disk while it was open, so one save went to ${c}`);
-            return;
-        }
-        case 'import': {
-            const src = positionals[0] ?? fail('usage: linework import <file.mmd|doc.md|-> [-o out.drawio.svg]');
-            const { importMermaid, mermaidBlocks } = await import('./import/mermaid.js');
-            const { toYaml } = await import('./drawio/show.js');
-            let text = src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
-            if (/\.(md|markdown|mdx)$/i.test(src)) {
-                const blocks = mermaidBlocks(text);
-                if (!blocks.length)
-                    fail(`${src} has no \`\`\`mermaid blocks`);
-                const n = values.block ? Number(values.block) : blocks.length === 1 ? 1 : 0;
-                if (!n || !blocks[n - 1]) {
-                    const first = blocks.map((b, i) => `  ${i + 1}: ${b.split('\n')[0]}`).join('\n');
-                    fail(`${src} has ${blocks.length} mermaid blocks; pick one with --block N:\n${first}`);
-                }
-                text = blocks[n - 1];
-            }
-            const res = importMermaid(text);
-            for (const w of res.warnings)
-                console.error(`import: ${w}`);
-            const yaml = toYaml(res.diagram, 'imported from Mermaid');
-            if (!values.out)
-                return void process.stdout.write(yaml);
-            const { build } = await import('./api.js');
-            const built = await build(yaml, { out: values.out, png: values.png, relayout: values.relayout, force: values.force, browser: await browser() });
-            console.log(`wrote ${built.out} (${built.check.stats.nodes} nodes, ${built.check.stats.edges} edges, ${built.direction})`);
-            await printCheck(built.check);
-            return;
-        }
-        case 'icons': {
-            const provider = positionals[0];
-            if (!provider || !['aws', 'gcp', 'k8s', 'azure'].includes(provider))
-                fail('usage: linework icons <aws|gcp|k8s|azure> [filter]');
-            const { listIcons } = await import('./api.js');
-            const names = await listIcons(provider, positionals[1], await browser());
-            console.log(names.map((n) => `${provider}.${n}`).join('\n') || 'no matches');
-            return;
-        }
-        case 'publish': {
-            if (!positionals.length)
-                fail('usage: linework publish <file.drawio.svg...> [--to DIR]');
-            const { publish } = await import('./publish.js');
-            const items = publish(positionals, { to: values.to, pull: values.pull, force: values.force });
-            for (const i of items) {
-                if (i.action === 'published')
-                    console.log(`published ${path.relative(process.cwd(), i.file)} -> ${i.dest}`);
-                else if (i.action === 'unchanged')
-                    console.log(`unchanged ${i.dest}`);
-                else if (i.action === 'pulled')
-                    console.log(`pulled ${i.dest} -> ${path.relative(process.cwd(), i.file)}`);
-                else
-                    console.log(`skipped ${path.relative(process.cwd(), i.file)}: the Drive copy was edited after the last publish. Run with --pull to take that version, or --force to overwrite it.`);
-            }
-            if (items.some((i) => i.action === 'published') && !values.pull) {
-                console.log('\nNot in the doc yet? In Google Docs: Extensions > draw.io > Insert diagrams, then pick the file.');
-                console.log('Already in the doc? After Drive syncs: Extensions > draw.io > Update diagrams.');
-            }
-            if (items.some((i) => i.action === 'conflict'))
-                process.exitCode = 1;
-            return;
-        }
-        case 'skill': {
-            const { fileURLToPath } = await import('node:url');
-            const src = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'linework');
-            if (positionals[0] !== 'install')
-                return void console.log(src);
-            const dir = positionals[1] ?? fail('usage: linework skill install <skills-dir>   e.g. .claude/skills');
-            const dest = path.join(dir.replace(/^~(?=$|\/)/, process.env.HOME ?? '~'), 'linework');
-            fs.mkdirSync(dest, { recursive: true });
-            fs.cpSync(src, dest, { recursive: true });
-            console.log(`installed the linework skill to ${dest}`);
-            return;
-        }
-        case 'mcp': {
-            const { runStdio } = await import('./mcp/server.js');
-            await runStdio({ root: path.resolve(values.root ?? process.env.LINEWORK_ROOT ?? process.cwd()) });
-            return;
-        }
-        case 'git-setup': {
-            const { gitSetup } = await import('./git.js');
-            for (const line of gitSetup())
-                console.log(line);
-            return;
-        }
-        case 'kinds': {
-            const { KINDS, DIAGRAM_TYPES } = await import('./spec/model.js');
-            const types = (positionals.length ? positionals : DIAGRAM_TYPES);
-            for (const t of types) {
-                if (!KINDS[t])
-                    fail(`unknown type ${t}`);
-                console.log(`${t}:`);
-                for (const [k, d] of Object.entries(KINDS[t]))
-                    console.log(`  ${k.padEnd(10)} ${d.description}`);
-            }
-            return;
-        }
-        case 'schema': {
-            const { jsonSchema } = await import('./spec/parse.js');
-            console.log(JSON.stringify(jsonSchema(), null, 2));
-            return;
-        }
-        case 'install-browser': {
-            const { browserInstallCommand } = await import('./render/browser.js');
-            const { spawnSync } = await import('node:child_process');
-            const [bin, ...args] = browserInstallCommand();
-            console.log('downloading headless Chromium for linework...');
-            const r = spawnSync(bin, args, { stdio: 'inherit' });
-            process.exitCode = r.status ?? 1;
-            return;
-        }
-        default:
-            fail(`unknown command "${cmd}"\n\n${USAGE}`);
-    }
-}
-async function printCheck(res) {
-    const { checkLines } = await import('./report.js');
-    for (const line of checkLines(res))
-        console.log(line);
-}
-function fail(msg) {
-    console.error(msg);
-    process.exit(2);
-}
-main(process.argv.slice(2)).catch((e) => {
-    if (e?.name === 'SpecError') {
-        console.error('spec error:');
-        for (const i of e.issues)
-            console.error(`  ${i.path ? i.path + ': ' : ''}${i.message}`);
-        process.exit(1);
-    }
-    console.error(`error: ${e.message}`);
-    process.exit(1);
+main(process.argv.slice(2)).catch(async (e) => {
+    const { report } = await import('./commands.js');
+    process.exit(report(e));
 });