synthesisui 0.2.1 → 0.3.0

package/dist/commands/add.js

@@ -110,6 +110,8 @@ export async function add(slug, opts) {
         console.log(`  philosophy.md → ${sections.length} section(s) (read after rules)`);
     }
     console.log(`  CLAUDE.md ${claudeMd.created ? "created" : "updated"} (${claudeMd.count} system(s) installed)`);
+    if (opts.setupHints === false)
+        return;
     const hasTheme = cssArtifacts.includes("theme.css");
     // ── DX: concrete paths + copy-pasteable snippets, with breathing room ──
     console.log(section("One-time setup (once per app)"));

package/dist/commands/upgrade.js

@@ -0,0 +1,140 @@
+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 { body, section, snippet } from "../output.js";
+import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
+import { add } from "./add.js";
+/**
+ * Marco B - `synthesisui upgrade <slug>`: brings the installed system to the
+ * latest version, GUIDED. In one run it:
+ *
+ * 1. compares the installed version (`_synthesisui/ds/<slug>/.lock`) with the
+ *    registry's latest and re-materializes the artifacts (same flow as `add`;
+ *    the previous version folder stays for rollback/diff);
+ * 2. REGENERATES every component previously materialized into componentsDir
+ *    from this system (detected by the generated-file header), so YOUR
+ *    components pick up the new recipes;
+ * 3. fetches the deterministic changelog (computed server-side) and writes it
+ *    to `_synthesisui/ds/<slug>/UPGRADE.md` - the migration brief your agent
+ *    walks to update the app (breaking changes first).
+ */
+export async function upgrade(slug, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    const slugDir = join(root, "_synthesisui", "ds", slug);
+    // installed version - upgrade only makes sense over an existing install
+    let installed;
+    try {
+        const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8"));
+        if (!Number.isInteger(lock.version))
+            throw new Error("no version");
+        installed = lock.version;
+    }
+    catch {
+        throw new RegistryError(`"${slug}" is not installed here - run \`synthesisui add ${slug}\` first.`);
+    }
+    console.log(`→ checking "${slug}" (installed: v${installed}) …`);
+    const latest = await fetchDesignSystem(base, slug);
+    if (latest.version === installed) {
+        console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+        return;
+    }
+    if (latest.version < installed) {
+        console.log(`✓ ${slug} v${installed} is newer than the registry's v${latest.version} - nothing to do.`);
+        return;
+    }
+    // 1. re-materialize the artifacts (v<latest>/ + root re-exports + .lock);
+    //    setup hints suppressed - an upgrade means the app is already wired.
+    await add(slug, { registry: opts.registry, dir: root, setupHints: false });
+    // 2. regenerate YOUR materialized components (the ones `component` wrote)
+    const config = await readProjectConfig(root);
+    const regenerated = [];
+    const failed = [];
+    if (config.target === "next") {
+        const componentsRoot = join(root, config.componentsDir);
+        const marker = `from the "${slug}" design system`;
+        let entries = [];
+        try {
+            entries = await readdir(componentsRoot);
+        }
+        catch {
+            // no componentsDir yet - nothing materialized
+        }
+        for (const entry of entries) {
+            const tsxPath = join(componentsRoot, entry, `${entry}.tsx`);
+            let head = "";
+            try {
+                head = (await readFile(tsxPath, "utf8")).slice(0, 300);
+            }
+            catch {
+                continue; // not a materialized component folder
+            }
+            if (!head.includes("Generated by SynthesisUI") || !head.includes(marker))
+                continue;
+            try {
+                const res = await fetchComponent(base, slug, entry);
+                const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles);
+                for (const file of files) {
+                    await writeFile(join(componentsRoot, entry, file.filename), file.code, "utf8");
+                }
+                regenerated.push(entry);
+            }
+            catch {
+                failed.push(entry); // e.g. component renamed/removed in the new version
+            }
+        }
+    }
+    // 3. deterministic changelog → UPGRADE.md (the agent's migration brief)
+    const log = await fetchChangelog(base, slug, installed, latest.version);
+    const upgradePath = join(slugDir, "UPGRADE.md");
+    const brief = [
+        log.markdown,
+        "",
+        "---",
+        "",
+        "## How to migrate this app",
+        "",
+        "- Fix the **Breaking** items first: search the codebase for each removed",
+        "  token/component/variant and move usages to the closest replacement.",
+        "- Changed tokens re-theme automatically (CSS variables) - review screens",
+        "  that hardcoded values instead of tokens.",
+        regenerated.length > 0
+            ? `- These materialized components were regenerated and may show in your diff: ${regenerated
+                .map((n) => `\`${n}\``)
+                .join(", ")}.`
+            : "- No materialized components needed regeneration.",
+        "- The full new contract lives in `design-system.json` / `GUIDE.md` next to this file.",
+        "",
+    ].join("\n");
+    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}):`));
+        console.log("");
+        console.log(snippet(log.changelog.breaking.map((item) => `- ${item}`)));
+    }
+    else {
+        console.log(body("No breaking changes detected."));
+    }
+    if (regenerated.length > 0) {
+        console.log("");
+        console.log(body(`Regenerated ${regenerated.length} materialized component(s): ${regenerated.join(", ")}`));
+    }
+    if (failed.length > 0) {
+        console.log("");
+        console.log(body(`⚠ Could not regenerate: ${failed.join(", ")} (removed/renamed in v${latest.version}?)`));
+    }
+    console.log(section("Migrate the app"));
+    console.log(body(`The migration brief is at _synthesisui/ds/${slug}/UPGRADE.md`));
+    console.log("");
+    console.log(body("Ask your agent:"));
+    console.log(snippet([
+        `"Read _synthesisui/ds/${slug}/UPGRADE.md and migrate this app to ${slug} v${latest.version} -`,
+        ` fix the breaking changes first, then review the changed components."`,
+    ]));
+    console.log("");
+    console.log(body(`(rollback: synthesisui add ${slug} --version ${installed})`));
+    console.log("");
+}

package/dist/index.js

@@ -7,6 +7,7 @@ import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
 import { template } from "./commands/template.js";
+import { upgrade } from "./commands/upgrade.js";
 import { use } from "./commands/use.js";
 import { RegistryError } from "./registry.js";
 const HELP = `synthesisui - bring SynthesisUI design systems into your project
@@ -18,6 +19,7 @@ Usage:
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
   synthesisui template <slug> <name>       materialize a whole page from a DS template
   synthesisui component <slug> <name>      bring one component in - artifacts + YOUR <Pascal>.tsx in componentsDir
+  synthesisui upgrade <slug>               update an installed DS + regenerate your components + migration brief
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui advise "<value prop>"        engagement-pattern proposals for this project (login required)
   synthesisui generate "<desc>"            generate a token-only component recipe for your DS (login required)
@@ -192,6 +194,16 @@ async function main() {
             });
             break;
         }
+        case "upgrade": {
+            const slug = args[0];
+            if (!slug) {
+                console.error("error: provide the slug - `synthesisui upgrade <slug>`");
+                process.exitCode = 1;
+                return;
+            }
+            await upgrade(slug, { registry, dir });
+            break;
+        }
         case "use": {
             const slug = args[0];
             if (!slug) {

package/dist/registry.js

@@ -136,3 +136,17 @@ export async function postGenerate(base, payload) {
     }
     return (await res.json());
 }
+/** Changelog determinístico entre duas versões (Marco B) - `?changelog&from=N`. */
+export async function fetchChangelog(base, slug, from, to) {
+    const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+    url.searchParams.set("changelog", "");
+    url.searchParams.set("from", String(from));
+    if (to != null)
+        url.searchParams.set("to", String(to));
+    const res = await request(url.toString());
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ?? `Registry responded ${res.status} for the changelog.`);
+    }
+    return (await res.json());
+}

package/package.json

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