synthesisui 0.16.172 → 0.16.176

package/dist/commands/add.js

@@ -130,16 +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
@@ -138,16 +174,52 @@ export async function versionBehind(root, opts = {}) {
     const token = await readToken();
     if (!token)
         return null;
-    const res = await fetch(`${lock.registry ?? resolveRegistry()}/api/registry/ds/${lock.slug}`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null);
+    /**
+     * `?meta=1` - a versão e o compilador, e nada mais.
+     *
+     * Isto baixava o payload INTEIRO para ler um número: o documento, três CSS compilados e o GUIDE,
+     * a cada abertura de sessão e a cada entrada na pasta pelo terminal.
+     */
+    const res = await fetch(`${lock.registry ?? resolveRegistry()}/api/registry/ds/${lock.slug}?meta=1`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null);
     if (!res?.ok)
         return null;
     const body = (await res.json().catch(() => null));
-    if (!body?.version || body.version <= lock.version)
+    if (!body?.version)
         return null;
-    return {
-        says: `v${body.version} of "${lock.slug}" is published and this repo is on v${lock.version}. The CSS here and the rules your agent reads are both v${lock.version} - they move together, which is why this is worth saying rather than applying.`,
-        run: `npx synthesisui upgrade ${lock.slug}`,
-    };
+    if (body.version > lock.version)
+        return {
+            says: `v${body.version} of "${lock.slug}" is published and this repo is on v${lock.version}. The CSS here and the rules your agent reads are both v${lock.version} - they move together, which is why this is worth saying rather than applying.`,
+            run: `npx synthesisui upgrade ${lock.slug}`,
+        };
+    /**
+     * A MESMA VERSÃO, COMPILADA DIFERENTE - o caso que não tinha como ser dito nem consertado.
+     *
+     * O CSS não é congelado na publicação: ele é compilado do documento a cada busca. Então um conserto
+     * nosso vale para uma versão JÁ publicada, e nenhum comando o buscava - `upgrade` age por versão e
+     * `connect` agia por CLI. Em 07/08 o bloco de esquema alternativo passou a emitir os dois
+     * ancestrais e não havia caminho até o disco de quem já tinha instalado.
+     */
+    if (typeof body.compiler === "number" &&
+        body.compiler !== (lock.compiler ?? null))
+        return {
+            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;
 }
 /**
  * A linha que a sessão vê.

package/dist/commands/connect.js

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { wireAgent } from "../agent-wiring.js";
 import { blockHomes, syncClaudeMd } from "../claude-md.js";
+import { resolveRegistry } from "../config.js";
 import { body, paint, section, snippet } from "../output.js";
 import { hasHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell-hook.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
@@ -48,6 +49,13 @@ 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 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 {};
+    return ((await res.json().catch(() => null)) ?? {});
+}
 async function refreshInstall(root, cli, registry) {
     const dsDir = join(root, "_synthesisui", "ds");
     const names = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
@@ -67,7 +75,24 @@ async function refreshInstall(root, cli, registry) {
         /** Um DS adotado é descrito aqui e pertencido em outro lugar - não há o que rematerializar. */
         if (!lock.slug || lock.adopted || typeof lock.version !== "number")
             continue;
-        if (lock.cli === cli)
+        /**
+         * O COMPILADOR TAMBÉM DECIDE, e sem ele um conserto de CSS não alcançava ninguém.
+         *
+         * `tokens.css` é compilado no servidor a cada busca, então ele melhora sem que uma linha do CLI
+         * mude e sem que a versão do sistema ande. Aí `upgrade` (que age por versão) e este bloco (que
+         * agia só por CLI) passavam batido, e o conserto ficava disponível para sempre sem caminho até o
+         * disco de quem instalou - foi o que aconteceu em 07/08 com o seletor do esquema alternativo.
+         *
+         * `?meta=1` custa algumas centenas de bytes; falhar nele não pode custar o `connect`, então um
+         * erro de rede simplesmente não aciona a rematerialização.
+         */
+        /** O host que emitiu ESTE install manda - um token pertence ao host que o emitiu. */
+        const base = resolveRegistry(registry ?? lock.registry);
+        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 } : {}),
@@ -283,12 +308,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/requests.js

@@ -32,7 +32,20 @@ function idOf(kind, name, at) {
 }
 export async function fileRequest(root, req) {
     const at = req.at ?? new Date().toISOString();
-    const full = { ...req, at, id: idOf(req.kind, req.name, at) };
+    /**
+     * O CARIMBO SÓ PODE SER FEITO AGORA: depois que alguém edita o sistema, não há como saber se o nome
+     * existia quando o pedido nasceu - e é essa a diferença entre "apareceu" e "sempre esteve lá".
+     */
+    const name = checkableName({ ...req, at, id: "" });
+    const existed = name
+        ? declaresName(await readInstalledCss(root), name)
+        : false;
+    const full = {
+        ...req,
+        at,
+        id: idOf(req.kind, req.name, at),
+        ...(existed ? { existed: true } : {}),
+    };
     try {
         await appendFile(path(root), `${JSON.stringify(full)}\n`, "utf8");
     }
@@ -94,24 +107,80 @@ export function checkableName(req) {
     const m = /[a-z][a-z0-9]*(?:-[a-z0-9]+)+/.exec(req.name.trim());
     return m ? m[0] : null;
 }
-/** Requests whose ask the installed css now demonstrably delivers. */
+/**
+ * Cada `--custom-property: valor` que o css instalado declara. A ÚLTIMA vence, que é o que a cascata
+ * faz para declarações do mesmo peso - ler a primeira responderia sobre um bloco que o navegador
+ * descarta.
+ */
+function declaredValues(css) {
+    const out = new Map();
+    const re = /(--[a-z0-9-]+)\s*:\s*([^;}]+)/gi;
+    let m = re.exec(css);
+    while (m) {
+        out.set(m[1].toLowerCase(), m[2].trim());
+        m = re.exec(css);
+    }
+    return out;
+}
+/**
+ * O valor final de uma declaração, seguindo `var()` enquanto der. Um design system nomeia um valor
+ * apontando um papel para uma primitiva, então o valor pedido quase nunca está escrito na linha do
+ * papel - parar no primeiro `var()` reprovaria justamente o caso comum.
+ */
+function resolved(map, value, hops = 5) {
+    let v = value.trim();
+    for (let i = 0; i < hops; i += 1) {
+        const m = /^var\(\s*(--[a-z0-9-]+)/i.exec(v);
+        if (!m)
+            break;
+        const next = map.get(m[1].toLowerCase());
+        if (next == null)
+            break;
+        v = next.trim();
+    }
+    return v.toLowerCase().replace(/\s+/g, " ");
+}
+const candidatesFor = (name) => name.startsWith("animate-") ? [`--${name}`] : [`--ds-${name}`, `--${name}`];
+/** Os nomes que o css instalado JÁ declara - ver `GapRequest.existed`. */
+export function declaresName(installedCss, name) {
+    const declared = declaredValues(installedCss);
+    return candidatesFor(name).some((c) => declared.has(c.toLowerCase()));
+}
+/**
+ * Requests whose ask the installed css now demonstrably delivers.
+ *
+ * APARECER É PROVA; EXISTIR NÃO É - e a diferença fechou um bug real como entregue.
+ *
+ * Um pedido é "isto não tem nome". Quando o nome de fato não existia, ele passar a existir é prova
+ * suficiente e é o caso comum - `animate-rise` não tem um valor comparável, o pedido é pelo NOME.
+ *
+ * Mas um pedido feito SOBRE um token que já existe é sobre o VALOR dele, e aí existir responde sim
+ * no instante em que o pedido nasce. Em 07/08 um agente reportou `color-semantic-canvas` apontando
+ * para a mesma primitiva que o `foreground` - 1.00:1, texto invisível - e o `sync` seguinte imprimiu
+ * *"delivered. Nothing for anyone to do"* com o defeito intacto no disco do dono.
+ *
+ * Então `existed` é carimbado quando o pedido é feito, e um pedido assim só fecha quando o css
+ * ENTREGA o valor pedido. Sem valor comparável ele fica aberto e quem decide é a pessoa, no cartão -
+ * um pedido aberto custa uma linha numa tela, um fechamento falso custa o bug.
+ */
 export function satisfiedRequests(requests, installedCss) {
+    const declared = declaredValues(installedCss);
     return requests.filter((r) => {
         const name = checkableName(r);
         if (!name)
             return false;
-        const candidates = name.startsWith("animate-")
-            ? [`--${name}`]
-            : [`--ds-${name}`, `--${name}`];
-        return candidates.some((c) => installedCss.includes(`${c}:`));
+        const present = candidatesFor(name).filter((c) => declared.has(c.toLowerCase()));
+        if (present.length === 0)
+            return false;
+        if (!r.existed)
+            return true;
+        const want = r.value?.trim();
+        if (!want)
+            return false;
+        const asked = resolved(declared, want);
+        return present.some((c) => resolved(declared, declared.get(c.toLowerCase()) ?? "") === asked);
     });
 }
-/**
- * Everything the pinned install actually ships, as one string - tokens.css
- * AND theme.css of the locked version, for every installed system. This is
- * the ground verification stands on: not the doc, not the GUIDE's promises,
- * the css a build would really read.
- */
 export async function readInstalledCss(root) {
     const dsDir = join(root, "_synthesisui", "ds");
     let css = "";

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