synthesisui 0.16.290 → 0.16.292

package/dist/commands/align.js

@@ -579,8 +579,23 @@ export async function nextStepFor(root) {
     if (locks.length > 0)
         return null;
     const measured = await readFile(join(root, "_synthesisui", "census.json"), "utf8").then(() => true, () => false);
+    /**
+     * MEDIDO E SEM SISTEMA INSTALADO SÃO DUAS HISTÓRIAS, e a frase antiga contava a errada.
+     *
+     * Ela dizia *"continue the import"*, e em 23/08 foi exatamente o que o agente fez: mediu o
+     * repositório inteiro de novo, refez a leitura, reenviou. O sistema JÁ EXISTIA na conta dele - o
+     * que faltava eram os arquivos aqui, e `add` é o comando que os traz. Medir de novo custou sete
+     * minutos e não mudou nada do que a plataforma sabia.
+     *
+     * As duas situações que produzem este estado, e as duas terminam no mesmo comando: um import que
+     * criou o sistema e parou antes de instalar (o que este CLI já não faz - ver o fim de `runImport`),
+     * e um clone fresco de um repositório onde alguém apagou a pasta `ds/`.
+     *
+     * `list --mine` primeiro porque o slug nasce no servidor: ele não está em nenhum arquivo daqui, e
+     * chutá-lo seria pior que pedir para olhar.
+     */
     return measured
-        ? 'This repo has been measured but has no design system yet. Ask me: "continue the import."'
+        ? "This repo has been measured and has no system installed here. If you already imported, the system is in your account: `synthesisui list --mine`, then `synthesisui add <slug>`."
         : 'This repo has no design system contract yet. Ask me: "import my design system."';
 }
 /**

package/dist/commands/generate.js

@@ -1,7 +1,8 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { installedSlugs } from "../installed.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { postGenerate, RegistryError } from "../registry.js";
 /** PascalCase para o hint de import (course-card → CourseCard). */
@@ -20,17 +21,6 @@ async function readActiveVersion(root, slug) {
     }
 }
 /** Slugs materialized under `_synthesisui/ds/` in the project. */
-async function installedSlugs(root) {
-    try {
-        const entries = await readdir(join(root, "_synthesisui", "ds"), {
-            withFileTypes: true,
-        });
-        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    }
-    catch {
-        return [];
-    }
-}
 /**
  * Generates a token-only component recipe for the project's design system
  * (chat-gen PRO, hosted) and materializes it additively under

package/dist/commands/import.js

@@ -49,6 +49,7 @@ import { phase, startProgress } from "../progress.js";
 import { repoStateOf } from "../repo-state.js";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
 import { placeInWorkspace } from "../workspace-place.js";
+import { add } from "./add.js";
 import { walk, walkAll } from "./doctor.js";
 /**
  * How many distinct values travel, PER KIND.
@@ -3942,4 +3943,42 @@ export async function runImport(opts) {
     if (payload?.url)
         console.log(body(`    ${paint.blue(payload.url)}`));
     console.log("");
+    /**
+     * E O SISTEMA CHEGA NO REPOSITÓRIO DELE - quem manda importar quer usar.
+     *
+     * O QUE ELE VIVEU TRÊS VEZES EM 23/08: mandou importar, viu o sistema no ar com uma URL, e
+     * concluiu que tinha acabado. O repositório ficava com o censo, o ledger e o relatório de
+     * lacunas - sem `ds/`, sem `.lock`, sem `tokens.css`. O agente dele não sabia que o design
+     * system existia, e o comando seguinte falhava com "no design system installed here". E nada
+     * dizia que faltava um passo: nem o fim do import, nem a skill (que não cita `add` uma vez),
+     * nem o `doctor`.
+     *
+     * A LINHA "não escrevemos sem pedir" já foi cruzada aqui: este comando escreve o censo, o
+     * ledger, o `not-expressed.md` e um `.gitignore`. Parar antes de instalar não protegia nada -
+     * interrompia. Quem quer olhar antes de escrever usa `--dry`, que retorna muito acima desta
+     * linha e é onde essa responsabilidade mora.
+     *
+     * E É AQUI, DEPOIS DO RESUMO, e não antes: o resumo é sobre o que a leitura encontrou, e a
+     * instalação é sobre o que passou a existir na máquina dele. Misturar as duas faria a saída
+     * mais longa do produto ficar mais longa no lugar onde ela já é mais difícil de ler.
+     */
+    if (payload?.slug) {
+        try {
+            await add(payload.slug, {
+                registry: opts.registry,
+                dir: root,
+            });
+        }
+        catch (error) {
+            /**
+             * O SISTEMA FOI CRIADO NO SERVIDOR, e isso não se desfaz. Uma rede que cai na materialização
+             * custa os arquivos locais e nada mais - então o comando diz o que rodar, e jamais devolve
+             * um erro que faria a pessoa achar que perdeu a medição.
+             */
+            console.log("");
+            console.log(body(`Your system exists, and the files did not land here: ${error instanceof Error ? error.message : String(error)}`));
+            console.log(body(`    synthesisui add ${payload.slug}`));
+            console.log("");
+        }
+    }
 }

package/dist/commands/refit.js

@@ -1,35 +1,13 @@
-import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
+import { installedSlugs } from "../installed.js";
 import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
 /** Slugs INSTALLED under `_synthesisui/ds/` (a `.lock` marks a real install -
  *  a folder holding only refit artifacts doesn't count). */
-async function installedSlugs(root) {
-    try {
-        const entries = await readdir(join(root, "_synthesisui", "ds"), {
-            withFileTypes: true,
-        });
-        const slugs = [];
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            try {
-                await access(join(root, "_synthesisui", "ds", entry.name, ".lock"));
-                slugs.push(entry.name);
-            }
-            catch {
-                // artifacts-only folder (e.g. a refit before `add`) - not installed
-            }
-        }
-        return slugs;
-    }
-    catch {
-        return [];
-    }
-}
 /** True when the system is actually installed (tokens.css present). */
 async function isInstalled(root, slug) {
     try {

package/dist/doctor/broken-refs.js

@@ -21,8 +21,26 @@ import { frontierKind } from "../frontier-kind.js";
 import { importMap } from "./imports.js";
 /** Quantos lugares viajam por referência quebrada. Ver `BrokenRef.at`. */
 const MAX_PLACES = 3;
-/** `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`. */
-const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
+/**
+ * `var(--x)`, including inside a Tailwind arbitrary value: `bg-[var(--x)]`.
+ *
+ * O SEGUNDO GRUPO É O FALLBACK, e é ele que separa uma referência quebrada de uma com rede:
+ * `var(--aurora-angle,125deg)` pinta 125deg. Chamar isso de "não pinta nada" é dizer ao cliente que
+ * o código dele está defeituoso quando ele escreveu a defesa.
+ */
+const VAR_REF = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(,)?/g;
+/**
+ * `el.style.setProperty("--tx", …)` - uma custom property DECLARADA em JavaScript.
+ *
+ * O QUE O CLIENTE RECEBIA SEM ISTO: `--tx` e `--ty` na lista de "referências que não pintam nada",
+ * quando um hook de tilt dele as escreve a cada movimento do mouse. O agente dele diagnosticou isso à
+ * mão em 23/08 e disse a frase que virou esta regra: *"o que um leitor não consegue ver é uma custom
+ * property escrita por JS"*. A resposta não é adivinhar - é procurar a escrita, e ela é literal.
+ *
+ * Medido em quatro populações: 2 nomes no `codelevel-ui`, 0 no `packages/ui` do `frontend-hub`, 2 no
+ * dashboard dele e 3 no nosso próprio app. Três de quatro escrevem variável por JS.
+ */
+const SET_PROPERTY = /setProperty\(\s*['"`](--[a-zA-Z0-9_-]+)/g;
 /**
  * VARIABLES A HEADLESS LIBRARY SETS AT RUNTIME, which no stylesheet can declare.
  *
@@ -90,12 +108,35 @@ const NAMESPACES = [
  */
 export function findBrokenRefs(sources, declared) {
     const seen = new Map();
+    /**
+     * AS QUE O PRÓPRIO CÓDIGO DELE ESCREVE EM JAVASCRIPT - ver `SET_PROPERTY`.
+     *
+     * Colhidas de TODAS as fontes antes do laço, e não por arquivo: quem escreve `--tx` é o hook, e
+     * quem a lê é a folha global. São dois arquivos, e perguntar por arquivo diria que a folha
+     * referencia algo que ninguém declara.
+     */
+    const setInJs = new Set();
+    for (const { source } of sources)
+        for (const m of source.matchAll(SET_PROPERTY))
+            setInJs.add(m[1]);
     for (const { file, source } of sources) {
         const runtime = importsHeadless(source);
         for (const m of source.matchAll(VAR_REF)) {
             const name = m[1];
             if (declared.has(name))
                 continue;
+            /**
+             * UMA CHAMADA COM FALLBACK NÃO ESTÁ QUEBRADA - ela pinta o fallback.
+             *
+             * Por CHAMADA e não por nome: a mesma variável pode ser lida com rede num lugar e sem rede em
+             * outro, e é a segunda que precisa de conserto. Contar as duas juntas ou descartar as duas
+             * juntas erra em direções opostas.
+             */
+            if (m[2])
+                continue;
+            /** Declarada em JS - só não em CSS. Ver `SET_PROPERTY`. */
+            if (setInJs.has(name))
+                continue;
             if (runtime && (RUNTIME_ANCHOR.has(name) || RUNTIME_PREFIX.test(name)))
                 continue;
             const hit = seen.get(name) ?? {

package/dist/index.js

@@ -30,6 +30,7 @@ import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
 import { use } from "./commands/use.js";
 import { appendEvent } from "./doctor/ledger.js";
+import { blueprintTarget, installedSlugs } from "./installed.js";
 import { RegistryError } from "./registry.js";
 /** Our own version, for pinning the hook and MCP commands we write into a
  *  project. Read from the package we are running out of, so a pinned command
@@ -44,8 +45,10 @@ 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 component <slug> <name>      bring one EXISTING component in as YOUR <Pascal>.tsx
-  synthesisui bp <slug> <name>             the same command, short for blueprint
+  synthesisui bp <name>                    bring one EXISTING blueprint in as YOUR <Pascal>.tsx
+                                           (the slug is optional - this repo's system answers for it)
+  synthesisui bp <slug> <name>             the same, from another system
+  synthesisui blueprint | component        the same command, spelled in full
   synthesisui template <slug> <name>       materialize a whole page from a DS template
                                            (--as landing-home names the output - multi-page safe)
   synthesisui upgrade <slug>               update an installed DS + regenerate your components + migration brief
@@ -468,14 +471,42 @@ async function main() {
          * que apelido nenhum.
          */
         case "bp":
+        case "blueprint":
         case "component": {
-            const slug = args[0];
-            const name = args[1];
-            if (!slug || !name) {
-                console.error("error: provide slug and component name - `synthesisui component <slug> <name>`");
+            /**
+             * O SLUG É OPCIONAL, e o repositório responde por ele.
+             *
+             * `synthesisui bp card` num repositório que tem UM sistema instalado é a forma que a pessoa
+             * escreve naturalmente - ela está dentro do projeto, o sistema dela é aquele, e repetir o nome
+             * dele é a plataforma pedindo uma informação que ela já tem no disco.
+             *
+             * COM DOIS ARGUMENTOS o primeiro é o slug, que é o comportamento de sempre e o que permite
+             * trazer um blueprint de OUTRO sistema para cá.
+             *
+             * E O CASO AMBÍGUO É RECUSADO EM VEZ DE ADIVINHADO: um argumento só que é exatamente o nome do
+             * sistema instalado - `synthesisui bp codelevel-ds` - é o erro que o comentário acima registra,
+             * e ele tem duas leituras opostas ("instale este sistema" / "materialize um blueprint chamado
+             * codelevel-ds"). Escolher uma em silêncio seria acertar metade das vezes.
+             */
+            const root = dir ?? process.cwd();
+            const installed = await installedSlugs(root);
+            const target = blueprintTarget({
+                args: [args[0], args[1]],
+                local: installed.length === 1 ? installed[0] : null,
+                installed,
+            });
+            if ("error" in target) {
+                console.error(target.error === "ambiguous"
+                    ? `error: "${target.name}" is the system installed here, not a blueprint name - say which blueprint you want: \`synthesisui bp <name>\``
+                    : target.error === "no-name"
+                        ? "error: provide a blueprint name - `synthesisui bp <name>`, or `synthesisui bp <slug> <name>` for another system"
+                        : target.error === "no-system"
+                            ? "error: no design system installed here - run `synthesisui add <slug>` first, or name one: `synthesisui bp <slug> <name>`"
+                            : `error: ${installed.length} systems installed here (${installed.join(", ")}) - say which: \`synthesisui bp <slug> <name>\``);
                 process.exitCode = 1;
                 return;
             }
+            const { slug, name } = target;
             let version;
             if (typeof flags.version === "string") {
                 version = Number.parseInt(flags.version.replace(/^v/i, ""), 10);

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

package/dist/installed.js

@@ -0,0 +1,68 @@
+import { access, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * QUAIS SISTEMAS ESTÃO INSTALADOS NESTE REPOSITÓRIO - um lugar só, e a resposta certa.
+ *
+ * ESTA FUNÇÃO EXISTIA DUAS VEZES, em `refit.ts` e `generate.ts`, e elas discordavam: a primeira
+ * exigia o `.lock` - o arquivo que prova que o `add` rodou - e a segunda listava a pasta. Uma pasta
+ * `ds/<slug>/` existe assim que qualquer comando escreve um artefato ali, então o `generate`
+ * enxergava como instalado um sistema que ainda não tinha nada materializado, e a mensagem que ele
+ * daria ao cliente seria sobre um sistema que ele não pode usar.
+ *
+ * O `.lock` é o portão porque ele é o que o `add` escreve por último: se ele está lá, os arquivos
+ * estão. Ver `RootLock` em `add.ts`.
+ *
+ * E COM ISTO O SLUG PASSA A SER OPCIONAL nos comandos que agem sobre um sistema. Quem está num
+ * repositório que tem um sistema instalado não deveria precisar repetir o nome dele - o repositório
+ * já sabe.
+ */
+export async function installedSlugs(root) {
+    try {
+        const dsDir = join(root, "_synthesisui", "ds");
+        const entries = await readdir(dsDir, { withFileTypes: true });
+        const slugs = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                await access(join(dsDir, entry.name, ".lock"));
+                slugs.push(entry.name);
+            }
+            catch {
+                // pasta de artefato (um refit antes do `add`, por exemplo) - não é um install
+            }
+        }
+        return slugs.sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * O SISTEMA DESTE REPOSITÓRIO, quando há exatamente um - e `null` quando a pergunta não tem resposta.
+ *
+ * Nenhum instalado e dois instalados são situações diferentes com a mesma consequência: a plataforma
+ * não pode escolher por ele. Escolher o primeiro em ordem alfabética seria a pior forma de errar -
+ * silenciosa, e correta na metade dos casos. Quem chama diz o que fazer com o `null`, e o que ele
+ * tem a dizer é diferente nos dois casos, então `installedSlugs` continua disponível para nomear os
+ * candidatos na mensagem.
+ */
+export async function theInstalledSlug(root) {
+    const slugs = await installedSlugs(root);
+    return slugs.length === 1 ? slugs[0] : null;
+}
+export function blueprintTarget(input) {
+    const [first, second] = input.args;
+    if (first && second)
+        return { slug: first, name: second };
+    const name = first;
+    if (!name)
+        return { error: "no-name" };
+    if (input.local && name === input.local)
+        return { error: "ambiguous", name };
+    if (!input.local)
+        return input.installed.length > 1
+            ? { error: "many-systems" }
+            : { error: "no-system" };
+    return { slug: input.local, name };
+}

package/package.json

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