synthesisui 0.16.8 → 0.16.9

package/dist/commands/doctor.js

@@ -76,7 +76,7 @@ export async function* walkAll(roots) {
  *  and the recipes `add` put next to them in `design-system.json`. Those
  *  recipes are why the component pass can exist at all - a linter has no idea
  *  what `ds-button` promised. */
-async function loadSystem(root) {
+export async function loadSystem(root) {
     const dsDir = join(root, "_synthesisui", "ds");
     let slugs;
     try {

package/dist/commands/mcp.js

@@ -0,0 +1,250 @@
+import { readFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { diagnose, scanSource } from "../doctor/scan.js";
+import { nearestToken, tokenFor } from "../doctor/tokens.js";
+import { component } from "./component.js";
+import { loadSystem, walkAll } from "./doctor.js";
+const send = (msg) => {
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+};
+/** A tool result is always text: readable by the model, and by a person
+ *  watching the transcript when something goes wrong. */
+const text = (body, isError = false) => ({
+    content: [{ type: "text", text: body }],
+    ...(isError ? { isError: true } : null),
+});
+/**
+ * Everything a command prints, captured.
+ *
+ * `component()` announces what it fetched, and that line would land in the
+ * middle of a JSON-RPC frame. Capturing is not just protection: the output is
+ * exactly what the agent needs to read back, so it becomes the result.
+ */
+async function capturing(run) {
+    const lines = [];
+    const real = console.log;
+    console.log = (...args) => void lines.push(args.join(" "));
+    try {
+        const value = await run();
+        return { value, out: lines.join("\n") };
+    }
+    finally {
+        console.log = real;
+    }
+}
+// ── The tools ────────────────────────────────────────────────────────────────
+const TOOLS = [
+    {
+        name: "check_file",
+        description: "Check one file (or folder) against the installed design system. Returns token coverage, every hardcoded value with the token this project already has for it, and any --ds- name the system does not declare. Run this after writing or editing any UI file, before moving on.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "File or folder, relative to the project root.",
+                },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "find_token",
+        description: "Ask what this design system calls a value. Give it a colour, spacing or radius exactly as you would write it (#2563eb, 12px, 0.75rem) and it answers with the token name, or says no token holds it - in which case do NOT invent one.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                value: { type: "string", description: "e.g. #2563eb, 12px, 1rem" },
+            },
+            required: ["value"],
+        },
+    },
+    {
+        name: "list_components",
+        description: "The components this design system defines, with what each is for. Look here BEFORE writing any UI element from scratch - if something covers the purpose, materialize it with add_component instead.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "add_component",
+        description: "Materialize a component from the design system as real typed code in this project, ready to import and extend. Use it yourself - the person who asked for a feature should never have to know component names.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Component name from list_components.",
+                },
+            },
+            required: ["name"],
+        },
+    },
+];
+async function checkFile(root, path) {
+    const { table } = await loadSystem(root);
+    if (table.byName.size === 0)
+        return "No design system installed here, so there is nothing to check against. Run `synthesisui init` or `synthesisui adopt`.";
+    const scope = resolve(root, path);
+    const reports = [];
+    for await (const file of walkAll([scope])) {
+        const src = await readFile(file, "utf8").catch(() => "");
+        if (src)
+            reports.push(scanSource(relative(root, file), src, table));
+    }
+    if (reports.length === 0)
+        return `Nothing readable at ${path}.`;
+    const d = diagnose(reports);
+    const out = [
+        `${table.name ?? table.slug}: ${d.coverage}% of design values come from the system.`,
+        `${d.tokenUses} from the system, ${d.findings.length} written by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}.`,
+    ];
+    if (d.findings.length > 0) {
+        out.push("", "Written by hand:");
+        for (const f of d.findings.slice(0, 40)) {
+            out.push(f.token
+                ? `  ${f.file}:${f.line}  ${f.literal} - this system calls it ${f.token}`
+                : `  ${f.file}:${f.line}  ${f.literal} - no token holds this value`);
+        }
+        out.push("", "Replace the ones that have a token. For a value with none, do NOT invent a token: say which value it is and what you would call it, and let a person decide.");
+    }
+    const phantoms = d.files.flatMap((f) => (f.phantoms ?? []).map((p) => `  ${f.file}:${p.line}  ${p.name}`));
+    if (phantoms.length > 0) {
+        out.push("", "Names this system does not declare. These look tokenized and apply nothing at all:", ...phantoms);
+    }
+    if (d.findings.length === 0 && phantoms.length === 0)
+        out.push("", "Nothing to fix here.");
+    return out.join("\n");
+}
+async function findToken(root, value) {
+    const { table } = await loadSystem(root);
+    if (table.byName.size === 0)
+        return "No design system installed here.";
+    const exact = tokenFor(table, value);
+    if (exact)
+        return `${value} is ${exact} in this system. Use var(${exact}).`;
+    const near = nearestToken(table, value);
+    if (near)
+        return `No token holds ${value}. The closest is ${near.name} at ${near.value}. If that is what you meant, use it - if it genuinely is not, say so rather than inventing a token.`;
+    // Same words the managed block uses. A refusal is only useful if it is the
+    // same refusal every time.
+    return `No token in this system holds ${value}, and nothing is close. Do NOT invent one. Say which value you need and what you would call it, and let a person decide.`;
+}
+async function listComponents(root) {
+    const { documents } = await loadSystem(root);
+    const rows = [];
+    for (const doc of documents) {
+        const comps = doc.components;
+        for (const [name, recipe] of Object.entries(comps ?? {}))
+            rows.push(`  ${name}${recipe?.description ? ` - ${recipe.description}` : ""}`);
+    }
+    if (rows.length === 0)
+        return "This system defines no components yet - write what you need with its tokens.";
+    return [
+        `${rows.length} components. Materialize with add_component before writing one from scratch:`,
+        "",
+        ...rows.sort(),
+    ].join("\n");
+}
+async function addComponent(root, name) {
+    const { table } = await loadSystem(root);
+    if (!table.slug)
+        return "No design system installed here.";
+    const { out } = await capturing(() => component(table.slug, name, { dir: root }));
+    return `${out}\n\nIt is real code in this project now - import it and extend it rather than writing your own.`;
+}
+// ── The protocol ─────────────────────────────────────────────────────────────
+async function callTool(root, name, args) {
+    switch (name) {
+        case "check_file":
+            return text(await checkFile(root, String(args.path ?? ".")));
+        case "find_token":
+            return text(await findToken(root, String(args.value ?? "")));
+        case "list_components":
+            return text(await listComponents(root));
+        case "add_component":
+            return text(await addComponent(root, String(args.name ?? "")));
+        default:
+            return text(`No tool named ${name}.`, true);
+    }
+}
+/**
+ * One request in, one response out - or null for a notification, which MUST
+ * NOT be answered. Replying to `notifications/initialized` is the classic way
+ * to break a handshake, and it is the kind of thing only a test catches.
+ *
+ * Split out from the stdin loop so the protocol can be exercised without a
+ * pipe: the loop below is framing, this is the protocol.
+ */
+export async function handleRequest(root, req) {
+    const id = req.id;
+    if (id === undefined)
+        return null;
+    try {
+        switch (req.method) {
+            case "initialize":
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        // Echo the client's version rather than asserting our own: this
+                        // server speaks a subset every revision of the protocol has had,
+                        // and refusing a client over a date string helps nobody.
+                        protocolVersion: req.params?.protocolVersion ?? "2025-06-18",
+                        capabilities: { tools: {} },
+                        serverInfo: { name: "synthesisui", version: VERSION },
+                    },
+                };
+            case "ping":
+                return { jsonrpc: "2.0", id, result: {} };
+            case "tools/list":
+                return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+            case "tools/call": {
+                const name = String(req.params?.name ?? "");
+                const args = (req.params?.arguments ?? {});
+                return { jsonrpc: "2.0", id, result: await callTool(root, name, args) };
+            }
+            default:
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: { code: -32601, message: `Method not found: ${req.method}` },
+                };
+        }
+    }
+    catch (err) {
+        // A tool that throws must not take the session with it.
+        return {
+            jsonrpc: "2.0",
+            id,
+            result: text(err instanceof Error ? err.message : String(err), true),
+        };
+    }
+}
+export async function mcp(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin) {
+        buffer += chunk;
+        // Newline-delimited JSON. A frame can arrive split across chunks, and two
+        // can arrive in one.
+        let nl = buffer.indexOf("\n");
+        while (nl !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            nl = buffer.indexOf("\n");
+            if (!line)
+                continue;
+            let req;
+            try {
+                req = JSON.parse(line);
+            }
+            catch {
+                continue; // Unparseable frame with no id: nobody to answer.
+            }
+            const res = await handleRequest(root, req);
+            if (res)
+                send(res);
+        }
+    }
+}
+const VERSION = "0.16.9";

package/dist/index.js

@@ -9,6 +9,7 @@ import { generate } from "./commands/generate.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
+import { mcp } from "./commands/mcp.js";
 import { refit } from "./commands/refit.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
@@ -133,6 +134,11 @@ async function main() {
                 slug: typeof flags.slug === "string" ? flags.slug : undefined,
             });
             break;
+        // Long-lived: it owns stdin/stdout until the client closes the pipe, so
+        // it must not be reached by anything that prints.
+        case "mcp":
+            await mcp({ dir });
+            return;
         case "doctor":
             // positional paths scope the READING (the system is still found from the
             // root): `doctor apps/web packages/ui` in a monorepo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.8",
+  "version": "0.16.9",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {