synthesisui 0.16.195 → 0.16.197

package/dist/commands/add.js

@@ -33,6 +33,8 @@ const IGNORED = [
     "census.json",
     "ledger.jsonl",
     ".ledger-sent",
+    /** O que a última medição viu, para a próxima dizer o que mudou - descreve ESTE clone. */
+    ".last-sync.json",
     "not-expressed.md",
 ];
 const IGNORE_HEADER = "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +

package/dist/commands/import.js

@@ -329,6 +329,19 @@ function screenOf(rel) {
     return `${parts[i]}/${after.slice(0, 2).join("/")}`;
 }
 export async function takeCensus(root, opts) {
+    /**
+     * O RELATÓRIO SÓ SAI QUANDO ALGUÉM O PEDIU - `say` cala quando o chamador é uma RE-medição.
+     *
+     * As 108 linhas deste relatório são o que faz um primeiro import ganhar confiança: elas mostram o
+     * que foi lido, o que não foi, e por quê. Numa re-medição elas são as MESMAS 108 linhas, e o dono
+     * rodou `sync` seis vezes num dia recebendo o mesmo texto (dono, 09/08). Um relatório repetido não
+     * informa - ele treina a pessoa a rolar até o fim sem ler.
+     *
+     * Então `import` continua contando tudo, e `sync` conta o que MUDOU, com este relatório a um
+     * comando de distância (`sync --full`). Silêncio não é o mesmo que esconder: nenhum número deixa de
+     * existir, e a lacuna continua alcançável por quem quiser ver.
+     */
+    const say = opts?.quiet ? () => { } : (line) => console.log(line);
     const scopeLabel = opts?.scopeLabel;
     /**
      * THE LIVE CATALOGUE, once, before anything is matched.
@@ -1203,11 +1216,11 @@ export async function takeCensus(root, opts) {
         { bucket: r.bucket, canonical: r.canonical, because: r.because },
     ]));
     if (usedThere.length > 0) {
-        console.log("");
-        console.log(body(`Read ${usageSeen.size} more file${usageSeen.size === 1 ? "" : "s"} for EVIDENCE only - ${(opts?.usage ?? []).map((u) => paint.strong(u.label)).join(", ")}. What comes from there is how often each component is used and which values get picked, which is what turns a settled choice into a law. The palette, the scales and the convention stay from ${paint.strong(scopeLabel ?? "the system")}: an app's average is not a scale, it is a set of choices made from one.`));
+        say("");
+        say(body(`Read ${usageSeen.size} more file${usageSeen.size === 1 ? "" : "s"} for EVIDENCE only - ${(opts?.usage ?? []).map((u) => paint.strong(u.label)).join(", ")}. What comes from there is how often each component is used and which values get picked, which is what turns a settled choice into a law. The palette, the scales and the convention stay from ${paint.strong(scopeLabel ?? "the system")}: an app's average is not a scale, it is a set of choices made from one.`));
         if (theirsOnly.length > 0) {
             const shown = theirsOnly.slice(0, 6).map((c) => c.name);
-            console.log(body(paint.faint(`(${theirsOnly.length} component${theirsOnly.length === 1 ? "" : "s"} live there and not in the system - ${shown.join(", ")}${theirsOnly.length > shown.length ? ", …" : ""}. Left out on purpose: the system is one place, and a union of two codebases is not a system. Point --scope at them if they belong in it.)`)));
+            say(body(paint.faint(`(${theirsOnly.length} component${theirsOnly.length === 1 ? "" : "s"} live there and not in the system - ${shown.join(", ")}${theirsOnly.length > shown.length ? ", …" : ""}. Left out on purpose: the system is one place, and a union of two codebases is not a system. Point --scope at them if they belong in it.)`)));
         }
     }
     /**
@@ -1260,11 +1273,11 @@ export async function takeCensus(root, opts) {
      */
     const signalLines = describeSignals(signals);
     if (signalLines.length > 0) {
-        console.log("");
-        console.log(section("What was countable, counted"));
+        say("");
+        say(section("What was countable, counted"));
         for (const line of signalLines)
-            console.log(body(line));
-        console.log(body(paint.faint("Do not go looking for any of this - it is measured, and a sweep would bring back a different slice than the next one.")));
+            say(body(line));
+        say(body(paint.faint("Do not go looking for any of this - it is measured, and a sweep would bring back a different slice than the next one.")));
     }
     /**
      * WHAT THE READER UNDERSTOOD AND REFUSED TO PLACE.
@@ -1281,14 +1294,14 @@ export async function takeCensus(root, opts) {
     }));
     if (unplacedByComponent.length > 0) {
         const total = unplacedByComponent.reduce((n, u) => n + u.lines.length, 0);
-        console.log("");
-        console.log(section("Conditional looks that were read and not placed"));
-        console.log(body(`${total} decision${total === 1 ? "" : "s"} across ${unplacedByComponent.length} component${unplacedByComponent.length === 1 ? "" : "s"} were understood and left off, because putting them on the component would paint the wrong element:`));
+        say("");
+        say(section("Conditional looks that were read and not placed"));
+        say(body(`${total} decision${total === 1 ? "" : "s"} across ${unplacedByComponent.length} component${unplacedByComponent.length === 1 ? "" : "s"} were understood and left off, because putting them on the component would paint the wrong element:`));
         for (const u of unplacedByComponent.slice(0, 8)) {
-            console.log(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
+            say(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
         }
         if (unplacedByComponent.length > 8) {
-            console.log(body(paint.faint(`  and ${unplacedByComponent.length - 8} more components`)));
+            say(body(paint.faint(`  and ${unplacedByComponent.length - 8} more components`)));
         }
     }
     /**
@@ -1307,13 +1320,13 @@ export async function takeCensus(root, opts) {
     }));
     if (notesByComponent.length > 0) {
         const total = notesByComponent.reduce((n, u) => n + u.lines.length, 0);
-        console.log("");
-        console.log(section("Looks that are in the recipe and need an attribute"));
-        console.log(body(`${total} decision${total === 1 ? "" : "s"} across ${notesByComponent.length} component${notesByComponent.length === 1 ? "" : "s"} were read and KEPT - they apply once the element carries the attribute the line names:`));
+        say("");
+        say(section("Looks that are in the recipe and need an attribute"));
+        say(body(`${total} decision${total === 1 ? "" : "s"} across ${notesByComponent.length} component${notesByComponent.length === 1 ? "" : "s"} were read and KEPT - they apply once the element carries the attribute the line names:`));
         for (const u of notesByComponent.slice(0, 6))
-            console.log(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
+            say(body(paint.faint(`  ${u.component}: ${u.lines[0]}`)));
         if (notesByComponent.length > 6)
-            console.log(body(paint.faint(`  and ${notesByComponent.length - 6} more components`)));
+            say(body(paint.faint(`  and ${notesByComponent.length - 6} more components`)));
     }
     /**
      * THE DROPS, SAID OUT LOUD. `p-spacing-sm` on a real menu popup read as nothing and
@@ -1330,14 +1343,14 @@ export async function takeCensus(root, opts) {
     }));
     if (unreadableByComponent.length > 0) {
         const total = unreadableByComponent.reduce((n, u) => n + u.classes.length, 0);
-        console.log("");
-        console.log(section("Design classes that read as nothing"));
-        console.log(body(`${total} class${total === 1 ? "" : "es"} start like a design decision and resolve to nothing - usually a typo in the source, and the element renders without that decision today. Nothing was guessed on their behalf:`));
+        say("");
+        say(section("Design classes that read as nothing"));
+        say(body(`${total} class${total === 1 ? "" : "es"} start like a design decision and resolve to nothing - usually a typo in the source, and the element renders without that decision today. Nothing was guessed on their behalf:`));
         for (const u of unreadableByComponent.slice(0, 8)) {
-            console.log(body(paint.faint(`  ${u.component}: ${u.classes.slice(0, 4).join(", ")}`)));
+            say(body(paint.faint(`  ${u.component}: ${u.classes.slice(0, 4).join(", ")}`)));
         }
         if (unreadableByComponent.length > 8) {
-            console.log(body(paint.faint(`  and ${unreadableByComponent.length - 8} more components`)));
+            say(body(paint.faint(`  and ${unreadableByComponent.length - 8} more components`)));
         }
     }
     /**
@@ -1363,10 +1376,10 @@ export async function takeCensus(root, opts) {
     const ledger = buildLedger(opts?.cli ?? "unknown", judgeFragments([...fragments.flat(), ...styleFiles.flatMap((s) => s.fragments)], declaredValues, admittedStyles));
     const coverageLines = describeCoverage(coverage, composition);
     if (coverageLines.length > 0) {
-        console.log("");
-        console.log(section("What this version reads, on your files"));
+        say("");
+        say(section("What this version reads, on your files"));
         for (const line of coverageLines)
-            console.log(body(line));
+            say(body(line));
     }
     /**
      * O QUE VOTA NAS LEIS DELE SEM ESTAR VIVO - dito, e nada excluído.
@@ -1377,12 +1390,12 @@ export async function takeCensus(root, opts) {
      */
     const reachLines = reachability ? describeReachability(reachability) : [];
     if (reachLines.length > 0) {
-        console.log("");
-        console.log(section("What no route reaches"));
+        say("");
+        say(section("What no route reaches"));
         for (const line of reachLines)
-            console.log(body(line));
+            say(body(line));
         if (reachability && reachability.unreached.length > 0)
-            console.log(body(paint.faint(`${reachability.unreached
+            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`)));
@@ -1405,42 +1418,42 @@ export async function takeCensus(root, opts) {
      */
     const ledgerLines = describeLedger(ledger);
     if (ledgerLines.length > 0) {
-        console.log("");
-        console.log(section("Every style fragment, accounted for"));
+        say("");
+        say(section("Every style fragment, accounted for"));
         for (const line of ledgerLines.slice(0, 24))
-            console.log(body(line));
+            say(body(line));
     }
     const pageRules = pageLaws(pages);
     if (pageRules.length > 0) {
-        console.log("");
-        console.log(section("What your pages agree on"));
+        say("");
+        say(section("What your pages agree on"));
         for (const law of pageRules) {
-            console.log(body(law.text));
-            console.log(body(paint.faint(`  ${law.evidence}`)));
+            say(body(law.text));
+            say(body(paint.faint(`  ${law.evidence}`)));
         }
     }
     if (architectures.length > 0) {
-        console.log("");
-        console.log(section("How this project is organised"));
+        say("");
+        say(section("How this project is organised"));
         const choice = describeChoice(architectures);
         if (choice)
-            console.log(body(choice));
+            say(body(choice));
         for (const a of architectures.slice(0, 4)) {
-            console.log(body(paint.faint(`  ${describeArchitecture(a)}`)));
+            say(body(paint.faint(`  ${describeArchitecture(a)}`)));
         }
     }
     if (skips.length > 0) {
-        console.log("");
-        console.log(body(describeGate(scoped.length, skips.length)));
+        say("");
+        say(body(describeGate(scoped.length, skips.length)));
         for (const group of groupSkips(skips)) {
             const shown = group.names.slice(0, 5);
             const more = group.names.length - shown.length;
-            console.log(body(paint.faint(`  ${group.names.length} ${group.label}: ${shown.join(", ")}${more > 0 ? `, and ${more} more` : ""}`)));
+            say(body(paint.faint(`  ${group.names.length} ${group.label}: ${shown.join(", ")}${more > 0 ? `, and ${more} more` : ""}`)));
         }
     }
     if (library) {
-        console.log("");
-        console.log(body(`This scope DECLARES its components and composes almost none of them inside itself - which is what a component library looks like from the inside. So every component it exports arrives as YOURS, with its own recipe. Where one reads like something in our catalogue, that is recorded as a note instead of replacing it.`));
+        say("");
+        say(body(`This scope DECLARES its components and composes almost none of them inside itself - which is what a component library looks like from the inside. So every component it exports arrives as YOURS, with its own recipe. Where one reads like something in our catalogue, that is recorded as a note instead of replacing it.`));
     }
     /**
      * THE LAWS READ THE MERGED LIST, not the scope's.
@@ -2362,7 +2375,14 @@ function rootBehaviour(tag, sketch) {
         ? { rootProps: first.behaviourProps }
         : {};
 }
-export async function resolveReadParts(census, root) {
+export async function resolveReadParts(census, root, 
+/** `true` numa re-medição: o resumo desta etapa fica para o `sync --full` - ver `say`. */
+quiet = false) {
+    const say = quiet
+        ? () => { }
+        : (line) => {
+            console.log(line);
+        };
     /**
      * A READING IS OPTIONAL HERE. THE SKETCH IS NOT.
      *
@@ -2663,27 +2683,27 @@ export async function resolveReadParts(census, root) {
     const authored = Object.keys(read).length;
     const total = authored || Object.keys(census.looks ?? {}).length;
     if (named > 0 || shaped > 0) {
-        console.log("");
-        console.log(body(
+        say("");
+        say(body(
         // "Your reading" only when there WAS one - otherwise the names came off
         // their own markup, and claiming otherwise credits somebody's absent work.
         `${named} part${named === 1 ? "" : "s"} named across ${total} component${total === 1 ? "" : "s"}${authored > 0 ? " - your reading and their markup" : " - read off their own markup"}, so each previews as what it IS rather than as a text box`));
     }
     if (shaped > 0) {
-        console.log(body(`${shaped} of them arrived with a SHAPE - the parts nested as they nest in your code, so the preview is the component and not a row of labels`));
+        say(body(`${shaped} of them arrived with a SHAPE - the parts nested as they nest in your code, so the preview is the component and not a row of labels`));
     }
     // A frontier is worth its own line, because it is the half nobody else has:
     // the edge is a rule an agent can obey, not a picture.
     if (edges > 0) {
-        console.log(body(`${edges} place${edges === 1 ? "" : "s"} where one of your components is built out of another - ${edges === 1 ? "it becomes a rule" : "each becomes a rule"} about the two of them, not a guess`));
+        say(body(`${edges} place${edges === 1 ? "" : "s"} where one of your components is built out of another - ${edges === 1 ? "it becomes a rule" : "each becomes a rule"} about the two of them, not a guess`));
     }
     if (libs.size > 0) {
         const named_ = [...libs].slice(0, 3).join(", ");
-        console.log(body(`${libs.size} librar${libs.size === 1 ? "y" : "ies"} your components need (${named_}) - ${libs.size === 1 ? "it does" : "they do"} not render here, and what to know about ${libs.size === 1 ? "it" : "them"} travels as rules`));
+        say(body(`${libs.size} librar${libs.size === 1 ? "y" : "ies"} your components need (${named_}) - ${libs.size === 1 ? "it does" : "they do"} not render here, and what to know about ${libs.size === 1 ? "it" : "them"} travels as rules`));
     }
     // NO SILENT FIX. A correction made quietly is a lie about what they wrote.
     for (const n of notes)
-        console.log(body(n));
+        say(body(n));
 }
 export async function runImport(opts) {
     const root = opts.root ?? process.cwd();

package/dist/commands/sync.js

@@ -4,6 +4,7 @@ import { isOlderCli } from "../cli-version.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { markSent, readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
+import { describeDelta, readSyncMark, writeSyncMark, } from "../last-sync.js";
 import { measuredScope, rememberScope } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
@@ -74,7 +75,14 @@ export async function sync(opts) {
      * ATUAL, funde a leitura no censo fresco, AVISA o que seria reescrito, e envia. Sem entrevista.
      */
     if (!opts.recordOnly)
-        await remeasure({ root, base, token, slug, cli: opts.cli });
+        await remeasure({
+            root,
+            base,
+            token,
+            slug,
+            cli: opts.cli,
+            ...(opts.full ? { full: true } : {}),
+        });
     // Verification first, so the snapshot never reports "open" about something
     // the installed css already delivers - a request closes because a machine
     // CHECKED, not because someone remembered to say so (dono, 29/07).
@@ -252,6 +260,8 @@ export async function remeasure(args) {
     const census = await takeCensus(scope ? join(root, scope) : root, {
         ...(scope ? { scopeLabel: scope } : {}),
         ...(args.cli ? { cli: args.cli } : {}),
+        /** Uma RE-medição conta o que MUDOU; o relatório inteiro fica no `--full` - ver `say`. */
+        ...(args.full ? {} : { quiet: true }),
         /** O `--usage` é EVIDÊNCIA e leva rótulo: sem ele o censo não sabe de que app o número veio. */
         usage: usage.map((u) => ({
             path: join(root, u),
@@ -265,7 +275,7 @@ export async function remeasure(args) {
     /** A LEITURA GRAVADA ENTRA NO CENSO FRESCO - ver a rota `reading`. */
     if (stored.reading)
         census.reading = stored.reading;
-    await resolveReadParts(census, root).catch(() => { });
+    await resolveReadParts(census, root, !args.full).catch(() => { });
     /**
      * O CENSO FRESCO TAMBÉM FICA NO DISCO.
      *
@@ -330,6 +340,34 @@ export async function remeasure(args) {
         console.log(body(paint.faint(note)));
     if (out.url)
         console.log(body(out.url));
+    /**
+     * O QUE MUDOU DESDE A ÚLTIMA VEZ - a linha que só uma RE-medição pode dar.
+     *
+     * O relatório longo responde "o que a esteira lê"; ele responde igual toda vez. Esta responde "o
+     * que mudou", que é a pergunta de quem já rodou isso antes - e era a única sem resposta em seis
+     * execuções seguidas (dono, 09/08).
+     */
+    const led = census.ledger;
+    const sum = (r) => Object.values(r ?? {}).reduce((n, v) => n + v, 0);
+    const mark = {
+        at: new Date().toISOString(),
+        components: out.written ?? 0,
+        /**
+         * LIDO DO CENSO, e não recontado aqui - ver `coverage.declarations`.
+         *
+         * A primeira versão contava por conta própria e deu 165 onde o relatório diz 519: ela somava só o
+         * `base` de cada look, e a conta do produto soma `base`, `dark` e os estados. Dois números sobre
+         * um fato só é como uma tela passa a se contradizer, e a única defesa é não ter o segundo.
+         */
+        declarations: census.coverage
+            ?.declarations ?? 0,
+        seen: sum(led?.counted),
+        interpreted: sum(led?.interpreted),
+    };
+    console.log(body(paint.faint(describeDelta(mark, await readSyncMark(root)))));
+    await writeSyncMark(root, mark);
+    if (!args.full)
+        console.log(body(paint.faint("everything the reader saw:  npx synthesisui sync --full")));
 }
 /**
  * Pergunta uma vez, e só num terminal de verdade.

package/dist/index.js

@@ -550,6 +550,8 @@ async function main() {
                 cli: CLI_VERSION,
                 recordOnly: args.includes("--record-only"),
                 yes: args.includes("--yes"),
+                /** `--full`: o relatório inteiro do leitor. Por padrão a re-medição conta o que MUDOU. */
+                full: args.includes("--full") || flags.full === true,
             });
             break;
         /**

package/dist/last-sync.js

@@ -0,0 +1,70 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * O QUE MUDOU DESDE A ÚLTIMA VEZ - porque a segunda leitura não é a primeira.
+ *
+ * Um primeiro import precisa das 108 linhas do relatório: é ali que a esteira mostra o que leu, o que
+ * não leu, e por quê, e é assim que ela ganha confiança. Uma RE-medição precisa de outra coisa - o
+ * dono rodou `sync` seis vezes num dia e recebeu o mesmo texto nas seis (dono, 09/08). Um relatório
+ * repetido não informa; ele treina a pessoa a rolar até o fim sem ler.
+ *
+ * Meia dúzia de números guardados ao lado do registro, no mesmo padrão do `.ledger-sent`: local,
+ * pequeno, e nunca uma segunda fonte de verdade. Se ele sumir, a próxima leitura simplesmente não tem
+ * "antes" - e diz isso, em vez de inventar um delta.
+ */
+export const LAST_SYNC_FILE = ".last-sync.json";
+const path = (root) => join(root, "_synthesisui", LAST_SYNC_FILE);
+export async function readSyncMark(root) {
+    try {
+        const raw = JSON.parse(await readFile(path(root), "utf8"));
+        return typeof raw?.at === "string" ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Nunca derruba o comando: um carimbo que falha custa um delta, não a medição. */
+export async function writeSyncMark(root, mark) {
+    await writeFile(path(root), `${JSON.stringify(mark, null, 2)}\n`, "utf8").catch(() => { });
+}
+/**
+ * A LINHA DO DELTA, ou o silêncio honesto.
+ *
+ * Sem "antes" ela diz que é a primeira - inventar um delta contra zero faria toda primeira medição
+ * parecer um salto enorme. E quando nada mudou ela DIZ que nada mudou: é a resposta mais útil que uma
+ * re-medição pode dar, e é a que o relatório longo nunca conseguiu dar em seis execuções.
+ */
+export function describeDelta(now, before) {
+    if (!before)
+        return "first measurement recorded here - the next one compares against it";
+    const parts = [];
+    const moved = (label, from, to) => {
+        if (from === to)
+            return;
+        parts.push(`${label} ${from} → ${to}`);
+    };
+    moved("components", before.components, now.components);
+    moved("declarations", before.declarations, now.declarations);
+    moved("fragments read", before.interpreted, now.interpreted);
+    moved("fragments seen", before.seen, now.seen);
+    const when = ago(before.at);
+    return parts.length === 0
+        ? `nothing moved since your last sync${when ? `, ${when}` : ""}`
+        : `${parts.join(" · ")} — since your last sync${when ? `, ${when}` : ""}`;
+}
+/** Quanto tempo faz, em palavras. Um carimbo ilegível não vira frase. */
+function ago(at) {
+    const then = Date.parse(at);
+    if (!Number.isFinite(then))
+        return "";
+    const mins = Math.round((Date.now() - then) / 60_000);
+    if (mins < 1)
+        return "moments ago";
+    if (mins < 60)
+        return `${mins} minute${mins === 1 ? "" : "s"} ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"} ago`;
+}

package/package.json

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