synthesisui 0.16.8 → 0.16.10

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/doctor/tokens.js

@@ -180,6 +180,57 @@ export function parseTokens(css) {
  * Harmless while nothing asked about existence. The moment the phantom check
  * did, it called them invented (caught before shipping, 27/07).
  */
+/**
+ * AN ALIAS IS NOT A DEAD END. IT IS USUALLY THE ANSWER.
+ *
+ * Every real system is written in two layers - `--ds-color-blue-600: #2563eb`
+ * on the shelf, `--ds-color-semantic-info: var(--ds-color-blue-600)` for the
+ * intent - and the value table only ever held the first. So `tokenFor` answered
+ * `#2563eb → --ds-color-blue-600`, the shelf, and its own rule two lines below
+ * ("semantic roles name intent; prefer intent") could never fire, because no
+ * semantic name was in the table to prefer.
+ *
+ * That is the one sentence the product is sold on: not "you have a hardcoded
+ * colour" but "your system already calls it this". It was naming the wrong
+ * thing on every system that layers its tokens, which is all of them. Found
+ * when an agent using the MCP tools read the answer, checked it against
+ * CLAUDE.md, and corrected the tool (my-test4, 27/07).
+ *
+ * Following the chain costs one pass and needs no CSS engine: a token either
+ * holds a literal or points at exactly one other token.
+ */
+export function resolveAliases(raw) {
+    const out = new Map();
+    const literal = (name, depth) => {
+        // A cycle is malformed CSS, not something to crash on. Ten hops is far
+        // past any real system and stops the recursion dead.
+        if (depth > 10)
+            return null;
+        const value = raw.get(name);
+        if (value === undefined)
+            return null;
+        const alias = /^var\(\s*(--[a-z0-9_-]+)/i.exec(value.trim());
+        return alias ? literal(alias[1].toLowerCase(), depth + 1) : value;
+    };
+    for (const name of raw.keys()) {
+        const value = literal(name, 0);
+        if (value !== null)
+            out.set(name, value);
+    }
+    return out;
+}
+/** Every `--ds-*` declaration, aliases kept - the input `resolveAliases` needs.
+ *  `parseTokens` drops them, which is right for a table of literals and wrong
+ *  for a table of what things are called. */
+export function parseTokensWithAliases(css) {
+    const out = new Map();
+    for (const m of css.matchAll(/(--ds-[a-z0-9-]+)\s*:\s*([^;}]+)[;}]/gi)) {
+        const name = m[1].toLowerCase();
+        if (!out.has(name))
+            out.set(name, m[2].trim());
+    }
+    return out;
+}
 export function parseDeclaredNames(css) {
     const out = new Set();
     for (const m of css.matchAll(/(--[a-z0-9_-]+)\s*:\s*[^;}]+[;}]/gi))
@@ -280,14 +331,35 @@ export function buildTable(input) {
     const byName = source === "installed"
         ? parseTokens(input.css)
         : parseRootTokens(input.css);
+    /**
+     * Built from the RESOLVED map, not from `byName`. A semantic role that
+     * aliases a primitive has to be findable by the primitive's value, or the
+     * "prefer intent" rule below is unreachable.
+     */
+    const resolved = source === "installed"
+        ? resolveAliases(parseTokensWithAliases(input.css))
+        : byName;
+    /**
+     * Aliases first in every list.
+     *
+     * `tokenFor` preferred a name containing `-semantic-`, which covers colour
+     * and nothing else: `--ds-spacing-md: var(--ds-spacing-4)` has no such
+     * marker, so the answer came back as the raw step rather than the scale name
+     * anyone actually writes. The general rule is structural, not lexical - in a
+     * layered system the name that POINTS at another name is the layer above.
+     */
+    const raw = source === "installed" ? parseTokensWithAliases(input.css) : new Map();
+    const isAlias = (name) => /^var\(/.test((raw.get(name) ?? "").trim());
     const byValue = new Map();
-    for (const [name, value] of byName) {
+    for (const [name, value] of resolved) {
         const key = normalizeValue(value);
         const list = byValue.get(key);
-        if (list)
-            list.push(name);
-        else
+        if (!list)
             byValue.set(key, [name]);
+        else if (isAlias(name))
+            list.unshift(name);
+        else
+            list.push(name);
     }
     return {
         source: byName.size > 0 ? source : null,

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.10",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {