synthesisui 0.16.384 → 0.16.386

package/dist/commands/align.js

@@ -278,6 +278,8 @@ opts = {}) {
                 ? "This run measured the app, and that reading is still on this machine - the platform keeps scoring the previous one until you send it."
                 : `${events.length} checked write${events.length === 1 ? "" : "s"} recorded here and not sent - the platform is scoring this repo on older evidence.`,
             run: "npx synthesisui sync",
+            /** Ver `Misalignment.fromThisRun`: o cabeçalho lê daqui, e não reimplementa a pergunta. */
+            fromThisRun: allFromThisRun,
         });
     }
     /**
@@ -570,12 +572,33 @@ export function describeMisalignments(items,
 from = "session") {
     if (items.length === 0)
         return "";
+    /**
+     * "STILL OUT OF ALIGNMENT" SOBRE O QUE O PRÓPRIO COMANDO ACABOU DE PRODUZIR - achado do dono em
+     * 06/09, e ele o descreveu na hora: *"depois do upgrade (pediu o sync novamente)"*.
+     *
+     * O QUE ELE VIU: o `sync` disse que as regras mudaram e mandou rodar `upgrade`. O `upgrade`
+     * materializou, MEDIU o app - e a medição nova é evidência que ainda não subiu -, então fechou
+     * dizendo "Still out of alignment" e mandou rodar `sync`. Dois comandos apontando um para o
+     * outro, com um cabeçalho que afirma que algo continua errado.
+     *
+     * NÃO É LOOP: o segundo `sync` fecha, porque o que falta é enviar o que este `upgrade` acabou de
+     * medir. Mas isso não está em lugar nenhum da tela, e quem lê não tem como distinguir progresso
+     * de giro - a diferença entre as duas é a única coisa que decide se ele roda de novo ou desiste.
+     *
+     * A INFORMAÇÃO JÁ EXISTIA UMA LINHA ABAIXO. `allFromThisRun` distingue "havia evidência velha
+     * parada aqui" de "esta execução acabou de medir", e a frase do item já diz *"This run measured
+     * the app"*. Só o CABEÇALHO tratava os dois casos como o mesmo. Quando todo achado é consequência
+     * desta execução, ele passa a dizer o que a próxima linha resolve - e não que algo falhou.
+     */
+    const consequencia = from === "after" && items.every((i) => i.fromThisRun === true);
     return [
-        from === "after"
-            ? "Still out of alignment:"
-            : 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:",
+        consequencia
+            ? "One step left, and it closes what this run produced:"
+            : from === "after"
+                ? "Still out of alignment:"
+                : 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:",
         ...grouped(items),
     ].join("\n");
 }

package/dist/commands/component.js

@@ -169,7 +169,29 @@ export async function component(slug, name, opts) {
          */
         const theirs = res.recipe?.api;
         const already = theirs?.file && existsSync(join(root, theirs.file)) ? theirs : null;
-        if (already && !opts.force) {
+        /**
+         * UM NOME PRÓPRIO JÁ É A RESPOSTA PARA A COLISÃO - achado do dono em 06/09, e é a SEGUNDA volta
+         * deste mesmo defeito.
+         *
+         * O QUE ELE FEZ: `component codelevel button --as=ButtonSample`, no repositório de onde o
+         * sistema foi importado. A recusa disparou, disse *"writing another one would leave you with
+         * two"* e ofereceu `--force` - com um `--as` na linha de comando, ignorado.
+         *
+         * OS DOIS ERROS DE UMA VEZ. O primeiro é a decisão: este guard responde "você já tem" sem
+         * nunca ler `opts.as`, embora `localName` - a função que resolve o nome - fique 70 linhas
+         * abaixo. O segundo é a frase: com um nome próprio NÃO ficariam dois `Button`; ficaria o dele
+         * e um `ButtonSample`. E a única saída oferecida, `--force`, escreve com o nome ORIGINAL - a
+         * única opção que de fato causaria a duplicação que a mensagem existe para evitar.
+         *
+         * A PRIMEIRA VOLTA está registrada em `component-as.spec.ts`: a recusa IMPRIMIA `--as` e a
+         * flag não existia em `ComponentOptions`. A flag nasceu; o guard não passou a consultá-la.
+         *
+         * E A POPULAÇÃO É O CLIENTE-ALVO INTEIRO. Medido na base viva em 06/09: no `codelevel`, **64
+         * dos 66** componentes (97%) apontam para um arquivo que existe no repositório dele - porque o
+         * sistema NASCEU dali. Nos 25 sistemas gerados aqui, **0 de ~45**. O comando funcionava para
+         * quem não é o cliente e recusava para quem é.
+         */
+        if (already && !opts.force && !opts.as?.trim()) {
             console.log(section("You already have this component"));
             console.log(body(`\`${already.name}\` lives in ${already.file} - writing another one would leave you with two.`));
             if (already.from) {
@@ -180,14 +202,44 @@ export async function component(slug, name, opts) {
                 console.log(body(`It is not re-exported from that folder's entry, so import it by path.`));
             }
             console.log("");
-            console.log(body("The recipe and the compiled CSS are on disk either way - only the .tsx was not written. Pass --force to write it anyway."));
+            /**
+             * A SAÍDA QUE NÃO DUPLICA VEM PRIMEIRO, e ela é a que a pessoa quer em quase todo caso.
+             *
+             * `--force` continua existindo e continua last: ele escreve com o nome DELE, que é a única
+             * opção que realmente deixa dois. Oferecê-lo como única saída era mandar a pessoa fazer
+             * exatamente o que a frase acima diz para evitar.
+             */
+            console.log(body(`To see what this recipe produces without touching your file, give it a name of its own:`));
+            console.log("");
+            console.log(snippet([
+                `npx synthesisui@latest component ${slug} ${res.name} --as ${res.name}-sample`,
+            ]));
+            console.log("");
+            console.log(body("The recipe and the compiled CSS are on disk either way - only the .tsx was not written. Pass --force to overwrite yours instead."));
             return;
         }
-        const clash = await findCollision(root, config.componentsDir, res.name, pascalName);
+        /**
+         * A COLISÃO SE MEDE PELO NOME QUE VAI SER ESCRITO, e não pelo do blueprint.
+         *
+         * A metade que o guard acima não resolvia sozinha: passado o primeiro guard com `--as`, este
+         * procurava por `button`/`Button` - o nome do BLUEPRINT - e achava o componente dele de novo.
+         * Consertar um e deixar o outro deixaria o `--as` aceito e barrado uma linha depois, o que é
+         * pior que recusar de cara: a pessoa faz o que a tela mandou e recebe outra recusa.
+         *
+         * `local` já era calculado, 70 linhas abaixo, para decidir a PASTA. Ele sobe para cá porque é
+         * a mesma pergunta - qual nome este comando vai ocupar - e duas respostas para ela é o defeito.
+         */
+        const local = localName(res.name, opts.as);
+        const localPascal = local
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        const clash = await findCollision(root, config.componentsDir, local, localPascal);
         if (!opts.force && (clash.exported || (clash.file && !clash.ours))) {
             console.log(section("This name is already taken in your project"));
             if (clash.exported) {
-                console.log(body(`\`${pascalName}\` is already exported from ${clash.exported}.`));
+                console.log(body(`\`${localPascal}\` is already exported from ${clash.exported}.`));
             }
             if (clash.file && !clash.ours) {
                 console.log(body(`${clash.file} exists and we did not write it.`));
@@ -211,7 +263,7 @@ export async function component(slug, name, opts) {
          * 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);
+        /** Ver o cálculo acima: uma resposta só para "qual nome este comando ocupa". */
         const compDir = join(root, config.componentsDir, local);
         await mkdir(compDir, { recursive: true });
         let filenames;
@@ -307,7 +359,19 @@ export async function component(slug, name, opts) {
     console.log(body(`(If you haven't installed the system yet, run: synthesisui add ${slug})`));
     console.log(section("Use it"));
     if (!opts.artifactsOnly && config.target === "next") {
-        const pascalName = res.name
+        /**
+         * O EXEMPLO APONTA PARA O QUE FOI ESCRITO - a terceira metade do defeito do `--as` (06/09).
+         *
+         * Este bloco derivava o nome e o caminho de `res.name`, o nome do BLUEPRINT. Com
+         * `--as button-sample`, o arquivo vai para `components/button-sample/` e o exemplo mandava
+         * importar de `components/button` - um caminho que não existe. Um comando que escreve certo e
+         * instrui errado é pior que um que recusa: a pessoa copia a linha e o build quebra.
+         *
+         * `localName` é a mesma função dos dois guards acima. Uma resposta só para o nome, do primeiro
+         * guard até a última linha impressa.
+         */
+        const usedName = localName(res.name, opts.as);
+        const pascalName = usedName
             .split(/[^a-zA-Z0-9]+/)
             .filter(Boolean)
             .map((p) => p[0].toUpperCase() + p.slice(1))
@@ -318,7 +382,7 @@ export async function component(slug, name, opts) {
             ? ` ${firstAxis[0]}="${Object.keys(firstAxis[1])[0]}"`
             : "";
         console.log(snippet([
-            `import { ${pascalName} } from "@/${config.componentsDir}/${res.name}";`,
+            `import { ${pascalName} } from "@/${config.componentsDir}/${usedName}";`,
             "",
             `<${pascalName}${exampleProp} />`,
         ]));
@@ -327,7 +391,7 @@ export async function component(slug, name, opts) {
         console.log("");
         console.log(body("Or ask your agent:"));
         console.log(snippet([
-            `"Use the ${pascalName} component from ${config.componentsDir}/${res.name} (SynthesisUI ${slug})."`,
+            `"Use the ${pascalName} component from ${config.componentsDir}/${usedName} (SynthesisUI ${slug})."`,
         ]));
     }
     else {

package/dist/commands/doctor.js

@@ -22,6 +22,7 @@ import { actingSlug, describeScope, measuredScope, scopePaths, } from "../measur
 import { body, paint, section, snippet } from "../output.js";
 import { resolveDeps } from "../stack.js";
 import { danglingTheirVars } from "../their-vars.js";
+import { wiringPrompt } from "../wiring-prompt.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -995,7 +996,29 @@ export async function doctor(opts) {
             console.log(body("are declared and nothing points at them, so the page renders in"));
             console.log(body("whatever the framework picked."));
         }
-        console.log(body("The exact snippets are in the output of `init`."));
+        /**
+         * A FIAÇÃO SAI DAQUI, e não de outro comando - achado do dono em 06/09, rodando o `upgrade`.
+         *
+         * O QUE ELE VIU: o doctor diz `installed - but not wired up yet` e *"none of the 66 tokens
+         * reach the browser"*, e a linha seguinte mandava ler *"the output of `init`"*. `init` é o
+         * comando de PRIMEIRA VEZ - ele instala um sistema em quem não tem nenhum. Quem chegou até
+         * aqui já importou, materializou e rodou upgrade: mandá-lo ao `init` é devolver ao começo
+         * alguém que está a um passo do fim.
+         *
+         * E O PASSO JÁ EXISTIA PRONTO. `wiringPrompt` mora em `wiring-prompt.ts`, exportado, e era
+         * usado só pelo `init`. Imprimi-lo aqui não é texto novo: é a MESMA fonte chegando na tela
+         * onde a pergunta nasce. Duas redações do mesmo passo divergiriam no primeiro conserto.
+         *
+         * O PROMPT E NÃO O SNIPPET, porque o caminho do `@import` é relativo à folha global DELE e
+         * ninguém aqui sabe onde ela está. O prompt manda o agente rodar o doctor, ler o que ele
+         * nomeia e fazer - que é o que funciona em projeto arbitrário.
+         */
+        if (table.slug) {
+            console.log("");
+            console.log(body("Paste this into your agent - it does the wiring:"));
+            console.log("");
+            console.log(snippet(wiringPrompt(table.slug).split("\n")));
+        }
     }
     /**
      * A FOLHA APONTA PARA O VOCABULÁRIO DELE, E UM NOME SUMIU - ver `their-vars.ts`.

package/package.json

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