synthesisui 0.16.156 → 0.16.158

package/dist/agent-wiring.js

@@ -45,20 +45,76 @@ export async function hookCommand(root, version) {
  * the owner reading the output against the file, 27/07). Two wrong sentences
  * from one wrong variable, and both point somebody at the wrong thing to debug.
  */
+/**
+ * A VERSÃO QUE O HOOK ESTÁ RODANDO, lida do arquivo dele - ou `null` quando não há hook pinado.
+ *
+ * O hook é PINADO de propósito (ver `hookCommand`): um verificador cujo comportamento muda sob você a
+ * cada edit é indebugável. O preço é que ele nunca fica mais novo sozinho, e em 06/08 o agente do dono
+ * montou essa comparação à mão - leu `.claude/settings.json`, leu `.mcp.json`, e reportou "0.16.153
+ * pinado contra 0.16.156 no MCP". Ele acertou, e nada nosso tinha dito isso a ele.
+ *
+ * Existe para o servidor MCP dizer a frase curta em vez de o agente ter que descobrir: a ferramenta sabe
+ * a própria versão e este leitor sabe a do hook, então a defasagem é aritmética.
+ *
+ * Instalação local devolve `null`: ali o hook segue o `node_modules` e nunca está atrás por si.
+ */
+export async function pinnedHookVersion(root) {
+    const settings = await readJson(join(root, ".claude", "settings.json")).catch(() => ({}));
+    const hooks = (settings.hooks ?? {});
+    const entries = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+    for (const entry of entries)
+        for (const h of entry.hooks ?? []) {
+            const command = h.command ?? "";
+            if (/--no-install synthesisui hook/.test(command))
+                return null;
+            const m = /synthesisui@(\d+\.\d+\.\d+)/.exec(command);
+            if (m)
+                return m[1];
+        }
+    return null;
+}
 async function wireHook(root, command) {
     const dir = join(root, ".claude");
     const path = join(dir, "settings.json");
     const settings = await readJson(path);
     const hooks = (settings.hooks ?? {});
     const post = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
-    // Idempotent on the COMMAND, not on the whole entry: someone may have
-    // widened the matcher or added a second hook beside ours, and running this
-    // again must not undo that.
+    /**
+     * O CASO QUE ESTA FUNÇÃO NÃO COBRIA, e ele tornava o `connect` uma promessa falsa.
+     *
+     * Ela achava QUALQUER hook contendo "synthesisui" e devolvia "already there" sem olhar a versão -
+     * então um hook pinado nunca subia. Medido em 06/08: o dono rodou `npx synthesisui connect` com o
+     * 0.16.157 e a saída disse `· .claude/settings.json already had it / npx synthesisui@0.16.153 hook`.
+     * O pin era permanente até alguém editar o arquivo à mão, e a mensagem que a gente acabou de escrever
+     * - "rode connect, depois reinicie" - mandava rodar um comando que não fazia a coisa.
+     *
+     * Agora o comando é REESCRITO no lugar quando ele é nosso e difere. O que a idempotência original
+     * protegia continua protegido: o matcher fica como estiver, os hooks vizinhos ficam, e uma segunda
+     * entrada nunca é criada - duas entradas rodariam o verificador duas vezes por escrita.
+     */
     const mine = post
         .flatMap((e) => e.hooks ?? [])
         .find((h) => (h.command ?? "").includes("synthesisui"));
-    if (mine)
-        return { status: "already there", command: mine.command ?? command };
+    if (mine) {
+        const was = mine.command ?? "";
+        /**
+         * SÓ UM PIN NOSSO É SUBSTITUÍDO, e a fronteira é estreita de propósito.
+         *
+         * Um comando SEM versão (`npx synthesisui hook`) ou com instalação local é escolha deliberada de
+         * alguém: reescrevê-lo seria pinar a decisão da pessoa, e um spec já protegia isso - o caso do
+         * matcher alargado à mão. O que sobe é `synthesisui@<semver>` para outro semver, que é o único caso
+         * em que "already there" mentia (dono, 06/08: `connect` do 0.16.157 imprimindo
+         * `npx synthesisui@0.16.153 hook` como "already had it").
+         */
+        const pinnedAt = /synthesisui@(\d+\.\d+\.\d+)/.exec(was)?.[1];
+        const proposedAt = /synthesisui@(\d+\.\d+\.\d+)/.exec(command)?.[1];
+        if (!pinnedAt || !proposedAt || pinnedAt === proposedAt)
+            return { status: "already there", command: was || command };
+        mine.command = command;
+        await mkdir(dir, { recursive: true });
+        await writeFile(path, `${JSON.stringify({ ...settings, hooks: { ...hooks, PostToolUse: post } }, null, 2)}\n`, "utf8");
+        return { status: "updated", command, was };
+    }
     post.push({
         matcher: HOOK_MATCHER,
         hooks: [{ type: "command", command }],
@@ -83,8 +139,20 @@ async function wireMcpAt(root, version, rel) {
     const path = join(root, rel);
     const config = await readJson(path);
     const servers = (config.mcpServers ?? {});
-    if (servers.synthesisui)
+    /**
+     * E O MESMO DEFEITO AQUI. Uma entrada nossa que já existe era aceita sem olhar o CONTEÚDO, então quem
+     * conectou antes de 06/08 - quando o MCP passou a flutuar em `@latest` - ficou com um servidor pinado
+     * para sempre, e nenhum `connect` o soltava. Só a NOSSA entrada é reescrita; o resto do arquivo é
+     * dele.
+     */
+    const current = servers.synthesisui;
+    const pinned = current &&
+        Array.isArray(current.args) &&
+        current.args.some((a) => /^synthesisui@\d/.test(String(a)));
+    if (current && !pinned)
         return "already there";
+    /** Reescrita de uma entrada PINADA: é atualização, e a saída tem que dizer isso. */
+    const replacing = Boolean(current && pinned);
     const local = await exists(join(root, "node_modules", ".bin", "synthesisui"));
     await mkdir(dirname(path), { recursive: true }).catch(() => { });
     await writeFile(path, `${JSON.stringify({
@@ -114,7 +182,7 @@ async function wireMcpAt(root, version, rel) {
             },
         },
     }, null, 2)}\n`, "utf8");
-    return "added";
+    return replacing ? "updated" : "added";
 }
 /**
  * Os caminhos de MCP que este repo merece: sempre o do Claude Code, e o do Cursor quando `.cursor/`
@@ -137,11 +205,12 @@ export async function wireAgent(root, version, want) {
     const proposed = await hookCommand(root, version);
     const hook = want.hook
         ? await wireHook(root, proposed)
-        : { status: "skipped", command: proposed };
+        : { status: "skipped", command: proposed, was: undefined };
     return {
         // What is actually installed - the only thing worth printing.
         command: hook.command,
         hook: hook.status,
+        ...(hook.was ? { was: hook.was } : {}),
         mcp: want.mcp ? await wireMcp(root, version) : "skipped",
     };
 }

package/dist/claude-md.js

@@ -199,13 +199,22 @@ nothing changed, nothing changed - carry on.
 about a census taken by an older reader is the worst way to be right - every absence
 in it may have been filled since, and the reader who trusts it has no way to know.
 
-**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.`;
+**And if it says the design system needs updating, do these three things in order:**
+say the one line, ask, and run it.
+
+\`\`\`
+Update the design system before continuing.
+  npx synthesisui@latest connect
+\`\`\`
+
+Then tell them to close and reopen the editor. Not as a footnote - it is the step
+that makes the other two count: 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. Both rewire on a new session and not before, so anything you write in this
+one is still checked by the old reader.
+
+Do not explain the pinning to them and stop there. A paragraph is what somebody
+reads; a command they approved and you ran is what changes the repo.`;
 const VERIFY = `
 
 **Verify with a build, not a running server.** If you do start a dev server, stop

package/dist/commands/connect.js

@@ -41,7 +41,14 @@ export async function connect(opts) {
     if (want.hook) {
         console.log(body(wired.hook === "added"
             ? "✓ .claude/settings.json  the check now runs after every write"
-            : "· .claude/settings.json  already had it"));
+            : wired.hook === "updated"
+                ? /**
+                   * A LINHA QUE FALTAVA, e a ausência dela fazia o comando mentir: rodando o 0.16.157, a
+                   * saída dizia "already had it" e imprimia `npx synthesisui@0.16.153 hook` embaixo
+                   * (dono, 06/08). Quem lê "already had it" fecha o terminal.
+                   */
+                    `✓ .claude/settings.json  the check moved from ${wired.was?.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? "an older version"} to this one`
+                : "· .claude/settings.json  already had it"));
         console.log(snippet([wired.command]));
     }
     /**
@@ -55,7 +62,11 @@ export async function connect(opts) {
         for (const one of wired.mcp)
             console.log(body(one.status === "added"
                 ? `✓ ${one.path.padEnd(22)} ${MCP_TOOL_COUNT} tools, so the agent can ask instead of guess`
-                : `· ${one.path.padEnd(22)} already had it`));
+                : one.status === "updated"
+                    ? /** Uma entrada pinada antes de o MCP flutuar ficava pinada para sempre - nenhum
+                       *  `connect` a soltava, e o agente segurava um leitor velho sem saber. */
+                        `✓ ${one.path.padEnd(22)} unpinned - it now follows the published reader`
+                    : `· ${one.path.padEnd(22)} already had it`));
     }
     /**
      * ONDE O BLOCO CAIU, DITO POR NOME.

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { pinnedHookVersion } from "../agent-wiring.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
@@ -898,8 +899,24 @@ cli) {
                 slug,
                 cli: VERSION,
             }));
-            return text(out.trim() ||
-                "Nothing was reported by the refresh - which means it found nothing to measure.");
+            /**
+             * E A DEFASAGEM DO HOOK, EM TRÊS LINHAS - não num parágrafo.
+             *
+             * O hook é pinado (ver `hookCommand`) e o servidor MCP flutua, então eles divergem no dia em que
+             * uma versão nova é publicada. Em 06/08 o agente do dono montou essa comparação sozinho, leu os
+             * dois arquivos e acertou - e nada nosso tinha dito a ele. Antes disso, a regra do bloco pedia um
+             * parágrafo de explicação; um parágrafo é o que se lê e não é o que se faz.
+             *
+             * Vai aqui e não em toda ferramenta porque a regra manda chamar `refresh_system` uma vez por
+             * sessão: um lugar que sempre roda vale mais que sete que podem rodar.
+             */
+            const pinned = await pinnedHookVersion(root);
+            const behind = pinned && pinned !== VERSION ? pinned : null;
+            const said = out.trim() ||
+                "Nothing was reported by the refresh - which means it found nothing to measure.";
+            return text(behind
+                ? `${said}\n\nUPDATE THE DESIGN SYSTEM BEFORE CONTINUING.\nThe check that runs after your writes is pinned to ${behind} and these tools are ${VERSION}.\n\n  npx synthesisui@latest connect\n\nAsk the person, run it for them, and then say this: close and reopen the editor. The hook and the tools only rewire on a new session, so nothing you write before that is checked by the reader you are holding.`
+                : said);
         }
         case "request_token": {
             const name = String(args.name ?? "");

package/package.json

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