synthesisui 0.16.171 → 0.16.174

package/dist/commands/add.js

@@ -137,6 +137,8 @@ export async function add(slug, opts) {
         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 } : {}),
         ...(scope ? { scope } : {}),
         ...(usage.length > 0 ? { usage } : {}),
     };

package/dist/commands/align.js

@@ -138,16 +138,38 @@ 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",
+        };
+    return null;
 }
 /**
  * A linha que a sessão vê.
@@ -156,11 +178,21 @@ export async function versionBehind(root, opts = {}) {
  * injetado no contexto de um agente, e cada linha decorativa é contexto que não é sobre o trabalho
  * dele.
  */
-export function describeMisalignments(items) {
+export function describeMisalignments(items, 
+/**
+ * DE ONDE A PERGUNTA VEIO decide a primeira frase, e não é enfeite.
+ *
+ * "Before this session starts" descreve o hook do editor. Num terminal não existe sessão nenhuma
+ * para começar, e a frase vira ruído em cima de um aviso que a pessoa precisa ler - o gancho de
+ * shell nasceu em 07/08 e a copy tinha que nascer com ele.
+ */
+from = "session") {
     if (items.length === 0)
         return "";
     return [
-        "Before this session starts, this environment is out of alignment with the design system that governs it:",
+        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:",
         ...items.map((m) => `  - ${m.says}${m.run ? `\n      ${m.run}` : ""}`),
     ].join("\n");
 }
@@ -180,7 +212,7 @@ export async function align(opts) {
     const remote = await versionBehind(root).catch(() => null);
     if (remote)
         items.push(remote);
-    const text = describeMisalignments(items);
+    const text = describeMisalignments(items, opts.shell ? "shell" : "session");
     if (text)
         console.log(text);
 }

package/dist/commands/connect.js

@@ -2,7 +2,9 @@ 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";
 import { INIT_SKILL, INIT_SKILL_PATH } from "../skill-init.js";
 import { add } from "./add.js";
@@ -47,6 +49,14 @@ 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) {
+    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;
+}
 async function refreshInstall(root, cli, registry) {
     const dsDir = join(root, "_synthesisui", "ds");
     const names = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
@@ -66,7 +76,22 @@ 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 fetchCompiler(base, lock.slug, lock.version);
+        const compilerMoved = remote != null && remote !== (lock.compiler ?? null);
+        if (lock.cli === cli && !compilerMoved)
             continue;
         const done = await add(lock.slug, {
             ...(registry ? { registry } : {}),
@@ -81,6 +106,59 @@ async function refreshInstall(root, cli, registry) {
     }
     return null;
 }
+/**
+ * O AVISO NO TERMINAL, oferecido uma vez - ver `shell-hook.ts` para o porquê e as três restrições.
+ *
+ * FORA DO REPOSITÓRIO É OUTRO TERRITÓRIO. Tudo que o `connect` escreve hoje mora no projeto, e um
+ * `.zshrc` é da PESSOA e de todos os outros projetos dela. Então isto pergunta, mostra exatamente o
+ * que vai escrever e onde, e um "não" não custa nada: o hook do editor continua valendo inteiro.
+ *
+ * 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) {
+    const shell = shellFrom(process.env);
+    if (!shell)
+        return;
+    const rc = rcPathFor(shell);
+    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. */
+    if (current != null && hasHook(current)) {
+        const next = withHook(current, shellSnippet(shell));
+        if (next !== current) {
+            await writeFile(rc, next, "utf8").catch(() => { });
+            console.log("");
+            console.log(body(`Refreshed the terminal check in ${rc}.`));
+        }
+        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");
+        console.log("");
+        console.log(body(`Terminal check written to ${rc}.`));
+        console.log(body(`Open a new terminal, or run: source ${rc}`));
+        return;
+    }
+    console.log("");
+    console.log(body("Your editor tells you when this repo drifts, once a session. Your terminal does not, and that is where most people notice something is stale."));
+    console.log(body(paint.faint(`Adding it writes one block to ${rc}. It stays silent when nothing is wrong, never blocks your prompt, and checks at most once an hour.`)));
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log(body(paint.blue("  npx synthesisui@latest connect --shell")));
+        return;
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const answer = await rl.question(`  Add it to ${rc}? [y/N] `).catch(() => "");
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim()))
+        return;
+    await writeFile(rc, withHook(current ?? "", shellSnippet(shell)), "utf8");
+    console.log(body(`Written. Open a new terminal, or run: source ${rc}`));
+}
 export async function connect(opts) {
     const root = opts.dir ?? process.cwd();
     // Both unless one is explicitly turned off - somebody who says `--no-hook`
@@ -228,6 +306,7 @@ 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);
     // The step that cost a round trip the first time this was tried by hand,
     // and would cost every single person one.
     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/index.js

@@ -246,6 +246,7 @@ async function main() {
                 hook: flags.hook !== false,
                 mcp: flags.mcp !== false,
                 ci: flags.ci === true,
+                shell: flags.shell === true,
             });
             return;
         case "hook":
@@ -555,7 +556,7 @@ async function main() {
          * `align.ts` para os nove estados e por que sete deles não tinham verificação nenhuma.
          */
         case "align":
-            await align({ dir, cli: CLI_VERSION });
+            await align({ dir, cli: CLI_VERSION, shell: flags.shell === true });
             break;
         case "request": {
             // `synthesisui request` lists; `request component --name x --for "..."`

package/dist/shell-hook.js

@@ -0,0 +1,100 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * O AVISO NO TERMINAL, e não só quando o agente abre.
+ *
+ * O `align` roda como `SessionStart` do editor, o que cobre o momento em que alguém vai trabalhar COM
+ * o agente. Não cobre o momento em que a maioria das pessoas percebe que algo está velho, que é abrir
+ * o terminal e dar `cd` no projeto (dono, 07/08). Entre um e outro cabe um dia inteiro de trabalho
+ * sobre um design system desatualizado - foi exatamente o que aconteceu com a v2 dele.
+ *
+ * TRÊS RESTRIÇÕES, e as três vieram de medir em vez de supor:
+ *
+ *   4 segundos     é o que um `align` custa através do npx. Rodar em primeiro plano transformaria
+ *                  todo `cd` numa espera, então o gancho joga para segundo plano e nunca segura o
+ *                  prompt.
+ *   uma vez por    sem trava, entrar e sair de uma pasta dispararia uma chamada de rede por vez. O
+ *   hora           carimbo mora em `~/.cache/synthesisui`, FORA do repositório - um arquivo de
+ *                  controle nosso dentro do projeto de alguém vira linha no `git status` dela.
+ *   silêncio       o `align` já não imprime nada quando está tudo certo, e é isso que faz um aviso
+ *                  continuar sendo lido no dia em que importa.
+ *
+ * O bloco é DELIMITADO por marcas. Sem elas, atualizar significaria pedir para a pessoa editar o
+ * próprio `.zshrc` à mão, e instalar duas vezes deixaria duas cópias.
+ */
+export const HOOK_BEGIN = "# >>> synthesisui align >>>";
+export const HOOK_END = "# <<< synthesisui align <<<";
+/**
+ * O bloco a escrever. `shell` decide só a forma de registrar o gancho de diretório: o zsh tem
+ * `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) {
+    const body = shell === "zsh"
+        ? [
+            "sui_align() {",
+            "  [[ -d _synthesisui ]] || return",
+            '  local dir="$HOME/.cache/synthesisui" key="${PWD//\\//_}"',
+            '  mkdir -p "$dir"',
+            '  local stamp="$dir/align$key"',
+            '  if [[ -f "$stamp" ]]; then',
+            '    (( $(date +%s) - $(stat -c %Y "$stamp" 2>/dev/null || echo 0) < 3600 )) && return',
+            "  fi",
+            '  : > "$stamp"',
+            "  (npx --yes synthesisui align --shell 2>/dev/null &)",
+            "}",
+            "autoload -U add-zsh-hook",
+            "add-zsh-hook chpwd sui_align",
+            "sui_align",
+        ]
+        : [
+            "sui_align() {",
+            "  [ -d _synthesisui ] || return 0",
+            '  [ "$PWD" = "$SUI_LAST_DIR" ] && return 0',
+            '  SUI_LAST_DIR="$PWD"',
+            '  local dir="$HOME/.cache/synthesisui" key=$(echo "$PWD" | tr / _)',
+            '  mkdir -p "$dir"',
+            '  local stamp="$dir/align$key"',
+            '  if [ -f "$stamp" ]; then',
+            '    [ $(( $(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 &)",
+            "}",
+            'case "$PROMPT_COMMAND" in *sui_align*) ;; *) PROMPT_COMMAND="sui_align;$PROMPT_COMMAND" ;; esac',
+        ];
+    return [
+        HOOK_BEGIN,
+        "# Tells you when this repo drifts from the design system that governs it.",
+        "# Silent when nothing is wrong. Never blocks the prompt; checks once an hour.",
+        "# Remove this block to uninstall - nothing else on disk depends on it.",
+        ...body,
+        HOOK_END,
+    ].join("\n");
+}
+/** Qual arquivo de perfil, a partir do shell que a pessoa está rodando. */
+export function rcPathFor(shell, home = homedir()) {
+    return join(home, shell === "zsh" ? ".zshrc" : ".bashrc");
+}
+/** 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;
+}
+export function hasHook(text) {
+    return text.includes(HOOK_BEGIN);
+}
+/**
+ * O arquivo com o bloco de HOJE. Instalar de novo SUBSTITUI o bloco antigo em vez de acrescentar um
+ * segundo - senão uma melhoria no gancho viraria duas funções brigando pelo mesmo nome.
+ */
+export function withHook(text, snippet) {
+    if (!hasHook(text))
+        return `${text.replace(/\n*$/, "")}\n\n${snippet}\n`.replace(/^\n+/, "");
+    const start = text.indexOf(HOOK_BEGIN);
+    const endMark = text.indexOf(HOOK_END, start);
+    /** Marca de abertura sem a de fechamento: alguém editou à mão, e apagar até o fim seria destrutivo. */
+    if (endMark === -1)
+        return text;
+    return text.slice(0, start) + snippet + text.slice(endMark + HOOK_END.length);
+}

package/package.json

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