synthesisui 0.16.318 → 0.16.320

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/ci.js

@@ -46,7 +46,7 @@ export async function ci(opts) {
         console.log(section("The contract"));
         console.log(body("--format=github    annotations on the exact line, always warnings"));
         console.log(body("--format=sarif     for code-scanning or SonarQube, same findings"));
-        console.log(body("--baseline         exit 1 only when drift went UP, in total or in any file"));
+        console.log(body("--baseline         exit 1 only when the count went UP, in total or in any file"));
         console.log(body("--write-baseline   freeze where you are today, and commit it - yesterday's"));
         console.log(body("                   debt stops hurting without going uncounted"));
         console.log(body("--strict           exit 1 on ANY finding. Honest, and red on day one in a"));

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/connect.js

@@ -388,7 +388,7 @@ export async function connect(opts) {
     }
     else {
         console.log("");
-        console.log(body(paint.dim("Your PRs can carry this too: annotations on the exact line, and a ratchet that fails only when drift goes UP - never on the debt you already have.")));
+        console.log(body(paint.dim("Your PRs can carry this too: annotations on the exact line, and a check that fails only when the count goes UP - never on the debt you already have.")));
         console.log(paint.blue(snippet(["npx synthesisui@latest ci"])));
     }
     /** A mesma versão que a fiação do editor recebe - os dois pinam no mesmo número. */

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/import.js

@@ -507,7 +507,7 @@ export async function takeCensus(root, opts) {
      * tipo de surpresa que ninguém pede.
      */
     if (globalClasses.size > MAX_GLOBAL_CLASSES) {
-        console.log(body(paint.faint(`${globalClasses.size} classes in your global sheet, and ${globalClasses.size - MAX_GLOBAL_CLASSES} of them are not travelling with this census - the first ${MAX_GLOBAL_CLASSES} are.`)));
+        console.log(body(paint.faint(`${globalClasses.size} classes in your global sheet, and ${globalClasses.size - MAX_GLOBAL_CLASSES} of them are not travelling with this measurement - the first ${MAX_GLOBAL_CLASSES} are.`)));
     }
     /**
      * OS KEYFRAMES DA FOLHA DELE, colhidos onde as folhas globais já estão na mão.
@@ -1831,7 +1831,7 @@ export async function takeCensus(root, opts) {
             say(body(paint.faint(`${reachability.unreached
                 .slice(0, 4)
                 .map((f) => relative(root, f))
-                .join(", ")}${reachability.unreached.length > 4 ? `, and ${reachability.unreached.length - 4} more` : ""} - the full list travels in the census, and nothing was left out because of it`)));
+                .join(", ")}${reachability.unreached.length > 4 ? `, and ${reachability.unreached.length - 4} more` : ""} - the full list travels in \`_synthesisui/census.json\`, and nothing was left out because of it`)));
     }
     /**
      * WHAT THE GATE TURNED AWAY - said out loud, grouped, with the reason.
@@ -2916,7 +2916,7 @@ function printCrosswalk(mine) {
 function printAgentContract() {
     console.log("");
     console.log(section("If you are an agent reading this"));
-    console.log(body("The census is deterministic and complete. What it cannot do is judge, so"));
+    console.log(body("The measurement is deterministic and complete. What it cannot do is judge, so"));
     console.log(body("add a `reading` object to the file and send that back to us:"));
     console.log("");
     console.log(body(paint.faint('  "reading": {')));
@@ -2926,7 +2926,7 @@ function printAgentContract() {
     console.log(body(paint.faint('    "themes": { "default": "dark", "has": ["dark"] }')));
     console.log(body(paint.faint("  }")));
     console.log("");
-    console.log(body("Every hex in `roles` must be one the census already observed - a value"));
+    console.log(body("Every hex in `roles` must be one the measurement already observed - a value"));
     console.log(body("we did not find in their code is dropped. Then send the file:"));
     console.log("");
     console.log(body(`    ${paint.strong("synthesisui import --census _synthesisui/census.json")}`));
@@ -3020,7 +3020,7 @@ async function sayAboutPlace(root, scope) {
     console.log(body(`    ${paint.strong(`synthesisui import --dir ${up} --scope ${vocab.rel} ${usage}`)}`));
     console.log(body(paint.faint(`      --dir points at the workspace root, so --scope and --usage are read from there.`)));
     console.log("");
-    console.log(body(paint.dim("Nothing you ran is wasted - this census is a fine diagnosis of this app. It is a system for one consumer, which is the part worth knowing before you publish it.")));
+    console.log(body(paint.dim("Nothing you ran is wasted - this measurement is a fine diagnosis of this app. It is a system for one consumer, which is the part worth knowing before you publish it.")));
 }
 async function sayIfWorkspace(root) {
     const { apps, shared } = await siblingProjects(root);
@@ -3028,7 +3028,7 @@ async function sayIfWorkspace(root) {
         return;
     console.log("");
     console.log(section("This root holds several projects"));
-    console.log(body(`${apps.length} apps (${apps.slice(0, 3).join(", ")}${apps.length > 3 ? ", …" : ""}) - and this census is the average of all of them.`));
+    console.log(body(`${apps.length} apps (${apps.slice(0, 3).join(", ")}${apps.length > 3 ? ", …" : ""}) - and this measurement is the average of all of them.`));
     console.log(body("That is a fine DIAGNOSIS and a poor system: a light app and a dark one"));
     console.log(body("average into a palette that is neither."));
     console.log("");
@@ -3836,7 +3836,7 @@ export async function runImport(opts) {
         }
         if (census.census !== 1) {
             console.log(section("Import"));
-            console.log(body("That file is not a census this version can send."));
+            console.log(body("That file is not a measurement this version can send."));
             return;
         }
         /**
@@ -3850,7 +3850,7 @@ export async function runImport(opts) {
          * Resolved here rather than at measure time because the reading arrives
          * AFTER the census was taken - this is the first moment both halves exist.
          */
-        phase(2, 3, "Resolving the reading against the census");
+        phase(2, 3, "Resolving your reading against the measurement");
         await resolveReadParts(census, root);
     }
     else {

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/status.js

@@ -105,11 +105,11 @@ export async function status(opts) {
             console.log(body(`Ratchet at ${parsed.totals?.drift ?? "?"} findings, frozen ${parsed.at ? ageOf(parsed.at) : "at an unrecorded time"} - CI fails only above it.`));
         }
         catch {
-            console.log(body("A drift baseline exists but is not readable JSON."));
+            console.log(body("`_synthesisui/drift-baseline.json` is here but is not readable JSON."));
         }
     }
     else {
-        console.log(body(paint.dim("No ratchet yet, so nothing in CI can fail on drift. `synthesisui ci` prints the two steps.")));
+        console.log(body(paint.dim("Nothing in your pipeline can fail on a hard-coded value yet. `synthesisui ci` prints the two steps.")));
     }
     /**
      * TODO REQUEST LIDO ESTÁ ABERTO: `closeRequest` REMOVE a linha do arquivo, então o arquivo é a fila

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.320",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {