synthesisui 0.16.174 → 0.16.177

package/dist/claude-md.js

@@ -412,6 +412,7 @@ export async function syncClaudeMd(projectRoot) {
     const installed = await readInstalled(projectRoot);
     const region = await renderRegion(projectRoot, installed);
     let createdAny = false;
+    const changed = [];
     for (const home of HOMES) {
         const path = join(projectRoot, home.path);
         let existing = null;
@@ -435,6 +436,7 @@ export async function syncClaudeMd(projectRoot) {
             await mkdir(dirname(path), { recursive: true }).catch(() => { });
             await writeFile(path, `${home.frontmatter ?? ""}${region}\n`, "utf8");
             createdAny = true;
+            changed.push(home.path);
             continue;
         }
         const startIdx = existing.indexOf(START);
@@ -450,10 +452,12 @@ export async function syncClaudeMd(projectRoot) {
             const sep = existing.endsWith("\n") ? "\n" : "\n\n";
             next = `${existing}${sep}${region}\n`;
         }
-        if (next !== existing)
+        if (next !== existing) {
             await writeFile(path, next, "utf8");
+            changed.push(home.path);
+        }
     }
-    return { created: createdAny, count: installed.length };
+    return { created: createdAny, count: installed.length, changed };
 }
 /**
  * Onde o bloco JÁ está, para o `connect` poder dizer isso em vez de ficar calado.

package/dist/commands/add.js

@@ -130,18 +130,39 @@ export async function add(slug, opts) {
     const measured = await censusScope(projectRoot);
     const scope = measured.system ?? prev?.scope ?? null;
     const usage = measured.usage.length > 0 ? measured.usage : (prev?.usage ?? []);
-    const lock = {
+    /**
+     * `fetchedAt` SÓ ANDA QUANDO ALGO ATERROU - e a alternativa sujava o git de um time inteiro.
+     *
+     * O `.lock` é commitado, e este era o único campo não determinístico dele: tudo mais é função da
+     * versão, do compilador e das regras. Então cada `connect` de cada pessoa produzia um diff mesmo
+     * quando nada tinha mudado, e um comando que sempre gera commit é um comando que as pessoas param
+     * de rodar (dono, 07/08).
+     *
+     * O campo continua significando o que ele diz - quando esta instalação chegou -, e `repo-state` o
+     * manda para a plataforma como `installedAt`. Se nada chegou, ela não chegou de novo.
+     */
+    const identity = {
         slug: payload.slug,
         name: payload.name,
         version: payload.version,
         registry: base,
-        fetchedAt: new Date().toISOString(),
         ...(opts.cli ? { cli: opts.cli } : {}),
         /** Ver `RegistryPayload.compiler`: é o que faz um conserto de CSS chegar a um install. */
         ...(payload.compiler != null ? { compiler: payload.compiler } : {}),
+        ...(payload.rulesStamp ? { rules: payload.rulesStamp } : {}),
         ...(scope ? { scope } : {}),
         ...(usage.length > 0 ? { usage } : {}),
     };
+    const landed = (() => {
+        if (!prev?.fetchedAt)
+            return true;
+        const { fetchedAt: _was, ...before } = prev;
+        return JSON.stringify(before) !== JSON.stringify(identity);
+    })();
+    const lock = {
+        ...identity,
+        fetchedAt: landed || !prev?.fetchedAt ? new Date().toISOString() : prev.fetchedAt,
+    };
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
     await writeGovernanceIgnore(projectRoot);
     const retired = await retireMaterializedDoctrine(slugDir);

package/dist/commands/align.js

@@ -4,6 +4,25 @@ import { join, resolve } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { measuredScope } from "../measured-scope.js";
+import { READER } from "../reader-version.js";
+/**
+ * Qual leitor mediu o censo em disco, quando ele o registra.
+ *
+ * `null` para censo anterior a esta marca: um censo que não diz quem o leu não prova nada, e supor
+ * que ele é velho faria toda pessoa que ainda não re-mediu ver o aviso para sempre.
+ */
+async function censusReader(root) {
+    const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        const c = JSON.parse(raw);
+        return typeof c.ledger?.reader === "number" ? c.ledger.reader : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function locksIn(root) {
     const dsDir = join(root, "_synthesisui", "ds");
     const entries = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
@@ -69,6 +88,23 @@ opts = {}) {
             says: `Your session is for ${creds.registry} and this system came from ${lock.registry}. That answers 401, which reads as an expired session on a host that never issued one.`,
             run: `npx synthesisui login --registry ${lock.registry}`,
         });
+    /**
+     * A MEDIÇÃO LIDA POR UM LEITOR ANTERIOR - e este era o quarto lado, sem cobertura nenhuma.
+     *
+     * Metade da esteira roda na máquina de quem tem o código, e o servidor não tem os arquivos: quando
+     * `transcribe`, `sketch` ou a derivação de anatomia melhoram, o censo guardado continua sendo a
+     * leitura de antes e NENHUMA re-interpretação nossa alcança isso. Só uma medição nova alcança, e
+     * ela é um comando que ninguém tinha motivo para rodar.
+     *
+     * Compara `READER`, não a string do CLI: em 07/08 o CLI subiu quatro vezes e nenhuma delas mudou um
+     * leitor - pedir re-medição em cada bump faria a pessoa parar de ler estas linhas.
+     */
+    const reader = await censusReader(root);
+    if (reader != null && reader !== READER)
+        out.push({
+            says: `the measurement stored in this repo was read by an older reader, so what the platform knows about your components is what that reader could see. A re-measure is the only thing that reaches it - the fix lives on this machine, not on the server.`,
+            run: "npx synthesisui sync",
+        });
     /**
      * O ESCOPO, que é o desalinho mais caro e o mais silencioso: sem ele o `sync` mede o repo inteiro
      * e manda os componentes de todos os apps para um sistema que é uma biblioteca (06/08, 338 num
@@ -169,6 +205,20 @@ export async function versionBehind(root, opts = {}) {
             says: `the css for "${lock.slug}" v${lock.version} is compiled differently now - same version, same document, a fix on our side. The files in this repo were written before it.`,
             run: "npx synthesisui connect",
         };
+    /**
+     * AS REGRAS MUDARAM - e nem a versão nem o CLI diziam isso.
+     *
+     * A governança de um sistema não é versionada com o documento: `listDsRuleSetByDsId` lê por
+     * SISTEMA, então uma lei escrita na plataforma vale no instante seguinte. O `doctrine.json` em
+     * disco, que é o que o agente lê com `system_doctrine`, só é reescrito por um `add`. Então quem
+     * cuida do sistema escrevia uma lei e o agente de quem o consome continuava obedecendo as de
+     * ontem, sem sinal nenhum (medido em 07/08).
+     */
+    if (body.rulesStamp && body.rulesStamp !== (lock.rules ?? null))
+        return {
+            says: `the rules that govern "${lock.slug}" changed since this repo materialized them - your agent reads the copy on disk, so it is still following the previous set.`,
+            run: "npx synthesisui connect",
+        };
     return null;
 }
 /**

package/dist/commands/connect.js

@@ -49,13 +49,12 @@ const LEGACY_SKILLS = ["import-design-system"];
  * SILENCIOSO QUANDO JÁ ESTÁ EM DIA, e sem rede não faz nada - um `connect` que falha por estar num
  * avião seria pior que a defasagem que ele conserta.
  */
-/** O número do compilador que serviria esta versão HOJE - `null` quando não dá para saber. */
-async function fetchCompiler(base, slug, version) {
+/** O compilador e as regras que serviriam esta versão HOJE - vazio quando não dá para saber. */
+async function fetchMeta(base, slug, version) {
     const res = await fetch(`${base}/api/registry/ds/${slug}?version=${version}&meta=1`).catch(() => null);
     if (!res?.ok)
-        return null;
-    const body = (await res.json().catch(() => null));
-    return typeof body?.compiler === "number" ? body.compiler : null;
+        return {};
+    return ((await res.json().catch(() => null)) ?? {});
 }
 async function refreshInstall(root, cli, registry) {
     const dsDir = join(root, "_synthesisui", "ds");
@@ -89,9 +88,11 @@ async function refreshInstall(root, cli, registry) {
          */
         /** O host que emitiu ESTE install manda - um token pertence ao host que o emitiu. */
         const base = resolveRegistry(registry ?? lock.registry);
-        const remote = await fetchCompiler(base, lock.slug, lock.version);
-        const compilerMoved = remote != null && remote !== (lock.compiler ?? null);
-        if (lock.cli === cli && !compilerMoved)
+        const remote = await fetchMeta(base, lock.slug, lock.version);
+        const compilerMoved = remote.compiler != null && remote.compiler !== (lock.compiler ?? null);
+        /** Regras valem no instante em que são escritas - ver `align`, e `rulesStamp` na plataforma. */
+        const rulesMoved = remote.rulesStamp != null && remote.rulesStamp !== (lock.rules ?? null);
+        if (lock.cli === cli && !compilerMoved && !rulesMoved)
             continue;
         const done = await add(lock.slug, {
             ...(registry ? { registry } : {}),
@@ -172,7 +173,7 @@ export async function connect(opts) {
     const wired = await wireAgent(root, opts.version, want);
     // The block reads the settings we just wrote, so it must be regenerated
     // after them, not before.
-    await syncClaudeMd(root);
+    const contract = await syncClaudeMd(root);
     console.log(section("Connected"));
     /**
      * O QUE ESTE CLI REESCREVEU NA PASTA DO SISTEMA - dito primeiro, porque é o que a pessoa não sabia
@@ -230,8 +231,18 @@ export async function connect(opts) {
      * qual ferramenta ela usa. Dizer os nomes é o que faz um time descobrir que a governança já chegou
      * no editor dele: até 05/08 ela só alcançava quem usa Claude Code, e ninguém tinha como saber.
      */
-    for (const home of await blockHomes(root))
-        console.log(body(`✓ ${home.padEnd(22)} ${home === "CLAUDE.md" ? "rewritten for what is installed" : "the same rules, where this agent reads them"}`));
+    /**
+     * `✓` SÓ PARA O QUE MUDOU - ver `syncClaudeMd.changed`. Esta linha era a única do bloco que
+     * marcava mudança sempre, e um `connect` seguido dizia "rewritten" sobre um arquivo intocado.
+     */
+    for (const home of await blockHomes(root)) {
+        const moved = contract.changed.includes(home);
+        console.log(body(`${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
+            ? home === "CLAUDE.md"
+                ? "rewritten for what is installed"
+                : "the same rules, where this agent reads them"
+            : "already says what is installed"}`));
+    }
     /**
      * The fourth layer, and the one that had no installer at all: the import
      * skill existed only in our own repo, so the only way to get it was to clone
@@ -307,12 +318,30 @@ export async function connect(opts) {
         console.log(paint.blue(snippet(["npx synthesisui@latest ci"])));
     }
     await offerShellHook(opts.shell === true);
-    // The step that cost a round trip the first time this was tried by hand,
-    // and would cost every single person one.
-    console.log("");
-    console.log(body("Reopen your editor session - all of them are read at startup."));
-    if (want.mcp) {
-        console.log(body('A project MCP server needs approving once; say yes when it asks. Then "/mcp" lists synthesisui.'));
+    /**
+     * O REINÍCIO SÓ QUANDO ELE É NECESSÁRIO - e pedi-lo sempre é o que fez o dono achar que reiniciar
+     * o editor fazia parte do fluxo (07/08).
+     *
+     * Hooks e servidores MCP são lidos UMA vez, quando a sessão abre - se um deles mudou, a sessão em
+     * curso está rodando o anterior e não há como avisá-la. Mas `connect` também roda quando só o CSS
+     * foi re-materializado, e aí não há nada em memória para atualizar: os arquivos são lidos pelo
+     * build, não pelo editor.
+     *
+     * Um pedido que aparece sempre é um pedido que a pessoa passa a ignorar - e aí ele não serve para
+     * a vez em que era mesmo obrigatório.
+     */
+    const moved = (s) => s === "added" || s === "updated";
+    const needsRestart = moved(wired.hook) ||
+        moved(wired.session) ||
+        (Array.isArray(wired.mcp) && wired.mcp.some((m) => moved(m.status)));
+    if (needsRestart) {
+        console.log("");
+        console.log(body("Reopen your editor session - all of them are read at startup."));
+        if (want.mcp &&
+            Array.isArray(wired.mcp) &&
+            wired.mcp.some((m) => moved(m.status))) {
+            console.log(body('A project MCP server needs approving once; say yes when it asks. Then "/mcp" lists synthesisui.'));
+        }
     }
     if (wired.command.startsWith("npx synthesisui@")) {
         console.log("");

package/dist/doctor/style-ledger.js

@@ -26,6 +26,7 @@
  * interpretação como um número que se move. Dizer 100% de cobertura existindo uma classe
  * calculada em runtime seria exatamente a mentira que esta esteira existe para não contar.
  */
+import { READER } from "../reader-version.js";
 const SHAPES = [
     "class",
     "template",
@@ -97,6 +98,7 @@ export function buildLedger(cli, seen) {
     }
     return {
         cli,
+        reader: READER,
         counted,
         interpreted,
         unread: [...groups.values()]

package/dist/reader-version.js

@@ -0,0 +1,24 @@
+/**
+ * A VERSÃO DO LEITOR - quem diz que uma medição já guardada ficou velha.
+ *
+ * Metade da esteira roda AQUI, na máquina de quem tem o código: `transcribe`, `sketch`,
+ * `anatomy-from-sketch`, os leitores de CSS Modules e de variantes. Quando um deles melhora, o censo
+ * gravado continua sendo a leitura antiga - e nenhuma re-interpretação no servidor alcança isso,
+ * porque o servidor não tem os arquivos. Só uma nova medição alcança, e ela é um comando: `sync`.
+ *
+ * O problema era saber QUANDO pedir. O censo grava a string do CLI que mediu, e o CLI sobe várias
+ * vezes por dia por motivos que não têm nada a ver com leitura - em 07/08 foram quatro versões, e
+ * nenhuma delas mudou um leitor. Comparar a string mandaria re-medir em todas, e um aviso que aparece
+ * à toa é um aviso que a pessoa aprende a não ler.
+ *
+ * Então este número existe e sobe SOZINHO, pelo mesmo critério do `COMPILER` na plataforma: quando os
+ * leitores passam a produzir um censo diferente para os MESMOS arquivos. Nunca por refactor, nunca por
+ * publicação, nunca por conserto que não toca leitura.
+ *
+ * As três marcas, e o que cada uma alcança:
+ *
+ *     READER          a medição na máquina dela   ->  npx synthesisui sync
+ *     COMPILER        o CSS de uma versão já instalada  ->  npx synthesisui connect
+ *     INTERPRETATION  a nossa metade, sobre censos já guardados  ->  roda no servidor, sem comando
+ */
+export const READER = 1;

package/package.json

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