synthesisui 0.2.1 → 0.4.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/refit.js

@@ -0,0 +1,144 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+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 { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
+/** Slugs materialized under `_synthesisui/ds/` in the project. */
+async function installedSlugs(root) {
+    try {
+        const entries = await readdir(join(root, "_synthesisui", "ds"), {
+            withFileTypes: true,
+        });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Marco B5 - the REVERSE bridge, from the CLI: takes a component that lives in
+ * YOUR app (arbitrary React/CSS), re-expresses it in the design system's
+ * token vocabulary (hosted refit - gated + metered), SAVES it into your
+ * personal DS draft (it ships with the next `publish`), and materializes it
+ * back into componentsDir as your typed component. One command closes the
+ * loop: app code → on-system recipe → back as code.
+ */
+export async function refit(file, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    // 1. the source component (the server caps at 24k chars - fail fast here)
+    let source;
+    try {
+        source = await readFile(join(root, file), "utf8");
+    }
+    catch {
+        throw new RegistryError(`Could not read "${file}".`);
+    }
+    if (source.trim().length === 0) {
+        throw new RegistryError(`"${file}" is empty.`);
+    }
+    if (source.length > 24_000) {
+        throw new RegistryError(`"${file}" is ${source.length} chars - the refit cap is 24k. Trim it to the component itself.`);
+    }
+    let support;
+    if (opts.support) {
+        try {
+            support = await readFile(join(root, opts.support), "utf8");
+        }
+        catch {
+            throw new RegistryError(`Could not read support file "${opts.support}".`);
+        }
+    }
+    // 2. target DS (same inference as `generate`: the single installed one)
+    let slug = opts.ds;
+    if (!slug) {
+        const slugs = await installedSlugs(root);
+        if (slugs.length === 1)
+            slug = slugs[0];
+        else if (slugs.length === 0)
+            throw new RegistryError("No design system installed here. Run `synthesisui add <slug>` first, or pass --ds <slug>.");
+        else
+            throw new RegistryError(`Multiple design systems installed (${slugs.join(", ")}). Pick one with --ds <slug>.`);
+    }
+    // 3. replace mode: fetch the existing recipe so the server keeps its name
+    //    (deterministic - the AI is not trusted with it)
+    let prior;
+    if (opts.replace) {
+        const existing = await fetchComponent(base, slug, opts.replace);
+        prior = { name: existing.name, recipe: existing.recipe };
+    }
+    console.log(`→ refitting ${basename(file)} into "${slug}"${prior ? ` (replacing ds-${prior.name})` : ""} …`);
+    const instruction = [
+        opts.instruction,
+        !prior && opts.name ? `Name it "${opts.name}".` : undefined,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    const res = await postRefit(base, {
+        slug,
+        source,
+        support,
+        instruction: instruction || undefined,
+        prior,
+    });
+    const tries = `${res.tries} ${res.tries === 1 ? "try" : "tries"}`;
+    console.log(`✓ adapted as ds-${res.name} (${res.model}, ${tries})`);
+    if (opts.dry) {
+        console.log(section("Dry run - nothing saved"));
+        console.log(body("The recipe it would save:"));
+        console.log("");
+        console.log(snippet(JSON.stringify(res.recipe, null, 2).split("\n")));
+        console.log("");
+        return;
+    }
+    // 4. save into the personal DS draft (server re-validates token-only)
+    const saved = await postSaveComponent(base, {
+        slug,
+        name: res.name,
+        recipe: res.recipe,
+    });
+    console.log(`✓ saved into "${slug}" (draft v${saved.version} - ships with your next publish)`);
+    // 5. materialize back into the project: artifacts + YOUR typed component
+    const artifactsDir = join(root, "_synthesisui", "ds", slug, "components");
+    await mkdir(artifactsDir, { recursive: true });
+    await writeFile(join(artifactsDir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
+    await writeFile(join(artifactsDir, `${res.name}.css`), `${res.css}\n`, "utf8");
+    const config = await readProjectConfig(root);
+    let materialized = false;
+    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);
+        for (const f of files) {
+            await writeFile(join(compDir, f.filename), f.code, "utf8");
+        }
+        materialized = true;
+        console.log(`✓ ${config.componentsDir}/${res.name}/ → ${files.map((f) => f.filename).join(", ")}  (styles: ${config.styles})`);
+    }
+    if (res.suggestedRule) {
+        console.log(section("Suggested rule"));
+        console.log(body("The AI inferred a reusable rule from this component:"));
+        console.log("");
+        console.log(snippet([`"${res.suggestedRule}"`]));
+        console.log("");
+        console.log(body(`(save it in the studio if it holds: /dashboard/mine/${slug}/studio)`));
+    }
+    console.log(section("Done - the loop is closed"));
+    console.log(body(`Your component now lives in the design system (docs, studio, showcase)`));
+    if (materialized) {
+        const pascal = res.name
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        console.log(body(`and back in your code, on-system:`));
+        console.log("");
+        console.log(snippet([
+            `import { ${pascal} } from "@/${config.componentsDir}/${res.name}";`,
+        ]));
+        console.log("");
+        console.log(body(`(replace the old ${basename(file)} usages with it when you're ready)`));
+    }
+    console.log("");
+}

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

@@ -6,7 +6,9 @@ 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 { refit } from "./commands/refit.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 +20,8 @@ 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 refit <file> [--ds <slug>]   send an app component INTO your DS (token-only) and get it back as code
   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)
@@ -33,6 +37,10 @@ Options:
   --components-dir <dir>  init: folder where components live (default: components)
   --styles <s>       init: component code flavor: css | tailwind (default: css)
   --artifacts-only   component: skip the .tsx materialization (recipe + css only)
+  --replace <name>   refit: replace an existing DS component (keeps its name)
+  --support <file>   refit: supporting CSS file (globals/vars the code references)
+  --instruction <s>  refit: extra guidance for the adaptation
+  --dry              refit: adapt and print, but save nothing
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
@@ -192,6 +200,35 @@ async function main() {
             });
             break;
         }
+        case "refit": {
+            const file = args[0];
+            if (!file) {
+                console.error("error: provide the component file - `synthesisui refit <file> [--ds <slug>]`");
+                process.exitCode = 1;
+                return;
+            }
+            await refit(file, {
+                registry,
+                dir,
+                ds: typeof flags.ds === "string" ? flags.ds : undefined,
+                name: typeof flags.name === "string" ? flags.name : undefined,
+                replace: typeof flags.replace === "string" ? flags.replace : undefined,
+                instruction: typeof flags.instruction === "string" ? flags.instruction : undefined,
+                support: typeof flags.support === "string" ? flags.support : undefined,
+                dry: flags.dry === true,
+            });
+            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,71 @@ 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());
+}
+/**
+ * Refit hospedado (INS-18 / Marco B5): manda código de componente arbitrário e
+ * recebe a recipe token-only vestida no DS. Gated + metered server-side:
+ * 401 = sem login, 429 = cota diária.
+ */
+export async function postRefit(base, payload) {
+    let res;
+    try {
+        res = await fetch(`${base}/api/ai/studio`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(await authHeaders()) },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch {
+        throw new RegistryError(`Could not reach the registry at ${base}. ` +
+            `Check the URL (--registry / SYNTHESISUI_REGISTRY_URL) and your connection.`);
+    }
+    if (res.status === 401) {
+        throw new RegistryError("Not authenticated. Run `synthesisui login` first.");
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ?? `Refit responded ${res.status}.`);
+    }
+    return (await res.json());
+}
+/**
+ * Persiste um componente no DS pessoal do usuário autenticado
+ * (`POST /api/ds/component`) - a metade "salvar" da ponte reversa. O servidor
+ * re-valida a recipe (token-only, sem refs órfãs) antes de gravar no rascunho.
+ */
+export async function postSaveComponent(base, payload) {
+    let res;
+    try {
+        res = await fetch(`${base}/api/ds/component`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(await authHeaders()) },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch {
+        throw new RegistryError(`Could not reach the registry at ${base}. ` +
+            `Check the URL (--registry / SYNTHESISUI_REGISTRY_URL) and your connection.`);
+    }
+    if (res.status === 401) {
+        throw new RegistryError("Not authenticated. Run `synthesisui login` first.");
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ?? `Save responded ${res.status}.`);
+    }
+    return (await res.json());
+}

package/package.json

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