synthesisui 0.16.318 → 0.16.319

package/dist/commands/add.js

@@ -308,6 +308,8 @@ export async function add(slug, opts) {
             const reference = lockReference(payload, prev);
             return reference ? { reference } : {};
         })(),
+        /** A memória do que NÓS escrevemos atravessa a re-materialização - ver `RootLock.written`. */
+        ...(prev?.written ? { written: prev.written } : {}),
     };
     const landed = (() => {
         if (!prev?.fetchedAt)

package/dist/commands/component.js

@@ -11,6 +11,7 @@ import { fetchComponent, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { inTheirTongue, projectTongue } from "../their-tongue.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
+import { recordWritten } from "../written.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
  * installed theme.
@@ -219,10 +220,16 @@ export async function component(slug, name, opts) {
             // it wears (.css) + the barrel. Ignores the css|tailwind flavor - the
             // template drives itself off the .ds-* classes.
             const tsx = interactiveTemplate(res.name);
-            await writeFile(join(compDir, `${local}.tsx`), tsx, "utf8");
-            await writeFile(join(compDir, `${local}.css`), `${css}\n`, "utf8");
-            await writeFile(join(compDir, "index.ts"), `export * from "./${local}";\n`, "utf8");
-            filenames = [`${local}.tsx`, `${local}.css`, "index.ts"];
+            const written = [
+                { filename: `${local}.tsx`, content: tsx },
+                { filename: `${local}.css`, content: `${css}\n` },
+                { filename: "index.ts", content: `export * from "./${local}";\n` },
+            ];
+            for (const f of written)
+                await writeFile(join(compDir, f.filename), f.content, "utf8");
+            /** O fingerprint do que escrevemos - é o que protege a edição dele no upgrade (T7). */
+            await recordWritten(join(root, "_synthesisui", "ds", slug), local, written);
+            filenames = written.map((f) => f.filename);
         }
         else {
             const files = generateComponentFiles(slug, res.name, res.recipe, css, res.version, flavour, await reactMajorOf(root), 
@@ -258,12 +265,19 @@ export async function component(slug, name, opts) {
              * sistema não tem censo nenhum, e ele recebe o que sempre recebeu.
              */
             const nota = unreadComment(unreadForComponent(await readCensus(root), res.name));
-            for (const file of files) {
-                await writeFile(join(compDir, file.filename), file.filename.endsWith(".tsx") ? `${nota}${file.code}` : file.code, "utf8");
-            }
+            /** Os bytes finais, para o fingerprint lembrar EXATAMENTE o que foi a disco (T7). */
+            const written = files.map((file) => ({
+                filename: file.filename,
+                content: file.filename.endsWith(".tsx")
+                    ? `${nota}${file.code}`
+                    : file.code,
+            }));
+            for (const f of written)
+                await writeFile(join(compDir, f.filename), f.content, "utf8");
+            await recordWritten(join(root, "_synthesisui", "ds", slug), local, written);
             if (flavour === "tailwind")
                 await writeCn(root, compDir, slug);
-            filenames = files.map((f) => f.filename);
+            filenames = written.map((f) => f.filename);
         }
         const flavor = wantInteractive ? "interactive" : `styles: ${flavour}`;
         console.log(`✓ ${config.componentsDir}/${local}/ → ${filenames.join(", ")}  (${flavor})${local === res.name ? "" : `  - the "${res.name}" blueprint, under your name`}`);

package/dist/commands/generate.js

@@ -6,6 +6,7 @@ import { installedSlugs } from "../installed.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { postGenerate, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
+import { recordWritten } from "../written.js";
 /** PascalCase para o hint de import (course-card → CourseCard). */
 function pascalName(name) {
     return name.replace(/(^|[-_])([a-z0-9])/g, (_, __, c) => c.toUpperCase());
@@ -75,6 +76,8 @@ export async function generate(description, opts) {
         for (const file of files) {
             await writeFile(join(compDir, file.filename), file.code, "utf8");
         }
+        /** O fingerprint do que escrevemos - protege a edição dele no upgrade (T7). */
+        await recordWritten(join(root, "_synthesisui", "ds", slug), res.name, files.map((x) => ({ filename: x.filename, content: x.code })));
         materialized = true;
         console.log(`✓ ${config.componentsDir}/${res.name}/ → ${files.map((f) => f.filename).join(", ")}  (styles: ${config.styles})`);
     }

package/dist/commands/refit.js

@@ -7,6 +7,7 @@ import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
+import { recordWritten } from "../written.js";
 /** Slugs INSTALLED under `_synthesisui/ds/` (a `.lock` marks a real install -
  *  a folder holding only refit artifacts doesn't count). */
 /** True when the system is actually installed (tokens.css present). */
@@ -121,6 +122,8 @@ export async function refit(file, opts) {
         for (const f of files) {
             await writeFile(join(compDir, f.filename), f.code, "utf8");
         }
+        /** O fingerprint do que escrevemos - protege a edição dele no upgrade (T7). */
+        await recordWritten(join(root, "_synthesisui", "ds", slug), res.name, files.map((x) => ({ filename: x.filename, content: x.code })));
         materialized = true;
         console.log(`✓ ${config.componentsDir}/${res.name}/ → ${files.map((f) => f.filename).join(", ")}  (styles: ${config.styles})`);
     }

package/dist/commands/upgrade.js

@@ -11,6 +11,7 @@ import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
+import { editedSinceWritten, keptLine, readWritten, recordWritten, } from "../written.js";
 import { add } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
 import { doctor } from "./doctor.js";
@@ -283,6 +284,9 @@ export async function upgrade(asked, opts) {
     const config = await readProjectConfig(root);
     const regenerated = [];
     const failed = [];
+    /** Componentes que ELE editou desde que os escrevemos - mantidos intactos (T7). */
+    const kept = [];
+    const writtenMap = await readWritten(slugDir);
     if (config.target === "next") {
         const componentsRoot = join(root, config.componentsDir);
         const marker = `from the "${slug}" design system`;
@@ -308,6 +312,17 @@ export async function upgrade(asked, opts) {
             }
             if (!head.includes("Generated by SynthesisUI") || !head.includes(marker))
                 continue;
+            /**
+             * A EDIÇÃO DELE VENCE A REGENERAÇÃO (T7) - ver `written.ts`. O fingerprint do que NÓS
+             * escrevemos foi gravado no `.lock` na hora da escrita; se o disco divergiu, ele editou, e o
+             * arquivo é DELE - fica intacto e o terminal diz qual. `null` é install de antes do
+             * fingerprint: sem memória não há veredito, e o comportamento de sempre continua.
+             */
+            const edited = await editedSinceWritten(writtenMap[entry], join(componentsRoot, entry));
+            if (edited && edited.length > 0) {
+                kept.push({ entry, edited });
+                continue;
+            }
             try {
                 const res = await fetchComponent(base, slug, entry);
                 const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, flavourOf(res.name), 
@@ -325,9 +340,17 @@ export async function upgrade(asked, opts) {
                  * Ver `unread-for-component.ts`: censo ausente responde vazio, e vazio não vira comentário.
                  */
                 const nota = unreadComment(unreadForComponent(await readCensus(root), res.name));
-                for (const file of files) {
-                    await writeFile(join(componentsRoot, entry, file.filename), file.filename.endsWith(".tsx") ? `${nota}${file.code}` : file.code, "utf8");
+                /** Os bytes finais, para o fingerprint lembrar EXATAMENTE o que foi a disco. */
+                const finalFiles = files.map((file) => ({
+                    filename: file.filename,
+                    content: file.filename.endsWith(".tsx")
+                        ? `${nota}${file.code}`
+                        : file.code,
+                }));
+                for (const file of finalFiles) {
+                    await writeFile(join(componentsRoot, entry, file.filename), file.content, "utf8");
                 }
+                await recordWritten(slugDir, entry, finalFiles);
                 regenerated.push(entry);
             }
             catch {
@@ -372,6 +395,13 @@ export async function upgrade(asked, opts) {
                 .map((n) => `\`${n}\``)
                 .join(", ")}.`
             : "- No materialized components needed regeneration.",
+        ...(kept.length > 0
+            ? [
+                `- These components were edited by hand after we wrote them, so the upgrade KEPT your files: ${kept
+                    .map((k) => `\`${k.entry}\``)
+                    .join(", ")}. To take the new version of one, rerun \`npx synthesisui component ${slug} <name>\`.`,
+            ]
+            : []),
         "- The full new contract lives in `design-system.json` / `GUIDE.md` next to this file.",
         "",
     ].join("\n");
@@ -394,6 +424,12 @@ export async function upgrade(asked, opts) {
         console.log("");
         console.log(body(`⚠ Could not regenerate: ${failed.join(", ")} (removed/renamed in v${latest.version}?)`));
     }
+    /** A prova VISÍVEL do T7: o dono fica sabendo AGORA, com o arquivo nomeado e a saída dita. */
+    if (kept.length > 0) {
+        console.log("");
+        for (const k of kept)
+            console.log(body(keptLine(slug, k.entry, k.edited)));
+    }
     await checkAfterWriting(root, `v${latest.version}`);
     console.log(section("Migrate the app"));
     console.log(body(`The migration brief is at _synthesisui/ds/${slug}/UPGRADE.md`));

package/dist/install-marks.js

@@ -137,7 +137,14 @@
  * ali, que é exatamente o que esta marca existe para dizer. Quem avisa versão nova passa a ser o
  * próprio align, com o `cli` que o servidor manda no `?meta=1`.
  */
-export const MATERIALISER_SINCE = "0.16.306";
+/**
+ * 0.16.306 -> 0.16.319 em 26/08 (T7), e o SIM é sobre DUAS coisas que caem na pasta: o `.lock`
+ * ganha `written` (o fingerprint do que NÓS escrevemos, por componente e arquivo) e o `upgrade`
+ * muda QUAIS bytes reescreve - um componente que o dono editou à mão fica INTACTO, com a frase no
+ * terminal dizendo qual arquivo e como tomar a versão nova por escolha. Antes desta versão a
+ * reescrita era incondicional e o único aviso era prosa depois do fato.
+ */
+export const MATERIALISER_SINCE = "0.16.319";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/written.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function fingerprintOf(content) {
+    return createHash("sha256")
+        .update(content, "utf8")
+        .digest("hex")
+        .slice(0, 12);
+}
+/** O mapa gravado, ou vazio - um `.lock` ausente/ilegível responde como install legado. */
+export async function readWritten(slugDir) {
+    try {
+        const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8"));
+        return lock.written ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Grava o fingerprint do que acabou de ser escrito. Lê-modifica-escreve o `.lock` inteiro para
+ * não perder nenhum campo irmão; sem `.lock` (componente materializado antes do install), não há
+ * onde lembrar - silêncio de propósito, o próximo `add` cria o arquivo e o próximo write grava.
+ */
+export async function recordWritten(slugDir, entry, files) {
+    const lockPath = join(slugDir, ".lock");
+    let lock;
+    try {
+        lock = JSON.parse(await readFile(lockPath, "utf8"));
+    }
+    catch {
+        return;
+    }
+    const written = (lock.written ?? {});
+    written[entry] = Object.fromEntries(files.map((f) => [f.filename, fingerprintOf(f.content)]));
+    lock.written = written;
+    await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+/**
+ * QUAIS ARQUIVOS ELE EDITOU desde que nós os escrevemos.
+ *
+ * Um arquivo que sumiu também conta: apagar é uma edição - regenerá-lo desfaria a decisão dele
+ * do mesmo jeito. Devolve vazio quando nada divergiu (nosso para regenerar) e `null` quando não
+ * há fingerprint gravado (install legado - o chamador mantém o comportamento de sempre).
+ */
+export async function editedSinceWritten(recorded, dir) {
+    if (!recorded)
+        return null;
+    const edited = [];
+    for (const [filename, fp] of Object.entries(recorded)) {
+        try {
+            const current = await readFile(join(dir, filename), "utf8");
+            if (fingerprintOf(current) !== fp)
+                edited.push(filename);
+        }
+        catch {
+            edited.push(filename);
+        }
+    }
+    return edited;
+}
+/**
+ * A FRASE DO TERMINAL, uma por componente mantido - o critério do T7 é a prova VISÍVEL: o dono
+ * fica sabendo na hora, com o arquivo nomeado e a saída dita, não num diff depois do fato. A
+ * saída oferecida regenera por ESCOLHA (o `component` reescreve e regrava o fingerprint).
+ */
+export function keptLine(slug, entry, edited) {
+    return (`! ${entry}: you edited ${edited.join(", ")} after we wrote it - kept YOUR file(s).\n` +
+        `  To take the new version anyway: npx synthesisui component ${slug} ${entry}`);
+}

package/package.json

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