synthesisui 0.16.292 → 0.16.294

package/dist/commands/add.js

@@ -1,15 +1,17 @@
 import { access, mkdir, readdir, readFile, rm, writeFile, } from "node:fs/promises";
 import { join } from "node:path";
 import { syncClaudeMd } from "../claude-md.js";
-import { readProjectConfig, resolveRegistry } from "../config.js";
+import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
 import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
 import { censusScope } from "../measured-scope.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
+import { repoStateOf } from "../repo-state.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
 import { detectStack } from "../stack.js";
+import { onlyWhatMatched } from "../their-theme.js";
 import { pointTokensAtTheirNames } from "../their-vars.js";
 /**
  * QUAL METADE DESTA PASTA UM TIME COMMITA.
@@ -203,9 +205,26 @@ export async function add(slug, opts) {
      * do servidor. A folha nunca fica pior do que estava.
      */
     const theirVars = await pointTokensAtTheirNames(projectRoot, payload);
+    /**
+     * O `theme.css` ALINHA ONDE HÁ O QUE ALINHAR - ver `onlyWhatMatched`.
+     *
+     * O QUE ISSO EVITA NA TELA DELE: `rounded-xl` valia 12px no código dele, o default do Tailwind, e
+     * a nossa folha o fazia valer 28px em 21 elementos. Ele não pediu e não declarou raio nenhum: a
+     * classe dele significava uma coisa e passava a significar outra. Medido em 23/08 - dos 68
+     * utilitários que o arquivo redefine, 4 apontavam para um token que casou com o vocabulário dele e
+     * 64 eram nossos.
+     *
+     * Só isto é possível porque o mapa existe. Sem ele, "este token é dele?" não tinha resposta na hora
+     * de escrever a folha.
+     */
+    const aligned = onlyWhatMatched(payload.artifacts["theme.css"] ?? "", new Set(theirVars.pairs.map((p) => p.ours)));
     // 1. server artifacts (tokens.css, theme.css, …) → pinned version folder
     for (const [filename, content] of Object.entries(payload.artifacts)) {
-        await writeFile(join(versionDir, filename), filename === "tokens.css" ? theirVars.css : content, "utf8");
+        await writeFile(join(versionDir, filename), filename === "tokens.css"
+            ? theirVars.css
+            : filename === "theme.css"
+                ? aligned.css
+                : content, "utf8");
     }
     // 2. canonical source of truth
     await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document, null, 2)}\n`, "utf8");
@@ -301,6 +320,33 @@ export async function add(slug, opts) {
         fetchedAt: landed || !prev?.fetchedAt ? new Date().toISOString() : prev.fetchedAt,
     };
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    /**
+     * O MAPA SOBE AGORA, e é o único momento em que ele é novo.
+     *
+     * O QUE ESTAVA FALTANDO, medido em 23/08: o `.lock` tinha 24 pares e a tabela `token_names` tinha
+     * zero. O `repo_state` viaja em três caminhos - o import, o ping do agente e o `sync` - e o import
+     * o envia ANTES de instalar, quando o `.lock` ainda não existe. Então o mapa ficava esperando o
+     * próximo comando que reportasse, e até lá o Studio continuava falando a nossa língua.
+     *
+     * Este é o comando que escreve o mapa. Ele é quem tem que contar.
+     *
+     * GUARDADO: o sistema está instalado e os arquivos estão no lugar. Uma rede que cai aqui custa o
+     * mapa no servidor até o próximo `sync`, e jamais o install que acabou de dar certo.
+     */
+    if (opts.cli) {
+        const state = await repoStateOf(projectRoot, payload.slug, opts.cli).catch(() => null);
+        const token = await readToken();
+        if (state?.tokenMap && token) {
+            await fetch(`${base}/api/ledger`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify({ slug: payload.slug, repo: state, events: [] }),
+            }).catch(() => null);
+        }
+    }
     await writeGovernanceIgnore(projectRoot);
     const retired = await retireMaterializedDoctrine(slugDir);
     // 5b. governance rules (personal DS) → doctrine.json at the slug root (stable path,
@@ -419,6 +465,15 @@ export async function add(slug, opts) {
             .map((r) => `${r.theirs} → ${theirVars.pairs.find((p) => p.ours === r.ours)?.theirs ?? "?"}`)
             .join(", ")}${renamed.length > 3 ? ", …" : ""}. The system follows the new name from here.`);
     }
+    /**
+     * E ELE FICA SABENDO DO QUE NÃO FOI ALINHADO - cortar em silêncio é a outra metade do erro.
+     *
+     * A linha diz quantos utilitários do Tailwind ficaram apontando para a decisão dele e quantos
+     * saíram por serem nossos, com os primeiros nomes. Quem lê pode discordar de qualquer um.
+     */
+    if (aligned.dropped.length > 0) {
+        console.log(line(`  ${aligned.kept} Tailwind utilit${aligned.kept === 1 ? "y" : "ies"} now point at your own decisions; ${aligned.dropped.length} were left alone because the value would be ours (${aligned.dropped.slice(0, 3).join(", ")}${aligned.dropped.length > 3 ? ", …" : ""}) - your classes keep meaning what they mean today.`));
+    }
     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` : ""}`);
     /**
@@ -436,7 +491,21 @@ export async function add(slug, opts) {
     /** Nomeado, nunca em silêncio: apagar arquivo no repo de alguém se diz em voz alta. */
     if (retired.length > 0)
         console.log(`  removed ${retired.join(" and ")} - nothing rewrote them after an install, so they stated an older version's rules as current`);
-    console.log(`  CLAUDE.md ${claudeMd.created ? "created" : "updated"} (${claudeMd.count} system(s) installed)`);
+    /**
+     * "CREATED" PRECISA DIZER A CONSEQUÊNCIA, e a palavra sozinha não dizia.
+     *
+     * A distinção já existia aqui - `created` contra `updated` -, e três vezes em 23/08 o arquivo foi
+     * criado porque ele não estava no disco, com 78 linhas dele vivas no git. A palavra `created` é
+     * neutra: ela descreve o que o comando fez e não o que aconteceu com o trabalho de quem lê.
+     *
+     * `updated` significa "o seu arquivo continua aí, com o nosso bloco dentro". `created` significa
+     * "não havia arquivo aqui" - e num repositório que TEM um versionado, isso quer dizer que ele está
+     * ausente do diretório de trabalho, o que ninguém faz de propósito. A linha passa a dizer isso e o
+     * comando de volta.
+     */
+    console.log(claudeMd.created
+        ? `  CLAUDE.md created - there was none here (${claudeMd.count} system(s) indexed). If your repo has one in git, it is missing from your working tree: \`git checkout -- CLAUDE.md\` and run this again to keep both.`
+        : `  CLAUDE.md updated - your file is intact, with our block inside it (${claudeMd.count} system(s) indexed)`);
     if (opts.setupHints === false)
         return;
     const hasTheme = cssArtifacts.includes("theme.css");

package/dist/commands/component.js

@@ -34,6 +34,22 @@ async function writeCn(root, compDir, slug) {
 /** Slugs/names are kebab-case by contract; reject anything else before it ever
  *  reaches a filesystem path (defense-in-depth against `../` traversal). */
 const SAFE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * O NOME QUE O ARQUIVO VAI TER - o do blueprint, ou o que ele pediu.
+ *
+ * Puro e exportado porque é a decisão, e ela precisa ser provada sem rede nem disco. O nome vem da
+ * linha de comando e termina dentro de um `join`, então a validação é defesa em profundidade e não
+ * capricho: `--as ../escape` não pode chegar ao sistema de arquivos.
+ */
+export function localName(blueprint, asked) {
+    const wanted = asked?.trim();
+    if (!wanted)
+        return blueprint;
+    if (!SAFE_NAME.test(wanted)) {
+        throw new RegistryError(`Invalid --as "${wanted}" - use kebab-case, like \`--as my-${blueprint}\`.`);
+    }
+    return wanted;
+}
 /**
  * Brings ONE component from a design system into the project (granular "bring
  * specific", INS-18 fatia 3):
@@ -172,7 +188,15 @@ export async function component(slug, name, opts) {
             console.log(body("Nothing of yours was touched. Which name it takes is your call, not ours."));
             return;
         }
-        const compDir = join(root, config.componentsDir, res.name);
+        /**
+         * O NOME QUE O ARQUIVO VAI TER - ver `localName`.
+         *
+         * `--as` é o que permite ele VER o que um blueprint produz num repositório que já tem o
+         * componente. O CSS não muda de nome: a receita é a do blueprint, e as classes dela são
+         * `.ds-<blueprint>` - o componente novo veste o mesmo desenho, com o nome dele no arquivo.
+         */
+        const local = localName(res.name, opts.as);
+        const compDir = join(root, config.componentsDir, local);
         await mkdir(compDir, { recursive: true });
         let filenames;
         if (wantInteractive) {
@@ -180,10 +204,10 @@ export async function component(slug, name, opts) {
             // it wears (.css) + the barrel. Ignores the css|tailwind flavor - the
             // template drives itself off the .ds-* classes.
             const tsx = interactiveTemplate(res.name);
-            await writeFile(join(compDir, `${res.name}.tsx`), tsx, "utf8");
-            await writeFile(join(compDir, `${res.name}.css`), `${css}\n`, "utf8");
-            await writeFile(join(compDir, "index.ts"), `export * from "./${res.name}";\n`, "utf8");
-            filenames = [`${res.name}.tsx`, `${res.name}.css`, "index.ts"];
+            await writeFile(join(compDir, `${local}.tsx`), tsx, "utf8");
+            await writeFile(join(compDir, `${local}.css`), `${css}\n`, "utf8");
+            await writeFile(join(compDir, "index.ts"), `export * from "./${local}";\n`, "utf8");
+            filenames = [`${local}.tsx`, `${local}.css`, "index.ts"];
         }
         else {
             const files = generateComponentFiles(slug, res.name, res.recipe, css, res.version, config.styles, await reactMajorOf(root), 
@@ -195,7 +219,17 @@ export async function component(slug, name, opts) {
              * it, so the TSX and the stylesheet in the same folder agree by
              * construction. Falling back to disk keeps an older registry working.
              */
-            res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug));
+            res.classNames ?? (await readInstalledConvention(root, slug)), 
+            /**
+             * O NOME LOCAL, e o codegen já sabia fazer isto - ver `localName` em
+             * `component-codegen.ts`: *"A project that already exports `Button` should not have to give
+             * the name up to install ours"*. A capacidade existia e nenhuma flag a alcançava, então a
+             * recusa oferecia `--as` e o comando ignorava.
+             *
+             * O ARQUIVO e o EXPORT levam o nome dele; a CLASSE continua sendo a do blueprint. Um
+             * `<CardPreview>` vestindo `.ds-card` está estilizado certo e não faz sombra em nada dele.
+             */
+            local, await readInstalledScheme(root, slug));
             /**
              * AS DECLARAÇÕES DO ARQUIVO DELE QUE O INTERPRETADOR NÃO LEU - ver `unread-for-component.ts`.
              *
@@ -217,7 +251,7 @@ export async function component(slug, name, opts) {
             filenames = files.map((f) => f.filename);
         }
         const flavor = wantInteractive ? "interactive" : `styles: ${config.styles}`;
-        console.log(`✓ ${config.componentsDir}/${res.name}/ → ${filenames.join(", ")}  (${flavor})`);
+        console.log(`✓ ${config.componentsDir}/${local}/ → ${filenames.join(", ")}  (${flavor})${local === res.name ? "" : `  - the "${res.name}" blueprint, under your name`}`);
     }
     else if (opts.interactive && !hasInteractiveTemplate(res.name)) {
         console.log(`  note: no interactive template for "${res.name}" - materialized the standard shell.`);

package/dist/index.js

@@ -522,6 +522,14 @@ async function main() {
                 version,
                 artifactsOnly: flags["artifacts-only"] === true,
                 interactive: flags.interactive === true,
+                /**
+                 * O NOME LOCAL - ver `localName` em `component.ts`.
+                 *
+                 * A recusa por nome ocupado já oferecia `--as`, e a flag não era lida: quem seguia a
+                 * instrução da tela recebia o arquivo com o nome de sempre.
+                 */
+                ...(typeof flags.as === "string" ? { as: flags.as } : {}),
+                ...(flags.force === true ? { force: true } : {}),
             });
             break;
         }

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.292";
+export const MATERIALISER_SINCE = "0.16.293";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/their-theme.js

@@ -0,0 +1,17 @@
+/** `--radius-lg: var(--ds-radius-lg);` - uma redefinição de utilitário do Tailwind pelo nosso token. */
+const ALIGNMENT = /^([ \t]*)(--[a-zA-Z0-9-]+)(\s*:\s*)var\(\s*(--ds-[a-zA-Z0-9-]+)\s*\)\s*;[ \t]*\n?/gm;
+export function onlyWhatMatched(css, 
+/** Os nossos tokens que casaram com um nome do código dele - ver `PointedAt.pairs`. */
+matched) {
+    let kept = 0;
+    const dropped = [];
+    const out = css.replace(ALIGNMENT, (whole, _indent, tailwind, _sep, ours) => {
+        if (matched.has(ours)) {
+            kept += 1;
+            return whole;
+        }
+        dropped.push(tailwind);
+        return "";
+    });
+    return { css: out, kept, dropped: dropped.sort() };
+}

package/package.json

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