synthesisui 0.16.249 → 0.16.251

package/dist/absorb-plan.js

@@ -170,15 +170,26 @@ export function describeAbsorb(plan) {
         return [
             "Nothing to absorb: every repeated value your code writes by hand already has a name in the system.",
         ];
-    lines.push(`${ready.length} of ${plan.entries.length} values already have a name in YOUR vocabulary - those travel as they are:`);
+    /**
+     * A SEÇÃO DOS QUE JÁ TÊM NOME SÓ EXISTE SE ALGUM TIVER - e no dia 1 nenhum tem.
+     *
+     * Quem começa do zero não declarou um token ainda, então isto abria com "0 of 4 values
+     * already have a name" e uma lista vazia: a primeira frase do comando dizendo um zero que
+     * não é notícia nenhuma, antes da única seção que importa para ela.
+     */
+    if (ready.length > 0)
+        lines.push(`${ready.length} of ${plan.entries.length} values already have a name in YOUR vocabulary - those travel as they are:`);
     for (const e of ready.slice(0, 8))
         lines.push(`  ${e.value.padEnd(24)} ${e.path.padEnd(28)} ${e.files} file${e.files === 1 ? "" : "s"}${e.theirName ? ` · your ${e.theirName}` : ""}`);
     if (ready.length > 8)
         lines.push(`  (${ready.length - 8} more)`);
     if (pending.length > 0) {
         const close = pending.filter((e) => e.near);
-        lines.push("");
-        lines.push(`${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`);
+        if (ready.length > 0)
+            lines.push("");
+        lines.push(ready.length > 0
+            ? `${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`
+            : `${pending.length} repeated values, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
         for (const e of pending.slice(0, 8))
             lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
         if (pending.length > 8)

package/dist/cli-flags.js

@@ -0,0 +1,79 @@
+/**
+ * A LINHA DE COMANDO, DESMONTADA - e o único lugar que sabe fazer isso.
+ *
+ * Este parser vivia dentro do `index.ts`, privado, e por isso nunca foi
+ * exercido por um teste. O custo apareceu inteiro num defeito: `login --force`
+ * era lido de `args` - a lista de POSICIONAIS, de onde este parser já tirou
+ * toda `--flag` - então a flag anunciada no help nunca chegou ao comando, e a
+ * resposta era sugerir o comando que a pessoa acabou de rodar.
+ *
+ * Separado, ele é testável, e `boolFlag` fecha a porta: quem lê uma flag
+ * booleana pede pelo NOME dela a quem tem a resposta, e não procura a string
+ * numa lista que por construção não a contém.
+ */
+/**
+ * A REPEATED FLAG ACCUMULATES rather than overwriting.
+ *
+ * `--usage apps/web --usage apps/admin` is the natural way to say two, and keeping
+ * only the last would drop one silently - which is the failure mode this codebase
+ * refuses everywhere else. Every existing flag is passed once and still arrives as
+ * a string, so nothing that reads `typeof flags.x === "string"` changes.
+ */
+export function parseFlags(argv) {
+    const positionals = [];
+    const flags = {};
+    const put = (key, value) => {
+        const had = flags[key];
+        if (had === undefined) {
+            flags[key] = value;
+            return;
+        }
+        if (typeof value !== "string")
+            return;
+        flags[key] = [
+            ...(Array.isArray(had) ? had : typeof had === "string" ? [had] : []),
+            value,
+        ];
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            flags.help = true;
+        }
+        else if (arg.startsWith("--")) {
+            const body = arg.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                // `--key=value` form (e.g. --out=templates/page.tsx)
+                put(body.slice(0, eq), body.slice(eq + 1));
+            }
+            else {
+                // `--key value` form
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith("--")) {
+                    put(body, next);
+                    i++;
+                }
+                else {
+                    put(body, true);
+                }
+            }
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, flags };
+}
+/**
+ * UMA FLAG BOOLEANA, LIDA PELO NOME - `true` só quando ela está mesmo lá.
+ *
+ * `--yes` sozinha chega como `true`; `--yes` seguida de um posicional chega
+ * como a string daquele posicional, porque o parser não sabe quais flags levam
+ * valor. Nos dois casos a pessoa DISSE a flag, e é isso que um booleano
+ * responde - tratar `--yes algo` como não-dito seria obedecer pela metade.
+ */
+export function boolFlag(flags, name) {
+    const v = flags[name];
+    return v === true || typeof v === "string" || Array.isArray(v);
+}

package/dist/commands/absorb.js

@@ -32,11 +32,23 @@ export async function absorb(opts) {
     if (opts.send)
         return sendProposal(root, path, opts.registry);
     const installed = await loadSystem(root);
-    if (!installed.table.slug) {
-        console.log(section("Absorb"));
-        console.log(body("No system installed here, so there is nothing to absorb INTO. `synthesisui list` shows what you can add."));
-        return;
-    }
+    /**
+     * SEM SISTEMA INSTALADO ISTO CONTINUA VALENDO - e recusar aqui fechava o dia 1.
+     *
+     * Este comando recusava com "não há nada para absorver PARA DENTRO", o que confundia o
+     * DESTINO com o TRABALHO. O trabalho é ler os valores que ela escreveu à mão e propor um
+     * nome para cada um; ele não depende de sistema nenhum, e as quatro coisas de que ele
+     * precisa já funcionam sem um: a tabela vem vazia (nada tem nome, então tudo é candidato),
+     * o vocabulário lido é o DELA, e a fundação existente é um conjunto vazio.
+     *
+     * Quem começa do zero era justamente quem mais precisava disto e quem menos podia rodar:
+     * ela escreve o primeiro componente, o doctor diz "9 valores à mão, nenhum tem nome", e o
+     * comando que dá nome respondia que não. Caminhado num projeto em branco em 18/08.
+     *
+     * O DESTINO É QUE MUDA, e ele se resolve sozinho: sem sistema, os tokens pertencem ao CSS
+     * dela - o mesmo caminho que `absorb: "code"` já servia a quem escolheu. Ver `sendProposal`.
+     */
+    const hasSystem = Boolean(installed.table.slug);
     const measured = await measuredScope(root);
     const rel = scopePaths(measured);
     const roots = rel.length > 0 ? rel.map((s) => resolve(root, s)) : [root];
@@ -61,7 +73,9 @@ export async function absorb(opts) {
         reports.push(scanSource(file.slice(root.length + 1), source, installed.table));
     }
     const plan = absorbPlan(diagnose(reports), theirs, pathsInSystem(installed.documents), opts.cap ?? 40);
-    console.log(section("What the system could absorb"));
+    console.log(section(hasSystem
+        ? "What the system could absorb"
+        : "Name what you wrote by hand"));
     console.log(body(paint.dim(`read from ${rel.length > 0 ? rel.join(", ") : "this project"} · your own vocabulary read from the root`)));
     console.log("");
     for (const line of describeAbsorb(plan))
@@ -69,7 +83,7 @@ export async function absorb(opts) {
     if (plan.entries.length === 0)
         return;
     const proposal = {
-        slug: installed.table.slug,
+        slug: installed.table.slug ?? null,
         at: new Date().toISOString(),
         scope: rel,
         entries: plan.entries,
@@ -146,17 +160,25 @@ async function sendProposal(root, path, registry) {
      * colar. Nunca escrevemos no arquivo do cliente - e o import seguinte lê os tokens de volta, o que faz
      * o caminho fechar sem nós tocarmos em nada.
      */
-    const target = (await readProjectConfig(root)).absorb ?? "system";
+    /**
+     * E SEM SISTEMA O DESTINO NÃO É UMA PREFERÊNCIA, é a única resposta que existe: os tokens
+     * pertencem ao CSS dela, porque não há outro lugar. Um `system` configurado aqui apontaria
+     * para um slug nulo e a chamada morreria num 404 depois de ela ter nomeado tudo à mão.
+     */
+    const configured = (await readProjectConfig(root)).absorb ?? "system";
+    const target = proposal.slug ? configured : "code";
     if (target === "code") {
         console.log(section("Paste this into your own vocabulary"));
-        console.log(body(paint.dim("Your config says absorbed values belong in your CSS, so nothing was sent.")));
+        console.log(body(paint.dim(proposal.slug
+            ? "Your config says absorbed values belong in your CSS, so nothing was sent."
+            : "You have no system yet, so these belong in your own CSS - nothing was sent, and nothing needed an account.")));
         console.log("");
         console.log("  :root {");
         for (const e of ready)
             console.log(`    --${e.path.replace(/\./g, "-")}: ${e.value};`);
         console.log("  }");
         console.log("");
-        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor cobra them by your own names."));
+        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
         return;
     }
     const token = await readToken();

package/dist/commands/doctor.js

@@ -401,6 +401,18 @@ function verdict(d, hasSystem, overruled, conflicts) {
             body("installed. Nothing to fix, and nothing to compare against."),
         ];
     }
+    /**
+     * O DIA ZERO - e o comando que serve a ele não era dito em lugar nenhum.
+     *
+     * "Dê um nome a eles" seguido de `init --ds <slug>` e o link da galeria oferece UMA saída, e
+     * ela é adotar o vocabulário de outra pessoa. A outra saída existe, faz exatamente o que a
+     * frase promete, e roda aqui mesmo sem conta e sem rede: `absorb` lê os valores repetidos e
+     * pede um nome para cada um. Ele passou a rodar sem sistema instalado neste mesmo PR, e uma
+     * capacidade que a pessoa precisa adivinhar não existe.
+     *
+     * A ordem é a da decisão dela: nomear o que ela já escreveu vem antes de escolher o de
+     * alguém, porque o primeiro é sobre o código que está na tela dela agora.
+     */
     if (!hasSystem) {
         const distinct = new Set(d.findings.map((f) => f.literal.toLowerCase()));
         return [
@@ -408,7 +420,10 @@ function verdict(d, hasSystem, overruled, conflicts) {
             body(`${distinct.size} distinct design values are written by hand here.`),
             body("No design system is installed, so none of them has a name yet."),
             "",
-            body("Give them one:"),
+            body("Name them yourself - this reads them and asks you for the words:"),
+            snippet(["npx synthesisui@latest absorb"]),
+            "",
+            body("Or start from a system somebody already published:"),
             snippet(["npx synthesisui@latest init --ds <slug>"]),
             body("Browse systems at https://www.synthesisui.com/gallery"),
         ];
@@ -784,7 +799,19 @@ export async function doctor(opts) {
      * na mesma tela (dono: "fiquei perdido"). Ou o número não significa nada, ou existe uma lista de
      * prioridades; as duas não cabem juntas.
      */
-    const blocked = hasSystem && (!wiring.imported || !wiring.scoped);
+    /**
+     * A FIAÇÃO SÓ EXISTE PARA UM SISTEMA NOSSO - e usar "tem nomes" no lugar disso recusava o
+     * `--fix` a quem nunca instalou nada (medido em 18/08, no caminho de quem começa do zero).
+     *
+     * Ela escreve os tokens dela no próprio `:root`, o doctor passa a dizer "7 dos seus valores
+     * têm nome", e o `--fix` respondia "trocar agora apontaria para variáveis que o navegador não
+     * resolve". Ele resolve: o CSS é dela e já está na página. A frase era literalmente falsa, e
+     * ela aparece no primeiro comando que promete adotar.
+     *
+     * `table.source` é a distinção certa e ela já estava aqui, uma linha abaixo, em `unwired`:
+     * `"yours"` e `"adopted"` são o vocabulário dela, e não há duas linhas para ligar.
+     */
+    const blocked = table.source === "installed" && (!wiring.imported || !wiring.scoped);
     const unwired = table.source === "installed" &&
         (!wiring.imported || !wiring.scoped || fontsPending);
     if (unwired) {
@@ -897,7 +924,15 @@ export async function doctor(opts) {
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${paint.strong(`${String(d.coverage).padStart(3)}%`)}`));
-        console.log(body(paint.dim(`                ${d.tokenUses} from ${systemName}${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
+        console.log(body(paint.dim(
+        /**
+         * DE QUEM É O VOCABULÁRIO, dito na própria linha.
+         *
+         * `systemName` cai em "this system" quando não há um instalado - e aí a tabela é a DELA,
+         * lida das folhas dela. "8 from this system" lê como se existisse um sistema nosso no
+         * projeto, e não existe: são os tokens que ela mesma declarou, usados no código dela.
+         */
+        `                ${d.tokenUses} ${table.source === "installed" ? `from ${systemName}` : "through your own tokens"}${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
         /**
          * A CAMADA DE TOKEN DELE, CONTADA - e a decisão é do dono, em 13/08.
          *
@@ -911,7 +946,22 @@ export async function doctor(opts) {
          * `--ds-*` também segura. Apontar uma para a outra é uma linha por variável, num arquivo só - e
          * os 122 usos seguem o sistema sem tocar em um componente sequer.
          */
-        if (d.ownTokens > 0) {
+        /**
+         * E ESTE BLOCO SÓ EXISTE CONTRA UM SISTEMA NOSSO - ele estava se comparando consigo mesmo.
+         *
+         * `mirrored` marca um token dela quando a tabela segura aquele valor. Quando a tabela É a
+         * dela, ela foi construída a partir daquelas mesmas declarações, então TODO token dela sai
+         * espelhado por construção - 4 de 4 no projeto que caminhei em 18/08. E a linha seguinte
+         * mandava apontá-los para `--ds-*` num projeto que não tem um único `--ds-*`: um conselho
+         * impossível de seguir, no primeiro relatório que ela lê.
+         *
+         * O `used 0x` era falso pelo mesmo motivo: os usos dos tokens dela foram contados na linha
+         * de cima, porque contra a tabela dela eles SÃO o vocabulário conhecido.
+         *
+         * Quando não há sistema nosso, "os seus tokens" e "o sistema" são a mesma coisa, e não há
+         * nada a apontar - a linha de cima já disse tudo o que é verdade.
+         */
+        if (d.ownTokens > 0 && table.source === "installed") {
             console.log(body(paint.dim(`                ${d.ownTokens} token${d.ownTokens === 1 ? "" : "s"} of your own, used ${d.ownUses}x${d.ownMirrored > 0 ? ` - ${d.ownMirrored} hold a value ${systemName} also names` : ""}`)));
             if (d.ownMirrored > 0)
                 console.log(body(paint.dim(`                point those at the \`--ds-*\` that holds it: ${d.ownMirrored} lines, one file`)));
@@ -1671,16 +1721,31 @@ export async function doctor(opts) {
          */
         if (table.source === "yours") {
             console.log("");
-            // Careful about what is being offered. This reader ALREADY has a design
-            // system, so "install ours" would mean replacing theirs, and a CTA that
-            // pretends otherwise is the kind of confident overclaim that costs
-            // trust the first time somebody follows it. What they are missing is
-            // not tokens - it is a contract their agent reads before writing UI.
+            /**
+             * E O COMANDO OFERECIDO É O QUE FAZ O SISTEMA DELA.
+             *
+             * O comentário que estava aqui já dizia a coisa certa - *"este leitor JÁ TEM um design
+             * system, então 'instale o nosso' significaria substituir o dele, e um CTA que finge o
+             * contrário é o tipo de exagero confiante que custa confiança"* - e a linha logo abaixo
+             * oferecia `init --ds <slug>` mais a galeria, que é literalmente instalar o de outra
+             * pessoa. O diagnóstico estava escrito e o conserto não (medido em 18/08).
+             *
+             * O comando que serve a ela existe e é outro: `import` lê o repositório DELA e devolve
+             * um sistema com o vocabulário dela dentro. Caminhado num projeto em branco: quatro
+             * tokens próprios e um componente saíram como "1 of 1 components came out with a
+             * blueprint - 100%".
+             *
+             * A galeria continua dita, uma linha abaixo e em voz baixa: forkar um sistema pronto é
+             * uma escolha legítima, só não é a primeira coisa a oferecer a quem já tem o dela.
+             */
             console.log(body("Your tokens exist. What your agent is missing is a contract:"));
             console.log(body("rules it reads BEFORE writing UI, and a manifest of what exists."));
             console.log("");
-            console.log(paint.blue(snippet(["npx synthesisui@latest init --ds <slug>"])));
-            console.log(body(paint.dim("starts you on a system that ships one - browse them at")));
+            console.log(paint.blue(snippet(["npx synthesisui@latest import --dry"])));
+            console.log(body(paint.dim("reads THIS repo and turns your own vocabulary into that contract -")));
+            console.log(body(paint.dim("local, free, and it writes nothing but the measurement.")));
+            console.log("");
+            console.log(body(paint.dim("Or start from a system somebody already published, if you would rather:")));
             console.log(body(paint.blue("https://www.synthesisui.com/gallery")));
         }
         console.log("");

package/dist/commands/login.js

@@ -53,7 +53,8 @@ export async function login(opts) {
         if (existing && sameRegistry(existing.registry, base)) {
             console.log("");
             console.log(`✓ Already signed in to ${base} on this machine.`);
-            console.log("  Run `synthesisui login --force` to sign in as someone else.");
+            console.log("  Run `synthesisui login --force` to sign in as someone else,");
+            console.log("  or `synthesisui logout` to sign out of this machine.");
             return;
         }
     }

package/dist/commands/logout.js

@@ -0,0 +1,26 @@
+import { clearCredentials, credentialsPath, readCredentials, } from "../config.js";
+/**
+ * SAIR DA CONTA NESTA MÁQUINA - o comando que faltava do par.
+ *
+ * O CLI sabia entrar e não sabia sair. Quem precisava trocar de conta era
+ * mandado apagar `~/.synthesisui/credentials.json` na mão - e uma instrução que
+ * termina em `rm` num diretório de configuração é a que faz alguém apagar a
+ * pasta errada.
+ *
+ * Ele diz de QUAL host saiu, porque a credencial guarda o registry que a
+ * emitiu: sair de um localhost e achar que saiu da produção é o mesmo mal
+ * entendido que fez o token de dev ser enviado para o site em 31/07.
+ */
+export async function logout() {
+    const existing = await readCredentials();
+    const had = await clearCredentials();
+    console.log("");
+    if (!had) {
+        console.log("✓ You are not signed in on this machine - nothing to do.");
+        console.log("  Run `synthesisui login` to connect the CLI to an account.");
+        return;
+    }
+    console.log(`✓ Signed out${existing?.registry ? ` of ${existing.registry}` : ""} on this machine.`);
+    console.log(`  Removed ${credentialsPath}`);
+    console.log("  Run `synthesisui login` to sign in as someone else.");
+}

package/dist/commands/mcp.js

@@ -1147,6 +1147,45 @@ const BY_COMPONENT = {
     describe_component: "describe",
     add_component: "add",
 };
+/**
+ * QUAL ARGUMENTO CARREGA O ASSUNTO DE CADA CHAMADA - e sem isto a medição não responde nada.
+ *
+ * Medido em 18/08: 2 das 15 ferramentas gravavam O QUE foi pedido; as outras 13 gravavam o
+ * próprio nome. `compose_context` estava entre as 13 - e ela é a ÚNICA que emite `composed`,
+ * que é o sinal inteiro de "aqui faltou uma receita". O banco acumulava "compose_context: 47"
+ * e nunca "a família `field`: 12", e é o segundo número que abre uma candidata a receita.
+ *
+ * Esperar volume não consertaria isso: o dado que estava sendo guardado não responde a
+ * pergunta, então o relógio da espera não estava correndo.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE ENTRA, E O QUE NÃO ENTRA DE PROPÓSITO
+ *
+ * Entra o que é um NOME - do vocabulário dela ou do nosso. Ficam de fora, e não por
+ * esquecimento:
+ *
+ *     find_token   `value`  é um valor do repositório dele (`#4f46e5`)
+ *     check_file   `path`   é um caminho do repositório dele
+ *     playbook     `section` é navegação nossa, e não diz nada sobre o sistema dele
+ *
+ * Os dois primeiros são dado DELE, e a nossa tabela de contadores não é lugar para eles. O
+ * `SLUG` do outro lado já os rejeitaria em silêncio; não mandar é dizer a mesma coisa em voz
+ * alta. `list_components`, `system_doctrine`, `recipe_vocabulary` e `refresh_system` não têm
+ * assunto nenhum - a pergunta É o sistema inteiro.
+ *
+ * `validate_recipes` no plural é um LOTE, e um lote não tem um assunto só.
+ */
+const SUBJECT_ARG = {
+    describe_component: "name",
+    add_component: "name",
+    /** A família pedida - o sinal que o A1 precisa e que não estava sendo guardado. */
+    compose_context: "family",
+    /** O que ela pediu e o sistema não tinha: a lacuna, com nome. */
+    request_component: "name",
+    request_rule: "name",
+    request_token: "name",
+    validate_recipe: "name",
+};
 /**
  * O ÚNICO PONTO DE INSTRUMENTAÇÃO - e é isto que o dono pediu (18/08): *"vira
  * comportamento padrão e não depende de disciplina futura."*
@@ -1163,8 +1202,9 @@ async function callTool(root, name, args,
 cli) {
     const answer = await runTool(root, name, args);
     const gesture = BY_COMPONENT[name];
-    const target = gesture
-        ? String(args.name ?? "")
+    const subject = SUBJECT_ARG[name];
+    const target = subject
+        ? String(args[subject] ?? "")
             .trim()
             .toLowerCase()
         : "";

package/dist/commands/status.js

@@ -52,7 +52,21 @@ export async function status(opts) {
     }
     console.log(section("Status"));
     if (installed.length === 0) {
+        /**
+         * NADA INSTALADO NÃO SIGNIFICA NADA A OFERECER, e mandar `list` era o conselho da outra pessoa.
+         *
+         * `list` mostra a GALERIA - sistemas que outros publicaram. Quem roda isto num repositório que
+         * já tem o próprio vocabulário recebia "escolha o de alguém", quando o comando que serve a ela
+         * lê o repositório DELA. O `doctor` cometia o mesmo desvio no parágrafo final, e ali o
+         * comentário até diagnosticava (medido em 18/08).
+         *
+         * As duas continuam ditas, na ordem certa: o dela primeiro, o de outra pessoa como alternativa.
+         */
         console.log(body("No design system installed in this project, so there is nothing to be in sync with."));
+        console.log("");
+        console.log(body("Make one out of this repo:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest import --dry"])));
+        console.log(body("Or bring in one somebody published:"));
         console.log(paint.blue(snippet(["npx synthesisui@latest list"])));
         return;
     }

package/dist/config.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 /**
@@ -76,6 +76,30 @@ export async function writeToken(token, registry) {
         mode: 0o600,
     });
 }
+/**
+ * SAIR DA MÁQUINA - o outro lado da porta que o `login` abre.
+ *
+ * Existir era o mínimo: até aqui a única forma de encerrar a sessão era apagar
+ * `~/.synthesisui/credentials.json` à mão, e um produto que só sabe entrar
+ * obriga a pessoa a mexer no disco para trocar de conta.
+ *
+ * O arquivo inteiro vai embora, e não só o campo `token`: um arquivo sem token
+ * é indistinguível de nenhum arquivo para quem lê (`readCredentials` devolve
+ * `null` nos dois casos) e ainda deixaria o host da sessão antiga gravado.
+ *
+ * Devolve `false` quando não havia nada - a diferença entre "saí" e "você já
+ * estava fora" é a única coisa que o comando tem para dizer.
+ */
+export async function clearCredentials() {
+    const existing = await readCredentials();
+    try {
+        await rm(credentialsPath, { force: true });
+    }
+    catch {
+        // já não existe, ou o disco recusou - o estado final é o mesmo
+    }
+    return existing !== null;
+}
 /** Project-level config (committed): `<root>/_synthesisui/config.json`. */
 export const DEFAULT_CONFIG = {
     target: "next",

package/dist/doctor/their-names.js

@@ -1,4 +1,4 @@
-import { FAMILY_PREFIX, familySays, normalizeValue, } from "./tokens.js";
+import { FAMILY_PREFIX, familySays, formDecides, normalizeValue, UNAMBIGUOUS, } from "./tokens.js";
 /**
  * COMO ELE CHAMA O VALOR - para a gente parar de renomear as variáveis dele.
  *
@@ -47,14 +47,6 @@ import { FAMILY_PREFIX, familySays, normalizeValue, } from "./tokens.js";
  * que o próprio css dele nomeia `--dashboard-font-family`. É pouco, e é o único grupo que sobrou do
  * item que eu tinha nomeado - os `em` saíram na leva anterior.
  */
-const UNAMBIGUOUS = {
-    /** `#rrggbbaa`, que é onde toda a família de dialetos cai. */
-    color: /^#[0-9a-f]{8}$/,
-    /** `s` e `ms` não aparecem em nenhuma outra família do contrato. */
-    motion: /^-?[\d.]+ms$/,
-    /** Uma pilha de fontes: tem vírgula, ou é uma das palavras genéricas do CSS. */
-    font: /,|^(?:serif|sans-serif|monospace|cursive|fantasy|system-ui)$/,
-};
 const segments = (name) => name.replace(/^--/, "").split("-");
 /**
  * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e são 18 no repo real.
@@ -142,8 +134,7 @@ export function theirNames(ours, theirs) {
              * Recusar aqui não perde informação: sem alias, `nameToWrite` cai no NOSSO token, que é da
              * família certa porque foi o prefixo dela que o trouxe a este laço.
              */
-            const formDecides = Object.values(UNAMBIGUOUS).some((f) => f.test(value));
-            const usable = formDecides
+            const usable = formDecides(value)
                 ? candidates
                 : candidates.filter((n) => familySays(kind, n));
             if (usable.length === 0)

package/dist/doctor/tokens.js

@@ -569,6 +569,27 @@ export const FAMILY_WORDS = {
  * `--dashboard-radius-lg` é um raio e o primeiro segmento é o namespace dele. Olhar só o começo
  * recusaria um nome certo por causa de um prefixo de produto, que é a metade oposta do mesmo erro.
  */
+/**
+ * OS VALORES CUJA FORMA JÁ DIZ A FAMÍLIA - e por isso o nome não precisa dizer.
+ *
+ * Morava em `their-names.ts`, privada, e a falta dela aqui foi medida no corpus: filtrar por
+ * palavra sem esta porta trocou `--brand-500` por `--loader-color` num hex. Os dois são cor, e
+ * o segundo só ganhou por ter a palavra "color" no nome - a doc de `FAMILY_WORDS` já avisava
+ * que 748 dos 755 nomes sem palavra de categoria são cor.
+ *
+ * O que fica de fora é o COMPRIMENTO, e fica de propósito: `24px` pode ser raio, espaçamento ou
+ * tamanho de fonte, e ali o nome é a única pista que existe.
+ */
+export const UNAMBIGUOUS = {
+    /** `#rrggbbaa`, que é onde toda a família de dialetos cai. */
+    color: /^#[0-9a-f]{8}$/,
+    /** `s` e `ms` não aparecem em nenhuma outra família do contrato. */
+    motion: /^-?[\d.]+ms$/,
+    /** Uma pilha de fontes: tem vírgula, ou é uma das palavras genéricas do CSS. */
+    font: /,|^(?:serif|sans-serif|monospace|cursive|fantasy|system-ui)$/,
+};
+/** A forma deste valor já decide a família dele, então a palavra no nome não precisa. */
+export const formDecides = (value) => Object.values(UNAMBIGUOUS).some((f) => f.test(value));
 export const familySays = (kind, name) => {
     const words = FAMILY_WORDS[kind] ?? [];
     const segments = name.replace(/^--/, "").toLowerCase().split("-");
@@ -596,8 +617,33 @@ export function tokenMatch(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal, table.rootPx));
     if (!hit || hit.length === 0)
         return null;
+    /**
+     * O PREFIXO É NOSSO; O NOME PODE SER DELA - e olhar só o prefixo reprovava todo o vocabulário
+     * dela como coincidência entre famílias (medido em 18/08, no caminho de quem começa do zero).
+     *
+     * `--ds-radius-md` carrega a família por construção, e é isso que o prefixo lê. `--radius-card`
+     * não carrega prefixo nenhum, então nenhum token dela casava e TODO achado saía marcado como
+     * erro de categoria - com a frase se contradizendo na mesma linha: "no radius named for it ·
+     * the value lives as --radius-card". O `--fix` então deixava de trocar exatamente os valores
+     * que ela acabou de nomear.
+     *
+     * `familySays` é a resposta e ela já existia para o outro lado da mesma pergunta (`their-names`,
+     * `absorb-plan`): a família sai de QUALQUER segmento do nome, então o namespace de produto dela
+     * não atrapalha. Os dois caminhos somam - a garantia por construção continua valendo primeiro.
+     */
     const prefix = kind ? FAMILY_PREFIX[kind] : undefined;
-    const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
+    /**
+     * E A PALAVRA SÓ DECIDE QUANDO A FORMA NÃO DECIDE - a mesma porta que `their-names` usa.
+     *
+     * Sem ela, filtrar por palavra num hex escolhia `--loader-color` em vez de `--brand-500`
+     * (medido no corpus dourado): os dois são cor, e o segundo perdia por não ter a palavra
+     * "color" no nome. Num comprimento cru é o contrário - ali a palavra é a única pista.
+     */
+    const byWord = kind && !formDecides(normalizeValue(literal, table.rootPx));
+    const family = kind
+        ? hit.filter((n) => (prefix ? n.startsWith(prefix) : false) ||
+            (byWord ? familySays(kind, n) : false))
+        : [];
     const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.
     const semantic = pool.find((n) => n.includes("-semantic-"));

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { boolFlag, parseFlags } from "./cli-flags.js";
 import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
@@ -18,6 +19,7 @@ import { runImport } from "./commands/import.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
+import { logout } from "./commands/logout.js";
 import { mcp } from "./commands/mcp.js";
 import { refit } from "./commands/refit.js";
 import { request } from "./commands/request.js";
@@ -37,6 +39,7 @@ const HELP = `synthesisui - bring SynthesisUI design systems into your project
 
 Usage - deterministic, FREE:
   synthesisui login [options]              connect the CLI to your account (device-flow; --force to switch accounts)
+  synthesisui logout                       sign out of this machine (removes the saved token)
   synthesisui init [options]               write _synthesisui/config.json (target, dirs); --ds to bring one in
   synthesisui list [options]               list the published design systems
   synthesisui list --mine                  your own systems, with their group
@@ -135,61 +138,6 @@ Examples:
   synthesisui advise "habit-building app for tracking personal finances"
   synthesisui generate "an upgrade banner with a title, message and a primary CTA"
 `;
-/** Extracts simple `--flag value` pairs and the remaining positionals. */
-/**
- * A REPEATED FLAG ACCUMULATES rather than overwriting.
- *
- * `--usage apps/web --usage apps/admin` is the natural way to say two, and keeping
- * only the last would drop one silently - which is the failure mode this codebase
- * refuses everywhere else. Every existing flag is passed once and still arrives as
- * a string, so nothing that reads `typeof flags.x === "string"` changes.
- */
-function parseFlags(argv) {
-    const positionals = [];
-    const flags = {};
-    const put = (key, value) => {
-        const had = flags[key];
-        if (had === undefined) {
-            flags[key] = value;
-            return;
-        }
-        if (typeof value !== "string")
-            return;
-        flags[key] = [
-            ...(Array.isArray(had) ? had : typeof had === "string" ? [had] : []),
-            value,
-        ];
-    };
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "-h" || arg === "--help") {
-            flags.help = true;
-        }
-        else if (arg.startsWith("--")) {
-            const body = arg.slice(2);
-            const eq = body.indexOf("=");
-            if (eq !== -1) {
-                // `--key=value` form (e.g. --out=templates/page.tsx)
-                put(body.slice(0, eq), body.slice(eq + 1));
-            }
-            else {
-                // `--key value` form
-                const next = argv[i + 1];
-                if (next !== undefined && !next.startsWith("--")) {
-                    put(body, next);
-                    i++;
-                }
-                else {
-                    put(body, true);
-                }
-            }
-        }
-        else {
-            positionals.push(arg);
-        }
-    }
-    return { positionals, flags };
-}
 async function main() {
     const { positionals, flags } = parseFlags(process.argv.slice(2));
     const [command, ...args] = positionals;
@@ -397,11 +345,19 @@ async function main() {
             await add(slug, { registry, dir, version, cli: CLI_VERSION });
             break;
         }
+        case "logout":
+            /**
+             * O outro lado do `login`. Sem ele a única saída era apagar
+             * `~/.synthesisui/credentials.json` à mão - e trocar de conta é o
+             * caminho normal de quem testa a plataforma em mais de um repositório.
+             */
+            await logout();
+            break;
         case "login":
             // `--force` porque o comando agora sai cedo quando esta máquina já tem
             // sessão para este host - trocar de conta continua possível, e passa a
             // ser dito em vez de ser o comportamento padrão.
-            await login({ registry, force: args.includes("--force") });
+            await login({ registry, force: boolFlag(flags, "force") });
             break;
         case "init": {
             const target = typeof flags.target === "string" ? flags.target : undefined;
@@ -562,10 +518,10 @@ async function main() {
                 dir,
                 registry,
                 cli: CLI_VERSION,
-                recordOnly: args.includes("--record-only"),
-                yes: args.includes("--yes"),
+                recordOnly: boolFlag(flags, "record-only"),
+                yes: boolFlag(flags, "yes"),
                 /** `--full`: o relatório inteiro do leitor. Por padrão a re-medição conta o que MUDOU. */
-                full: args.includes("--full") || flags.full === true,
+                full: boolFlag(flags, "full"),
             });
             break;
         /**

package/dist/install-marks.js

@@ -159,7 +159,7 @@ export const MATERIALISER_SINCE = "0.16.241";
  * `var(--text-caption)` - um token de tipo numa posição de raio. Medido no repositório real: 290
  * sugestões com a categoria trocada, 66 delas graváveis por um `--fix --write`.
  */
-export const CHECKER_SINCE = "0.16.232";
+export const CHECKER_SINCE = "0.16.250";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/package.json

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