flowfig 0.1.0 → 0.2.0

package/dist/mcp.js

@@ -0,0 +1,216 @@
+// The MCP server: the check, render, verify, diff and docs tools over stdio JSON-RPC, for an agent with no shell.
+// No SDK: the subset the clients need is small, and the package keeps its zero dependencies.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { diff, formatDiff } from './diff.js';
+import { GUIDE } from './guide.js';
+import { loadSpec, reportLines, sortFindings, svgWithSpec } from './load.js';
+import { check } from './svg.js';
+import { verify } from './verify.js';
+import { VERSION } from './version.js';
+const specSchema = {
+    description: 'The figure: the props object, { props }, or a path to a .json file or an SVG that flowfig wrote.',
+    anyOf: [{ type: 'object' }, { type: 'string' }],
+};
+const checkProps = {
+    spec: specSchema,
+    strict: { type: 'boolean', description: 'Warnings count as errors.' },
+    width: { type: 'number', description: 'The page width in px the reader sees. Default 830.' },
+    minText: { type: 'number', description: 'The smallest text in px at that width. Default 10.' },
+};
+export const TOOLS = [
+    { name: 'docs', description: 'The flowfig guide. Read it before the first render.', inputSchema: { type: 'object', properties: {} } },
+    {
+        name: 'check',
+        description: 'List the faults of a figure: unknown ids, text overflow, crossings, label overlap, small text, low contrast. Fix every error before render.',
+        inputSchema: { type: 'object', properties: checkProps, required: ['spec'] },
+    },
+    {
+        name: 'render',
+        description: 'Check a figure, then write it as one animated SVG file. Returns the check lines and the path. On an error, writes nothing.',
+        inputSchema: {
+            type: 'object',
+            properties: { ...checkProps, out: { type: 'string', description: 'The SVG path to write.' } },
+            required: ['spec', 'out'],
+        },
+    },
+    {
+        name: 'verify',
+        description: 'Check the code links (source) of one or more figures: the file and the symbol must exist under root.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                paths: { type: 'array', items: { type: 'string' }, description: 'Paths to .json files or SVGs.' },
+                root: { type: 'string', description: 'The folder the links resolve against. Default: the working directory.' },
+                strict: { type: 'boolean' },
+            },
+            required: ['paths'],
+        },
+    },
+    {
+        name: 'diff',
+        description: 'The spec changes between two figures, as a Markdown list.',
+        inputSchema: { type: 'object', properties: { old: specSchema, new: specSchema }, required: ['old', 'new'] },
+    },
+];
+class Bad extends Error {
+} // bad params: a JSON-RPC error, not a tool result
+class Fault extends Error {
+} // a path that cannot be read or written: a tool result with isError
+const ok = (text, isError = false) => isError ? { content: [{ type: 'text', text }], isError: true } : { content: [{ type: 'text', text }] };
+const spec = (v, name) => {
+    if (typeof v !== 'string' && (typeof v !== 'object' || v === null))
+        throw new Bad(`${name}: spec must be an object or a path`);
+    try {
+        return loadSpec(v);
+    }
+    catch (e) {
+        // The message of a path failure already starts with the path.
+        throw typeof v === 'string' ? new Fault(e.message) : new Bad(`${name}: ${e.message}`);
+    }
+};
+const need = (args, tool, keys) => {
+    for (const k of keys)
+        if (args[k] == null)
+            throw new Bad(`${tool}: ${k} is required`);
+};
+/** A present argument must have its type; a number must be positive. */
+const types = (args, tool, want) => {
+    for (const [k, t] of Object.entries(want)) {
+        const v = args[k];
+        if (v == null)
+            continue;
+        if (typeof v !== t || (t === 'number' && !(v > 0 && Number.isFinite(v)))) {
+            throw new Bad(`${tool}: ${k} must be ${t === 'number' ? 'a positive number' : `a ${t}`}`);
+        }
+    }
+};
+function run(name, args) {
+    if (name === 'docs')
+        return ok(GUIDE);
+    if (name === 'check' || name === 'render') {
+        need(args, name, name === 'render' ? ['spec', 'out'] : ['spec']);
+        types(args, name, { width: 'number', minText: 'number', out: 'string', strict: 'boolean' });
+        const props = spec(args.spec, name);
+        const opts = { width: args.width, minText: args.minText };
+        const findings = sortFindings(check(props, opts), args.strict === true);
+        const errors = findings.some((f) => f.severity === 'error');
+        const lines = reportLines(props, findings);
+        if (name === 'check' || errors)
+            return ok(lines.join('\n'), errors);
+        const out = String(args.out);
+        const svg = svgWithSpec(props);
+        try {
+            mkdirSync(dirname(out), { recursive: true });
+            writeFileSync(out, svg);
+        }
+        catch (e) {
+            throw new Fault(`${out}: ${e.message}`);
+        }
+        return ok([...lines, `${out} — ${(svg.length / 1024).toFixed(1)} kB`].join('\n'));
+    }
+    if (name === 'verify') {
+        need(args, name, ['paths']);
+        if (!Array.isArray(args.paths) || args.paths.some((p) => typeof p !== 'string'))
+            throw new Bad('verify: paths must be an array of strings');
+        types(args, name, { root: 'string', strict: 'boolean' });
+        const root = args.root == null ? process.cwd() : String(args.root);
+        const lines = [];
+        let errors = 0;
+        for (const p of args.paths) {
+            let props;
+            try {
+                props = spec(p, 'verify');
+            }
+            catch (e) {
+                if (!(e instanceof Fault))
+                    throw e;
+                errors++;
+                lines.push(`${'error'.padEnd(8)} ${'missing-file'.padEnd(18)} ${e.message}`);
+                continue;
+            }
+            const findings = sortFindings([...check(props), ...verify(props, { root })], args.strict === true);
+            errors += findings.filter((f) => f.severity === 'error').length;
+            lines.push(...findings.map((f) => `${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${p}: ${f.message}`));
+        }
+        const n = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`;
+        const total = lines.length;
+        lines.push(`${n(errors, 'error')}, ${n(total - errors, 'warning')}`);
+        return ok(lines.join('\n'), errors > 0);
+    }
+    if (name === 'diff') {
+        need(args, name, ['old', 'new']);
+        return ok(formatDiff(diff(spec(args.old, 'diff'), spec(args.new, 'diff')), 'md'));
+    }
+    throw new Bad(`unknown tool "${name}"`);
+}
+const reply = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+/** One JSON-RPC message in, one response out; `undefined` for a notification. Pure, so the tests call it directly. */
+export function handle(message) {
+    if (typeof message !== 'object' || message === null)
+        return fail(null, -32600, 'invalid request');
+    const { id, method, params } = message;
+    const notification = id === undefined;
+    if (typeof method !== 'string')
+        return notification ? undefined : fail(id, -32600, 'invalid request');
+    if (notification)
+        return undefined; // a notification gets no reply, and a call sent as one does not run
+    const info = { name: 'flowfig', version: VERSION };
+    try {
+        switch (method) {
+            case 'initialize':
+                return reply(id, {
+                    protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : '2025-11-25',
+                    capabilities: { tools: {} },
+                    serverInfo: info,
+                });
+            case 'server/discover':
+                return reply(id, {
+                    resultType: 'complete',
+                    supportedVersions: ['2026-07-28'],
+                    capabilities: { tools: {} },
+                    _meta: { 'io.modelcontextprotocol/serverInfo': info },
+                });
+            case 'ping':
+                return reply(id, {});
+            case 'tools/list':
+                return reply(id, { tools: TOOLS });
+            case 'tools/call': {
+                const name = String(params?.name ?? '');
+                if (!TOOLS.some((t) => t.name === name))
+                    throw new Bad(`unknown tool "${name}"`);
+                return reply(id, run(name, params?.arguments ?? {}));
+            }
+            default:
+                return fail(id, -32601, `method not found: ${method}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof Bad)
+            return fail(id, -32602, e.message);
+        if (e instanceof Fault)
+            return reply(id, ok(e.message, true));
+        return fail(id, -32603, e.message);
+    }
+}
+/** Read one message per line from `input`, write one response per line to `output`. Returns when `input` ends. */
+export async function serve(input, output) {
+    const rl = createInterface({ input, crlfDelay: Infinity });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            output.write(JSON.stringify(fail(null, -32700, 'parse error')) + '\n');
+            continue;
+        }
+        const response = handle(message);
+        if (response)
+            output.write(JSON.stringify(response) + '\n');
+    }
+}

package/dist/model.d.ts

@@ -13,6 +13,8 @@ export type FigNode = {
     lines?: number;
     /** Width in px. Overrides the width the layout picks. */
     width?: number;
+    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    source?: string;
 };
 /** A frame that lays out its children in a row or a column. Groups can hold groups. */
 export type FigGroup = {
@@ -43,6 +45,8 @@ export type FigEdge = {
     around?: 'above' | 'below';
     /** Draws the edge only while a step uses it. Use it for long edges that would cut across everything. */
     quiet?: boolean;
+    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    source?: string;
 };
 /** One packet on one edge. A string is the edge `id`. */
 export type FigHop = string | {
@@ -54,6 +58,8 @@ export type FigHop = string | {
     data?: ReactNode;
     /** Marks a message that does not wait for an answer. The rail draws it dashed, with an `async` tag. Default: `false`. */
     async?: boolean;
+    /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
+    source?: string;
 };
 /** One moment of a step. No edges means a pause. */
 export type FigBeat = {
@@ -132,6 +138,7 @@ export type Beat = Omit<FigBeat, 'edges'> & {
         back: boolean;
         data?: ReactNode;
         async?: boolean;
+        source?: string;
     }[];
 };
 export declare const toBeat: (b: FigHop | FigHop[] | FigBeat) => Beat;

package/dist/scene.d.ts

@@ -12,12 +12,14 @@ export type SceneBox = {
     rect: Rect;
     texts: TextRun[];
 };
+/** `step` marks a rail row: rows of two steps never show at the same time, so their labels cannot overlap. */
 export type SceneEdge = {
     id: string;
     from: string;
     to: string;
     curve: [Pt, Pt, Pt, Pt];
     label?: Rect;
+    step?: number;
 };
 /** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
 export type Scene = {

package/dist/source.d.ts

@@ -0,0 +1,16 @@
+import { type FlowProps } from './model.ts';
+/** `path` or `path#symbol`. No spaces, one `#` at most, both parts non-empty. `null` for a bad form. */
+export declare function parseSource(s: string): {
+    path: string;
+    symbol?: string;
+} | null;
+export type Link = {
+    owner: string;
+    source: string;
+    path: string;
+    symbol?: string;
+};
+/** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
+export declare function owners(fig: FlowProps): [string, string | undefined][];
+/** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
+export declare function links(fig: FlowProps): Link[];

package/dist/source.js

@@ -0,0 +1,24 @@
+// Code links, pure: no Node import, so the React and SVG entries stay browser-safe. `verify` in verify.ts reads the disk.
+import { edgeId, nodes, toBeat } from './model.js';
+/** `path` or `path#symbol`. No spaces, one `#` at most, both parts non-empty. `null` for a bad form. */
+export function parseSource(s) {
+    const m = /^([^\s#]+)(?:#([^\s#]+))?$/.exec(s);
+    if (!m)
+        return null;
+    return m[2] ? { path: m[1], symbol: m[2] } : { path: m[1] };
+}
+/** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
+export function owners(fig) {
+    return [
+        ...nodes(fig.layout).map((n) => [`box "${n.id}"`, n.source]),
+        ...fig.edges.map((e) => [`edge "${edgeId(e)}"`, e.source]),
+        ...(fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => [`hop on "${h.edge}"`, h.source]))),
+    ];
+}
+/** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
+export function links(fig) {
+    return owners(fig).flatMap(([owner, source]) => {
+        const p = source == null ? null : parseSource(source);
+        return p ? [{ owner, source: source, ...p }] : [];
+    });
+}

package/dist/svg.d.ts

@@ -3,6 +3,8 @@ import type { Finding, Scene } from './scene.ts';
 export type { CheckOptions } from './check.ts';
 export type { Finding, Scene } from './scene.ts';
 export type * from './model.ts';
+export { parseSource, links, type Link } from './source.ts';
+export { diff, formatDiff, type Change } from './diff.ts';
 import { type FigTheme, type FlowProps } from './model.ts';
 export { LIGHT, DARK } from './model.ts';
 /** Options for `toSvg`, `render` and `check`. */

package/dist/svg.js

@@ -10,6 +10,8 @@ import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
+export { parseSource, links } from './source.js';
+export { diff, formatDiff } from './diff.js';
 import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, toBeat, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
@@ -541,6 +543,7 @@ ${said.join('\n')}
                 return [
                     {
                         id: `rail:${row.n}`,
+                        step: row.step,
                         from: rail.columns[row.from].id,
                         to: rail.columns[row.to].id,
                         curve: [p, p, q, q],

package/dist/verify.d.ts

@@ -0,0 +1,7 @@
+import type { FlowProps } from './model.ts';
+import type { Finding } from './scene.ts';
+export { parseSource, owners, links, type Link } from './source.ts';
+/** The links against the files under `root`. A path outside the root is a missing file: the figure names the repo, not the disk. */
+export declare function verify(fig: FlowProps, { root }?: {
+    root?: string;
+}): Finding[];

package/dist/verify.js

@@ -0,0 +1,36 @@
+// `flowfig verify`: checks that the code a link names is still there. The link parsing lives in source.ts, which has no Node import.
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { links } from './source.js';
+export { parseSource, owners, links } from './source.js';
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** The file text, or null for a missing path, a folder or an unreadable file. */
+function read(full) {
+    try {
+        return statSync(full).isFile() ? readFileSync(full, 'utf8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The links against the files under `root`. A path outside the root is a missing file: the figure names the repo, not the disk. */
+export function verify(fig, { root = process.cwd() } = {}) {
+    const out = [];
+    const all = links(fig);
+    if (!all.length)
+        return [{ rule: 'no-source', severity: 'warning', ids: [], message: 'no box, edge or hop has a source' }];
+    const files = new Map();
+    for (const l of all) {
+        const full = resolve(root, l.path);
+        const rel = relative(root, full);
+        const outside = isAbsolute(l.path) || rel === '..' || rel.startsWith('../');
+        if (!files.has(full))
+            files.set(full, outside ? null : read(full));
+        const text = files.get(full);
+        if (text == null)
+            out.push({ rule: 'missing-file', severity: 'error', ids: [], message: `${l.owner} -> ${l.source}: file not found` });
+        else if (l.symbol && !new RegExp(`(^|[^\\w$])${escape(l.symbol)}(?![\\w$])`).test(text))
+            out.push({ rule: 'missing-symbol', severity: 'error', ids: [], message: `${l.owner} -> ${l.source}: symbol not found` });
+    }
+    return out;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
+export const VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Your coding agent draws animated diagrams from your code, and flowfig checks them. One animated SVG for a GitHub README, PR or issue, and a React player. Set up Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf and Kiro with npx flowfig init.",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,10 @@
     "./svg": {
       "types": "./dist/svg.d.ts",
       "default": "./dist/svg.js"
+    },
+    "./verify": {
+      "types": "./dist/verify.d.ts",
+      "default": "./dist/verify.js"
     }
   },
   "bin": {