@itsthecsguy/linework 0.0.0-stage → 0.1.0

package/dist/lint/check.js

@@ -0,0 +1,184 @@
+const inter = (a, b) => Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+const shrink = (b, d) => ({ x: b.x + d, y: b.y + d, w: Math.max(0, b.w - 2 * d), h: Math.max(0, b.h - 2 * d) });
+const inside = (a, b, tol = 1) => a.x >= b.x - tol && a.y >= b.y - tol && a.x + a.w <= b.x + b.w + tol && a.y + a.h <= b.y + b.h + tol;
+function segHitsBox(a, b, r) {
+    // Liang–Barsky clip
+    let t0 = 0, t1 = 1;
+    const dx = b.x - a.x, dy = b.y - a.y;
+    const edges = [[-dx, a.x - r.x], [dx, r.x + r.w - a.x], [-dy, a.y - r.y], [dy, r.y + r.h - a.y]];
+    for (const [p, q] of edges) {
+        if (p === 0) {
+            if (q < 0)
+                return false;
+            continue;
+        }
+        const t = q / p;
+        if (p < 0) {
+            if (t > t1)
+                return false;
+            if (t > t0)
+                t0 = t;
+        }
+        else {
+            if (t < t0)
+                return false;
+            if (t < t1)
+                t1 = t;
+        }
+    }
+    return t1 - t0 > 1e-6;
+}
+function segsCross(a, b, c, d) {
+    const o = (p, q, r) => Math.sign((q.x - p.x) * (r.y - p.y) - (q.y - p.y) * (r.x - p.x));
+    const near = (p, q) => Math.abs(p.x - q.x) < 1 && Math.abs(p.y - q.y) < 1;
+    if (near(a, c) || near(a, d) || near(b, c) || near(b, d))
+        return false;
+    return o(a, b, c) * o(a, b, d) < 0 && o(c, d, a) * o(c, d, b) < 0;
+}
+export function check(cells) {
+    const findings = [];
+    const byId = new Map(cells.map((c) => [c.id, c]));
+    const name = (c) => (c.label ? `"${c.label.slice(0, 40)}"` : c.id);
+    // Sequence scaffolding (lifelines, frames, activation bars, guards) isn't an obstacle.
+    const scaffold = (c) => c.shape === 'umlLifeline' || c.shape === 'umlFrame' || ['bar', 'guard', 'frame'].includes(c.aivizType ?? '');
+    const nodes = cells.filter((c) => c.vertex && !c.container && !c.text && !scaffold(c));
+    const containers = cells.filter((c) => c.vertex && c.container);
+    const edges = cells.filter((c) => c.edge && c.points && c.points.length >= 2);
+    function ancestors(id) {
+        const s = new Set();
+        for (let p = id ? byId.get(id)?.parent : null; p; p = byId.get(p)?.parent ?? null)
+            s.add(p);
+        return s;
+    }
+    for (let i = 0; i < nodes.length; i++)
+        for (let j = i + 1; j < nodes.length; j++) {
+            const a = nodes[i], b = nodes[j];
+            if (ancestors(a.id).has(b.id) || ancestors(b.id).has(a.id))
+                continue;
+            if (inter(a.box, b.box) > 4)
+                findings.push({ level: 'error', rule: 'overlap', message: `${name(a)} and ${name(b)} overlap` });
+        }
+    for (const n of [...nodes, ...containers]) {
+        const p = n.parent ? byId.get(n.parent) : undefined;
+        if (p?.container && !inside(n.box, p.box, 2))
+            findings.push({ level: 'warning', rule: 'outside-group', message: `${name(n)} sticks out of its group ${name(p)}` });
+    }
+    for (const e of edges) {
+        const pts = e.points;
+        const skip = new Set([e.source, e.target, ...ancestors(e.source), ...ancestors(e.target)]);
+        for (const n of nodes) {
+            if (skip.has(n.id))
+                continue;
+            const r = shrink(n.box, 3);
+            for (let i = 0; i < pts.length - 1; i++)
+                if (segHitsBox(pts[i], pts[i + 1], r)) {
+                    findings.push({ level: 'error', rule: 'edge-through-node', message: `edge ${edgeName(e, byId)} passes through ${name(n)}`, edge: e.id });
+                    break;
+                }
+        }
+        // A route that doubles back through its own source or target (stale waypoints after a move).
+        for (const endId of [e.source, e.target]) {
+            const n = endId ? byId.get(endId) : undefined;
+            if (!n || n.container)
+                continue;
+            const r = shrink(n.box, 4);
+            // Skip the segment that attaches to this node: on diamonds and cylinders it
+            // legitimately starts inside the bounding box.
+            const isSource = endId === e.source;
+            const back = pts.slice(0, -1).some((p, i) => {
+                if (isSource ? i === 0 : i === pts.length - 2)
+                    return false;
+                const q = pts[i + 1];
+                const mid = { x: (p.x + q.x) / 2, y: (p.y + q.y) / 2 };
+                return mid.x > r.x && mid.x < r.x + r.w && mid.y > r.y && mid.y < r.y + r.h;
+            });
+            if (back) {
+                findings.push({ level: 'error', rule: 'edge-through-endpoint', message: `edge ${edgeName(e, byId)} doubles back through ${name(n)}`, edge: e.id });
+                break;
+            }
+        }
+    }
+    for (const n of nodes) {
+        if (!n.textBox || !n.label)
+            continue;
+        if (n.textBox.w > n.box.w + 2 || n.textBox.h > n.box.h + 2)
+            findings.push({ level: 'warning', rule: 'label-overflow', message: `label of ${name(n)} doesn't fit its shape; shorten it` });
+    }
+    const edgeLabels = edges.filter((e) => e.textBox && e.label);
+    const grow = (b, m) => ({ x: b.x - m, y: b.y - m, w: b.w + 2 * m, h: b.h + 2 * m });
+    for (const e of edgeLabels) {
+        // A label touching a box reads as part of it, so keep a few px clear.
+        for (const n of nodes)
+            if (inter(e.textBox, grow(n.box, 3)) > 4)
+                findings.push({ level: 'warning', rule: 'label-on-node', message: `label "${e.label}" on edge ${edgeName(e, byId)} covers ${name(n)}`, labelEdges: [e.id] });
+        // A label sitting on another edge, or on a group's border, hides part of that line.
+        const tb = grow(e.textBox, -2);
+        const lines = [
+            ...edges.filter((o) => o !== e).map((o) => ({ what: `edge ${edgeName(o, byId)}`, pts: o.points, box: tb })),
+            ...containers.filter((g) => !scaffold(g)).map((g) => ({
+                box: grow(e.textBox, 3),
+                what: `the border of ${name(g)}`,
+                pts: [
+                    { x: g.box.x, y: g.box.y },
+                    { x: g.box.x + g.box.w, y: g.box.y },
+                    { x: g.box.x + g.box.w, y: g.box.y + g.box.h },
+                    { x: g.box.x, y: g.box.y + g.box.h },
+                    { x: g.box.x, y: g.box.y },
+                ],
+            })),
+        ];
+        for (const o of lines) {
+            const hit = o.pts.some((p, k) => {
+                const q = o.pts[k + 1];
+                if (!q)
+                    return false;
+                const x1 = Math.min(p.x, q.x), x2 = Math.max(p.x, q.x), y1 = Math.min(p.y, q.y), y2 = Math.max(p.y, q.y);
+                return x1 <= o.box.x + o.box.w && x2 >= o.box.x && y1 <= o.box.y + o.box.h && y2 >= o.box.y;
+            });
+            if (hit) {
+                findings.push({ level: 'warning', rule: 'label-on-edge', message: `label "${e.label}" on edge ${edgeName(e, byId)} sits on ${o.what}`, labelEdges: [e.id] });
+                break;
+            }
+        }
+    }
+    for (let i = 0; i < edgeLabels.length; i++)
+        for (let j = i + 1; j < edgeLabels.length; j++)
+            if (inter(edgeLabels[i].textBox, edgeLabels[j].textBox) > 6)
+                findings.push({ level: 'warning', rule: 'label-collision', message: `edge labels "${edgeLabels[i].label}" and "${edgeLabels[j].label}" overlap`, labelEdges: [edgeLabels[j].id, edgeLabels[i].id] });
+    let crossings = 0;
+    for (let i = 0; i < edges.length; i++)
+        for (let j = i + 1; j < edges.length; j++) {
+            const a = edges[i].points, b = edges[j].points;
+            for (let s = 0; s < a.length - 1; s++)
+                for (let t = 0; t < b.length - 1; t++)
+                    if (segsCross(a[s], a[s + 1], b[t], b[t + 1]))
+                        crossings++;
+        }
+    const real = nodes.filter((n) => n.box.w > 30 || n.box.h > 30);
+    if (real.length > 20)
+        findings.push({ level: 'warning', rule: 'too-big', message: `${real.length} nodes; consider splitting into two diagrams` });
+    if (crossings > Math.max(3, edges.length / 3))
+        findings.push({ level: 'warning', rule: 'crossings', message: `${crossings} edge crossings; try direction: LR/TB, reordering nodes, or splitting` });
+    const all = cells.filter((c) => c.vertex).map((c) => c.box);
+    const minX = Math.min(...all.map((b) => b.x)), maxX = Math.max(...all.map((b) => b.x + b.w));
+    const minY = Math.min(...all.map((b) => b.y)), maxY = Math.max(...all.map((b) => b.y + b.h));
+    // A doc column is ~800px; past this, text shrinks below readable size when embedded.
+    if (maxX - minX > 1400)
+        findings.push({ level: 'warning', rule: 'too-wide', message: `${Math.round(maxX - minX)}px wide; embedded in a doc, its text shrinks to about ${Math.round((800 / (maxX - minX)) * 13)}px. Try direction: TB, fewer nodes per row, or splitting it` });
+    return {
+        findings: dedupe(findings),
+        stats: { nodes: nodes.filter((n) => !ancestors(n.id).size || !nodes.some((p) => ancestors(n.id).has(p.id))).length + cells.filter((c) => c.shape === 'umlLifeline').length, edges: edges.length, crossings, width: Math.round(maxX - minX), height: Math.round(maxY - minY) },
+    };
+}
+function edgeName(e, byId) {
+    const lab = (id) => (id ? byId.get(id)?.label || id : '?');
+    return `${lab(e.source)} -> ${lab(e.target)}`;
+}
+function dedupe(f) {
+    const seen = new Set();
+    return f.filter((x) => (seen.has(x.message) ? false : (seen.add(x.message), true)));
+}
+/** Edge cell ids whose routes are broken in a way rerouting fixes. */
+export function brokenEdges(res) {
+    return [...new Set(res.findings.filter((f) => f.edge).map((f) => f.edge))];
+}

package/dist/lint/fixlabels.js

@@ -0,0 +1,128 @@
+// Slide edge labels along their edges until they stop colliding with other labels
+// or sitting on nodes. Only label positions change; routes and nodes stay put.
+// Spots in the middle of a straight run come first, so a label never ends up
+// wedged into a bend when there's a clear stretch of line for it.
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { check } from './check.js';
+const OFFSETS = [-0.35, 0.35, -0.65, 0.65, -0.15, 0.15, -0.85, 0.85];
+const LABEL_RULES = new Set(['label-collision', 'label-on-node', 'label-on-edge']);
+function edgeGeometry(doc, id) {
+    const objs = doc.getElementsByTagName('object');
+    for (let i = 0; i < objs.length; i++) {
+        const o = objs[i];
+        if (o.getAttribute('id') !== id)
+            continue;
+        return o.getElementsByTagName('mxGeometry')[0] ?? undefined;
+    }
+    return undefined;
+}
+/** Label positions (draw.io's -1..1 along the path) on straight runs, roomiest run first. */
+export function runSpots(pts, label) {
+    const segs = [];
+    let total = 0;
+    for (let i = 0; i < pts.length - 1; i++) {
+        const a = pts[i], b = pts[i + 1];
+        const len = Math.hypot(b.x - a.x, b.y - a.y);
+        const vertical = Math.abs(b.x - a.x) < Math.abs(b.y - a.y);
+        segs.push({ start: total, len, need: (vertical ? label.h : label.w) / 2 + 10 });
+        total += len;
+    }
+    if (!total)
+        return [];
+    const out = [];
+    for (const sg of segs.filter((x) => x.len >= 2 * x.need).sort((x, y) => y.len - x.len))
+        for (const t of [0.5, 0.3, 0.7, 0.15, 0.85]) {
+            const at = sg.start + Math.min(sg.len - sg.need, Math.max(sg.need, t * sg.len));
+            const f = (at / total) * 2 - 1;
+            if (!out.some((o) => Math.abs(o - f) * total < 16))
+                out.push(f);
+        }
+    return out;
+}
+function labelEdges(findings) {
+    return [...new Set(findings.filter((f) => LABEL_RULES.has(f.rule) && f.labelEdges).flatMap((f) => f.labelEdges))];
+}
+export async function fixLabels(b, xml, maxRounds = 6) {
+    let cur = xml;
+    let score = check(await b.inspect(cur)).findings.filter((f) => LABEL_RULES.has(f.rule)).length;
+    let moved = 0;
+    for (let round = 0; round < maxRounds && score > 0; round++) {
+        const cells = await b.inspect(cur);
+        const res = check(cells);
+        const targets = labelEdges(res.findings);
+        let improved = false;
+        for (const id of targets) {
+            const doc = new DOMParser().parseFromString(cur, 'text/xml');
+            const g = edgeGeometry(doc, id);
+            if (!g)
+                continue;
+            const base = Number(g.getAttribute('x') ?? 0);
+            const cell = cells.find((c) => c.id === id);
+            const spots = cell?.points && cell.textBox ? runSpots(cell.points, cell.textBox) : [];
+            const tries = [...spots, ...OFFSETS.map((off) => Math.max(-0.9, Math.min(0.9, base + off)))];
+            let best;
+            for (const x of tries) {
+                g.setAttribute('x', x.toFixed(3));
+                const candidate = new XMLSerializer().serializeToString(doc);
+                const s = check(await b.inspect(candidate)).findings.filter((f) => LABEL_RULES.has(f.rule)).length;
+                if (s < (best?.score ?? score))
+                    best = { xml: candidate, score: s };
+                if (s === 0)
+                    break;
+            }
+            if (best) {
+                cur = best.xml;
+                score = best.score;
+                moved++;
+                improved = true;
+                if (score === 0)
+                    break;
+            }
+        }
+        if (!improved)
+            break;
+    }
+    cur = await matchLabelBackgrounds(b, cur);
+    return { xml: cur, moved };
+}
+/**
+ * A label's backing has to match what it sits on: the fill of the smallest group
+ * under it, or the canvas. Run after labels move, since a move can carry a label
+ * from the canvas onto a group or back.
+ */
+export async function matchLabelBackgrounds(b, xml) {
+    const cells = await b.inspect(xml);
+    const doc = new DOMParser().parseFromString(xml, 'text/xml');
+    const canvas = doc.getElementsByTagName('mxGraphModel')[0]?.getAttribute('background') ?? '#FFFFFF';
+    const styleOf = new Map();
+    const objs = doc.getElementsByTagName('object');
+    for (let i = 0; i < objs.length; i++) {
+        const cell = objs[i].getElementsByTagName('mxCell')[0];
+        if (cell)
+            styleOf.set(objs[i].getAttribute('id') ?? '', cell);
+    }
+    const fillOf = (id) => /(?:^|;)fillColor=([^;]+)/.exec(styleOf.get(id)?.getAttribute('style') ?? '')?.[1];
+    const groups = cells.filter((c) => c.aivizType === 'group');
+    let changed = false;
+    for (const e of cells.filter((c) => c.edge && c.textBox && c.label)) {
+        const el = styleOf.get(e.id);
+        const style = el?.getAttribute('style') ?? '';
+        if (!el || !/labelBackgroundColor=/.test(style))
+            continue;
+        const cx = e.textBox.x + e.textBox.w / 2, cy = e.textBox.y + e.textBox.h / 2;
+        let bg = canvas, area = Infinity;
+        for (const g of groups) {
+            const r = g.box, f = fillOf(g.id);
+            if (cx < r.x || cx > r.x + r.w || cy < r.y || cy > r.y + r.h || !f || f === 'none' || r.w * r.h >= area)
+                continue;
+            bg = f;
+            area = r.w * r.h;
+        }
+        const next = style.replace(/labelBackgroundColor=[^;]*/, `labelBackgroundColor=${bg}`);
+        if (next !== style) {
+            el.setAttribute('style', next);
+            changed = true;
+        }
+    }
+    return changed ? new XMLSerializer().serializeToString(doc) : xml;
+}

package/dist/mcp/server.js

@@ -0,0 +1,239 @@
+// `linework mcp`: the same operations as the CLI, over MCP stdio, for chat apps
+// and harnesses without a shell. Tools return text the model can act on, plus a
+// PNG preview so models that see images can check their work.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as z from 'zod';
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { build, checkFile, listIcons, show, tidy } from '../api.js';
+import { readDrawio } from '../drawio/read.js';
+import { DrawioBrowser } from '../render/browser.js';
+import { SpecError } from '../spec/parse.js';
+import { buildLines, checkLines } from '../report.js';
+import { PROVIDERS } from '../drawio/icons.js';
+const INSTRUCTIONS = `linework draws software diagrams (architecture, flow, state, sequence, ER) as .drawio.svg files. They render in Markdown, HTML and GitHub like any SVG, and people can open them in draw.io and edit them by hand.
+
+You write a small YAML spec; linework does layout and styling. Never write coordinates, SVG or draw.io XML.
+- Call linework_guide once before your first diagram. It has the spec format and the style rules.
+- build_diagram writes the file and returns lint results and a PNG preview. Fix every check error, look at the preview, rebuild until it reads well.
+- To change an existing diagram, call show_diagram first, edit the YAML it returns (keep its "# linework-base:" line), then build_diagram to the same path. Hand edits made in draw.io survive.
+- Never pass relayout: true unless the user asks; it throws away their hand-made layout.
+- Embed the .drawio.svg in docs, not the PNG.`;
+const PKG = (() => {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 4; i++) {
+        if (fs.existsSync(path.join(dir, 'skills', 'linework', 'SKILL.md')))
+            return dir;
+        dir = path.dirname(dir);
+    }
+    throw new Error('linework: bundled skill not found. Reinstall linework.');
+})();
+const TOOL_NAMES = `In this MCP server the CLI commands in the guide are tools: build -> build_diagram, show -> show_diagram, check -> check_diagram, render -> render_diagram, tidy -> tidy_diagram, import -> import_mermaid, icons -> list_icons, edit -> edit_diagram, publish -> publish_diagram. Pass the spec text to build_diagram directly instead of writing a file.\n\n`;
+export function createServer(opts) {
+    let browser;
+    const getBrowser = () => (browser ??= DrawioBrowser.launch({ scale: 2 }));
+    // One page does all the work, so calls run one at a time.
+    let queue = Promise.resolve();
+    const serial = (fn) => {
+        const next = queue.then(fn, fn);
+        queue = next.catch(() => { });
+        return next;
+    };
+    const editors = new Map();
+    const resolvePath = (p) => (path.isAbsolute(p) ? p : path.resolve(opts.root, p));
+    const text = (t) => ({ type: 'text', text: t });
+    const wrap = (fn) => async () => {
+        try {
+            return await serial(fn);
+        }
+        catch (e) {
+            if (e instanceof SpecError)
+                return { isError: true, content: [text(['spec error:', ...e.issues.map((i) => `  ${i.path ? i.path + ': ' : ''}${i.message}`)].join('\n'))] };
+            return { isError: true, content: [text(`error: ${e.message}`)] };
+        }
+    };
+    const preview = async (file) => {
+        const b = await getBrowser();
+        const png = await b.renderPng(readDrawio(fs.readFileSync(file, 'utf8')).xml);
+        return { type: 'image', data: png.toString('base64'), mimeType: 'image/png' };
+    };
+    const server = new McpServer({ name: 'linework', version: version() }, { instructions: INSTRUCTIONS, capabilities: { tools: {} } });
+    const pathArg = z.string().describe(`Diagram file, e.g. docs/diagrams/checkout.drawio.svg. Relative paths resolve against ${opts.root}.`);
+    server.registerTool('linework_guide', {
+        title: 'How to write linework diagrams',
+        description: 'Returns the linework guide: diagram types, the YAML spec format with examples, and the style rules. Read it before your first diagram.',
+        inputSchema: z.object({
+            topic: z
+                .enum(['overview', 'spec', 'style', 'google-docs'])
+                .default('overview')
+                .describe('overview: workflow and cheat sheet. spec: the full spec reference. style: what makes a good diagram. google-docs: getting diagrams into Google Docs.'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, async ({ topic }) => {
+        const file = { overview: 'SKILL.md', spec: 'references/spec.md', style: 'references/style-guide.md', 'google-docs': 'references/google-docs.md' }[topic];
+        const body = fs.readFileSync(path.join(PKG, 'skills', 'linework', file), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, '');
+        return { content: [text(TOOL_NAMES + body)] };
+    });
+    server.registerTool('build_diagram', {
+        title: 'Build a diagram',
+        description: 'Lay out a YAML spec and write it as a .drawio.svg. If the file exists and someone edited it by hand, the spec is merged in and their layout is kept. Returns what changed, lint results and a PNG preview.',
+        inputSchema: z.object({
+            spec: z.string().describe('The YAML spec. See linework_guide.'),
+            path: pathArg,
+            relayout: z.boolean().default(false).describe('Throw away the existing layout, hand edits included. Only when the user asks.'),
+            preview: z.boolean().default(true).describe('Return a PNG preview.'),
+        }),
+        annotations: { destructiveHint: false, idempotentHint: true },
+    }, (args) => wrap(async () => {
+        const out = resolvePath(args.path);
+        const res = await build(args.spec, { out, relayout: args.relayout, browser: await getBrowser() });
+        const content = [text(buildLines(res).join('\n'))];
+        if (args.preview)
+            content.push(await preview(out));
+        return { content };
+    })());
+    server.registerTool('show_diagram', {
+        title: 'Show a diagram as a spec',
+        description: 'Returns the YAML spec of an existing .drawio.svg, including edits people made by hand in draw.io. Edit this output and pass it to build_diagram to change the diagram.',
+        inputSchema: z.object({ path: pathArg }),
+        annotations: { readOnlyHint: true },
+    }, (args) => wrap(async () => {
+        const res = show(resolvePath(args.path));
+        const notes = res.notes.map((n) => `note: ${n}`);
+        if (res.edits.length)
+            notes.push(`note: edited by hand since the last build. build_diagram keeps those positions and merges your changes in.`);
+        return { content: [text(res.yaml + (notes.length ? '\n' + notes.join('\n') : ''))] };
+    })());
+    server.registerTool('check_diagram', {
+        title: 'Lint a diagram',
+        description: 'Lints the layout of a .drawio.svg: overlapping shapes, edges through nodes, labels that collide or overflow.',
+        inputSchema: z.object({ path: pathArg }),
+        annotations: { readOnlyHint: true },
+    }, (args) => wrap(async () => ({ content: [text(checkLines(await checkFile(resolvePath(args.path), await getBrowser())).join('\n'))] }))());
+    server.registerTool('render_diagram', {
+        title: 'Render a diagram to PNG',
+        description: 'Returns a PNG of a .drawio.svg so you can look at it. Optionally also writes the PNG to a file, e.g. for Google Docs or slides.',
+        inputSchema: z.object({ path: pathArg, out: z.string().optional().describe('Also write the PNG here.') }),
+        annotations: { readOnlyHint: false },
+    }, (args) => wrap(async () => {
+        const img = await preview(resolvePath(args.path));
+        if (args.out) {
+            const out = resolvePath(args.out);
+            fs.mkdirSync(path.dirname(out), { recursive: true });
+            fs.writeFileSync(out, Buffer.from(img.data, 'base64'));
+        }
+        return { content: [img, ...(args.out ? [text(`wrote ${resolvePath(args.out)}`)] : [])] };
+    })());
+    server.registerTool('tidy_diagram', {
+        title: 'Reroute broken edges',
+        description: 'Reroutes edges that pass through shapes, e.g. after someone moved shapes by hand. Nothing else in the file changes.',
+        inputSchema: z.object({ path: pathArg }),
+        annotations: { idempotentHint: true },
+    }, (args) => wrap(async () => {
+        const file = resolvePath(args.path);
+        const res = await tidy(file, await getBrowser());
+        return { content: [text([res.fixed ? `rerouted ${res.fixed} edges in ${file}` : 'nothing to fix', ...checkLines(res.check)].join('\n'))] };
+    })());
+    server.registerTool('import_mermaid', {
+        title: 'Convert Mermaid to an linework spec',
+        description: 'Converts a Mermaid diagram (flowchart, stateDiagram, sequenceDiagram, erDiagram) to an linework spec. Returns the spec; review the guessed node kinds, then build it. With path, builds it straight away.',
+        inputSchema: z.object({ source: z.string().describe('Mermaid source, without the ``` fence.'), path: pathArg.optional() }),
+    }, (args) => wrap(async () => {
+        const { importMermaid } = await import('../import/mermaid.js');
+        const { toYaml } = await import('../drawio/show.js');
+        const res = importMermaid(args.source);
+        const yaml = toYaml(res.diagram, 'imported from Mermaid');
+        const lines = [yaml, ...res.warnings.map((w) => `import: ${w}`)];
+        const content = [];
+        if (args.path) {
+            const out = resolvePath(args.path);
+            const built = await build(yaml, { out, browser: await getBrowser() });
+            lines.push('', ...buildLines(built));
+            content.push(text(lines.join('\n')), await preview(out));
+        }
+        else
+            content.push(text(lines.join('\n')));
+        return { content };
+    })());
+    server.registerTool('list_icons', {
+        title: 'Search cloud icons',
+        description: 'Lists icon names for architecture nodes (icon: aws.lambda). Pass a filter word to search, e.g. provider aws, filter "queue".',
+        inputSchema: z.object({ provider: z.enum(Object.keys(PROVIDERS)), filter: z.string().optional() }),
+        annotations: { readOnlyHint: true },
+    }, (args) => wrap(async () => {
+        const names = await listIcons(args.provider, args.filter, await getBrowser());
+        return { content: [text(names.map((n) => `${args.provider}.${n}`).join('\n') || 'no matches')] };
+    })());
+    server.registerTool('edit_diagram', {
+        title: 'Open a diagram in draw.io',
+        description: "Opens the diagram in the bundled draw.io editor in the user's browser, served locally. When they save, the file updates. When they say they're done, call show_diagram to pick up their changes.",
+        inputSchema: z.object({ path: pathArg, open: z.boolean().default(true).describe('Open the browser. False just returns the URL.') }),
+    }, (args) => wrap(async () => {
+        const { startEditor, openInBrowser } = await import('../edit/server.js');
+        const file = resolvePath(args.path);
+        const existing = editors.get(file);
+        if (existing) {
+            if (args.open)
+                openInBrowser(existing.url);
+            return { content: [text(`already open at ${existing.url}`)] };
+        }
+        const session = await startEditor(file);
+        editors.set(file, session);
+        void session.done.then(() => editors.delete(file));
+        const opened = args.open && openInBrowser(session.url);
+        return { content: [text(`${opened ? 'Opened' : 'Open'} ${session.url} to edit ${file}. Saving in the editor (Ctrl/Cmd+S) writes the file.`)] };
+    })());
+    server.registerTool('publish_diagram', {
+        title: 'Publish diagrams to Google Drive',
+        description: "Copies diagrams into the user's Google Drive folder (Google Drive for desktop) at a fixed path, so draw.io's Google Docs add-on can insert them and refresh them. pull: true copies back a version someone edited from Docs. See linework_guide topic google-docs.",
+        inputSchema: z.object({
+            paths: z.array(z.string()).min(1).describe('Diagram files to publish.'),
+            to: z.string().optional().describe('Publish into this synced folder instead of the detected Google Drive folder.'),
+            pull: z.boolean().default(false).describe('Copy the Drive versions back over the local files.'),
+        }),
+    }, (args) => wrap(async () => {
+        const { publish } = await import('../publish.js');
+        const items = publish(args.paths.map(resolvePath), { to: args.to && resolvePath(args.to), pull: args.pull, cwd: opts.root });
+        const lines = items.map((i) => i.action === 'conflict'
+            ? `skipped ${i.file}: the Drive copy was edited after the last publish. Ask the user whether to pull it (pull: true) or overwrite it.`
+            : `${i.action} ${i.action === 'pulled' ? `${i.dest} -> ${i.file}` : `${i.file} -> ${i.dest}`}`);
+        if (items.some((i) => i.action === 'published'))
+            lines.push('', 'Tell the user: in Google Docs, Extensions > draw.io > Insert diagrams to add it, or Extensions > draw.io > Update diagrams if it is already in the doc.');
+        return { content: [text(lines.join('\n'))] };
+    })());
+    const dispose = async () => {
+        for (const e of editors.values())
+            await e.close();
+        if (browser)
+            await (await browser.catch(() => undefined))?.close();
+    };
+    return { server, dispose };
+}
+function version() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(PKG, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export async function runStdio(opts) {
+    let disposers = [];
+    serveStdio(() => {
+        const { server, dispose } = createServer(opts);
+        disposers.push(dispose);
+        return server;
+    });
+    const shutdown = async () => {
+        const d = disposers;
+        disposers = [];
+        await Promise.allSettled(d.map((f) => f()));
+        process.exit(0);
+    };
+    process.stdin.on('end', shutdown);
+    process.stdin.on('close', shutdown);
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}