synthesisui 0.16.149 → 0.16.152

package/dist/agent-wiring.js

@@ -71,7 +71,7 @@ async function wireHook(root, command) {
  * O MESMO SERVIDOR MCP, NOS CAMINHOS QUE CADA AGENTE LÊ.
  *
  * `.mcp.json` é o escopo-de-projeto do Claude Code; o Cursor lê `.cursor/mcp.json` com o MESMO shape
- * (`mcpServers`). Então cobrir os dois é o mesmo JSON num segundo caminho, e as 11 ferramentas passam
+ * (`mcpServers`). Então cobrir os dois é o mesmo JSON num segundo caminho, e as ferramentas passam
  * a existir nos dois editores sem uma linha de motor novo - era a lacuna mais barata da análise de DX
  * (05/08).
  *
@@ -94,9 +94,23 @@ async function wireMcpAt(root, version, rel) {
             synthesisui: {
                 type: "stdio",
                 command: "npx",
+                /**
+                 * O MCP FLUTUA, E O HOOK NÃO - e a diferença é o custo, não o gosto.
+                 *
+                 * O comentário do `hookCommand` mede 720ms-1,5s POR ESCRITA e conclui que um hook cujo
+                 * comportamento muda sob você a cada edit é indebugável. Está certo, e não vale para aqui:
+                 * um servidor MCP sobe UMA VEZ quando o editor abre a sessão e fica estável durante ela.
+                 *
+                 * Pinado, ele nunca ficava mais novo - e a regra que manda o agente comparar `ledger.cli`
+                 * com a versão do servidor quase nunca disparava, porque os dois congelavam juntos no dia
+                 * do `connect` (dono, 06/08). Com `@latest`, um leitor publicado hoje alcança o repo dele
+                 * na próxima vez que ele abrir o editor, sem ninguém rodar nada.
+                 *
+                 * O install local continua ganhando: quem tem o CLI no `node_modules` escolheu a versão.
+                 */
                 args: local
                     ? ["--no-install", "synthesisui", "mcp"]
-                    : [`synthesisui@${version}`, "mcp"],
+                    : ["synthesisui@latest", "mcp"],
             },
         },
     }, null, 2)}\n`, "utf8");

package/dist/claude-md.js

@@ -166,6 +166,38 @@ shadcn components wear this system and need no edits from you. Without it they
 stay on shadcn's defaults, which looks like the design system failing rather than
 one import missing - so check for it before you add a shadcn component, and add
 it if it is not there.`;
+/**
+ * A REGRA QUE TIRA O "O DEV FAZ ALGO", e ela vale para todo agente que lê este bloco.
+ *
+ * Um leitor novo do CLI precisa olhar o código do cliente, e a esteira não guarda esse código - então
+ * a medição é irredutível na máquina dele. O que era redutível é o GATILHO: até 06/08 era uma pessoa
+ * lembrando de rodar `sync` num momento em que ela precisava escolher, e um conserto que depende disso
+ * alcança a minoria dos clientes.
+ *
+ * A checagem é LOCAL e grátis: o censo grava qual CLI o mediu (`ledger.cli`) e o servidor MCP É o CLI,
+ * então comparar as duas versões é aritmética em disco. Nada aqui telefona para casa - é a mesma
+ * decisão que mantém o hook instalado.
+ */
+const REFRESH = `
+
+**If the measurement is older than the reader, refresh it before you write UI.**
+Read \`_synthesisui/census.json\` → \`ledger.cli\` and compare it with the version
+of the \`synthesisui\` MCP server you are talking to. When they differ, call
+\`refresh_system\` once. It re-measures this repo with the current reader, reuses
+the reading that was already authored, and sends it - a newer reader sees styles
+the old one could not, and until it runs, this project's system is missing them.
+
+It never asks anyone anything, and it never overwrites a recipe a person wrote on
+the screen: when a send would rewrite one, it refuses and names them. If it says
+nothing changed, nothing changed - carry on.
+
+**And if it reports that a newer CLI is published, say so to the person and stop
+there.** You cannot fix that one: the check that runs after your writes is pinned
+to the version installed at setup, and the tools you are holding were started by
+the editor. One command rewires both - \`npx synthesisui@latest connect\` - and it
+takes effect the next time the editor starts a session. Telling them is the whole
+job; doing it yourself would leave them with a file that says one version and a
+process running another.`;
 const VERIFY = `
 
 **Verify with a build, not a running server.** If you do start a dev server, stop
@@ -185,7 +217,7 @@ const SELF_CHECK_MANUAL = `
 It names the token for every hardcoded value it finds. Fix what it names, run it
 again, and only then move to the next thing. Do not batch this up for the end -
 a component checked while you still have its context is a two-line fix; the same
-component found in a repo-wide audit next week is an archaeology exercise.${REFUSAL}
+component found in a repo-wide audit next week is an archaeology exercise.${REFUSAL}${REFRESH}
 
 Better than remembering: \`npx synthesisui@latest connect\` installs the check as
 an editor hook, so it runs on its own and this paragraph stops being your job.${VERIFY}`;
@@ -196,7 +228,7 @@ token this project already has for anything hardcoded. You do not need to run
 \`doctor\` by hand, and you should not wait for a final pass.
 
 When it names something, fix it in that file before moving to the next one -
-you still have the context, so it is a two-line change.${REFUSAL}${VERIFY}`;
+you still have the context, so it is a two-line change.${REFUSAL}${REFRESH}${VERIFY}`;
 /**
  * THE INTERFACE LANGUAGE, READ FROM THE PROJECT RATHER THAN ASKED FOR.
  *

package/dist/commands/connect.js

@@ -6,6 +6,7 @@ import { body, paint, section, snippet } from "../output.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
 import { INIT_SKILL, INIT_SKILL_PATH } from "../skill-init.js";
 import { ci } from "./ci.js";
+import { MCP_TOOL_COUNT } from "./mcp.js";
 /**
  * `synthesisui connect` - put the three layers where they actually run.
  *
@@ -44,13 +45,16 @@ export async function connect(opts) {
         console.log(snippet([wired.command]));
     }
     /**
-     * OS CAMINHOS DE MCP, POR NOME - e o número certo. Dizia "four tools" desde quando eram quatro; são
-     * 11, e um número velho na primeira tela é a coisa mais fácil de perder a confiança de alguém.
+     * OS CAMINHOS DE MCP, POR NOME - e o número vem da LISTA, não da minha memória.
+     *
+     * Dizia "four tools" desde quando eram quatro; eu troquei por 11 contando o `serverInfo` como
+     * ferramenta, e eram 10. Um número que alguém digita envelhece na primeira ferramenta nova - este é
+     * lido de `MCP_TOOL_COUNT`, que é `TOOLS.length`.
      */
     if (want.mcp && wired.mcp !== "skipped") {
         for (const one of wired.mcp)
             console.log(body(one.status === "added"
-                ? `✓ ${one.path.padEnd(22)} 11 tools, so the agent can ask instead of guess`
+                ? `✓ ${one.path.padEnd(22)} ${MCP_TOOL_COUNT} tools, so the agent can ask instead of guess`
                 : `· ${one.path.padEnd(22)} already had it`));
     }
     /**

package/dist/commands/doctor.js

@@ -672,10 +672,20 @@ export async function doctor(opts) {
      * today the honest answer was that nobody knew.
      */
     if (hasSystem && measurable && scopes.length === 0) {
+        /**
+         * E A CONTAGEM DE COINCIDÊNCIAS VAI JUNTO - ver `crossFamily` em `scan.ts`.
+         *
+         * É a única classe de bug NOSSO que a plataforma não tinha como ver: ela nasce no casamento entre
+         * um valor dele e o nome de um token nosso, então só a máquina dele mede. Zero também é resposta -
+         * a biblioteca dele deu 0 de 76 no mesmo dia em que o app deu 14 de 129.
+         */
+        const crossFamily = d.findings.filter((f) => f.crossFamily).length;
         await appendEvent(root, {
             kind: "doctor",
             at: new Date().toISOString(),
             coverage: d.coverage,
+            named: d.named,
+            ...(crossFamily > 0 ? { crossFamily } : {}),
         });
     }
     if (hasSystem && scopes.length === 0) {

package/dist/commands/mcp.js

@@ -7,6 +7,7 @@ import { nearestToken, tokenFor } from "../doctor/tokens.js";
 import { repoStateOf } from "../repo-state.js";
 import { component } from "./component.js";
 import { loadSystem, walkAll } from "./doctor.js";
+import { installedSlug, remeasure } from "./sync.js";
 const send = (msg) => {
     process.stdout.write(`${JSON.stringify(msg)}\n`);
 };
@@ -37,6 +38,11 @@ async function capturing(run) {
 }
 // ── The tools ────────────────────────────────────────────────────────────────
 const TOOLS = [
+    {
+        name: "refresh_system",
+        description: "Re-measure this repository with the reader you are running and send it to the design system, reusing the reading already authored. Call this when `_synthesisui/census.json` was measured by an OLDER CLI than this server - the tool tells you the two versions and refuses politely when there is nothing to refresh. It never asks a person anything: when a recipe in the draft was written on the screen and this send would rewrite it, it refuses and names them instead. Nothing on the platform is deleted and no published version moves.",
+        inputSchema: { type: "object", properties: {} },
+    },
     {
         name: "check_file",
         description: "Check one file (or folder) against the installed design system. Returns token coverage, every hardcoded value with the token this project already has for it, and any --ds- name the system does not declare. Run this after writing or editing any UI file, before moving on.",
@@ -187,6 +193,14 @@ const TOOLS = [
         },
     },
 ];
+/**
+ * QUANTAS FERRAMENTAS ESTE SERVIDOR SERVE, lido da lista.
+ *
+ * O `connect` imprimia o número à mão: ficou em "four tools" muito depois de serem mais, e quando eu
+ * corrigi escrevi 11 contando o `serverInfo` como ferramenta - eram 10. Um número digitado envelhece na
+ * primeira ferramenta nova.
+ */
+export const MCP_TOOL_COUNT = TOOLS.length;
 async function checkFile(root, path) {
     const { table } = await loadSystem(root);
     if (table.byName.size === 0)
@@ -855,6 +869,38 @@ cli) {
             });
             return text(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it - keep building with your workaround, and say in your summary that the request exists.`);
         }
+        case "refresh_system": {
+            /**
+             * O ELO QUE TIRA O "O DEV FAZ ALGO" - e ele é uma ferramenta e não um comando de propósito.
+             *
+             * Um leitor novo do CLI precisa OLHAR o código do cliente, e a gente não guarda esse código: a
+             * medição é irredutível na máquina dele. O que era redutível é o GATILHO - até 06/08 era uma
+             * pessoa lembrando de um comando num momento que ela precisava escolher. Aqui é o agente,
+             * dentro de uma sessão que ela já começou, seguindo a regra que o bloco gerenciado carrega.
+             *
+             * Chama o MESMO `remeasure` do `sync`, capturando a saída: um segundo caminho de medição
+             * discordaria do primeiro na primeira mudança, e a diferença apareceria no sistema de um cliente.
+             *
+             * ENVIA SOZINHO quando não há nada em risco, e RECUSA nomeando quando há - sem TTY o guarda de
+             * rascunho responde "não" por construção, então o pior caso automatizado é uma resposta dizendo
+             * o que não foi feito e por quê (dono, 06/08).
+             */
+            const slug = await installedSlug(root);
+            if (!slug)
+                return text("No system installed here that belongs to a dashboard row, so there is nothing to refresh. `synthesisui add <slug>` installs one; an adopted system is described here and owned elsewhere.");
+            const token = await readToken();
+            if (!token)
+                return text("Not signed in, so nothing could be sent. A person has to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.");
+            const { out } = await capturing(() => remeasure({
+                root,
+                base: resolveRegistry(),
+                token,
+                slug,
+                cli: VERSION,
+            }));
+            return text(out.trim() ||
+                "Nothing was reported by the refresh - which means it found nothing to measure.");
+        }
         case "request_token": {
             const name = String(args.name ?? "");
             // TRIAGE AT FILING: if the system's own contract already promises this

package/dist/commands/status.js

@@ -139,6 +139,12 @@ export async function status(opts) {
         : `${owned.slug} on the platform did not come from an import, so there is no measurement to compare.`));
     if (remote.hasCensus)
         console.log(body(paint.dim("`synthesisui sync` measures this repo again with today's reader and sends it.")));
+    /** E a distância até o leitor publicado, com o comando que a fecha - ver `sync`. */
+    if (remote.publishedCli && opts.cli && remote.publishedCli !== opts.cli) {
+        console.log("");
+        console.log(body(`Your CLI is ${opts.cli} and ${remote.publishedCli} is published - a newer reader sees styles this one cannot.`));
+        console.log(paint.blue(snippet(["npx synthesisui@latest connect"])));
+    }
 }
 /** "2 hours ago", sem dependência - e `Invalid Date` nunca chega à tela. */
 function ageOf(iso) {

package/dist/commands/sync.js

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
-import { body, paint, section } from "../output.js";
+import { body, paint, section, snippet } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
 import { resolveReadParts, takeCensus } from "./import.js";
 /**
@@ -53,32 +53,7 @@ export async function sync(opts) {
         console.log(body("    synthesisui login"));
         return;
     }
-    // Which system does this project's record belong to? The .lock says.
-    const dsDir = join(root, "_synthesisui", "ds");
-    let slug = null;
-    try {
-        const slugs = (await readdir(dsDir, { withFileTypes: true }))
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name);
-        for (const s of slugs) {
-            const raw = await readFile(join(dsDir, s, ".lock"), "utf8").catch(() => "");
-            try {
-                const lock = JSON.parse(raw);
-                // An adopted system is described, not owned on the platform - there is
-                // no dashboard row to sync into (yet).
-                if (lock.slug && !lock.adopted) {
-                    slug = lock.slug;
-                    break;
-                }
-            }
-            catch {
-                // unreadable lock - try the next
-            }
-        }
-    }
-    catch {
-        // no _synthesisui at all
-    }
+    const slug = await installedSlug(root);
     if (!slug) {
         console.log(section("Sync"));
         console.log(body("No installed system here, so there is nowhere to sync to."));
@@ -180,7 +155,7 @@ export async function sync(opts) {
  *      avisar.
  *   5. envia para a rota que atualiza o RASCUNHO pelo slug - nada publicado se move.
  */
-async function remeasure(args) {
+export async function remeasure(args) {
     const { root, base, token, slug } = args;
     const head = await fetch(`${base}/api/registry/ds/${slug}/reading`, {
         headers: { Authorization: `Bearer ${token}` },
@@ -202,6 +177,20 @@ async function remeasure(args) {
         console.log(body(`"${slug}" did not come from an import, so there is no measurement to refresh. Import it first: npx synthesisui import`));
         return;
     }
+    /**
+     * A DISTÂNCIA ATÉ O CLI PUBLICADO, dita onde ele já está.
+     *
+     * O hook fica pinado na versão do dia do `connect` - por um motivo medido: 720ms por escrita, e um
+     * check que muda sob você é indebugável. O preço é que ele não avança sozinho, e a única pessoa que
+     * pode movê-lo é quem roda o comando. Então o número é dito aqui, com o comando ao lado, em vez de
+     * viver numa tela que alguém precisa lembrar de abrir.
+     */
+    if (stored.publishedCli && args.cli && stored.publishedCli !== args.cli) {
+        console.log(section("A newer reader is published"));
+        console.log(body(`You are running ${args.cli} and ${stored.publishedCli} is published. The measurement below uses ${args.cli}.`));
+        console.log(paint.blue(snippet(["npx synthesisui@latest connect"])));
+        console.log(body(paint.faint("That rewires the hook and the tools to the new version - the editor picks them up on the next session.")));
+    }
     console.log(section("Measuring your repository again"));
     console.log(body(paint.faint(`${stored.scope ? `scope ${stored.scope}` : "the whole repo"} · the reading you already authored travels unchanged`)));
     const census = await takeCensus(stored.scope ? join(root, stored.scope) : root, {
@@ -296,3 +285,34 @@ async function askToOverwrite() {
         rl.close();
     }
 }
+/**
+ * O SLUG QUE ESTE PROJETO TEM INSTALADO, ou `null`.
+ *
+ * Uma função e não duas cópias: o `sync` e a ferramenta `refresh_system` do MCP precisam da mesma
+ * busca, e a regra que ela carrega - um DS ADOTADO é descrito aqui e pertencido em outro lugar, então
+ * não tem linha no dashboard para onde sincronizar - discordaria entre duas cópias na primeira vez que
+ * alguém a mudasse.
+ */
+export async function installedSlug(root) {
+    const dsDir = join(root, "_synthesisui", "ds");
+    try {
+        const slugs = (await readdir(dsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+        for (const name of slugs) {
+            const raw = await readFile(join(dsDir, name, ".lock"), "utf8").catch(() => "");
+            try {
+                const lock = JSON.parse(raw);
+                if (lock.slug && !lock.adopted)
+                    return lock.slug;
+            }
+            catch {
+                // unreadable lock - try the next
+            }
+        }
+    }
+    catch {
+        // no _synthesisui at all
+    }
+    return null;
+}

package/dist/repo-state.js

@@ -50,6 +50,9 @@ export async function repoStateOf(projectRoot, slug, cli) {
         ...(typeof doctor?.phantoms === "number"
             ? { drifts: doctor.phantoms }
             : {}),
+        ...(typeof doctor?.crossFamily === "number"
+            ? { crossFamily: doctor.crossFamily }
+            : {}),
     };
     /** Só o `cli` não é estado: sem nada do repo, não há o que reportar. */
     return Object.keys(payload).length > 1 ? payload : null;

package/package.json

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