synthesisui 0.4.4 → 0.4.6

package/dist/claude-md.js

@@ -26,23 +26,83 @@ async function readInstalled(projectRoot) {
     }
     return locks;
 }
-function renderRegion(installed) {
+/** First sentence of a description, capped - the manifest must stay lean. */
+function summarize(desc) {
+    if (typeof desc !== "string" || !desc.trim())
+        return "";
+    const first = desc.trim().split(/(?<=\.)\s/)[0] ?? desc.trim();
+    return first.length > 90 ? `${first.slice(0, 87)}…` : first;
+}
+/** One manifest line per recipe: name, what it is, and its variant axes. */
+function catalogLines(recipes) {
+    return Object.entries(recipes)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, recipe]) => {
+        const r = recipe;
+        const axes = Object.entries(r.variants ?? {})
+            .map(([axis, options]) => {
+            const keys = Object.keys(options);
+            return keys.length <= 4 ? `${axis}: ${keys.join("|")}` : axis;
+        })
+            .join("; ");
+        const desc = summarize(r.description);
+        return {
+            name,
+            line: `  - \`ds-${name}\`${desc ? ` - ${desc}` : ""}${axes ? ` [${axes}]` : ""}`,
+        };
+    });
+}
+/**
+ * The COMPONENT MANIFEST for one installed system, read from its versioned
+ * design-system.json. This is what lets the app's agent know what it already
+ * HAS - "use these before creating new ones" - instead of re-inventing
+ * buttons. Returns null when the document isn't readable (older installs).
+ */
+async function readManifest(projectRoot, ds) {
+    try {
+        const raw = await readFile(join(projectRoot, "_synthesisui", "ds", ds.slug, `v${ds.version}`, "design-system.json"), "utf8");
+        const doc = JSON.parse(raw);
+        const components = catalogLines(doc.components ?? {});
+        const blocks = catalogLines(doc.blocks ?? {});
+        if (components.length === 0 && blocks.length === 0)
+            return null;
+        const lines = [];
+        if (components.length > 0) {
+            lines.push(`  Components (${components.length}) - USE these before creating new ones:`);
+            lines.push(...components.map((c) => c.line));
+        }
+        if (blocks.length > 0) {
+            lines.push(`  Engagement blocks (${blocks.length}):`);
+            lines.push(...blocks.map((c) => c.line));
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return null;
+    }
+}
+async function renderRegion(projectRoot, installed) {
     if (installed.length === 0) {
         return `${START}\n${END}`;
     }
-    const lines = installed
-        .map((ds) => `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``)
-        .join("\n");
+    const sections = [];
+    for (const ds of installed) {
+        const head = `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``;
+        const manifest = await readManifest(projectRoot, ds);
+        sections.push(manifest ? `${head}\n${manifest}` : head);
+    }
     const body = `## Design Systems (via SynthesisUI)
 
 This project uses design system(s) brought in by the \`synthesisui\` CLI. **When creating or editing
 components, read the system's GUIDE.md and follow it:** use only semantic tokens
 (\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), scope the UI with \`data-ds="<slug>"\`,
-and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale. **To review a
+and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale. **Before
+creating any UI element, check the component manifest below - if it exists, use or extend
+it (\`synthesisui component <slug> <name>\` materializes it as your code).** To review a
 component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
-apply it to real production pages unless asked.**
+apply it to real production pages unless asked.
 
-${lines}
+${sections.join("\n")}
 
 _Block managed by the CLI - do not edit by hand; run \`synthesisui add <slug>\` to update._`;
     return `${START}\n${body}\n${END}`;
@@ -54,7 +114,7 @@ _Block managed by the CLI - do not edit by hand; run \`synthesisui add <slug>\`
  */
 export async function syncClaudeMd(projectRoot) {
     const installed = await readInstalled(projectRoot);
-    const region = renderRegion(installed);
+    const region = await renderRegion(projectRoot, installed);
     const path = join(projectRoot, "CLAUDE.md");
     let existing = null;
     try {

package/dist/commands/upgrade.js

@@ -2,6 +2,7 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 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 { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
@@ -85,11 +86,29 @@ export async function upgrade(slug, opts) {
             }
         }
     }
-    // 3. deterministic changelog → UPGRADE.md (the agent's migration brief)
-    const log = await fetchChangelog(base, slug, installed, latest.version);
+    // 3. deterministic changelog → UPGRADE.md (the agent's migration brief).
+    //    Diffed against the LOCALLY installed snapshot: personal systems mutate
+    //    their working draft in place under a version number, so the server's
+    //    vN may have moved since this app installed it ("draft drift") - a
+    //    server-side history diff can be empty while this app's files differ.
+    //    Fallback to the server changelog if the local snapshot is unreadable.
+    let markdown;
+    let breaking;
+    try {
+        const beforeDoc = JSON.parse(await readFile(join(slugDir, `v${installed}`, "design-system.json"), "utf8"));
+        const afterDoc = JSON.parse(await readFile(join(slugDir, `v${latest.version}`, "design-system.json"), "utf8"));
+        const local = diffLocalDocuments(beforeDoc, afterDoc);
+        markdown = localChangelogMarkdown(slug, installed, latest.version, local);
+        breaking = local.breaking;
+    }
+    catch {
+        const log = await fetchChangelog(base, slug, installed, latest.version);
+        markdown = log.markdown;
+        breaking = log.changelog.breaking;
+    }
     const upgradePath = join(slugDir, "UPGRADE.md");
     const brief = [
-        log.markdown,
+        markdown,
         "",
         "---",
         "",
@@ -110,10 +129,10 @@ export async function upgrade(slug, opts) {
     await writeFile(upgradePath, brief, "utf8");
     // ── report ──
     console.log(section(`Upgraded ${slug}: v${installed} → v${latest.version}`));
-    if (log.changelog.breaking.length > 0) {
-        console.log(body(`Breaking changes (${log.changelog.breaking.length}):`));
+    if (breaking.length > 0) {
+        console.log(body(`Breaking changes (${breaking.length}):`));
         console.log("");
-        console.log(snippet(log.changelog.breaking.map((item) => `- ${item}`)));
+        console.log(snippet(breaking.map((item) => `- ${item}`)));
     }
     else {
         console.log(body("No breaking changes detected."));

package/dist/document-diff.js

@@ -0,0 +1,174 @@
+/**
+ * LOCAL document diff for `upgrade` - computed against the design-system.json
+ * snapshots on disk, not against the server's version history.
+ *
+ * Why local: personal design systems mutate their WORKING DRAFT in place under
+ * a fixed version number; only publishing freezes it. So the server's "v3" may
+ * have moved since this app installed it ("draft drift"), and a server-side
+ * v3→v4 changelog can be legitimately empty while the app's files differ. The
+ * app's truth is what it has installed - so that's what we diff.
+ */
+/** Flatten a token subtree into `prefix.path → value` leaves. */
+function flattenTokens(prefix, value, out) {
+    if (value == null)
+        return;
+    if (typeof value === "string" || typeof value === "number") {
+        out.set(prefix, String(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => flattenTokens(`${prefix}.${i}`, v, out));
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            flattenTokens(prefix ? `${prefix}.${k}` : k, v, out);
+        }
+    }
+}
+/** Key-order-insensitive equality (JSON docs round-trip with unstable order). */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (a && b && typeof a === "object") {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        if (ka.length !== kb.length)
+            return false;
+        return ka.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/** Variant options that existed and disappeared (breaking for the consumer). */
+function removedVariantOptions(before, after) {
+    const out = [];
+    const prevVariants = (before.variants ?? {});
+    const nextVariants = (after.variants ?? {});
+    for (const [axis, options] of Object.entries(prevVariants)) {
+        const nextAxis = nextVariants[axis];
+        if (!nextAxis) {
+            out.push(axis);
+            continue;
+        }
+        for (const option of Object.keys(options)) {
+            if (!(option in nextAxis))
+                out.push(`${axis}="${option}"`);
+        }
+    }
+    return out;
+}
+function diffRecipeMaps(before, after, label, breaking) {
+    const out = [];
+    const names = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const name of [...names].sort()) {
+        const prev = before[name];
+        const next = after[name];
+        if (!prev) {
+            out.push({ name, kind: "added" });
+            continue;
+        }
+        if (!next) {
+            out.push({ name, kind: "removed" });
+            breaking.push(`${label} "${name}" was removed`);
+            continue;
+        }
+        if (deepEqual(prev, next))
+            continue;
+        out.push({ name, kind: "changed" });
+        for (const gone of removedVariantOptions(prev, next)) {
+            breaking.push(`${label} "${name}" no longer supports ${gone}`);
+        }
+    }
+    return out;
+}
+/** Diff two installed design-system.json documents (token + recipe level). */
+export function diffLocalDocuments(before, after) {
+    const breaking = [];
+    const prevTokens = new Map();
+    const nextTokens = new Map();
+    flattenTokens("", before.foundations, prevTokens);
+    flattenTokens("motion", before.motion, prevTokens);
+    flattenTokens("", after.foundations, nextTokens);
+    flattenTokens("motion", after.motion, nextTokens);
+    const tokens = [];
+    const paths = new Set([...prevTokens.keys(), ...nextTokens.keys()]);
+    for (const path of [...paths].sort()) {
+        const prev = prevTokens.get(path);
+        const next = nextTokens.get(path);
+        if (prev === next)
+            continue;
+        if (prev === undefined)
+            tokens.push({ path, after: next, kind: "added" });
+        else if (next === undefined) {
+            tokens.push({ path, before: prev, kind: "removed" });
+            breaking.push(`token "${path}" was removed`);
+        }
+        else
+            tokens.push({ path, before: prev, after: next, kind: "changed" });
+    }
+    const components = diffRecipeMaps((before.components ?? {}), (after.components ?? {}), "component", breaking);
+    const blocks = diffRecipeMaps((before.blocks ?? {}), (after.blocks ?? {}), "block", breaking);
+    return {
+        tokens,
+        components,
+        blocks,
+        breaking,
+        isEmpty: tokens.length === 0 && components.length === 0 && blocks.length === 0,
+    };
+}
+const CAP_TOKENS = 40;
+/** The migration brief body, mirroring the server changelog's format. */
+export function localChangelogMarkdown(slug, from, to, log) {
+    const lines = [
+        `# ${slug} - v${from} → v${to}`,
+        "",
+        `_Diffed against this app's installed v${from} snapshot (the app's truth) -`,
+        "personal systems can evolve in place under a version, so a server-side",
+        "history diff may miss what changed HERE._",
+        "",
+    ];
+    if (log.isEmpty) {
+        lines.push("No visual-contract changes for this app.", "");
+        return lines.join("\n");
+    }
+    if (log.breaking.length > 0) {
+        lines.push("## Breaking", "");
+        for (const item of log.breaking)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (log.tokens.length > 0) {
+        lines.push(`## Tokens (${log.tokens.length} change(s))`, "");
+        for (const t of log.tokens.slice(0, CAP_TOKENS)) {
+            const val = t.kind === "removed"
+                ? `removed (was \`${t.before}\`)`
+                : t.kind === "added"
+                    ? `added: \`${t.after}\``
+                    : `\`${t.before}\` → \`${t.after}\``;
+            lines.push(`- ${t.path}: ${val}`);
+        }
+        if (log.tokens.length > CAP_TOKENS) {
+            lines.push(`- …and ${log.tokens.length - CAP_TOKENS} more`);
+        }
+        lines.push("");
+    }
+    for (const [title, entries] of [
+        ["Components", log.components],
+        ["Blocks", log.blocks],
+    ]) {
+        if (entries.length === 0)
+            continue;
+        lines.push(`## ${title}`, "");
+        for (const entry of entries)
+            lines.push(`- \`ds-${entry.name}\` - ${entry.kind}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {