synthesisui 0.16.356 → 0.16.358

package/dist/commands/align.js

@@ -9,7 +9,7 @@ import { readRequests } from "../doctor/requests.js";
 import { declaredReference } from "../group-role.js";
 import { CHECKER_SINCE, installedBehind, MATERIALISER_SINCE, READER_SINCE, } from "../install-marks.js";
 import { measuredScope } from "../measured-scope.js";
-import { body } from "../output.js";
+import { body, bodyWrapped, paint, section, snippet } from "../output.js";
 import { SKILLS } from "../skills.js";
 /**
  * QUAL CLI MEDIU O CENSO EM DISCO - e era o `reader`, um inteiro, até 11/08.
@@ -625,8 +625,38 @@ export async function nextStepFor(root) {
      * chutá-lo seria pior que pedir para olhar.
      */
     return measured
-        ? "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."';
+        ? {
+            sentence: "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>`.",
+            headline: "Your system is already in your account. Bring it in here:",
+            run: ["synthesisui list --mine", "synthesisui add <slug>"],
+            why: "Re-measuring would cost minutes and change nothing the platform already knows.",
+        }
+        : {
+            sentence: 'This repo has no design system contract yet. Ask me: "import my design system."',
+            headline: "Open a new agent session in this repo and say:",
+            say: "import my design system",
+            why: "I read what is already in your code - the colours, the type, the shapes, the components. Nothing is invented.",
+        };
+}
+/**
+ * A AÇÃO RECOMENDADA, DESENHADA PARA SER VISTA - uma, com título, o literal copiável e o por quê.
+ *
+ * A hierarquia usa a paleta que já existe e no papel que ela declara: `blue` marca o que é VIVO (o
+ * que ele diz ou roda), `dim` é prosa secundária (o por quê e a exigência de sessão nova). A seção
+ * traz as linhas em branco de graça, que é o "respiro" pedido.
+ */
+export function renderNextStep(next, freshSession) {
+    const lines = [section("Do this next"), body(next.headline), ""];
+    if (next.say)
+        lines.push(paint.blue(snippet([next.say])), "");
+    if (next.run?.length)
+        lines.push(paint.blue(snippet(next.run)), "");
+    lines.push(...bodyWrapped(next.why).map(paint.dim));
+    if (freshSession)
+        lines.push(...bodyWrapped(freshSession.mcp
+            ? "A new session is what loads the skills and tools just installed, and the project's tools ask for approval once - say yes."
+            : "A new session is what loads the skills just installed.").map(paint.dim));
+    return lines.join("\n");
 }
 /**
  * A CAUDA DE UM COMANDO QUE TERMINOU: o que ainda está fora, ou nada.
@@ -642,10 +672,8 @@ export async function reportWhatIsLeft(root, opts = {}) {
     const items = await misalignments(root, opts).catch(() => []);
     if (items.length === 0) {
         const next = await nextStepFor(root).catch(() => null);
-        if (next) {
-            console.log("");
-            console.log(body(next));
-        }
+        if (next)
+            console.log(renderNextStep(next, opts.freshSession));
         return;
     }
     console.log("");
@@ -673,5 +701,5 @@ export async function align(opts) {
      */
     const next = await nextStepFor(root).catch(() => null);
     if (next)
-        console.log(next);
+        console.log(next.sentence);
 }

package/dist/commands/connect.js

@@ -153,7 +153,13 @@ version) {
         if (next !== current) {
             const was = pinnedInHook(current);
             console.log("");
-            console.log(body(`Updating the terminal check in ${rc} - ${was ? `it was pinned to ${was}` : "it was on an unpinned version"}, moving it to ${version}.`));
+            /**
+             * DITA, E EM SEGUNDO PLANO. O dono pediu em 03/09 que ela saísse da tela; ela FICA porque
+             * reporta uma escrita FORA do repositório, e "um `.zshrc` que muda sem uma palavra é a
+             * definição de invasivo" é decisão dele mesmo, de 11/08. O que muda é o peso: cinza claro,
+             * como toda prosa secundária, para ela informar sem disputar com a ação recomendada.
+             */
+            console.log(body(paint.dim(`Updating the terminal check in ${rc} - ${was ? `it was pinned to ${was}` : "it was on an unpinned version"}, moving it to ${version}.`)));
             await writeFile(rc, next, "utf8").catch(() => { });
         }
         return;
@@ -379,18 +385,19 @@ export async function connect(opts) {
                 : `✓ ${skill.label.padEnd(22)} updated to this CLI's pipeline`));
     }
     /**
-     * O CI: escrito só quando pedido, e OFERECIDO sempre - com o que ele faz em duas linhas, porque
-     * "adicione CI" sem dizer que nada reprova dívida herdada não é uma oferta, é um risco.
+     * O CI: escrito quando pedido, e NÃO MAIS OFERECIDO aqui.
+     *
+     * A oferta era verdadeira e estava no lugar errado: ela ocupava o espaço imediatamente antes da
+     * ação recomendada, num repositório onde a pessoa ainda não tem sistema nenhum - então o produto
+     * sugeria um portão de PR para uma dívida que ainda não existe. Ela mora agora na documentação do
+     * `connect` (dono, 03/09: "vamos deixar isso para uma documentação dentro do synthesisui").
+     *
+     * `--ci` continua fazendo tudo que fazia: quem pede, recebe.
      */
     if (opts.ci) {
         console.log("");
         await ci({ dir: root, write: true });
     }
-    else {
-        console.log("");
-        console.log(body(paint.dim("Your PRs can carry this too: annotations on the exact line, and a check that fails only when the count goes UP - never on the debt you already have.")));
-        console.log(paint.blue(snippet(["npx synthesisui@latest ci"])));
-    }
     /** A mesma versão que a fiação do editor recebe - os dois pinam no mesmo número. */
     await offerShellHook(opts.shell === true, opts.version);
     /**
@@ -409,16 +416,13 @@ export async function connect(opts) {
     const needsRestart = moved(wired.hook) ||
         moved(wired.session) ||
         (Array.isArray(wired.mcp) && wired.mcp.some((m) => moved(m.status)));
-    if (needsRestart) {
-        console.log("");
-        console.log(body("Reopen your editor session - all of them are read at startup."));
-        if (want.mcp &&
-            Array.isArray(wired.mcp) &&
-            wired.mcp.some((m) => moved(m.status))) {
-            console.log(body('A project MCP server needs approving once; say yes when it asks. Then "/mcp" lists synthesisui.'));
-        }
-    }
-    await reportWhatIsLeft(root, { cli: opts.version });
+    const mcpMoved = Boolean(want.mcp &&
+        Array.isArray(wired.mcp) &&
+        wired.mcp.some((m) => moved(m.status)));
+    await reportWhatIsLeft(root, {
+        cli: opts.version,
+        ...(needsRestart ? { freshSession: { mcp: mcpMoved } } : {}),
+    });
     /**
      * O CUSTO DO HOOK, DITO SEM UM NÚMERO QUE NÃO É NOSSO.
      *
@@ -434,10 +438,10 @@ export async function connect(opts) {
      */
     if (wired.command.startsWith("npx synthesisui@")) {
         console.log("");
-        console.log(body("The hook runs through npx, which resolves this package against the"));
-        console.log(body("registry on every edit - that wait is the network, not the check itself"));
-        console.log(body("(the analysis is about 80ms). Adding synthesisui to your devDependencies"));
-        console.log(body("makes npx resolve it locally instead, which is several times faster;"));
-        console.log(body("run this again afterwards and it will switch by itself."));
+        console.log(body(paint.dim("The hook runs through npx, which resolves this package against the")));
+        console.log(body(paint.dim("registry on every edit - that wait is the network, not the check itself")));
+        console.log(body(paint.dim("(the analysis is about 80ms). Adding synthesisui to your devDependencies")));
+        console.log(body(paint.dim("makes npx resolve it locally instead, which is several times faster;")));
+        console.log(body(paint.dim("run this again afterwards and it will switch by itself.")));
     }
 }

package/dist/doctor/their-names.js

@@ -59,23 +59,49 @@ const segments = (name) => name.replace(/^--/, "").split("-");
  *
  *     1. quantos segmentos ele compartilha com o nosso token daquela família
  *        `--ds-radius-xs` puxa `--radius-xs` (2) e não `--spacing` (0)
- *     2. a convenção dominante dele - o primeiro segmento mais frequente entre os tokens dele
+ *     2. quantos segmentos dele são um PAPEL que este sistema declara - ver `roles`
+ *     3. a convenção dominante dele - o primeiro segmento mais frequente entre os tokens dele
  *        no repo real, `--color-*` (57) contra `--dashboard-*` (25)
- *     3. ordem de declaração, que é o desempate que sempre existe e nunca inventa
+ *     4. ordem de declaração, que é o desempate que sempre existe e nunca inventa
+ *
+ * O CRITÉRIO 2 NASCEU DE UMA DECISÃO DO DONO (03/09), e o critério 1 não alcançava o caso. No
+ * sistema dele `#f59e0b` é `--color-tier-gold` E `--color-feedback-warning`, e medindo o censo:
+ * `tier-gold` tem 59 menções contra 7, e uma escada própria (bronze 13, prata 13). Pela contagem
+ * bruta ele venceria - e vencia, sempre que o nosso token daquele valor não existisse para o
+ * critério 1 comparar: aí caía na ORDEM DE DECLARAÇÃO, e `tier-gold` vem antes no CSS dele.
+ *
+ * A ESCOLHA NÃO É PELO MAIS FREQUENTE, É PELO ERRO QUE SE ANUNCIA. `feedback-warning` escrito num
+ * badge de nível mostra "warning" onde devia ser ouro, e quem lê corrige. `tier-gold` escrito num
+ * alerta pinta a cor CERTA com o nome de outro domínio - a tela fica visualmente correta e ninguém
+ * corrige nunca. Entre dois nomes dele, o que descreve um PAPEL erra alto; o que descreve um
+ * domínio de negócio erra calado.
  */
-function pick(candidates, ours, convention) {
+function pick(candidates, ours, convention, 
+/**
+ * OS PAPÉIS QUE ESTE SISTEMA DECLARA - o critério 2, e o único que decide quando não há token
+ * nosso daquele valor para comparar.
+ *
+ * DERIVADO, nunca escrito: são os segmentos finais dos papéis semânticos do próprio sistema, e
+ * por isso a regra vale em qualquer projeto. Um projeto que chame o aviso de `atencao` puxa
+ * `atencao`; nenhum nome de família deste ou daquele repositório entra aqui (`INV-GERAL-07`).
+ */
+roles) {
     const mine = ours ? new Set(segments(ours)) : null;
     let best = candidates[0];
-    let bestScore = [-1, -1];
+    let bestScore = [-1, -1, -1];
     for (const name of candidates) {
         const parts = segments(name);
         const shared = mine ? parts.filter((p) => mine.has(p)).length : 0;
         const score = [
             shared,
+            parts.filter((p) => roles.has(p)).length,
             convention.get(parts[0] ?? "") ?? 0,
         ];
         if (score[0] > bestScore[0] ||
-            (score[0] === bestScore[0] && score[1] > bestScore[1])) {
+            (score[0] === bestScore[0] && score[1] > bestScore[1]) ||
+            (score[0] === bestScore[0] &&
+                score[1] === bestScore[1] &&
+                score[2] > bestScore[2])) {
             best = name;
             bestScore = score;
         }
@@ -106,14 +132,29 @@ function pick(candidates, ours, convention) {
  * sistema do dono, `#f59e0b` é `--color-tier-gold` E `--color-feedback-warning` - dois conceitos
  * dele, gamificação e estado -, e o relatório dizia `→ {color.tier-gold}` como se fosse fato.
  */
-function escolha(candidates, ours, convention) {
-    const name = pick(candidates, ours, convention);
+function escolha(candidates, ours, convention, roles) {
+    const name = pick(candidates, ours, convention, roles);
     return { name, also: candidates.filter((c) => c !== name) };
 }
 export function theirNames(ours, theirs) {
     const out = new Map();
     if (theirs.byName.size === 0)
         return out;
+    /**
+     * OS PAPÉIS QUE ESTE SISTEMA DECLARA, derivados dos NOSSOS nomes - ver o critério 2 de `pick`.
+     *
+     * O último segmento de cada token semântico é o papel: `--ds-color-semantic-warning` dá
+     * `warning`. Sai daqui e não de uma lista escrita porque uma lista seria o nosso vocabulário
+     * virando régua - um sistema que chame o aviso de `atencao` tem que puxar `atencao`.
+     */
+    const roles = new Set();
+    for (const name of ours.byName.keys()) {
+        if (!name.includes("-semantic-"))
+            continue;
+        const last = segments(name).at(-1);
+        if (last)
+            roles.add(last);
+    }
     /** A convenção dominante dele, contada e não suposta - ver `pick`. */
     const convention = new Map();
     for (const name of theirs.byName.keys()) {
@@ -151,7 +192,7 @@ export function theirNames(ours, theirs) {
                 : candidates.filter((n) => familySays(kind, n));
             if (usable.length === 0)
                 continue;
-            out.set(key, escolha(usable, name, convention));
+            out.set(key, escolha(usable, name, convention, roles));
         }
     }
     for (const [value, candidates] of theirs.byValue) {
@@ -161,7 +202,7 @@ export function theirNames(ours, theirs) {
             const key = `${kind}:${value}`;
             if (out.has(key))
                 continue;
-            out.set(key, escolha(candidates, null, convention));
+            out.set(key, escolha(candidates, null, convention, roles));
         }
     }
     return out;

package/dist/output.js

@@ -20,6 +20,34 @@ export function snippet(lines) {
 export function body(line) {
     return `  ${line}`;
 }
+/**
+ * PROSA LONGA QUEBRADA NA MESMA LARGURA QUE O RESTO DA TELA RESPEITA.
+ *
+ * Todo parágrafo daqui foi quebrado À MÃO até agora, uma string por linha - o que funciona para
+ * texto fixo e não funciona para texto que vem de dado. Medido em 03/09 na ação recomendada do
+ * `connect`: a linha do "por quê" saiu com 103 colunas num desenho de 66, e num terminal estreito
+ * ela dobra no meio de uma palavra, exatamente na frase que a pessoa mais precisa ler.
+ *
+ * Quebra por PALAVRA e nunca no meio de uma; uma palavra maior que a largura fica sozinha na linha
+ * em vez de ser cortada. Já indenta como `body`, porque a indentação conta para a largura.
+ */
+export function bodyWrapped(text, width = WIDTH) {
+    const lines = [];
+    let current = "";
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (!current)
+            current = word;
+        else if (`${current} ${word}`.length <= width)
+            current += ` ${word}`;
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines.map(body);
+}
 /**
  * Colour, used the way the product uses motion: a quiet base and a few
  * deliberate accents (dono, 30/07: "um cinza mais escuro e um mais claro,

package/package.json

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