synthesisui 0.16.77 → 0.16.79

package/dist/commands/import.js

@@ -1,5 +1,6 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
+import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
@@ -11,9 +12,9 @@ import { describeConvention, describeRemainder, detectConventions, } from "../do
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
-import { rootClasses, rootTag, transcribe, transcribeParts, } from "../doctor/transcribe.js";
+import { rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { body, paint, section } from "../output.js";
-import { detectStack } from "../stack.js";
+import { detectStack, resolveDeps } from "../stack.js";
 import { walk, walkAll } from "./doctor.js";
 /**
  * How many distinct values travel, PER KIND.
@@ -896,28 +897,79 @@ function sayReach(c) {
     }
 }
 /**
- * Fold the skill's named parts into the transcription, in place.
+ * Fold the skill's anatomy into the transcription, in place.
+ *
+ * A CLEAN SPLIT OF WHO KNOWS WHAT. Only the skill can say that a span holds the
+ * title and that the thing in the middle is their own `TextEditor`; only this
+ * side can say that `text-ocean-500` is `{color.ocean.500}` and that
+ * `@tiptap/react` is pinned at `^2.1.0` in their manifest. The platform then
+ * turns declarations into roles, because only it has the two palettes.
  *
  * Their declared tokens come from the census itself, so a run that only sends a
  * file it was handed still resolves a `bg-ocean-500` by their own name.
  */
-function resolveReadParts(census) {
+async function resolveReadParts(census, root) {
     const read = census.reading?.components;
     if (!read)
         return;
     const declared = new Map(Object.entries(census.declared));
-    const looks = census.looks ?? (census.looks = {});
+    // The manifest is read ONCE for the whole run: the version belongs in a rule's
+    // EVIDENCE, never in its text, so the rule does not go stale on an upgrade and
+    // the number is not lost either.
+    const deps = await resolveDeps(root).catch(() => ({}));
+    census.looks ??= {};
+    const looks = census.looks;
     let named = 0;
+    let shaped = 0;
+    let edges = 0;
+    const libs = new Set();
+    const notes = new Set();
+    /**
+     * WHAT A NAME IN THEIR CODE REACHES IN THE SYSTEM - from the crosswalk.
+     *
+     * The census already decided this for every component it read: `Tag` is
+     * `nearly`, canonical `badge`; `ToolbarButton` is `nearly`, canonical `button`;
+     * `Card` `exists` as `card`. The first version of the frontier kebab-cased the
+     * name and looked for `ds-tag`, which does not exist - so a component whose
+     * recipe was sitting right there drew as a grey chip (dono, 01/08).
+     */
+    const crosswalked = new Map();
+    for (const c of census.components ?? []) {
+        if (c.from)
+            continue; // a package's component is not one of theirs
+        const target = c.canonical ?? (c.bucket === "exclusive" ? c.name : null);
+        if (target)
+            crosswalked.set(c.name, safePartName(target));
+    }
+    const resolveRef = (name) => crosswalked.get(name) ?? null;
     for (const [component, entry] of Object.entries(read)) {
-        const parts = entry?.parts;
-        if (!Array.isArray(parts) || parts.length === 0)
+        const anatomy = entry?.anatomy;
+        const resolved = Array.isArray(anatomy) && anatomy.length > 0
+            ? resolveAnatomy(anatomy, declared, deps, resolveRef, entry?.root)
+            : Array.isArray(entry?.parts) && entry.parts.length > 0
+                ? resolveFlatParts(entry.parts, declared)
+                : null;
+        if (!resolved)
             continue;
-        const resolved = transcribeParts(parts, declared);
-        if (Object.keys(resolved).length === 0)
+        const hasParts = Object.keys(resolved.parts).length > 0;
+        if (!hasParts && resolved.tree.length === 0)
             continue;
         const look = looks[component];
+        const carried = {
+            ...(hasParts ? { parts: resolved.parts } : {}),
+            ...(resolved.tree.length > 0 ? { tree: resolved.tree } : {}),
+            ...(resolved.composes.length > 0 ? { composes: resolved.composes } : {}),
+            ...(resolved.external.length > 0 ? { external: resolved.external } : {}),
+            ...(resolved.root ? { root: resolved.root } : {}),
+        };
         looks[component] = look
-            ? { ...look, parts: { ...(look.parts ?? {}), ...resolved } }
+            ? {
+                ...look,
+                ...carried,
+                ...(hasParts
+                    ? { parts: { ...(look.parts ?? {}), ...resolved.parts } }
+                    : {}),
+            }
             : {
                 base: {},
                 dark: {},
@@ -926,14 +978,37 @@ function resolveReadParts(census) {
                 literals: [],
                 fromToken: 0,
                 fromLiteral: 0,
-                parts: resolved,
+                ...carried,
             };
-        named += Object.keys(resolved).length;
+        named += Object.keys(resolved.parts).length;
+        if (resolved.tree.length > 0)
+            shaped += 1;
+        edges += resolved.composes.length;
+        for (const e of resolved.external)
+            libs.add(e.from);
+        for (const n of resolved.notes)
+            notes.add(n);
     }
-    if (named > 0) {
+    const total = Object.keys(read).length;
+    if (named > 0 || shaped > 0) {
         console.log("");
-        console.log(body(`${named} part${named === 1 ? "" : "s"} your reading named across ${Object.keys(read).length} component${Object.keys(read).length === 1 ? "" : "s"} - each previews as what it IS rather than as a text box`));
+        console.log(body(`${named} part${named === 1 ? "" : "s"} your reading named across ${total} component${total === 1 ? "" : "s"} - each previews as what it IS rather than as a text box`));
+    }
+    if (shaped > 0) {
+        console.log(body(`${shaped} of them arrived with a SHAPE - the parts nested as they nest in your code, so the preview is the component and not a row of labels`));
+    }
+    // A frontier is worth its own line, because it is the half nobody else has:
+    // the edge is a rule an agent can obey, not a picture.
+    if (edges > 0) {
+        console.log(body(`${edges} place${edges === 1 ? "" : "s"} where one of your components is built out of another - ${edges === 1 ? "it becomes a rule" : "each becomes a rule"} about the two of them, not a guess`));
+    }
+    if (libs.size > 0) {
+        const named_ = [...libs].slice(0, 3).join(", ");
+        console.log(body(`${libs.size} librar${libs.size === 1 ? "y" : "ies"} your components need (${named_}) - ${libs.size === 1 ? "it does" : "they do"} not render here, and what to know about ${libs.size === 1 ? "it" : "them"} travels as rules`));
     }
+    // NO SILENT FIX. A correction made quietly is a lie about what they wrote.
+    for (const n of notes)
+        console.log(body(n));
 }
 export async function runImport(opts) {
     const root = opts.root ?? process.cwd();
@@ -981,7 +1056,7 @@ export async function runImport(opts) {
          * Resolved here rather than at measure time because the reading arrives
          * AFTER the census was taken - this is the first moment both halves exist.
          */
-        resolveReadParts(census);
+        await resolveReadParts(census, root);
     }
     else {
         console.log(section("Reading your project"));

package/dist/commands/mcp.js

@@ -65,6 +65,20 @@ const TOOLS = [
         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: "describe_component",
+        description: "Everything the system knows about ONE component: what it is made of, what it composes, WHICH LIBRARIES IT NEEDS, and the rules that govern it. Call this before writing code that uses a component - `list_components` gives you a name and a sentence, and a name does not tell you that the editor needs @tiptap/react or that a card is built out of a metric card.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Component name from list_components.",
+                },
+            },
+            required: ["name"],
+        },
+    },
     {
         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.",
@@ -191,6 +205,109 @@ async function listComponents(root) {
         ...rows.sort(),
     ].join("\n");
 }
+/**
+ * ONE COMPONENT, IN FULL - the round trip that did not exist.
+ *
+ * `list_components` returns a name and a description, so an agent building with
+ * `ds-text-editor` had no way to know it needs `@tiptap/react` before writing the
+ * first line. The anatomy, the composition chain and the required libraries are all
+ * in the installed contract; nothing was asking for them.
+ *
+ * It is also the confirmation the skill never had. After an import, reading this
+ * back says what the platform UNDERSTOOD - so a reading that came out thin is
+ * visible instead of being discovered later in a preview.
+ */
+async function describeComponent(root, name) {
+    const { documents, requires } = await loadSystem(root);
+    let recipe;
+    for (const doc of documents) {
+        const d = doc;
+        recipe = d.components?.[name] ?? d.blocks?.[name];
+        if (recipe)
+            break;
+    }
+    if (!recipe) {
+        return `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`;
+    }
+    const out = [
+        `${name}${recipe.description ? ` - ${recipe.description}` : ""}`,
+    ];
+    // WHAT IT SITS ON. 17 of 23 components in a real library carry no surface of
+    // their own, because the surface belongs to what they return.
+    const p = recipe.preview;
+    if (p?.rootRef) {
+        out.push("", `Sits on: ${p.rootRef}${p.rootName && p.rootName !== p.rootRef ? ` (your ${p.rootName})` : ""} - its background, border and radius come from there, not from this component.`);
+    }
+    else if (p?.rootFrom) {
+        out.push("", `Sits on: ${p.rootFrom} - a third-party root. Its markup and behaviour are that library's.`);
+    }
+    // WHAT IT IS MADE OF, and where it ends.
+    const composes = [];
+    const libs = [];
+    const shape = [];
+    const walk = (nodes, depth) => {
+        for (const raw of nodes) {
+            const n = raw;
+            const pad = "  ".repeat(depth + 1);
+            if (n.as === "component" && n.ref) {
+                shape.push(`${pad}<${n.ref}>${n.refName && n.refName !== n.ref ? `  (your ${n.refName})` : ""}`);
+                if (!composes.includes(n.ref))
+                    composes.push(n.ref);
+            }
+            else if (n.as === "external" && n.from) {
+                shape.push(`${pad}${n.from}  (third party - not ours to render)`);
+                if (!libs.includes(n.from))
+                    libs.push(n.from);
+            }
+            else {
+                shape.push(`${pad}${n.as}${n.part ? ` .${name}-${n.part}` : ""}`);
+            }
+            if (Array.isArray(n.children))
+                walk(n.children, depth + 1);
+        }
+    };
+    if (Array.isArray(p?.parts) && p.parts.length > 0) {
+        walk(p.parts, 0);
+        out.push("", "Made of:", ...shape);
+    }
+    else if (recipe.parts && Object.keys(recipe.parts).length > 0) {
+        out.push("", `Parts: ${Object.keys(recipe.parts).join(", ")} - compose them inside it.`);
+    }
+    if (composes.length > 0) {
+        out.push("", `Built out of: ${composes.join(", ")}. Change one of those in one place rather than reproducing it here, and call describe_component on it before you do.`);
+    }
+    /**
+     * WHAT IT NEEDS INSTALLED - the whole reason this tool earns its place.
+     *
+     * From `requires.json`, filtered by the stack at install time, so the answer is
+     * about THIS project. Never installs: a dependency has a licence, a bundle cost
+     * and a maintainer attached, so the agent reports and the person decides.
+     */
+    const needed = requires.filter((r) => (r.applies ?? []).includes(name));
+    if (needed.length > 0 || libs.length > 0) {
+        const named = [
+            ...new Set([...needed.map((r) => r.requires), ...libs]),
+        ];
+        out.push("", `Needs installed: ${named.join(", ")}.`, "Check the manifest before you write against it. If it is missing, say so and ASK - do not install it yourself.");
+        for (const r of needed) {
+            if (r.pinned)
+                out.push(`  ${r.requires}  ${r.pinned}`);
+        }
+    }
+    // THE RULES, scoped. A relation names both, which is what an agent needs in
+    // order not to assemble it wrongly.
+    const laws = [...(recipe.usage ?? [])];
+    if (laws.length > 0) {
+        out.push("", "Rules for this component:", ...laws.map((l) => `  ${l}`));
+    }
+    if (needed.length > 0) {
+        out.push(...needed.map((r) => `  ${r.text}`));
+    }
+    if (laws.length === 0 && needed.length === 0) {
+        out.push("", "No rules govern this component yet. Build with it, and if you find yourself working around it, file request_component with the reasoning.");
+    }
+    return out.join("\n");
+}
 async function addComponent(root, name) {
     const { table } = await loadSystem(root);
     if (!table.slug)
@@ -207,6 +324,8 @@ async function callTool(root, name, args) {
             return text(await findToken(root, String(args.value ?? "")));
         case "list_components":
             return text(await listComponents(root));
+        case "describe_component":
+            return text(await describeComponent(root, String(args.name ?? "")));
         case "add_component":
             return text(await addComponent(root, String(args.name ?? "")));
         case "request_component": {

package/dist/commands/refit.js

@@ -3,6 +3,7 @@ import { basename, join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { body, section, snippet } from "../output.js";
+import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
 import { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
 /** Slugs INSTALLED under `_synthesisui/ds/` (a `.lock` marks a real install -
  *  a folder holding only refit artifacts doesn't count). */
@@ -132,7 +133,7 @@ export async function refit(file, opts) {
     if (config.target === "next") {
         const compDir = join(root, config.componentsDir, res.name);
         await mkdir(compDir, { recursive: true });
-        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, saved.version, config.styles);
+        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, saved.version, config.styles, await reactMajorOf(root), await readInstalledConvention(root, slug));
         for (const f of files) {
             await writeFile(join(compDir, f.filename), f.code, "utf8");
         }

package/dist/commands/upgrade.js

@@ -4,6 +4,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
 import { body, section, snippet } from "../output.js";
+import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
 /**
@@ -151,7 +152,11 @@ export async function upgrade(slug, opts) {
                 continue;
             try {
                 const res = await fetchComponent(base, slug, entry);
-                const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles);
+                const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles, 
+                // Both were missing here, and `upgrade` is the command that REWRITES
+                // components somebody already has: without the convention it would have
+                // taken a working component and stripped its styles.
+                await reactMajorOf(root), res.classNames ?? (await readInstalledConvention(root, slug)));
                 for (const file of files) {
                     await writeFile(join(componentsRoot, entry, file.filename), file.code, "utf8");
                 }