synthesisui 0.16.277 → 0.16.278

package/dist/commands/component.js

@@ -8,6 +8,7 @@ import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-tem
 import { body, section, snippet } from "../output.js";
 import { findCollision, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
+import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
  * installed theme.
@@ -165,8 +166,21 @@ export async function component(slug, name, opts) {
              * construction. Falling back to disk keeps an older registry working.
              */
             res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug));
+            /**
+             * AS DECLARAÇÕES DO ARQUIVO DELE QUE O INTERPRETADOR NÃO LEU - ver `unread-for-component.ts`.
+             *
+             * Sem isto ele recebe o componente sem elas e nada diz que faltou algo: ele descobre
+             * comparando o resultado com o código original. Elas saem em comentário no `.tsx`, com
+             * caminho e linha, porque a plataforma não sabe a qual parte do componente elas se aplicam -
+             * escrevê-las como estilo seria supor o destino e entregar um componente errado em vez de um
+             * incompleto.
+             *
+             * Vazio não vira comentário, e o censo ausente não é erro: um projeto que só instalou o
+             * sistema não tem censo nenhum, e ele recebe o que sempre recebeu.
+             */
+            const nota = unreadComment(unreadForComponent(await readCensus(root), res.name));
             for (const file of files) {
-                await writeFile(join(compDir, file.filename), file.code, "utf8");
+                await writeFile(join(compDir, file.filename), file.filename.endsWith(".tsx") ? `${nota}${file.code}` : file.code, "utf8");
             }
             if (config.styles === "tailwind")
                 await writeCn(root, compDir, slug);

package/dist/commands/mcp.js

@@ -151,7 +151,7 @@ const TOOLS = [
     },
     {
         name: "list_components",
-        description: "The components this design system defines, with what each is for. Look here BEFORE writing any UI element from scratch - if something covers the purpose, materialize it with add_component instead.",
+        description: "The components this design system defines, with what each is for. Look here BEFORE writing any UI element from scratch - if something covers the purpose, materialize it with add_blueprint instead.",
         inputSchema: { type: "object", properties: {} },
     },
     {
@@ -169,7 +169,7 @@ const TOOLS = [
         },
     },
     {
-        name: "add_component",
+        name: "add_blueprint",
         description: "Materialize a component from the design system as real typed code in this project, ready to import and extend. Use it yourself - the person who asked for a feature should never have to know component names.",
         inputSchema: {
             type: "object",
@@ -570,7 +570,7 @@ async function listComponents(root) {
     if (rows.length === 0)
         return "This system defines no components yet - write what you need with its tokens.";
     return [
-        `${rows.length} components. Materialize with add_component before writing one from scratch:`,
+        `${rows.length} components. Materialize with add_blueprint before writing one from scratch:`,
         "",
         ...rows.sort(),
     ].join("\n");
@@ -1311,7 +1311,7 @@ async function describeComponent(root, name) {
         if (states.length > 0) {
             out.push(`  states the recipe already carries: ${states.join(", ")} - they are CSS, so do not write them again in JS.`);
         }
-        out.push(`  Or call add_component { "name": "${name}" } and get it as typed code, one prop per axis.`);
+        out.push(`  Or call add_blueprint { "name": "${name}" } and get it as typed code, one prop per axis.`);
     }
     /**
      * AS INSTRUÇÕES DE RENDER QUE A LEITURA MEDIU - e até aqui elas morriam no
@@ -1387,6 +1387,13 @@ async function addComponent(root, name) {
  */
 const BY_COMPONENT = {
     describe_component: "describe",
+    /**
+     * OS DOIS NOMES GRAVAM `add`, e é isso que impede a métrica de se dividir em duas.
+     *
+     * Sem esta linha o uso da ferramenta cairia pela metade no dia do apelido sem nada ter caído - e
+     * uma métrica que despenca por causa de um rename é uma métrica que ninguém confia depois.
+     */
+    add_blueprint: "add",
     add_component: "add",
 };
 /**
@@ -1419,6 +1426,7 @@ const BY_COMPONENT = {
  */
 const SUBJECT_ARG = {
     describe_component: "name",
+    add_blueprint: "name",
     add_component: "name",
     /** A família pedida - o sinal que o A1 precisa e que não estava sendo guardado. */
     compose_context: "family",
@@ -1520,6 +1528,18 @@ cli) {
             return fromContract(await listComponents(root));
         case "describe_component":
             return describeComponent(root, String(args.name ?? ""));
+        /**
+         * OS DOIS NOMES CHAMAM A MESMA FUNÇÃO, e o antigo sai numa versão futura.
+         *
+         * `blueprint` é o nome público do que a plataforma produz, e `add_component` era o único lugar
+         * da superfície pública que ainda usava o nome antigo. Renomear SUBSTITUINDO quebraria o agente
+         * que já carregou a lista de ferramentas na sessão em curso: ele chamaria um nome que não
+         * existe mais e a sessão dele falharia sem explicação.
+         *
+         * A remoção do apelido fica para quando a telemetria mostrar que ninguém mais o chama - e aí
+         * ela é medida, não estimada.
+         */
+        case "add_blueprint":
         case "add_component":
             return addComponent(root, String(args.name ?? ""));
         case "playbook": {

package/dist/commands/upgrade.js

@@ -9,6 +9,7 @@ import { installedBehind, MATERIALISER_SINCE } from "../install-marks.js";
 import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
+import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
 import { add } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
 import { doctor } from "./doctor.js";
@@ -301,8 +302,18 @@ export async function upgrade(asked, opts) {
                 // components somebody already has: without the convention it would have
                 // taken a working component and stripped its styles.
                 await reactMajorOf(root), res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug));
+                /**
+                 * A NOTA DAS DECLARAÇÕES NÃO INTERPRETADAS SOBREVIVE AO UPGRADE.
+                 *
+                 * Este comando REESCREVE componentes que a pessoa já tem. Sem esta linha, a nota apareceria
+                 * no `component`/`add_blueprint` e sumiria no próximo `upgrade` - o cliente veria a
+                 * informação uma vez e a perderia sem nada dizer que ela existiu.
+                 *
+                 * Ver `unread-for-component.ts`: censo ausente responde vazio, e vazio não vira comentário.
+                 */
+                const nota = unreadComment(unreadForComponent(await readCensus(root), res.name));
                 for (const file of files) {
-                    await writeFile(join(componentsRoot, entry, file.filename), file.code, "utf8");
+                    await writeFile(join(componentsRoot, entry, file.filename), file.filename.endsWith(".tsx") ? `${nota}${file.code}` : file.code, "utf8");
                 }
                 regenerated.push(entry);
             }

package/dist/index.js

@@ -44,6 +44,7 @@ Usage - deterministic, FREE:
   synthesisui list [options]               list the published design systems
   synthesisui list --mine                  your own systems, with their group
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
+  synthesisui bp  <slug> [options]         the same command, short for blueprint
   synthesisui component <slug> <name>      bring one EXISTING component in as YOUR <Pascal>.tsx
   synthesisui template <slug> <name>       materialize a whole page from a DS template
                                            (--as landing-home names the output - multi-page safe)
@@ -348,6 +349,15 @@ async function main() {
              */
             await list({ registry, mine: flags.mine === true });
             break;
+        /**
+         * `bp` É O MESMO COMANDO QUE `add`, e o apelido existe porque `blueprint` é o nome público do
+         * que a plataforma produz.
+         *
+         * Apelido e não substituição: `add` está escrito em toda mensagem que o CLI já imprimiu, em
+         * todo GUIDE.md já materializado e na cabeça de quem usa. Trocá-lo faria um comando que a pessoa
+         * digitou ontem parar de existir hoje.
+         */
+        case "bp":
         case "add": {
             const slug = args[0];
             if (!slug) {

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

package/dist/unread-for-component.js

@@ -0,0 +1,127 @@
+/**
+ * AS DECLARAÇÕES QUE O INTERPRETADOR NÃO LEU, entregues junto com o componente.
+ *
+ * O QUE O CLIENTE GANHA. Ele recebe o componente com as declarações que a plataforma interpretou,
+ * mais as que ela não interpretou, identificadas com arquivo e linha. Hoje ele recebe só as
+ * primeiras e nada diz que faltou algo - ele descobre comparando o resultado com o código original.
+ *
+ * O QUE MUDA NO CÓDIGO. O gerador passa a ler `ledger.unread[].unreadable` do censo e a casar o
+ * arquivo de cada declaração com o arquivo do componente. As que casam saem em comentário no arquivo
+ * gerado.
+ *
+ * O QUE O CLIENTE PERCEBE. O mesmo componente que ele recebe hoje, mais um bloco dizendo quais
+ * declarações do arquivo dele não estão governadas por token ainda - com o caminho e a linha, para
+ * ele decidir o que fazer. Ele não para de codificar por causa de uma lacuna nossa.
+ *
+ * POR QUE COMENTÁRIO E NÃO CÓDIGO. Uma declaração não interpretada não tem lugar conhecido na
+ * recipe: a plataforma não sabe a qual parte do componente ela se aplica. Escrevê-la como estilo
+ * seria supor onde ela vai, e supor aqui produz um componente errado em vez de um incompleto. O
+ * comentário entrega a informação sem inventar o destino.
+ *
+ * O CAMINHO PRECISA DO PREFIXO DO ESCOPO. `ledger.unread[].unreadable[].file` é relativo ao escopo
+ * medido (`src/Card/Card.tsx`) e `looks[X].api.file` é relativo à raiz do repositório
+ * (`packages/ui/src/Card/Card.tsx`). Comparar os dois direto não casa nenhum - medido no censo do
+ * cliente: 0 casam sem o prefixo, 4 casam com ele.
+ *
+ * E A MAIOR PARTE NÃO É DE COMPONENTE NENHUM. Das 194 declarações não interpretadas daquele censo,
+ * 190 estão no `globals.css` - reset, `@theme`, `@utility` - que não veste componente. Elas têm
+ * destino próprio (a nota do sistema) e não podem entrar aqui: 190 linhas de reset dentro de um
+ * `Card` é ruído que faz alguém parar de ler o bloco inteiro.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * AS DECLARAÇÕES NÃO INTERPRETADAS DO ARQUIVO DAQUELE COMPONENTE.
+ *
+ * `name` é o nome do componente COMO O CENSO O CONHECE - a chave de `looks`. O chamador tem o slug
+ * da recipe (`metric-card`), então ele precisa resolver o nome antes; a resolução não mora aqui
+ * porque ela é do crosswalk, e duas cópias dela discordariam.
+ */
+export function unreadForComponent(census, name) {
+    const file = census.looks?.[name]?.api?.file ?? fileForSlug(census, name);
+    if (!file)
+        return [];
+    const scope = census.scope ? `${census.scope}/` : "";
+    const out = [];
+    for (const group of census.ledger?.unread ?? []) {
+        for (const one of group.unreadable ?? []) {
+            if (!one.file || !one.text)
+                continue;
+            if (`${scope}${one.file}` !== file)
+                continue;
+            out.push({
+                file: one.file,
+                ...(typeof one.line === "number" ? { line: one.line } : {}),
+                text: one.text,
+                reason: group.reason ?? "unread",
+            });
+        }
+    }
+    return out;
+}
+/**
+ * O CENSO CONHECE O COMPONENTE PELO NOME DELE; QUEM CHAMA TEM O SLUG DA RECIPE.
+ *
+ * `MetricCard` no censo é `metric-card` na recipe, e o comando `add` recebe o segundo. A conversão
+ * é a mesma que `exclusive-contract.ts` faz do outro lado - se as duas divergirem, o componente
+ * certo perde as declarações dele e nenhum erro aparece.
+ *
+ * Busca reversa e não um mapa novo: o censo já tem os nomes, e guardar a correspondência seria uma
+ * segunda fonte para uma pergunta que a primeira já responde.
+ */
+function fileForSlug(census, slug) {
+    const kebab = (v) => v
+        .split(".")
+        .join("-")
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    for (const [name, look] of Object.entries(census.looks ?? {}))
+        if (kebab(name) === slug && look?.api?.file)
+            return look.api.file;
+    return undefined;
+}
+/**
+ * O BLOCO DE COMENTÁRIO, ou string vazia quando não há nada a dizer.
+ *
+ * Vazio não vira comentário: um bloco que aparece em todo arquivo dizendo "nada aqui" ensina a
+ * pular o bloco, e aí ele não é lido no arquivo onde ele importa.
+ *
+ * A frase diz as três coisas que decidem o que a pessoa faz: que aquilo NÃO está governado por
+ * token, ONDE está no código dela, e que a plataforma está resolvendo do lado dela. Sem a terceira,
+ * a leitura é "a plataforma não deu conta"; com ela, é "isto chega governado depois".
+ */
+export function unreadComment(lines) {
+    if (lines.length === 0)
+        return "";
+    const rows = lines.map((l) => ` *   ${l.file}${l.line ? `:${l.line}` : ""}  ${l.text}`);
+    const n = lines.length;
+    return `/**
+ * ${n} declaration${n === 1 ? "" : "s"} from your own file ${n === 1 ? "was" : "were"} not interpreted, so ${n === 1 ? "it is" : "they are"} not
+ * governed by a token here yet. ${n === 1 ? "It" : "They"} still work${n === 1 ? "s" : ""} in your project - this is a gap in
+ * what this pipeline can read, not in your code, and it is being closed on our side.
+ *
+${rows.join("\n")}
+ */
+`;
+}
+/**
+ * O CENSO DO PROJETO, ou vazio quando não existe.
+ *
+ * Um projeto que só instalou o sistema nunca rodou `import` e não tem censo. Isso não é erro: é o
+ * estado normal de quem CONSOME o design system sem alimentá-lo. Ele recebe o componente como
+ * sempre recebeu, sem a nota - e um erro aqui transformaria uma ausência normal em falha do comando.
+ */
+export async function readCensus(root) {
+    const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

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