synthesisui 0.12.0 → 0.12.1

package/dist/commands/upgrade.js

@@ -6,6 +6,64 @@ 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";
+/**
+ * The highest `v<n>` below `installed` among the folder names given, or the one
+ * asked for. Pure, so the version arithmetic can be tested without a disk.
+ */
+export function pickSnapshot(names, installed, asked) {
+    const versions = names
+        .map((n) => /^v(\d+)$/.exec(n))
+        .filter((m) => m !== null)
+        .map((m) => Number(m[1]))
+        .filter((v) => v < installed)
+        .sort((a, b) => b - a);
+    if (asked !== undefined)
+        return versions.includes(asked) ? asked : null;
+    return versions[0] ?? null;
+}
+/**
+ * Re-diff two snapshots already on disk and rewrite UPGRADE.md. Touches
+ * nothing else: the artifacts are already correct, it is only the brief about
+ * them that was written by an older, wronger version of this tool.
+ */
+async function rewriteBrief(slug, slugDir, from, to) {
+    const read = async (v) => JSON.parse(await readFile(join(slugDir, `v${v}`, "design-system.json"), "utf8"));
+    let local;
+    try {
+        local = diffLocalDocuments(await read(from), await read(to));
+    }
+    catch {
+        console.log(`✗ could not read both snapshots (v${from}, v${to}).`);
+        return;
+    }
+    const brief = [
+        localChangelogMarkdown(slug, from, to, local),
+        "",
+        "---",
+        "",
+        "## 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.",
+        "- The full new contract lives in `design-system.json` / `GUIDE.md` next to this file.",
+        "",
+    ].join("\n");
+    await writeFile(join(slugDir, "UPGRADE.md"), brief, "utf8");
+    console.log(section(`Rewrote the brief: ${slug} v${from} → v${to}`));
+    if (local.breaking.length > 0) {
+        console.log(body(`Breaking changes (${local.breaking.length}):`));
+        console.log("");
+        console.log(snippet(local.breaking.map((i) => `- ${i}`)));
+    }
+    else {
+        console.log(body("No breaking changes between those two versions."));
+    }
+    console.log("");
+    console.log(body(`_synthesisui/ds/${slug}/UPGRADE.md`));
+    console.log("");
+}
 /**
  * Marco B - `synthesisui upgrade <slug>`: brings the installed system to the
  * latest version, GUIDED. In one run it:
@@ -38,7 +96,25 @@ export async function upgrade(slug, opts) {
     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}).`);
+        if (!opts.force) {
+            console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+            return;
+        }
+        // The brief is a PHOTOGRAPH: written once, at the moment of the upgrade,
+        // and it ages. When the tool that wrote it is fixed - as the breaking-change
+        // diff was on 25/07, after it had announced ten changes that were not
+        // breaking - the file on disk keeps the old answer and there is no way back
+        // to it, because there is no version gap left to trigger a rewrite. This is
+        // that way back: re-diff from the highest older snapshot still on disk.
+        const onDisk = await readdir(slugDir).catch(() => []);
+        const from = pickSnapshot(onDisk, installed, opts.from);
+        if (from === null) {
+            console.log(opts.from !== undefined
+                ? `✗ v${opts.from} is not on disk under ${slugDir}.`
+                : `✗ nothing to diff against: no snapshot older than v${installed} on disk.`);
+            return;
+        }
+        await rewriteBrief(slug, slugDir, from, installed);
         return;
     }
     if (latest.version < installed) {

package/dist/index.js

@@ -52,6 +52,8 @@ Options:
   --instruction <s>  refit: extra guidance for the adaptation
   --dry              refit: adapt and print, but save nothing
   --force            clean: apply the changes (without it, dry run)
+                     upgrade: rewrite UPGRADE.md even with no version gap left
+  --from <n>         upgrade --force: which older snapshot to diff from
   --strict           doctor: exit 1 when drift is found in THIS repo (for CI)
   --strict-system    doctor: also exit 1 when the system itself is inconsistent
   --verbose          doctor: every finding, file by file (default is a summary)
@@ -267,7 +269,12 @@ async function main() {
                 process.exitCode = 1;
                 return;
             }
-            await upgrade(slug, { registry, dir });
+            await upgrade(slug, {
+                registry,
+                dir,
+                force: flags.force === true,
+                from: typeof flags.from === "string" ? Number(flags.from) : undefined,
+            });
             break;
         }
         case "use": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {