synthesisui 0.16.202 → 0.16.204

package/dist/claude-md.js

@@ -350,9 +350,10 @@ Only write something new when nothing in the manifest covers the purpose - and w
 say which entry you considered and why it did not fit, then FILE it while the reasoning is
 still yours: the \`request_component\` MCP tool, or \`npx synthesisui@latest request component
 --name "<name>" --for "<the use case>" --considered "<entries and why not>"\`. That queue is
-what the system's author works from - a refusal said only in chat evaporates. To review a
-component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
-apply it to real production pages unless asked.${selfCheck}`;
+what the system's author works from - a refusal said only in chat evaporates. If you want to eyeball a
+component on its own, an isolated scratch page is optional and never required - and if you make
+one, put it somewhere that does not become a route in this app, and delete it when you are done.
+Do not apply a component to real production pages unless asked.${selfCheck}`;
     const locale = await readInterfaceLanguage(projectRoot);
     const language = locale === null
         ? ""

package/dist/commands/align.js

@@ -148,11 +148,7 @@ opts = {}) {
      * o único lugar que fala sem ser perguntado. Apontava `connect` até 07/08, quando o dono nomeou a
      * incoerência - a palavra que significa atualizar era a única que não atualizava.
      */
-    if (cli && lock.cli && lock.cli !== cli)
-        out.push({
-            says: `the files under _synthesisui/ds/${lock.slug} were written by CLI ${lock.cli} and you are running ${cli} - the design system's version has not changed, but what this CLI writes into that folder has.`,
-            run: "npx synthesisui upgrade",
-        });
+    const folderBehind = cli && lock.cli && lock.cli !== cli ? lock.cli : null;
     /**
      * O HOOK, MEDIDO NELE MESMO - e não pelo `.lock`, que é um proxy que se move sozinho.
      *
@@ -165,11 +161,39 @@ opts = {}) {
      * nunca está atrás por si.
      */
     const pinned = await pinnedHookVersion(root).catch(() => null);
-    if (cli && pinned && pinned !== cli)
+    const hookBehind = cli && pinned && pinned !== cli ? pinned : null;
+    /**
+     * UMA CAUSA, UMA LINHA - e as duas metades nomeadas dentro dela.
+     *
+     * A pasta e o hook são dois lugares diferentes e por isso são duas verificações: o `.lock` já
+     * disse 0.16.180 com o `PostToolUse` pinado em 0.16.178, e um alarme desligado por um conserto
+     * parcial é pior que alarme nenhum. Mas quando os dois estão na MESMA versão anterior, a causa é
+     * uma só - alguém subiu o CLI - e o remédio é um só.
+     *
+     * O que isso custava: duas frases de ~185 caracteres repetindo "e você está rodando X", com
+     * `npx synthesisui upgrade` impresso duas vezes numa mensagem de cinco linhas. O dono leu e
+     * chamou de grande demais (11/08), e ele estava certo pelo motivo errado: não era prolixidade,
+     * era a mesma coisa dita duas vezes.
+     *
+     * Divergiram, voltam a ser dois fatos - que é o caso em que a distinção existe para servir.
+     */
+    if (folderBehind && hookBehind && folderBehind === hookBehind)
         out.push({
-            says: `the check that runs after every write is pinned to CLI ${pinned} and you are running ${cli} - your agent's edits are being checked by an older reader than the one measuring this repo.`,
+            says: `you are running CLI ${cli} and two things here are still on ${folderBehind}: the files under _synthesisui/ds/${lock.slug}, and the check that runs after every write - so your agent's edits are read by the older one.`,
             run: "npx synthesisui upgrade",
         });
+    else {
+        if (folderBehind)
+            out.push({
+                says: `the files under _synthesisui/ds/${lock.slug} were written by CLI ${folderBehind} and you are running ${cli} - the design system's version has not changed, but what this CLI writes into that folder has.`,
+                run: "npx synthesisui upgrade",
+            });
+        if (hookBehind)
+            out.push({
+                says: `the check that runs after every write is pinned to CLI ${hookBehind} and you are running ${cli} - your agent's edits are being checked by an older reader than the one measuring this repo.`,
+                run: "npx synthesisui upgrade",
+            });
+    }
     if (cli && lock.version == null)
         out.push({
             says: `"${lock.slug}" has no version recorded, so nothing can tell whether the CSS in this repo is the one the platform publishes.`,
@@ -328,10 +352,51 @@ from = "session") {
             : from === "shell"
                 ? "This repo is out of alignment with the design system that governs it:"
                 : "Before this session starts, this environment is out of alignment with the design system that governs it:",
-        /** O `then` sai numa linha própria e rotulada: um segundo comando solto lê como parte do primeiro. */
-        ...items.map((m) => `  - ${m.says}${m.run ? `\n      ${m.run}` : ""}${m.then ? `\n      then, to pick up where you left off:\n      ${m.then}` : ""}`),
+        ...grouped(items),
     ].join("\n");
 }
+/**
+ * UM COMANDO APARECE UMA VEZ, com todos os fatos que ele resolve acima dele.
+ *
+ * O dono leu esta mensagem em 11/08 e a chamou de grande demais. Ela era - mas por repetição, não
+ * por prolixidade: as duas linhas diziam a MESMA causa (o CLI andou) e propunham o MESMO comando,
+ * e `npx synthesisui upgrade` saía duas vezes numa mensagem de cinco linhas.
+ *
+ * Contado no código: 5 dos achados propõem `upgrade`, 3 propõem `sync`, 1 propõe `login`. No pior
+ * caso alguém via o mesmo comando cinco vezes.
+ *
+ * Os FATOS continuam separados, um por linha, porque são coisas diferentes que estão erradas - e
+ * é isso que a pessoa precisa saber. O que some é a repetição do remédio. E eles não se fundem
+ * quando divergem: o `.lock` já disse 0.16.180 com o hook pinado em 0.16.178, e são dois fatos.
+ *
+ * A ordem é a da primeira aparição: o primeiro achado decide onde o grupo dele fica.
+ */
+function grouped(items) {
+    const order = [];
+    const byRun = new Map();
+    for (const m of items) {
+        /** O `then` entra na chave: dois achados só compartilham bloco se o remédio for o mesmo INTEIRO. */
+        const key = `${m.run ?? ""}\u0000${m.then ?? ""}`;
+        if (!byRun.has(key)) {
+            byRun.set(key, []);
+            order.push(key);
+        }
+        byRun.get(key)?.push(m);
+    }
+    const out = [];
+    for (const key of order) {
+        const group = byRun.get(key) ?? [];
+        for (const m of group)
+            out.push(`  - ${m.says}`);
+        const { run, then } = group[0];
+        if (run)
+            out.push(`      ${run}`);
+        /** O `then` sai numa linha própria e rotulada: um segundo comando solto lê como parte do primeiro. */
+        if (then)
+            out.push(`      then, to pick up where you left off:\n      ${then}`);
+    }
+    return out;
+}
 /**
  * `synthesisui align` - o comando que o hook de sessão roda.
  *

package/dist/commands/clean.js

@@ -1,4 +1,4 @@
-import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { body, section } from "../output.js";
 // The five SVGs create-next-app drops into public/. Filenames are specific
@@ -100,6 +100,35 @@ export async function clean(opts) {
             run: () => rm(readmePath),
         });
     }
+    /**
+     * O RASCUNHO QUE A NOSSA PRÓPRIA INSTRUÇÃO PEDIU - e que ninguém sabia remover.
+     *
+     * O `CLAUDE.md` que este CLI escreve sugere uma página isolada para olhar um componente sozinho,
+     * e o agente da pessoa a cria. Nada aqui a escreve, e nada aqui a apagava: ela ficava numa rota
+     * de VERDADE do app dela (`src/app/synthesisui-samples/<x>` é URL acessível), sem dono e sem
+     * saída, até alguém commitar sem querer. Encontrada no repo do dono em 11/08.
+     *
+     * É a mesma assimetria do bloco de shell: fácil de entrar, sem porta de saída. Aqui a saída é
+     * este comando, e ele mantém o contrato que já tem - seco por padrão, cada caminho nomeado antes
+     * de qualquer escrita, `--force` para aplicar.
+     *
+     * UMA AÇÃO POR PÁGINA, e não uma pela pasta: um destrutivo que anuncia um e remove seis faz mais
+     * do que diz, e essa lei já foi paga uma vez na poda de órfãos.
+     */
+    const samplesDir = join(appDir, "synthesisui-samples");
+    for (const entry of await readdir(samplesDir, {
+        withFileTypes: true,
+    }).catch(() => [])) {
+        if (!entry.isDirectory())
+            continue;
+        const p = join(samplesDir, entry.name);
+        actions.push({
+            verb: "remove",
+            path: rel(p),
+            why: "scratch page for eyeballing a component - nothing depends on it",
+            run: () => rm(p, { recursive: true }),
+        });
+    }
     if (actions.length === 0) {
         console.log(section("Clean up scaffold"));
         console.log(body("Nothing to clean - this project is already tidy."));

package/dist/commands/connect.js

@@ -4,7 +4,8 @@ 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 { readShellAnswer, rememberShellNo } from "../shell-answer.js";
+import { existingRc, hasHook, pinnedInHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell-hook.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
 import { INIT_SKILL, INIT_SKILL_PATH } from "../skill-init.js";
 import { add } from "./add.js";
@@ -118,25 +119,48 @@ async function refreshInstall(root, cli, registry) {
  * Sem TTY (CI, um agente rodando o comando) não há a quem perguntar, e a resposta certa é não
  * escrever - um pipeline não deveria acordar com o perfil de shell de alguém alterado.
  */
-async function offerShellHook(asked) {
+async function offerShellHook(asked, 
+/** A versão que fica pinada no bloco - ver `shellSnippet`. */
+version) {
     const shell = shellFrom(process.env);
     if (!shell)
         return;
-    const rc = rcPathFor(shell);
+    /**
+     * O PERFIL QUE EXISTE E QUE O SHELL LÊ - e quando não há nenhum, a gente não cria.
+     *
+     * Acrescentar a um `.zshrc` que a pessoa mantém é uma coisa; CRIAR um perfil que ela nunca teve é
+     * outra, e é maior que a pergunta que fizemos. Quem pediu com `--shell` já decidiu, e aí o padrão
+     * vale. Ver `existingRc` - ele também é o que impede escrever num `.bashrc` que um login shell de
+     * macOS nunca lê.
+     */
+    const rc = (await existingRc(shell)) ?? (asked ? rcPathFor(shell) : null);
+    if (!rc)
+        return;
     const current = await readFile(rc, "utf8").catch(() => null);
-    /** Já instalado: re-materializa em silêncio, para uma melhoria no bloco alcançar quem já disse sim. */
+    /**
+     * JÁ INSTALADO: rematerializa, mas DIZENDO ANTES - e o antes é o conserto.
+     *
+     * Isto escrevia calado e avisava depois, numa linha que a pessoa pode rolar sem ver. O arquivo é
+     * dela e de todos os outros projetos dela, e um `.zshrc` que muda sem uma palavra é a definição
+     * de invasivo (dono, 11/08). Ela consentiu em TER o bloco; mover o que está dentro dele é manter
+     * o que ela aceitou, então isto informa em vez de perguntar - mas informa ANTES.
+     *
+     * E passou a acontecer mais: com a versão pinada no bloco, todo bump do CLI o muda. Os dois
+     * consertos são um só - ver `shellSnippet`.
+     */
     if (current != null && hasHook(current)) {
-        const next = withHook(current, shellSnippet(shell));
+        const next = withHook(current, shellSnippet(shell, version));
         if (next !== current) {
-            await writeFile(rc, next, "utf8").catch(() => { });
+            const was = pinnedInHook(current);
             console.log("");
-            console.log(body(`Refreshed the terminal check in ${rc}.`));
+            console.log(body(`Updating the terminal check in ${rc} - ${was ? `it was pinned to ${was}` : "it was on an unpinned version"}, moving it to ${version}.`));
+            await writeFile(rc, next, "utf8").catch(() => { });
         }
         return;
     }
     /** `--shell` é alguém que já decidiu - perguntar de novo seria não ter escutado. */
     if (asked) {
-        await writeFile(rc, withHook(current ?? "", shellSnippet(shell)), "utf8");
+        await writeFile(rc, withHook(current ?? "", shellSnippet(shell, version)), "utf8");
         console.log("");
         console.log(body(`Terminal check written to ${rc}.`));
         console.log(body(`Open a new terminal, or run: source ${rc}`));
@@ -149,6 +173,18 @@ async function offerShellHook(asked) {
         console.log(body(paint.blue("  npx synthesisui@latest connect --shell")));
         return;
     }
+    /**
+     * ELE JÁ DISSE NÃO - e uma recusa que não é lembrada não é uma decisão.
+     *
+     * Fica a linha calada com o caminho de volta, que é a mesma forma da recusa na tela dele: sumir
+     * de vez esconderia algo que ele pode querer rever; perguntar de novo a cada `connect` é o que
+     * transforma a recusa em nada. Ver `shell-answer.ts`.
+     */
+    const said = await readShellAnswer();
+    if (said) {
+        console.log(body(paint.faint(`You said no to this on ${said.at.slice(0, 10)}. It stays off - \`npx synthesisui@latest connect --shell\` turns it on.`)));
+        return;
+    }
     const { createInterface } = await import("node:readline/promises");
     const rl = createInterface({
         input: process.stdin,
@@ -156,9 +192,11 @@ async function offerShellHook(asked) {
     });
     const answer = await rl.question(`  Add it to ${rc}? [y/N] `).catch(() => "");
     rl.close();
-    if (!/^y(es)?$/i.test(answer.trim()))
+    if (!/^y(es)?$/i.test(answer.trim())) {
+        await rememberShellNo(rc);
         return;
-    await writeFile(rc, withHook(current ?? "", shellSnippet(shell)), "utf8");
+    }
+    await writeFile(rc, withHook(current ?? "", shellSnippet(shell, version)), "utf8");
     console.log(body(`Written. Open a new terminal, or run: source ${rc}`));
 }
 export async function connect(opts) {
@@ -318,7 +356,8 @@ export async function connect(opts) {
         console.log(body(paint.dim("Your PRs can carry this too: annotations on the exact line, and a ratchet that fails only when drift goes UP - never on the debt you already have.")));
         console.log(paint.blue(snippet(["npx synthesisui@latest ci"])));
     }
-    await offerShellHook(opts.shell === true);
+    /** A mesma versão que a fiação do editor recebe - os dois pinam no mesmo número. */
+    await offerShellHook(opts.shell === true, opts.version);
     /**
      * 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).

package/dist/last-sync.js

@@ -24,7 +24,14 @@ export const LAST_SYNC_FILE = ".last-sync.json";
  *
  * `name` sai do valor porque já É a chave - hasheá-lo junto só gastaria bytes.
  */
-export function fingerprintReadings(components) {
+export function fingerprintReadings(
+/**
+ * A LINHA INTEIRA, e o tipo tem que dizer isso: `{ name?: unknown }` prometia menos do que esta
+ * função aceita, e o próprio spec precisou de um `as never` para passar uma linha real. Um tipo
+ * que obriga a burlá-lo está errado - e o `as never` que ele forçava é exatamente o que faria a
+ * impressão parar de ver um campo novo sem ninguém notar.
+ */
+components) {
     const out = {};
     for (const c of components ?? []) {
         const name = typeof c?.name === "string" ? c.name : null;

package/dist/shell-answer.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * A RESPOSTA DELE SOBRE O TERMINAL, GRAVADA - senão a pergunta não decide nada.
+ *
+ * O dono rodou `connect` duas vezes num dia e foi perguntado das duas (11/08). O código já não
+ * pergunta quando o bloco EXISTE - ele reescreve calado e sai. O que não existia era memória do
+ * "não": quem recusa é perguntado de novo em toda conexão, para sempre.
+ *
+ * É a mesma lei que a tela dele já segue em `meta.declined`: *sem gravar, o botão não decide nada*.
+ * E é a mesma forma da recusa lá - ela não SOME, vira uma linha calada com o caminho de volta:
+ * sumir de vez esconderia uma decisão que ele pode querer rever, e continuar cobrando transforma a
+ * recusa em nada.
+ *
+ * MORA NO HOME, ao lado das credenciais, porque a decisão é da MÁQUINA e não do repositório - é o
+ * `.zshrc` dela que está em jogo, e ele é o mesmo para todos os projetos que ela tem. Gravar isso
+ * dentro de um repo faria a pessoa ser perguntada outra vez no próximo clone.
+ */
+const answerPath = (home = homedir()) => join(home, ".synthesisui", "shell.json");
+export async function readShellAnswer(home) {
+    try {
+        const raw = JSON.parse(await readFile(answerPath(home), "utf8"));
+        return raw?.answered === "no" ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Nunca derruba o comando: uma recusa que não grava custa uma pergunta, não a conexão. */
+export async function rememberShellNo(rc, home) {
+    const path = answerPath(home);
+    await mkdir(dirname(path), { recursive: true }).catch(() => { });
+    await writeFile(path, `${JSON.stringify({ answered: "no", at: new Date().toISOString(), rc }, null, 2)}\n`, "utf8").catch(() => { });
+}

package/dist/shell-hook.js

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 /**
@@ -29,7 +30,20 @@ export const HOOK_END = "# <<< synthesisui align <<<";
  * `add-zsh-hook chpwd`, o bash tem `PROMPT_COMMAND` e nenhum equivalente de `chpwd`, então lá a
  * função se protege sozinha comparando o diretório com o da última vez.
  */
-export function shellSnippet(shell) {
+/**
+ * A VERSÃO FICA PINADA AQUI TAMBÉM - e a incoerência que isso resolve estava escrita nos dois lados.
+ *
+ * O hook do editor é pinado de propósito, e o comentário de `agent-wiring` diz por quê: *"um check
+ * que muda sob você é indebugável"*. Este rodava `npx --yes synthesisui align` sem versão - sempre
+ * o `latest`, resolvido a cada hora, na máquina de todo mundo que disse sim. O mesmo argumento,
+ * duas decisões opostas; e o lado despinado é o que ninguém consegue depurar quando um `align`
+ * ruim sai: ele é silencioso por desenho (`2>/dev/null`, em background).
+ *
+ * O PREÇO, dito porque é real: pinar faz o bloco MUDAR a cada bump do CLI, então o `connect` passa
+ * a reescrever um arquivo que é da PESSOA com mais frequência. É por isso que a reescrita passou a
+ * falar antes de escrever, em vez de avisar depois - os dois consertos são um só.
+ */
+export function shellSnippet(shell, version) {
     const body = shell === "zsh"
         ? [
             "sui_align() {",
@@ -41,7 +55,7 @@ export function shellSnippet(shell) {
             '    (( $(date +%s) - $(stat -c %Y "$stamp" 2>/dev/null || echo 0) < 3600 )) && return',
             "  fi",
             '  : > "$stamp"',
-            "  (npx --yes synthesisui align --shell 2>/dev/null &)",
+            `  (npx --yes synthesisui@${version} align --shell 2>/dev/null &)`,
             "}",
             "autoload -U add-zsh-hook",
             "add-zsh-hook chpwd sui_align",
@@ -59,7 +73,7 @@ export function shellSnippet(shell) {
             '    [ $(( $(date +%s) - $(stat -c %Y "$stamp" 2>/dev/null || echo 0) )) -lt 3600 ] && return 0',
             "  fi",
             '  : > "$stamp"',
-            "  (npx --yes synthesisui align --shell 2>/dev/null &)",
+            `  (npx --yes synthesisui@${version} align --shell 2>/dev/null &)`,
             "}",
             'case "$PROMPT_COMMAND" in *sui_align*) ;; *) PROMPT_COMMAND="sui_align;$PROMPT_COMMAND" ;; esac',
         ];
@@ -76,11 +90,46 @@ export function shellSnippet(shell) {
 export function rcPathFor(shell, home = homedir()) {
     return join(home, shell === "zsh" ? ".zshrc" : ".bashrc");
 }
+/**
+ * O PERFIL QUE EXISTE E QUE É LIDO - e `null` quando não há nenhum.
+ *
+ * Duas coisas que `rcPathFor` sozinho não sabe, e as duas escrevem no home de alguém:
+ *
+ *   O ARQUIVO PODE NÃO EXISTIR. Acrescentar um bloco a um `.zshrc` que a pessoa mantém é uma coisa;
+ *   CRIAR um perfil de shell que ela nunca teve é outra, e é maior do que a pergunta que fizemos.
+ *
+ *   `.bashrc` NÃO É LIDO POR TODO BASH. Num login shell de macOS quem é lido é o `.bash_profile`,
+ *   então escrever no `.bashrc` ali instala um aviso que nunca dispara - a pessoa diz sim, a gente
+ *   escreve, e nada acontece nunca. Uma promessa que falha em silêncio é pior que a recusa.
+ *
+ * A ordem para bash é a que o shell usa: o perfil de login primeiro, o `.bashrc` depois.
+ */
+export async function existingRc(shell, home = homedir()) {
+    const candidates = shell === "zsh"
+        ? [".zshrc"]
+        : [".bash_profile", ".bash_login", ".profile", ".bashrc"];
+    for (const name of candidates) {
+        const path = join(home, name);
+        if (await readFile(path, "utf8").then(() => true, () => false))
+            return path;
+    }
+    return null;
+}
 /** Qual shell, lido do ambiente. `null` quando não é um dos dois - aí não há o que escrever. */
 export function shellFrom(env) {
     const name = (env.SHELL ?? "").split("/").pop();
     return name === "zsh" || name === "bash" ? name : null;
 }
+/**
+ * A VERSÃO PINADA DENTRO DO BLOCO - para o `connect` poder dizer o que MOVE antes de mover.
+ *
+ * `null` num bloco escrito antes da pinagem, e a frase trata isso: "was on an unpinned version"
+ * é diferente de "was on 0.16.201", e inventar um número ali seria mentir sobre o arquivo de
+ * alguém.
+ */
+export function pinnedInHook(text) {
+    return /synthesisui@(\d+\.\d+\.\d+)\s+align/.exec(text)?.[1] ?? null;
+}
 export function hasHook(text) {
     return text.includes(HOOK_BEGIN);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.202",
+  "version": "0.16.204",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {
@@ -32,7 +32,8 @@
     "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build",
-    "test": "vitest run"
+    "test": "vitest run",
+    "check": "tsc -p tsconfig.check.json"
   },
   "license": "MIT"
 }