synthesisui 0.16.283 → 0.16.285

package/dist/commands/add.js

@@ -10,6 +10,7 @@ import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
 import { detectStack } from "../stack.js";
+import { pointTokensAtTheirNames } from "../their-vars.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
  *
@@ -193,9 +194,18 @@ export async function add(slug, opts) {
     // know what was active before, to report install vs update vs switch
     const prev = await readRootLock(rootLockPath);
     await mkdir(versionDir, { recursive: true });
+    /**
+     * O VOCABULÁRIO DELE, LIDO NESTA MÁQUINA - ver `their-vars.ts`, e é por isso que isto acontece
+     * aqui e não no compilador: a pergunta *"esta variável existe NESTE repositório?"* só tem resposta
+     * onde o repositório está.
+     *
+     * Falha calada de propósito: um repositório sem folha de estilo, ou sem build, devolve o que veio
+     * do servidor. A folha nunca fica pior do que estava.
+     */
+    const theirVars = await pointTokensAtTheirNames(projectRoot, payload);
     // 1. server artifacts (tokens.css, theme.css, …) → pinned version folder
     for (const [filename, content] of Object.entries(payload.artifacts)) {
-        await writeFile(join(versionDir, filename), content, "utf8");
+        await writeFile(join(versionDir, filename), filename === "tokens.css" ? theirVars.css : content, "utf8");
     }
     // 2. canonical source of truth
     await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document, null, 2)}\n`, "utf8");
@@ -250,6 +260,14 @@ export async function add(slug, opts) {
         /** 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 } : {}),
+        /**
+         * QUANTAS LINHAS DESTA FOLHA APONTAM PARA UMA VARIÁVEL DELE - ver `their-vars.ts`.
+         *
+         * Sem isto, o `tokens.css` de dois repositórios do mesmo sistema seria diferente e nada diria por
+         * quê. O número é o rastro: o `doctor` sabe que aquelas linhas dependem do vocabulário DESTE
+         * repositório, e é ele que avisa quando uma delas deixa de resolver.
+         */
+        ...(theirVars.pointed > 0 ? { theirVars: theirVars.pointed } : {}),
         ...(scope ? { scope } : {}),
         ...(systems.length > 0 ? { scopes: systems } : {}),
         ...(usage.length > 0 ? { usage } : {}),
@@ -371,6 +389,13 @@ export async function add(slug, opts) {
         "GUIDE.md",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
+    /**
+     * A FOLHA NÃO É A QUE O SERVIDOR COMPILOU, e calar isso é o pior dos dois mundos: o cliente vê um
+     * `var(--color-ink-500)` num arquivo "gerenciado pelo synthesisui" e não tem como saber de onde
+     * veio. Dito assim, ele lê a linha como o que ela é - o sistema seguindo o vocabulário dele.
+     */
+    if (theirVars.pointed > 0)
+        console.log(`  ${theirVars.pointed} value${theirVars.pointed === 1 ? "" : "s"} in tokens.css now point at the name YOUR code already gives ${theirVars.pointed === 1 ? "it" : "them"} - change yours and the system follows${theirVars.pruned > 0 ? `; ${theirVars.pruned} matched but your build does not emit ${theirVars.pruned === 1 ? "that name" : "those names"}, so ${theirVars.pruned === 1 ? "it keeps" : "they keep"} the value` : ""}`);
     /**
      * O QUE O AGENTE VAI LER, e por qual porta - nomear o arquivo quando a porta é uma ferramenta
      * mandaria alguém procurar um caminho que não existe mais.
@@ -465,20 +490,39 @@ export async function add(slug, opts) {
         ? nextFontSnippet(families, payload.slug, appDir)
         : null;
     if (nextFonts) {
-        const fontsPath = join(projectRoot, ...appDir.split("/"), "fonts.ts");
-        let wroteFonts = false;
-        if (!(await exists(fontsPath)) &&
-            (await exists(join(projectRoot, ...appDir.split("/"))))) {
+        /**
+         * UM `fonts.ts` POR APP, e não só no primeiro - lacuna do próprio conserto de 22/08.
+         *
+         * Aquele conserto ensinou o `add` a ENCONTRAR os apps de um monorepo e a NOMEAR todos eles, e
+         * depois escrevia em um só. Metade da fiação entregue é a metade que engana: o cliente lê que
+         * dois apps foram encontrados, vê o arquivo aparecer, e descobre que o segundo ficou sem quando
+         * a tipografia dele não carrega.
+         *
+         * Cada app tem o seu, porque `next/font` é por app: o `layout.tsx` de cada um importa do próprio
+         * `fonts.ts`. Um arquivo compartilhado atravessaria a fronteira do workspace.
+         */
+        const wroteIn = [];
+        for (const dir of appDirs.length > 0 ? appDirs : [appDir]) {
+            const fontsPath = join(projectRoot, ...dir.split("/"), "fonts.ts");
+            /** Arquivo dele que já existe nunca é reescrito - o setup impresso diz o que ele deve exportar. */
+            if (await exists(fontsPath))
+                continue;
+            if (!(await exists(join(projectRoot, ...dir.split("/")))))
+                continue;
+            const snippet = nextFontSnippet(families, payload.slug, dir);
+            if (!snippet)
+                continue;
             const header = [
                 `// Self-hosted type for the "${payload.slug}" design system (via next/font -`,
                 `// preloaded, no font flash). Generated by \`synthesisui add\`; edit freely.`,
             ];
-            await writeFile(fontsPath, `${[...header, ...nextFonts.fontsFile.slice(1)].join("\n")}\n`, "utf8");
-            wroteFonts = true;
+            await writeFile(fontsPath, `${[...header, ...snippet.fontsFile.slice(1)].join("\n")}\n`, "utf8");
+            wroteIn.push(`${dir}/fonts.ts`);
         }
+        const wroteFonts = wroteIn.length > 0;
         console.log("");
         if (wroteFonts) {
-            console.log(line(`3. ✓ wrote ${appDir}/fonts.ts - self-hosted type via next/font (preloaded, no font flash).`));
+            console.log(line(`3. ✓ wrote ${wroteIn.join(", ")} - self-hosted type via next/font (preloaded, no font flash).`));
             console.log(line("   Finish the wiring with two small edits:"));
         }
         else {

package/dist/commands/doctor.js

@@ -20,6 +20,7 @@ import { groupRole } from "../group-role.js";
 import { actingSlug, describeScope, measuredScope, scopePaths, } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { resolveDeps } from "../stack.js";
+import { danglingTheirVars } from "../their-vars.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -891,6 +892,25 @@ export async function doctor(opts) {
         }
         console.log(body("The exact snippets are in the output of `init`."));
     }
+    /**
+     * A FOLHA APONTA PARA O VOCABULÁRIO DELE, E UM NOME SUMIU - ver `their-vars.ts`.
+     *
+     * O `add` reescreve `--ds-color-ink-500: #6b6b78` como `var(--color-ink-500)` quando o repositório
+     * já nomeia aquele valor, para não existirem duas fontes da verdade. Não há fallback, por decisão:
+     * uma cópia do valor sobreviveria a um rename DELE pintando o valor velho, que é a plataforma
+     * decidindo por cima da decisão dele.
+     *
+     * O preço é que um rename apaga a cor, e este é o único lugar que conhece as duas pontas. Sem esta
+     * linha ele veria um componente sem cor e nada explicaria de onde veio.
+     */
+    const dangling = danglingTheirVars(await readFile(join(root, "_synthesisui", "ds", table.slug ?? "", "tokens.css"), "utf8").catch(() => ""), installed.theirs);
+    if (dangling.length > 0) {
+        console.log("");
+        console.log(body(`${dangling.length} line${dangling.length === 1 ? "" : "s"} of this system point at ${dangling.length === 1 ? "a variable" : "variables"} your code no longer declares, so ${dangling.length === 1 ? "that value" : "those values"} paint nothing:`));
+        for (const { ours, theirs: name } of dangling.slice(0, 6))
+            console.log(body(`  ${ours} → ${name}`));
+        console.log(body("Rename it back, or run `npx synthesisui add <slug>` to re-point the sheet at what you have now."));
+    }
     /**
      * E AQUI O RELATÓRIO PARA, quando a fiação está vermelha: uma instrução, e nada mais.
      *

package/dist/commands/sync.js

@@ -150,7 +150,24 @@ export async function sync(opts) {
     const requests = await readRequests(root);
     /** O que ele declarou sobre as formas dele - ver `declared-forms.ts`. */
     const forms = await readDeclaredForms(root);
-    if (events.length === 0 && requests.length === 0) {
+    /**
+     * O REGISTRO ESTAR VAZIO NÃO É MOTIVO PARA NÃO ENVIAR NADA - e era, e isso custou uma promessa.
+     *
+     * O QUE O CLIENTE PERDIA. O estado do repositório - em que versão ele está, com qual CLI - viaja no
+     * MESMO pacote que o registro de checagens. Este `return` acontecia antes do envio, e ele dispara
+     * exatamente no estado de quem acabou de instalar: o hook nunca rodou, então não há evento nenhum.
+     *
+     * Resultado medido em 22/08: `repo_state` nulo em 25 dos 26 sistemas em produção. A tela nunca
+     * conseguiu dizer *"você está na v1 e existe a v2"*, para ninguém, desde que a coluna existe.
+     *
+     * A ROTA JÁ ESTAVA PRONTA, e é isso que faz disto meia jornada e não uma feature faltando:
+     * `api/ledger` grava o estado antes dos eventos e diz por quê - *"gravá-lo não depende de haver
+     * evento nenhum"*. Os dois lados concordavam; o cliente é que voltava antes de falar.
+     *
+     * A frase continua sendo dita - ela é verdade e é útil. O que muda é que ela para de ser uma saída.
+     */
+    const emptyLedger = events.length === 0 && requests.length === 0;
+    if (emptyLedger && !repo && forms.length === 0) {
         console.log(section("Sync"));
         console.log(body("Nothing recorded yet. The record fills as the hook checks writes and doctor runs."));
         return;
@@ -209,7 +226,15 @@ export async function sync(opts) {
      */
     const gained = await inherit(root, out.inheritedForms ?? []);
     console.log(section("Sync"));
-    console.log(body(`${out.eventsReceived} checks sent, ${out.eventsNew} new. ${out.requestsNow} open request${out.requestsNow === 1 ? "" : "s"}.`));
+    /**
+     * "0 CHECKS SENT" NÃO É O QUE ACONTECEU quando o registro está vazio e o estado do repo foi.
+     *
+     * A frase antiga contava eventos; num repositório recém-instalado ela leria "0 checks sent, 0 new"
+     * e esconderia a única coisa que realmente subiu. Quem lê "0" conclui que o comando não fez nada.
+     */
+    console.log(body(emptyLedger
+        ? `No checks recorded here yet - the record fills as the hook checks writes and doctor runs.${repo ? " This repo's installed version was sent, so the platform can tell you when a newer one exists." : ""}`
+        : `${out.eventsReceived} checks sent, ${out.eventsNew} new. ${out.requestsNow} open request${out.requestsNow === 1 ? "" : "s"}.`));
     if (gained > 0) {
         console.log("");
         console.log(body(`${gained} form${gained === 1 ? "" : "s"} your team already taught the pipeline now apply here too - the next measurement reads them without you declaring anything.`));

package/dist/install-marks.js

@@ -128,7 +128,7 @@
  * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
  * publicar no meio.
  */
-export const MATERIALISER_SINCE = "0.16.283";
+export const MATERIALISER_SINCE = "0.16.285";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/their-vars.js

@@ -0,0 +1,200 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { theirNames } from "./doctor/their-names.js";
+import { buildTable, normalizeValue, } from "./doctor/tokens.js";
+/**
+ * A FOLHA APONTA PARA O NOME QUE O CÓDIGO DELE JÁ DÁ AO VALOR.
+ *
+ * O QUE O CLIENTE VÊ. O `tokens.css` que a gente instala declara `--ds-color-ink-500: #6b6b78` num
+ * repositório que declara `--color-ink-500: #6b6b78` desde antes da gente existir. Mesmo valor,
+ * mesma palavra, prefixo nosso - e duas fontes da verdade. Ele muda a dele e a nossa fica congelada
+ * no valor que a gente copiou. Medido em 22/08 no `codelevel-monorepo`: 78 de 161 declarações.
+ *
+ * Depois disto a nossa linha vira `--ds-color-ink-500: var(--color-ink-500)`, e a cor do sistema
+ * segue a decisão dele sem a gente reescrever nada no arquivo dele.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * POR QUE ISTO MORA NO CLI E NÃO NO COMPILADOR, que é onde eu ia colocar.
+ *
+ * O mesmo `compileDesignSystemCss` serve DOIS consumidores: o `tokens.css` que vai para a pasta dele
+ * e o Canvas do Studio, onde a folha de estilo dele não existe. Apontar para `var(--color-ink-500)`
+ * lá dentro apagaria a cor do nosso próprio preview - e apagaria também em todo projeto de DESTINO,
+ * que é o caso que `orphan-var.ts` já descreve: *"no projeto de origem isso nunca aparece, porque o
+ * globals.css dele ainda está lá"*.
+ *
+ * A informação que decide - *"esta variável existe NESTE repositório?"* - só existe na máquina dele.
+ * Rodando aqui, o projeto de destino se resolve sozinho: nada casa, nada é reescrito.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE PROTEGE, e cada guarda saiu de uma medição.
+ *
+ *     o BUILD é a autoridade     o Tailwind PODA `@theme` que nenhuma utility usa. Medido nos 19
+ *                                arquivos CSS que o build dele produziu: 7 das 78 declarações somem.
+ *                                Apontar para uma podada não deixa a cor errada - apaga a cor.
+ *                                (as 29 cores dele sobreviveram; a poda pegou só `--animate-*`)
+ *     sem build, sem reescrita   um repositório que nunca buildou não tem como provar o que resolve,
+ *                                e chutar aqui é o oposto do objetivo. A folha fica como veio e o
+ *                                comando DIZ que ficou.
+ *     a categoria fecha          `theirNames` recusa comprimento cru: `24px` pode ser raio ou
+ *                                espaçamento no vocabulário dele, e escolher errado escreve um token
+ *                                de tipo num `border-radius`.
+ *     nada de fallback           `var(--x, #6b6b78)` sobreviveria a um rename DELE pintando o valor
+ *                                velho - a plataforma decidindo por cima da decisão dele. Se ele
+ *                                renomear, quebra, e o `doctor` diz qual (dono, 22/08: *"a gente não
+ *                                pode ser invasivo... mas tem que ser capaz de identificar"*).
+ */
+/** Onde um build costuma deixar o CSS que o navegador realmente recebe. */
+const BUILD_DIRS = [".next", "dist", "build", "out", "storybook-static"];
+async function* cssUnder(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* cssUnder(path);
+        else if (entry.name.endsWith(".css"))
+            yield path;
+    }
+}
+/**
+ * AS VARIÁVEIS QUE O BUILD DELE REALMENTE EMITE - a autoridade sobre o que resolve no navegador.
+ *
+ * `null` quando não há build nenhum, e null significa *não sei*, não *nenhuma*. Quem chama trata os
+ * dois de forma oposta.
+ */
+export async function resolvableVars(root) {
+    const out = new Set();
+    let found = false;
+    for (const dir of BUILD_DIRS) {
+        for await (const file of cssUnder(join(root, dir))) {
+            found = true;
+            const css = await readFile(file, "utf8").catch(() => "");
+            for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g))
+                out.add(m[1]);
+        }
+        /** Monorepo: o build mora dentro de cada app, não na raiz. */
+        for (const group of ["apps", "packages"]) {
+            for (const entry of await readdir(join(root, group), {
+                withFileTypes: true,
+            }).catch(() => [])) {
+                if (!entry.isDirectory())
+                    continue;
+                for await (const file of cssUnder(join(root, group, entry.name, dir))) {
+                    found = true;
+                    const css = await readFile(file, "utf8").catch(() => "");
+                    for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g))
+                        out.add(m[1]);
+                }
+            }
+        }
+    }
+    return found ? out : null;
+}
+/**
+ * REESCREVE A FOLHA, e só as linhas que passam nos dois portões.
+ *
+ * `theirs` é a tabela do repositório dele (`harvestOwnTokens`); `resolvable` é o que o build emite,
+ * ou `null` quando não há build - e aí nada é reescrito.
+ */
+export function pointAtTheirNames(css, theirs, resolvable) {
+    if (!resolvable || theirs.byName.size === 0)
+        return { css, pointed: 0, pruned: 0 };
+    const ours = buildTable({ css, source: "installed" });
+    const alias = theirNames(ours, theirs);
+    let pointed = 0;
+    let pruned = 0;
+    const out = css.replace(/^(\s*)(--ds-[a-zA-Z0-9_-]+)(\s*:\s*)([^;]+);/gm, (line, indent, name, sep, value) => {
+        /** Uma linha que já aponta para outra variável não é uma cópia de valor. */
+        if (value.includes("var("))
+            return line;
+        const kind = Object.entries(FAMILY_KIND).find(([prefix]) => name.startsWith(prefix))?.[1];
+        if (!kind)
+            return line;
+        const theirName = alias.get(`${kind}:${normalizeValue(value.trim(), ours.rootPx)}`);
+        if (!theirName || theirName === name)
+            return line;
+        if (!resolvable.has(theirName)) {
+            pruned += 1;
+            return line;
+        }
+        pointed += 1;
+        return `${indent}${name}${sep}var(${theirName});`;
+    });
+    return { css: out, pointed, pruned };
+}
+/**
+ * O PREFIXO DA NOSSA VARIÁVEL -> A FAMÍLIA, e a chave que `theirNames` devolve é `<família>:<valor>`.
+ *
+ * Comprimento cru fica de fora por decisão de `their-names.ts`, e a razão é a mesma aqui: `24px` pode
+ * ser raio ou espaçamento no vocabulário dele.
+ */
+const FAMILY_KIND = {
+    "--ds-color-": "color",
+    "--ds-shadow-": "shadow",
+    "--ds-typography-families-": "font",
+    "--ds-motion-durations-": "motion",
+    "--ds-motion-easings-": "motion",
+};
+/**
+ * A JORNADA INTEIRA, num chamador só - varrer, medir o build, reescrever.
+ *
+ * Recebe o payload em vez do CSS solto porque um argumento opcional a menos é uma chamada pela
+ * metade a menos: quem chama não tem como esquecer de passar a folha certa.
+ */
+export async function pointTokensAtTheirNames(root, payload) {
+    const css = payload.artifacts["tokens.css"] ?? "";
+    if (!css)
+        return { css, pointed: 0, pruned: 0 };
+    const [theirs, resolvable] = await Promise.all([
+        harvestTheirCss(root),
+        resolvableVars(root),
+    ]);
+    return pointAtTheirNames(css, theirs, resolvable);
+}
+/** As folhas de estilo DELE, e nenhuma da nossa pasta. Gêmeo de `harvestOwnTokens` no doctor. */
+async function harvestTheirCss(root) {
+    const skip = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        ".next",
+        "build",
+        "out",
+        "_synthesisui",
+    ]);
+    let css = "";
+    const walk = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            if (skip.has(entry.name) || entry.name.startsWith("."))
+                continue;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (/\.(css|scss|sass|less)$/i.test(entry.name))
+                css += `\n${await readFile(path, "utf8").catch(() => "")}`;
+        }
+    };
+    await walk(root);
+    return buildTable({ css, source: "yours" });
+}
+/**
+ * AS LINHAS QUE APONTAM PARA UM NOME DELE QUE NÃO EXISTE MAIS.
+ *
+ * O dono decidiu a política em 22/08, e ela é o oposto de defensiva: *"só fazer o design dele quebrar
+ * e ele mesmo acaba consertando. A gente não pode ser invasivo... mas tem que ser capaz de, se o
+ * usuário precisar, corrigir, ou pelo menos identificar o problema."*
+ *
+ * Então não existe fallback. Se ele renomeia `--color-ink-500`, a cor some - e este é o único lugar
+ * que sabe dizer POR QUÊ, porque só ele conhece as duas pontas: a folha que a gente instalou e o
+ * vocabulário que o repositório declara hoje.
+ */
+export function danglingTheirVars(installedCss, theirs) {
+    const out = [];
+    for (const m of installedCss.matchAll(/(--ds-[a-zA-Z0-9_-]+)\s*:\s*var\(\s*(--[a-zA-Z0-9_-]+)\s*\)\s*;/g)) {
+        const target = m[2];
+        /** Uma referência à nossa própria folha resolve nela mesma - não é dependência do repo dele. */
+        if (target.startsWith("--ds-"))
+            continue;
+        if (!theirs.byName.has(target))
+            out.push({ ours: m[1], theirs: target });
+    }
+    return out;
+}

package/package.json

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