synthesisui 0.16.250 → 0.16.252

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/import.js

@@ -3,6 +3,7 @@ import { basename, dirname, join, relative } from "node:path";
 import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
+import { declaredElsewhere } from "../declared-elsewhere.js";
 import { architectureRule, describeArchitecture, describeChoice, detectArchitectures, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, readRuntime, } from "../doctor/call-sites.js";
@@ -37,6 +38,7 @@ import { withLibraryStructure } from "../library-structure.js";
 import { body, paint, section } from "../output.js";
 import { phase, startProgress } from "../progress.js";
 import { detectStack, resolveDeps, stackVersions } from "../stack.js";
+import { placeInWorkspace } from "../workspace-place.js";
 import { walk, walkAll } from "./doctor.js";
 /**
  * How many distinct values travel, PER KIND.
@@ -1996,7 +1998,15 @@ export async function takeCensus(root, opts) {
         },
     };
 }
-function summarize(c) {
+/**
+ * O RESUMO RECEBE O LUGAR JUNTO COM O CENSO - e não a metade dele.
+ *
+ * `sayBrokenRefs` precisa saber ONDE procurar a declaração que o escopo não viu,
+ * e um parâmetro opcional aqui seria a mesma porta que o §6 do método manda
+ * fechar: uma função que pode ser chamada pela metade vai ser, e o sintoma seria
+ * o relatório voltando a dizer "your CSS never declares" sem que nada falhe.
+ */
+async function summarize(c, root, scope) {
     const byKind = new Map();
     for (const v of c.observed)
         byKind.set(v.kind, (byKind.get(v.kind) ?? 0) + v.count);
@@ -2045,7 +2055,7 @@ function summarize(c) {
         }
     }
     sayConventions(c);
-    sayBrokenRefs(c);
+    await sayBrokenRefs(c, root, scope);
 }
 /**
  * THEIR VOCABULARY, MEASURED. This section exists so every later finding can be
@@ -2076,14 +2086,70 @@ function sayConventions(c) {
  * finding that needs no agreement with us: the convention being broken is
  * theirs.
  */
-function sayBrokenRefs(c) {
-    const broken = c.brokenRefs ?? [];
-    if (broken.length === 0)
+/**
+ * A PASTA QUE CONTÉM TODOS ESTES CAMINHOS - o `--scope` que traria as
+ * declarações junto, derivado dos endereços e não sugerido de cabeça.
+ *
+ * Devolve `null` quando os caminhos não compartilham pasta nenhuma: aí não existe
+ * um escopo único que resolva, e inventar um seria pior que dizer a regra geral.
+ */
+function commonPrefix(paths) {
+    if (paths.length === 0)
+        return null;
+    const out = [];
+    for (let i = 0;; i++) {
+        const seg = paths[0][i];
+        // O último segmento é o arquivo, e um arquivo não é um escopo.
+        if (seg == null || i >= paths[0].length - 1)
+            break;
+        if (!paths.every((p) => p[i] === seg && i < p.length - 1))
+            break;
+        out.push(seg);
+    }
+    return out.length > 0 ? out.join("/") : null;
+}
+async function sayBrokenRefs(c, root, scope) {
+    const all = c.brokenRefs ?? [];
+    if (all.length === 0)
         return;
+    /**
+     * DUAS PERGUNTAS DIFERENTES, E O RELATÓRIO FAZIA UMA SÓ.
+     *
+     * "Não resolve no que eu medi" e "não existe no seu código" são coisas
+     * distintas, e o texto afirmava a segunda. Com `--scope src/components` no
+     * monorepo do dono são 1021 referências contra 2 declarações, enquanto o CSS
+     * dele declara 118 em `src/app/**` e 764 em `packages/ui` (medido 19/08).
+     *
+     * Culpar o CSS de quem confiou o repositório por um recorte NOSSO é o pior
+     * lugar para errar: o relatório é o que a pessoa lê depois, sozinha.
+     */
+    const at = await declaredElsewhere(root, scope, all.map((b) => b.name)).catch(() => new Map());
+    const outside = all.filter((b) => at.has(b.name));
+    const broken = all.filter((b) => !at.has(b.name));
+    if (outside.length > 0) {
+        const uses = outside.reduce((n, b) => n + b.count, 0);
+        console.log("");
+        console.log(section("These are declared outside what was measured"));
+        console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${outside.length} token${outside.length === 1 ? "" : "s"} your code DOES declare - just not inside ${paint.strong(scope ?? "this folder")}. Your CSS is fine; the recipes carry the value you typed instead of the name you gave it, because the name was not in what we read.`));
+        console.log("");
+        for (const b of outside.slice(0, 6)) {
+            console.log(body(`${paint.strong(`var(${b.name})`)} ${paint.faint(`${b.count}× here`)} - declared in ${paint.strong(at.get(b.name) ?? "")}`));
+        }
+        if (outside.length > 6)
+            console.log(body(paint.faint(`(${outside.length - 6} more)`)));
+        console.log("");
+        /** O caminho comum dos endereços é o escopo que traria todos de uma vez. */
+        const wider = commonPrefix([...at.values()].map((v) => v.split("/")));
+        console.log(body(wider
+            ? `A wider ${paint.strong("--scope")} keeps your names: ${paint.strong(`--scope ${wider}`)} covers the declarations above.`
+            : "A wider --scope keeps your names, because the declarations come along with the code that uses them."));
+        if (broken.length === 0)
+            return;
+    }
     const uses = broken.reduce((n, b) => n + b.count, 0);
     console.log("");
     console.log(section("These resolve to nothing"));
-    console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${broken.length} token${broken.length === 1 ? "" : "s"} your CSS never declares. A ${paint.strong("var()")} with no declaration paints no colour - not a different colour. Where exactly one declared token differs by a namespace, the recipe now uses THAT one, so the look survives; the rest travel as the value you typed.`));
+    console.log(body(`${uses} reference${uses === 1 ? "" : "s"} to ${broken.length} token${broken.length === 1 ? "" : "s"} nothing in this repository declares. A ${paint.strong("var()")} with no declaration paints no colour - not a different colour. Where exactly one declared token differs by a namespace, the recipe now uses THAT one, so the look survives; the rest travel as the value you typed.`));
     console.log("");
     for (const b of broken.slice(0, 8)) {
         const where = `${b.count}× in ${b.files} file${b.files === 1 ? "" : "s"}`;
@@ -2286,6 +2352,75 @@ function printAgentContract() {
  * just stops letting a person believe the average of three apps is their design
  * system.
  */
+/**
+ * O LUGAR, DITO ANTES DO ESCOPO - e o comando que a resposta implica.
+ *
+ * A detecção de monorepo olhava só para BAIXO (`siblingProjects` lê `apps/`,
+ * `packages/`, `libs/` dentro do root), então quem roda o import de dentro do app
+ * que está migrando recebia silêncio: `apps/web-dashboard` não contém `apps/`.
+ * Medido no monorepo do dono (19/08): 5 pacotes, `packages/ui` declarando 764
+ * tokens em 3 arquivos contra 114 em 6 no app onde ele rodou, e o aviso que
+ * ensina `--scope packages/ui --usage apps/web-dashboard` nunca apareceu.
+ *
+ * A ORDEM É A DA DÚVIDA DE QUEM LÊ: onde eu estou, onde mora o vocabulário, e só
+ * então o comando. Um comando oferecido antes das duas primeiras respostas é uma
+ * receita para copiar sem entender.
+ */
+async function sayAboutPlace(root, scope) {
+    const place = await placeInWorkspace(root);
+    /** Sem workspace acima, a pergunta antiga ainda vale: há projetos AQUI dentro? */
+    if (!place) {
+        if (!scope)
+            await sayIfWorkspace(root);
+        return;
+    }
+    /** Na raiz do workspace o aviso que já existia é o certo - ele lista os apps. */
+    if (place.here === null) {
+        if (!scope)
+            await sayIfWorkspace(root);
+        return;
+    }
+    const vocab = place.vocabulary;
+    const mine = place.packages.find((p) => p.rel === place.here);
+    /**
+     * NADA A DIZER quando o vocabulário está aqui mesmo: a pessoa escolheu o
+     * pacote que declara os tokens, e repetir o que ela acertou é ruído.
+     */
+    if (!vocab || vocab.rel === place.here)
+        return;
+    /** Nem quando o escopo dado já aponta para lá - ela já sabe. */
+    if (scope && join(place.here, scope) === vocab.rel)
+        return;
+    const up = relative(root, place.workspaceRoot).split("\\").join("/") || ".";
+    /**
+     * SÓ QUEM CONSOME A BIBLIOTECA doa evidência. Oferecer `--usage apps/web-admin`
+     * para um app que nunca a importa ensina a medir escolhas de um lugar que não
+     * vota - e `--usage` existe justamente para dizer quais escolhas já são lei.
+     * Medido no monorepo do dono: dos dois outros apps, nenhum declara a
+     * biblioteca, e a primeira versão desta mensagem oferecia os dois.
+     */
+    const consumers = place.packages.filter((p) => p.rel !== vocab.rel &&
+        p.rel !== place.here &&
+        vocab.name != null &&
+        p.dependsOn.includes(vocab.name));
+    const usage = [place.here, ...consumers.map((c) => c.rel)]
+        .slice(0, 3)
+        .map((a) => `--usage ${a}`)
+        .join(" ");
+    console.log("");
+    console.log(section("This folder is one package of a workspace"));
+    console.log(body(`${paint.strong(place.here)} is one of ${place.packages.length} packages under ${paint.strong(place.workspaceRoot)}.`));
+    console.log("");
+    console.log(body(`And the vocabulary is not here: ${paint.strong(vocab.rel)} declares ${vocab.declarations} token${vocab.declarations === 1 ? "" : "s"} across ${vocab.files} file${vocab.files === 1 ? "" : "s"}, while this package declares ${mine?.declarations ?? 0} across ${mine?.files ?? 0}.`));
+    console.log(body(paint.faint("A system built from the app is the average of one consumer; the tokens live where the library declares them.")));
+    console.log("");
+    console.log(body("The system is one place, and the evidence is another:"));
+    console.log("");
+    console.log(body(`    ${paint.strong(`synthesisui import --dir ${up} --scope ${vocab.rel} ${usage}`)}`));
+    console.log(body(paint.faint(`      --dir points at the workspace root, so --scope and --usage are read from there.`)));
+    console.log("");
+    console.log(body(paint.dim("Nothing you ran is wasted - this census is a fine diagnosis of this app. It is a system for one consumer, which is the part worth knowing before you publish it.")));
+}
 async function sayIfWorkspace(root) {
     const { apps, shared } = await siblingProjects(root);
     if (apps.length < 2)
@@ -3058,11 +3193,22 @@ export async function runImport(opts) {
      */
     if (!opts.census)
         await resolveReadParts(census, root);
-    summarize(census);
-    // Only when nobody has scoped yet. Telling someone to scope to the folder
-    // they just scoped to reads as the tool not having noticed.
-    if (!opts.census && !scope)
-        await sayIfWorkspace(root);
+    await summarize(census, root, scope);
+    /**
+     * ONDE ESTOU vem antes de O QUE EU LEIO, e o `!scope` calava exatamente quem
+     * mais precisava ouvir.
+     *
+     * A condição era "só quando ninguém escopou ainda", pelo motivo certo: mandar
+     * escopar para a pasta que a pessoa acabou de escopar lê como a ferramenta não
+     * ter percebido. Só que ela também calava o caso em que o escopo escolhido não
+     * é onde o vocabulário mora - e aí o silêncio não é discrição, é perder a
+     * única chance de dizer que o sistema está em outro pacote.
+     *
+     * `sayAboutPlace` faz as duas perguntas na ordem: onde este comando está, e
+     * onde as declarações estão. Ele só fala quando as respostas divergem.
+     */
+    if (!opts.census)
+        await sayAboutPlace(root, scope);
     // A census handed to us is written BACK TO ITSELF; one we took lands at the
     // ROOT, whatever it measured. Everything else in `_synthesisui/` is anchored
     // there - config, `ds/<slug>/`, the hook's marker - and the census was the

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/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/declared-elsewhere.js

@@ -0,0 +1,77 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { placeInWorkspace } from "./workspace-place.js";
+/**
+ * ONDE ESTE TOKEN É DECLARADO, QUANDO NÃO É NO QUE FOI MEDIDO.
+ *
+ * `findBrokenRefs` compara os `var()` do escopo contra as declarações do escopo,
+ * e o relatório chama o resto de *"tokens your CSS never declares"*. Com
+ * `--scope` isso pode ser falso, e no monorepo do dono era (19/08):
+ * `--scope src/components` deixa 1021 referências contra 2 declarações, e o CSS
+ * dele declara 118 em `src/app/**` e 764 em `packages/ui`.
+ *
+ * Afirmar um defeito que não existe no código de quem confiou o repositório é
+ * pior do que não dizer nada - o relatório é o documento que a pessoa lê depois,
+ * sozinha, e ele estava culpando o CSS dela por uma escolha de recorte NOSSA.
+ *
+ * Então a pergunta muda de "existe?" para "existe ONDE?", em duas camadas: fora
+ * do escopo mas dentro do que foi apontado, e nos outros pacotes do mesmo
+ * workspace - que é onde uma biblioteca de design system mora.
+ */
+const SHEET = /\.(css|scss|sass|less)$/i;
+const DECL = /(^|[\s{;])(--[a-zA-Z0-9-]+)\s*:/g;
+/** Onde cada nome aparece declarado, primeiro achado ganha - basta um endereço. */
+async function harvest(dir, label, skip, into) {
+    const visit = async (at, depth) => {
+        if (depth > 8)
+            return;
+        for (const e of await readdir(at, { withFileTypes: true }).catch(() => [])) {
+            if (e.name.startsWith(".") || e.name === "node_modules")
+                continue;
+            const full = join(at, e.name);
+            if (skip && full === skip)
+                continue;
+            if (e.isDirectory()) {
+                await visit(full, depth + 1);
+                continue;
+            }
+            if (!SHEET.test(e.name))
+                continue;
+            const body = await readFile(full, "utf8").catch(() => "");
+            for (const m of body.matchAll(DECL)) {
+                const name = m[2];
+                if (!into.has(name))
+                    into.set(name, `${label}${relative(dir, full).split("\\").join("/")}`);
+            }
+        }
+    };
+    await visit(dir, 0);
+}
+/**
+ * NOME -> CAMINHO onde ele é declarado, fora do que foi medido.
+ *
+ * Só roda quando há algo a explicar: sem referências pendentes não há pergunta,
+ * e um walk a mais por nada é um walk a mais.
+ */
+export async function declaredElsewhere(root, scope, names) {
+    const out = new Map();
+    if (names.length === 0)
+        return out;
+    const wanted = new Set(names);
+    const found = new Map();
+    /** Camada 1: o resto do que a pessoa apontou, sem reler o escopo. */
+    await harvest(root, "", scope ? join(root, scope) : null, found);
+    /** Camada 2: os outros pacotes do workspace - onde uma biblioteca mora. */
+    const place = await placeInWorkspace(root);
+    if (place) {
+        for (const pkg of place.packages) {
+            if (pkg.rel === place.here)
+                continue;
+            await harvest(join(place.workspaceRoot, pkg.rel), `${pkg.rel}/`, null, found);
+        }
+    }
+    for (const [name, where] of found)
+        if (wanted.has(name))
+            out.set(name, where);
+    return out;
+}

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/stack.js

@@ -27,6 +27,15 @@ import { join } from "node:path";
  * app que usa o sistema, então o manifesto daquele app é evidência tanto quanto
  * o da raiz.
  */
+/**
+ * O RANGE QUE DIZ "ISTO É DESTE REPOSITÓRIO" - o mesmo prefixo que
+ * `frontier-kind.ts` já reconhece como local, escrito aqui uma vez.
+ *
+ * Sobrescrever o range com este valor é mais verdadeiro do que preservar o que o
+ * app digitou: um `*` num monorepo NÃO significa "qualquer versão do npm", e era
+ * assim que ele estava sendo lido.
+ */
+const LOCAL_RANGE = "workspace:*";
 export async function resolveDeps(root) {
     const deps = {};
     const workspaceDirs = [];
@@ -84,6 +93,47 @@ export async function resolveDeps(root) {
     }
     for (const w of workspaceDirs)
         await readManifest(w);
+    /**
+     * O NOME DE UM PACOTE DESTE WORKSPACE É LOCAL, QUALQUER QUE SEJA O RANGE - e
+     * é a lei 13 se aplicando a si mesma: a ORIGEM decide, não o nome.
+     *
+     * Medido no monorepo do dono (19/08): `apps/web-dashboard` declara
+     * `"@frontend-hub/ui": "*"`, que é como npm e yarn workspaces apontam para o
+     * pacote ao lado. `LOCAL_RANGE` em `frontier-kind.ts` reconhece
+     * `workspace:|file:|link:|portal:`, então `frontierOf` respondia `opaque` -
+     * "de terceiro, se desenha sozinha" - sobre a biblioteca que É o design
+     * system dele, em 52 arquivos daquele app. Um monorepo que versiona de
+     * verdade (`"^2.1.0"`) caía igual.
+     *
+     * Quem decidia era o FORMATO DO RANGE, que não é a origem nem o nome: é uma
+     * terceira coisa. A origem está aqui - a raiz declara `workspaces`, e um
+     * daqueles diretórios tem um `package.json` cujo `name` é aquele
+     * especificador. Este laço grava esse fato, e ele SOBRESCREVE o range que o
+     * app escreveu, porque um pacote deste repositório não deixa de ser deste
+     * repositório por causa de como alguém o apontou.
+     *
+     * Corrigido aqui e não em `frontier-kind.ts` por dois motivos: a informação já
+     * passa por esta função, e aquele arquivo é gêmeo byte-idêntico de
+     * `libs/ds-contracts/src/frontier-kind.ts` - mudar a pergunta lá custaria os
+     * dois, e a pergunta lá está certa.
+     *
+     * ENTRA MESMO SEM O APP DECLARAR: alias de tsconfig, import direto ou
+     * dependência esquecida - o pacote existe no repositório, e é isso que a lei
+     * pergunta.
+     */
+    for (const w of workspaceDirs) {
+        const raw = await readFile(join(w, "package.json"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        try {
+            const name = JSON.parse(raw).name;
+            if (typeof name === "string" && name)
+                deps[name] = LOCAL_RANGE;
+        }
+        catch {
+            // manifesto ilegível custa a detecção daquele pacote, nunca a corrida
+        }
+    }
     return deps;
 }
 /**

package/dist/workspace-place.js

@@ -0,0 +1,140 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const MANIFEST = "package.json";
+const SHEET = /\.(css|scss|sass|less)$/i;
+const DECL = /(^|[\s{;])--[a-zA-Z0-9-]+\s*:/g;
+async function manifest(dir) {
+    const raw = await readFile(join(dir, MANIFEST), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Os globs que um manifesto usa para declarar workspaces, nas duas formas reais. */
+function workspaceGlobs(p) {
+    const w = p.workspaces;
+    const list = Array.isArray(w)
+        ? w
+        : Array.isArray(w?.packages)
+            ? w.packages
+            : [];
+    return list.filter((g) => typeof g === "string");
+}
+/**
+ * Quantas custom properties um pacote declara - o mesmo peso que
+ * `siblingProjects` já usa para escolher entre `packages/core` e `packages/ui`.
+ *
+ * Diretório com ponto e `node_modules` ficam fora pelo mesmo motivo que o `walk`
+ * do doctor os ignora: `.next/` guarda CSS COMPILADO, e contá-lo faria o build
+ * output votar em onde mora o vocabulário.
+ */
+async function weigh(dir) {
+    let declarations = 0;
+    let files = 0;
+    const visit = async (at, depth) => {
+        if (depth > 8)
+            return;
+        for (const e of await readdir(at, { withFileTypes: true }).catch(() => [])) {
+            if (e.name.startsWith(".") || e.name === "node_modules")
+                continue;
+            const full = join(at, e.name);
+            if (e.isDirectory()) {
+                // Um pacote aninhado fala o próprio sistema - ver `walk`, mesma regra.
+                if (await manifest(full))
+                    continue;
+                await visit(full, depth + 1);
+                continue;
+            }
+            if (!SHEET.test(e.name))
+                continue;
+            const body = await readFile(full, "utf8").catch(() => "");
+            const n = (body.match(DECL) ?? []).length;
+            if (n > 0) {
+                declarations += n;
+                files += 1;
+            }
+        }
+    };
+    await visit(dir, 0);
+    return { declarations, files };
+}
+/**
+ * O LUGAR, ou `null` quando não há workspace nenhum acima - e aí não há nada a
+ * anunciar, que é o caso da maioria dos projetos.
+ *
+ * Sobe no máximo quatro níveis, o mesmo teto de `resolveDeps`: cobre todo layout
+ * pnpm/npm/yarn sem sair andando pela pasta pessoal de quem roda.
+ */
+export async function placeInWorkspace(root) {
+    let dir = root;
+    let workspaceRoot = null;
+    let globs = [];
+    for (let up = 0; up < 4; up++) {
+        const p = await manifest(dir);
+        if (p) {
+            const g = workspaceGlobs(p);
+            if (g.length > 0) {
+                workspaceRoot = dir;
+                globs = g;
+                break;
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!workspaceRoot)
+        return null;
+    const dirs = [];
+    for (const g of globs) {
+        if (g.endsWith("/*")) {
+            const parent = join(workspaceRoot, g.slice(0, -2));
+            for (const e of await readdir(parent, { withFileTypes: true }).catch(() => []))
+                if (e.isDirectory())
+                    dirs.push(join(parent, e.name));
+        }
+        else if (!g.includes("*")) {
+            dirs.push(join(workspaceRoot, g));
+        }
+    }
+    const packages = [];
+    const local = new Set();
+    const read = [];
+    for (const d of dirs) {
+        const p = await manifest(d);
+        if (!p)
+            continue;
+        read.push({ p, d });
+        if (typeof p.name === "string")
+            local.add(p.name);
+    }
+    for (const { p, d } of read) {
+        const { declarations, files } = await weigh(d);
+        const deps = {
+            ...(p.dependencies ?? {}),
+            ...(p.devDependencies ?? {}),
+        };
+        packages.push({
+            rel: relative(workspaceRoot, d).split("\\").join("/"),
+            name: typeof p.name === "string" ? p.name : null,
+            declarations,
+            files,
+            dependsOn: Object.keys(deps).filter((k) => local.has(k)),
+        });
+    }
+    if (packages.length === 0)
+        return null;
+    const rel = relative(workspaceRoot, root).split("\\").join("/");
+    const ranked = [...packages].sort((a, b) => b.declarations - a.declarations);
+    return {
+        workspaceRoot,
+        here: rel === "" ? null : rel,
+        packages,
+        vocabulary: ranked[0]?.declarations > 0 ? ranked[0] : null,
+    };
+}

package/package.json

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