synthesisui 0.16.7 → 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 {
@@ -409,7 +409,12 @@ export async function doctor(opts) {
         }
     }
     else if (asideTotal > 0) {
-        console.log(body(`set aside ${plural(asideTotal, "value")} a token could never hold (--verbose for why)`));
+        // "a token could never hold" was written when every aside was an image
+        // renderer or an SVG paint. A literal sitting in a token's OWN fallback -
+        // `var(--ds-color-semantic-knob, #ffffff)` - is set aside for the opposite
+        // reason: it is already tokenized. The summary said the false half out
+        // loud and hid the true half behind a flag.
+        console.log(body(`set aside ${plural(asideTotal, "value")} that are not drift (--verbose for why)`));
     }
     // 0 of 0 is not a perfect score, it is an empty measurement - printing a
     // full bar there would be the report's first lie.

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/component-codegen.js

@@ -32,11 +32,36 @@ function elementFor(name, recipe) {
             ? { tag: "button", attrs: ' type="button"' }
             : undefined);
     const tag = hit?.tag ?? "div";
-    return {
-        tag,
-        attrs: hit?.attrs ?? "",
-        voidEl: tag === "input" || tag === "hr",
-    };
+    const attrs = hit?.attrs ?? "";
+    const isVoid = tag === "input" || tag === "hr";
+    /**
+     * A VOID ELEMENT CANNOT HOST THE PARTS WE TELL PEOPLE TO PUT INSIDE IT.
+     *
+     * `switch` resolved to `<input type="checkbox">`, and the recipe gives it a
+     * `thumb` part - so the generated file documented `<Switch><SwitchThumb/>
+     * </Switch>`, which React refuses at runtime: input is void and must not
+     * have children. Found by an agent building a settings page against it
+     * (my-test4, 27/07). The documented usage was impossible.
+     *
+     * The recipe was right and the tag was wrong. Its own CSS styles `.ds-switch`
+     * as an `inline-flex` track with a 16px knob inside a 24px rail - that is a
+     * container, described as one, and only the element choice disagreed.
+     *
+     * `<button role="switch">` is the accessible pattern for exactly this: it
+     * takes children, it is focusable and operable by keyboard for free, and the
+     * caller supplies `aria-checked`. Promotion happens ONLY when parts exist, so
+     * a plain input stays an input.
+     */
+    if (isVoid && Object.keys(recipe.parts ?? {}).length > 0) {
+        // Carry the ARIA role across - it is the part of the input's meaning that
+        // survives the tag change, and dropping it would trade a runtime error for
+        // a silent accessibility regression.
+        const role = / role="[a-z]+"/.exec(attrs)?.[0] ?? "";
+        return tag === "input"
+            ? { tag: "button", attrs: ` type="button"${role}`, voidEl: false }
+            : { tag: "div", attrs: role || ' role="separator"', voidEl: false };
+    }
+    return { tag, attrs, voidEl: isVoid };
 }
 /** Variant axes → typed props. An axis whose options ⊆ {true,false} is a
  *  boolean prop; empty axes (no visual effect) are skipped. */
@@ -272,13 +297,44 @@ const STATE_PREFIX = {
 function blockToTailwind(block, prefix = "") {
     return Object.entries(block).flatMap(([prop, value]) => declToTailwind(prop, value).map((cls) => `${prefix}${cls}`));
 }
-function tailwindClassList(recipe) {
+function tailwindClassList(recipe, 
+/** CSS properties a variant axis owns - see `variantOwnedProps`. */
+exclude) {
+    const base = exclude
+        ? Object.fromEntries(Object.entries(recipe.base).filter(([prop]) => !exclude.has(prop)))
+        : recipe.base;
     const classes = [
-        ...blockToTailwind(recipe.base),
+        ...blockToTailwind(base),
+        // States keep everything: `hover:` and `disabled:` cannot collide with an
+        // unprefixed variant class, so there is nothing to resolve.
         ...Object.entries(recipe.states ?? {}).flatMap(([state, block]) => STATE_PREFIX[state] ? blockToTailwind(block, STATE_PREFIX[state]) : []),
     ];
     return classes.join(" ");
 }
+/**
+ * A VARIANT CANNOT OVERRIDE THE BASE WHEN BOTH ARE PLAIN UTILITIES.
+ *
+ * `Card` emitted `p-md` in BASE and `[padding:0]` for `padding="none"`. Same
+ * specificity, so which one wins is decided by the order Tailwind emits them
+ * in the stylesheet - not by the order of the class names, which is what the
+ * code looks like it controls. The prop silently did nothing (found by an
+ * agent that worked around it in a comment rather than reporting it,
+ * my-test4, 27/07).
+ *
+ * CSS mode never had this: it selects on `[data-padding="none"]`, which
+ * outranks the base class honestly. Tailwind mode has no such ladder, so the
+ * conflict has to be resolved where it is created - at generation.
+ *
+ * The property leaves BASE and the base value becomes the axis's default, so
+ * exactly one class ever sets it.
+ */
+function variantOwnedProps(variants, axis) {
+    const props = new Set();
+    for (const option of axis.options)
+        for (const prop of Object.keys(variants?.[axis.key]?.[option] ?? {}))
+            props.add(prop);
+    return [...props];
+}
 // ── Emission ─────────────────────────────────────────────────────────────────
 function header(slug, name, version, mode) {
     const setup = mode === "tailwind"
@@ -295,8 +351,14 @@ const joinCls = (parts) => `[${parts.join(", ")}].filter(Boolean).join(" ")`;
 /** JSDoc showing how to compose the component with its parts + content, so the
  *  materialized code doesn't read as "a bare shell renders nothing" (dogfood
  *  #5). Built from the recipe's parts. */
-function compositionHint(comp, name, recipe) {
+function compositionHint(comp, name, recipe, voidEl = false) {
     const partNames = Object.keys(recipe.parts ?? {});
+    // An `<input>` or `<hr>` takes no children, and telling somebody to put
+    // content inside one is an instruction that throws. With parts, the element
+    // was promoted above and this branch never runs for a void tag.
+    if (voidEl) {
+        return `/** Wears the "${name}" recipe. Takes no children - it renders a single void element. */`;
+    }
     if (partNames.length === 0) {
         return `/** Wears the "${name}" recipe. Put your content inside: <${comp}>…</${comp}>. */`;
     }
@@ -317,7 +379,6 @@ function emitCssMode(slug, name, recipe, version) {
     const comp = pascal(name);
     const propNames = axes.map((a) => a.prop);
     const destructure = [...propNames, "className", "...props"].join(", ");
-    void voidEl; // both void and container elements self-close ({...props} carries children)
     const rootJsx = `    <${tag}${attrs}\n      className={${joinCls([`"ds-${name}"`, "className"])}}\n${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}\n    />`;
     const parts = Object.entries(recipe.parts ?? {}).map(([partName, part]) => {
         const partAxes = axesOf(part.variants ?? {});
@@ -345,7 +406,7 @@ import type { ComponentPropsWithoutRef } from "react";
 
 type ${comp}Props = ${propsType(axes, tag)};
 
-${compositionHint(comp, name, recipe)}
+${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
   return (
 ${rootJsx}
@@ -368,11 +429,17 @@ function emitTailwindMode(slug, name, recipe, version) {
     const booleanConsts = axes
         .filter((a) => a.boolean)
         .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.true ?? {}).join(" "))};`);
+    // Every property some axis controls leaves BASE, and the base value becomes
+    // that axis's default - so exactly one class ever sets it and the prop
+    // actually wins.
+    const owned = new Map(axes.map((a) => [a.prop, variantOwnedProps(recipe.variants, a)]));
+    const excluded = new Set([...owned.values()].flat());
+    const fallbackFor = (a) => JSON.stringify(blockToTailwind(Object.fromEntries(Object.entries(recipe.base).filter(([prop]) => (owned.get(a.prop) ?? []).includes(prop)))).join(" "));
     const clsParts = [
         "BASE",
         ...axes.map((a) => a.boolean
-            ? `${a.prop} ? ${a.prop.toUpperCase()} : ""`
-            : `${a.prop} ? ${a.prop.toUpperCase()}[${a.prop}] : ""`),
+            ? `${a.prop} ? ${a.prop.toUpperCase()} : ${fallbackFor(a)}`
+            : `${a.prop} ? ${a.prop.toUpperCase()}[${a.prop}] : ${fallbackFor(a)}`),
         "className",
     ];
     const destructure = [
@@ -380,17 +447,16 @@ function emitTailwindMode(slug, name, recipe, version) {
         "className",
         "...props",
     ].join(", ");
-    void voidEl;
     return `${header(slug, name, version, "tailwind")}
 
 import type { ComponentPropsWithoutRef } from "react";
 
-const BASE = ${JSON.stringify(tailwindClassList(recipe))};
+const BASE = ${JSON.stringify(tailwindClassList(recipe, excluded))};
 ${[...variantConsts, ...booleanConsts].join("\n")}
 
 type ${comp}Props = ${propsType(axes, tag)};
 
-${compositionHint(comp, name, recipe)}
+${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
   return (
     <${tag}${attrs}

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.7",
+  "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": {