synthesisui 0.16.141 → 0.16.145

package/dist/commands/status.js

@@ -0,0 +1,158 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { readToken, resolveRegistry } from "../config.js";
+import { readEvents } from "../doctor/ledger.js";
+import { readRequests } from "../doctor/requests.js";
+import { body, paint, section, snippet } from "../output.js";
+/**
+ * `synthesisui status` - a resposta do dia a dia, no terminal.
+ *
+ * A pergunta que um engenheiro faz sobre um sistema de design é sempre a mesma: em que pé estamos, e
+ * o que falta. Até 05/08 a resposta morava numa tela - cobertura, o que mudou, o que está pendente - e
+ * uma resposta que exige abrir o navegador é uma resposta que ninguém busca no meio de uma tarefa.
+ * Essa é a "terceira aba" que faz uma plataforma de governança ser ignorada, e ela era nossa.
+ *
+ * LOCAL PRIMEIRO, e a rede é opcional. Tudo que importa para decidir o próximo passo já está no disco:
+ * a versão instalada no `.lock`, o último doctor no registro, os pedidos abertos, o baseline commitado.
+ * A rede entra para UMA pergunta que o disco não sabe - "existe medição mais nova do que a minha?" - e
+ * a ausência dela nunca é um erro: sem login, sem rede, sem token, o resto continua respondido.
+ *
+ * E NÃO ESCREVE NADA. Nem ledger, nem cache, nem arquivo de estado: é uma leitura, e uma leitura que
+ * deixa rastro é a razão pela qual alguém desconfia de rodar um comando dentro de um repo alheio.
+ */
+export async function status(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    /** Todo sistema instalado aqui, com a versão que o `.lock` diz. */
+    const dsDir = join(root, "_synthesisui", "ds");
+    const installed = [];
+    try {
+        for (const entry of await readdir(dsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const raw = await readFile(join(dsDir, entry.name, ".lock"), "utf8").catch(() => "");
+            try {
+                const lock = JSON.parse(raw);
+                installed.push({
+                    slug: lock.slug ?? entry.name,
+                    ...(typeof lock.version === "number"
+                        ? { version: lock.version }
+                        : {}),
+                    ...(lock.adopted ? { adopted: true } : {}),
+                });
+            }
+            catch {
+                installed.push({ slug: entry.name });
+            }
+        }
+    }
+    catch {
+        // sem _synthesisui: tratado abaixo
+    }
+    console.log(section("Status"));
+    if (installed.length === 0) {
+        console.log(body("No design system installed in this project, so there is nothing to be in sync with."));
+        console.log(paint.blue(snippet(["npx synthesisui@latest list"])));
+        return;
+    }
+    for (const ds of installed)
+        console.log(body(`${ds.slug}${ds.version ? ` · v${ds.version}` : ""}${ds.adopted ? " · adopted (described here, owned elsewhere)" : ""}`));
+    /**
+     * O ÚLTIMO DOCTOR, pelo mesmo leitor que o `sync` e o `repo-state` usam. Ler o formato do registro
+     * por conta própria aqui seria uma segunda implementação, e a primeira coisa que ela faria é
+     * discordar da outra sobre o que é uma linha válida.
+     */
+    const events = await readEvents(root);
+    const doctors = events
+        .filter((e) => e.kind === "doctor" && e.at)
+        .sort((a, b) => String(b.at).localeCompare(String(a.at)));
+    const last = doctors[0];
+    console.log("");
+    if (last) {
+        const age = ageOf(String(last.at));
+        console.log(body(`Last check ${age}${typeof last.coverage === "number" ? ` · token coverage ${last.coverage}%` : ""}${typeof last.named === "number" && last.named > 0 ? ` · ${last.named} hand-written values your system already names` : ""}`));
+        /**
+         * O NÚMERO ACIONÁVEL VEM COM O COMANDO QUE O RESOLVE. `named` é o que tem resposta pronta no
+         * sistema deles, e desde 05/08 existe uma coisa para fazer com ele em vez de encarar a lista.
+         */
+        if (typeof last.named === "number" && last.named > 0)
+            console.log(paint.blue(snippet(["npx synthesisui@latest doctor --fix"])));
+    }
+    else {
+        console.log(body("Nothing checked yet in this project - one command, no login:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest doctor"])));
+    }
+    /** A catraca: existe uma linha a manter, ou o CI ainda não tem o que comparar? */
+    const baseline = await readFile(join(root, "_synthesisui", "drift-baseline.json"), "utf8").catch(() => null);
+    if (baseline) {
+        try {
+            const parsed = JSON.parse(baseline);
+            console.log(body(`Ratchet at ${parsed.totals?.drift ?? "?"} findings, frozen ${parsed.at ? ageOf(parsed.at) : "at an unrecorded time"} - CI fails only above it.`));
+        }
+        catch {
+            console.log(body("A drift baseline exists but is not readable JSON."));
+        }
+    }
+    else {
+        console.log(body(paint.dim("No ratchet yet, so nothing in CI can fail on drift. `synthesisui ci` prints the two steps.")));
+    }
+    /**
+     * TODO REQUEST LIDO ESTÁ ABERTO: `closeRequest` REMOVE a linha do arquivo, então o arquivo é a fila
+     * e não um histórico. Filtrar por um campo de fechado aqui seria inventar um estado que o formato
+     * não tem.
+     */
+    const open = await readRequests(root);
+    if (open.length > 0) {
+        console.log("");
+        console.log(body(`${open.length} open request${open.length === 1 ? "" : "s"} the system has not answered yet:`));
+        for (const r of open.slice(0, 4))
+            console.log(body(paint.dim(`  ${r.id} · ${r.name ?? r.kind}`)));
+        console.log(body(paint.dim("They travel on the next `synthesisui sync`.")));
+    }
+    /**
+     * A ÚNICA PERGUNTA QUE O DISCO NÃO SABE: existe medição mais nova do que a minha? Sem login isso
+     * simplesmente não é dito - e não é um erro, porque tudo acima continua verdadeiro.
+     */
+    const token = await readToken();
+    if (!token) {
+        console.log("");
+        console.log(body(paint.dim("Not logged in, so this is the local half. `synthesisui login` adds what the platform knows.")));
+        return;
+    }
+    const base = resolveRegistry(opts.registry);
+    const owned = installed.find((ds) => !ds.adopted);
+    if (!owned)
+        return;
+    const res = await fetch(`${base}/api/registry/ds/${owned.slug}/reading`, {
+        headers: { Authorization: `Bearer ${token}` },
+    }).catch(() => null);
+    if (!res?.ok) {
+        console.log("");
+        console.log(body(paint.dim(res
+            ? `The registry answered ${res.status} for ${owned.slug} - the local half above still holds.`
+            : "Could not reach the registry - the local half above still holds.")));
+        return;
+    }
+    const remote = (await res.json());
+    console.log("");
+    console.log(body(remote.hasCensus
+        ? `On the platform: ${remote.draft?.components ?? 0} components in the draft${remote.scope ? `, measured from ${remote.scope}` : ""}${(remote.draft?.edited?.length ?? 0) > 0 ? ` · ${remote.draft?.edited?.length} written on the screen` : ""}.`
+        : `${owned.slug} on the platform did not come from an import, so there is no measurement to compare.`));
+    if (remote.hasCensus)
+        console.log(body(paint.dim("`synthesisui sync` measures this repo again with today's reader and sends it.")));
+}
+/** "2 hours ago", sem dependência - e `Invalid Date` nunca chega à tela. */
+function ageOf(iso) {
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return "at an unrecorded time";
+    const mins = Math.max(0, Math.round((Date.now() - then) / 60000));
+    if (mins < 2)
+        return "just now";
+    if (mins < 60)
+        return `${mins} minutes ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"} ago`;
+}

package/dist/config.js

@@ -45,6 +45,20 @@ export function sameRegistry(a, b) {
     return norm(a) === norm(b);
 }
 export async function readToken() {
+    /**
+     * O AMBIENTE GANHA DO ARQUIVO, e é o que permite CI sem navegador.
+     *
+     * O `login` é device flow: abre um browser e precisa de uma pessoa. Isso é certo na primeira vez de
+     * alguém e é um beco sem saída num runner - e a checagem que interessa em CI (`doctor`) nem pede
+     * token, mas `sync` pede, e sem env var não existe caminho headless nenhum. Um segredo do runner é
+     * exatamente o lugar onde uma credencial de CI deve morar.
+     *
+     * A precedência é o ambiente porque é a mais específica: quem exporta a variável está dizendo
+     * "use esta agora", e um arquivo em `~/.synthesisui` não pode ganhar dessa intenção.
+     */
+    const fromEnv = process.env.SYNTHESISUI_TOKEN?.trim();
+    if (fromEnv)
+        return fromEnv;
     try {
         const raw = await readFile(credentialsPath, "utf8");
         const parsed = JSON.parse(raw);

package/dist/doctor/apply-fix.js

@@ -0,0 +1,161 @@
+/**
+ * O CONSERTO QUE O DOCTOR JÁ SABIA APONTAR - aplicado.
+ *
+ * O doctor sempre disse a frase certa: "`#4A90E2` está escrito à mão e o seu sistema já nomeia esse
+ * valor". E parava ali, o que numa lista de 1500 achados significa 1500 edições à mão que ninguém faz.
+ * A objeção de um Design System Lead cético é exatamente esta: governança que aponta o problema e não
+ * carrega o conserto é auditoria, e engenheiro não adota auditoria.
+ *
+ * SÓ O QUE TEM TOKEN. Um achado sem token é uma decisão de design - nomear um valor novo é uma
+ * conversa, e trocar `#ff0000` por um nome inventado por nós seria a pior coisa que esta esteira pode
+ * fazer. `--fix` só toca o caso em que a resposta já existe no sistema DELES.
+ *
+ * E é aqui que ele se aplica, e não num codemod solto: a troca é `literal` → `var(--token)` na LINHA
+ * que o scanner já mediu, com o literal exato que ele já leu. Nada de regex sobre o arquivo inteiro,
+ * nada de AST: o achado carrega arquivo, linha e literal, então a edição é cirúrgica por construção.
+ *
+ * TRÊS COISAS QUE ELE SE RECUSA A FAZER, e cada uma é um jeito conhecido de um codemod destruir
+ * confiança:
+ *
+ *   1. tocar uma linha que mudou desde a medição - se o texto não bate, pula e conta
+ *   2. trocar mais de uma ocorrência por achado - dois `#fff` na mesma linha são dois achados,
+ *      e cada um tem a sua própria linha no relatório
+ *   3. escrever em arquivo que o scanner marcou como fora (gerado, vendored) - esses nunca
+ *      chegam aqui, porque o walk já os pula
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * A substituição numa linha só, e ela é deliberadamente burra.
+ *
+ * `indexOf` do literal exato, primeira ocorrência, nada mais. Um literal de cor ou de comprimento não
+ * tem sintaxe ambígua o suficiente para justificar um parser aqui, e um parser que erra num arquivo de
+ * outra pessoa custa mais que os achados que ele conserta.
+ */
+function swap(line, literal, token) {
+    const at = line.indexOf(literal);
+    if (at === -1)
+        return null;
+    return `${line.slice(0, at)}var(${token})${line.slice(at + literal.length)}`;
+}
+/**
+ * Aplica o que tem token, em memória, e devolve o conteúdo novo por arquivo.
+ *
+ * Pura de propósito - quem escreve em disco é o comando. Um spec precisa poder afirmar a lei sem um
+ * diretório temporário, e o `--dry` sai de graça: o mesmo cálculo, sem a escrita.
+ */
+export function planFix(d, read) {
+    const applied = [];
+    const skipped = [];
+    const next = new Map();
+    /** Linhas por arquivo, mutadas em memória: dois achados no mesmo arquivo compõem. */
+    const lines = new Map();
+    /**
+     * DE BAIXO PARA CIMA no arquivo não é necessário - a troca não muda a contagem de linhas - mas a
+     * ORDEM por arquivo é, para dois achados na mesma linha não se atropelarem: o segundo procura o seu
+     * literal no texto que o primeiro já deixou.
+     */
+    for (const f of d.findings) {
+        if (!f.token) {
+            skipped.push({
+                file: f.file,
+                line: f.line,
+                literal: f.literal,
+                because: "no-token",
+            });
+            continue;
+        }
+        if (!lines.has(f.file)) {
+            const raw = read(f.file);
+            if (raw === null) {
+                skipped.push({
+                    file: f.file,
+                    line: f.line,
+                    literal: f.literal,
+                    because: "unreadable",
+                });
+                continue;
+            }
+            lines.set(f.file, raw.split("\n"));
+        }
+        const body = lines.get(f.file);
+        if (!body)
+            continue;
+        const idx = f.line - 1;
+        const current = body[idx];
+        const swapped = current === undefined ? null : swap(current, f.literal, f.token);
+        if (swapped === null) {
+            /** O arquivo mudou desde a medição, ou o literal já foi trocado por outro achado. */
+            skipped.push({
+                file: f.file,
+                line: f.line,
+                literal: f.literal,
+                because: "moved",
+            });
+            continue;
+        }
+        body[idx] = swapped;
+        applied.push({
+            file: f.file,
+            line: f.line,
+            literal: f.literal,
+            token: f.token,
+        });
+    }
+    for (const [file, body] of lines) {
+        const touched = applied.some((a) => a.file === file);
+        if (touched)
+            next.set(file, body.join("\n"));
+    }
+    return {
+        result: { applied, skipped, files: next.size },
+        next,
+    };
+}
+/** Escreve o que o plano decidiu. Nada aqui decide nada. */
+export async function writeFix(root, next) {
+    for (const [file, content] of next)
+        await writeFile(join(root, file), content, "utf8");
+}
+/** O leitor síncrono que o plano usa, para o comando não ter que carregar tudo antes. */
+export async function readerFor(root, files) {
+    const cache = new Map();
+    for (const file of new Set(files))
+        cache.set(file, await readFile(join(root, file), "utf8").catch(() => null));
+    return (file) => cache.get(file) ?? null;
+}
+/**
+ * O que aconteceu, em texto, e ele lidera pelo número que importa.
+ *
+ * `no-token` NÃO é uma falha e não aparece como uma: é o resto do trabalho, e é uma conversa de
+ * design. Chamar de "pulado" o que é "não é seu para decidir" seria treinar alguém a rodar `--fix` e
+ * achar que terminou.
+ */
+export function describeFix(result, dry) {
+    const { applied, skipped } = result;
+    const moved = skipped.filter((s) => s.because === "moved").length;
+    const unread = skipped.filter((s) => s.because === "unreadable").length;
+    const decisions = skipped.filter((s) => s.because === "no-token").length;
+    const lines = [];
+    if (applied.length === 0) {
+        lines.push(decisions > 0
+            ? `Nothing to apply. All ${decisions} findings are values your system has no name for - those are design decisions, not fixes.`
+            : "Nothing to apply.");
+        return lines;
+    }
+    lines.push(`${dry ? "Would replace" : "Replaced"} ${applied.length} hand-written value${applied.length === 1 ? "" : "s"} with the token your system already has, across ${result.files} file${result.files === 1 ? "" : "s"}.`);
+    const byToken = new Map();
+    for (const a of applied)
+        byToken.set(a.token, (byToken.get(a.token) ?? 0) + 1);
+    for (const [token, n] of [...byToken.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 6))
+        lines.push(`  var(${token}) · ${n} time${n === 1 ? "" : "s"}`);
+    if (moved > 0)
+        lines.push(`${moved} line${moved === 1 ? "" : "s"} changed since the scan and ${moved === 1 ? "was" : "were"} left alone - run it again.`);
+    if (unread > 0)
+        lines.push(`${unread} file${unread === 1 ? "" : "s"} could not be read.`);
+    if (decisions > 0)
+        lines.push(`${decisions} finding${decisions === 1 ? "" : "s"} left: values your system has no name for. Those are decisions - name them, or file a request: npx synthesisui request token`);
+    return lines;
+}

package/dist/doctor/ci-format.js

@@ -0,0 +1,205 @@
+/**
+ * O DOCTOR NA PIPELINE - anotação na linha, e uma CATRACA em vez de um pedágio.
+ *
+ * A objeção mais dura que um Design System Lead cético faz a qualquer plataforma de governança é que
+ * ela vive numa terceira aba: se a checagem não está no PR, no linter, no autocomplete, o engenheiro
+ * ignora. O doctor já respondia metade disso - roda offline, sem login, em 1,8s sobre 2797 arquivos -
+ * e não tinha como falar a língua de um PR.
+ *
+ * O QUE FALTAVA MAIS QUE O FORMATO, e é o achado que decidiu esta peça: o doctor só reprova com
+ * `--strict`, e `--strict` num repo legado é vermelho no dia um. Um portão que fica vermelho para
+ * sempre é um portão que alguém contorna na segunda semana - é literalmente o "pedágio" que faz times
+ * criarem biblioteca paralela. Então o que entra na pipeline não é um portão: é uma CATRACA.
+ *
+ *     sem baseline    nunca reprova, e anota tudo como aviso
+ *     com baseline    reprova SÓ quando a conta subiu - no total ou em algum arquivo
+ *     --write-baseline  congela onde vocês estão hoje, e a dívida de ontem para de doer
+ *
+ * Um arquivo que piorou reprova mesmo quando o total caiu, de propósito: num monorepo o total esconde
+ * um time melhorando e outro regredindo, e a regressão é a única coisa que uma catraca existe para
+ * pegar.
+ *
+ * NADA AQUI FALA COM A REDE nem pede login. É a mesma decisão que mantém o hook instalado: uma
+ * checagem que telefona para casa é uma checagem que alguém desinstala.
+ */
+const byFileOf = (d) => {
+    const out = {};
+    for (const f of d.files)
+        if (f.findings.length > 0)
+            out[f.file] = f.findings.length;
+    return out;
+};
+/** O retrato de agora, para ser gravado e comparado depois. */
+export function baselineOf(d, meta) {
+    return {
+        baseline: 1,
+        at: meta.at,
+        ...(meta.cli ? { cli: meta.cli } : {}),
+        ...(meta.scope ? { scope: meta.scope } : {}),
+        totals: { drift: d.findings.length, phantoms: d.phantomUses },
+        byFile: byFileOf(d),
+    };
+}
+/**
+ * A conta subiu?
+ *
+ * `incomparable` existe porque comparar dois escopos diferentes produz uma regressão inventada - o
+ * dono mediu `packages/ui` e `apps/web-dashboard` no mesmo dia, e um deles tem 2,5x os arquivos do
+ * outro. Nesse caso a catraca NÃO reprova e diz por quê: reprovar por diferença de input é o alarme
+ * falso que ensina um time a passar `--no-verify`.
+ */
+export function compareToBaseline(d, base, now) {
+    const mine = byFileOf(d);
+    const regressed = [];
+    let improved = 0;
+    for (const [file, count] of Object.entries(mine)) {
+        const was = base.byFile[file] ?? 0;
+        if (count > was)
+            regressed.push({ file, was, now: count });
+    }
+    for (const [file, was] of Object.entries(base.byFile))
+        if ((mine[file] ?? 0) < was)
+            improved += 1;
+    const drift = { was: base.totals.drift, now: d.findings.length };
+    const phantoms = { was: base.totals.phantoms, now: d.phantomUses };
+    const scopeChanged = (base.scope ?? "") !== (now.scope ?? "");
+    return {
+        worse: !scopeChanged &&
+            (drift.now > drift.was ||
+                phantoms.now > phantoms.was ||
+                regressed.length > 0),
+        drift,
+        phantoms,
+        regressed: regressed.sort((a, b) => b.now - b.was - (a.now - a.was)),
+        improved,
+        ...(scopeChanged
+            ? {
+                incomparable: `the baseline was measured on ${base.scope ?? "the whole repo"} and this run read ${now.scope ?? "the whole repo"} - different inputs, so nothing is failed on the difference`,
+            }
+            : {}),
+    };
+}
+/** O que a mensagem de uma anotação diz, e é a mesma frase nos dois formatos. */
+function messageFor(f) {
+    return f.token
+        ? `${f.literal} is written by hand, and this project's system already names it: var(${f.token}). Use the token.`
+        : `${f.literal} is a ${f.kind} value written by hand, and the system has no name for it yet. Name it, or file a token request: npx synthesisui request token`;
+}
+/**
+ * ANOTAÇÕES DO GITHUB, que aparecem na linha exata do diff.
+ *
+ * Nenhuma Action é necessária: o GitHub lê estes comandos do stdout de qualquer step, então a
+ * integração inteira é uma linha no workflow deles. Uma Action publicada seria uma peça a mais para
+ * manter oferecendo exactamente isto.
+ *
+ * TUDO É `warning`, e nunca `error`: a severidade que reprova é o exit code, e ela é decidida pela
+ * catraca. Anotação vermelha em cima de dívida herdada é o mesmo pedágio de sempre, pintado de outra
+ * cor.
+ */
+export function githubAnnotations(d, cap = 200) {
+    const out = [];
+    /**
+     * O QUE TEM CONSERTO ÓBVIO VEM PRIMEIRO, porque o teto é real e ele decide o que chega ao PR.
+     *
+     * Um achado cujo token JÁ EXISTE é uma troca de uma linha; um valor que o sistema não nomeia é uma
+     * decisão de design. Ordenar assim faz o teto cortar a conversa difícil em vez do conserto fácil -
+     * e medido no repo do dono, sem ordem nenhuma as 200 anotações saíram todas de um diretório gerado.
+     */
+    const ranked = [...d.findings].sort((a, b) => a.token && !b.token ? -1 : b.token && !a.token ? 1 : 0);
+    for (const f of ranked.slice(0, cap)) {
+        const title = f.token
+            ? "Token exists for this value"
+            : "Design value not in the system";
+        /** `::` e `%` quebram o parser do GitHub, e uma anotação que não parseia desaparece calada. */
+        const clean = (s) => s
+            .replace(/%/g, "%25")
+            .replace(/\r/g, "%0D")
+            .replace(/\n/g, "%0A")
+            .replace(/::/g, ":");
+        out.push(`::warning file=${f.file},line=${f.line},title=${clean(title)}::${clean(messageFor(f))}`);
+    }
+    if (d.findings.length > cap)
+        out.push(`::notice::${d.findings.length - cap} more findings are in the report - annotations are capped at ${cap} so the log stays readable. Run \`npx synthesisui doctor --verbose\` locally for all of them.`);
+    return out;
+}
+/**
+ * SARIF 2.1.0, para quem já tem um pipeline de qualidade de código.
+ *
+ * É o formato que o code-scanning do GitHub, o SonarQube e as ferramentas de segurança já ingerem -
+ * então o achado entra na mesma caixa de entrada em que o time já olha, em vez de exigir uma nova.
+ * Mínimo e válido: `runs[].tool`, `results[]` com `ruleId`, `level`, `message`, `locations`.
+ */
+export function sarifOf(d, cli) {
+    const rules = [
+        {
+            id: "synthesisui/token-exists",
+            shortDescription: {
+                text: "A design value written by hand that the system already names",
+            },
+            help: {
+                text: "The project's own design system declares a token with this exact value. Using the literal means a later change to the token will not reach this line.",
+            },
+        },
+        {
+            id: "synthesisui/unnamed-value",
+            shortDescription: {
+                text: "A design value the system has no name for",
+            },
+            help: {
+                text: "Nothing in the system holds this value. Either it belongs in the system - file a token request - or it is deliberately one-off, which is a decision worth writing down.",
+            },
+        },
+    ];
+    return JSON.stringify({
+        $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "SynthesisUI doctor",
+                        ...(cli ? { version: cli } : {}),
+                        informationUri: "https://www.synthesisui.com",
+                        rules,
+                    },
+                },
+                results: d.findings.map((f) => ({
+                    ruleId: f.token
+                        ? "synthesisui/token-exists"
+                        : "synthesisui/unnamed-value",
+                    /** `warning` sempre: quem reprova é a catraca, não o achado. */
+                    level: "warning",
+                    message: { text: messageFor(f) },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: f.file },
+                                region: { startLine: f.line, snippet: { text: f.excerpt } },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    }, null, 1);
+}
+/** O veredito da catraca em texto, para o log do CI - e ele lidera pela boa notícia. */
+export function describeVerdict(v) {
+    const lines = [];
+    if (v.incomparable) {
+        lines.push(`Baseline not comparable: ${v.incomparable}.`);
+        return lines;
+    }
+    lines.push(`Drift ${v.drift.was} → ${v.drift.now}${v.phantoms.was || v.phantoms.now ? ` · phantom tokens ${v.phantoms.was} → ${v.phantoms.now}` : ""}.`);
+    if (v.improved > 0)
+        lines.push(`${v.improved} file${v.improved === 1 ? "" : "s"} improved since the baseline.`);
+    if (v.regressed.length === 0) {
+        lines.push("Nothing regressed. The ratchet holds.");
+        return lines;
+    }
+    lines.push(`${v.regressed.length} file${v.regressed.length === 1 ? "" : "s"} got worse than the baseline:`);
+    for (const r of v.regressed.slice(0, 10))
+        lines.push(`  ${r.file}: ${r.was} → ${r.now}`);
+    lines.push("Fix those lines, or accept them into the baseline on purpose: npx synthesisui doctor --write-baseline");
+    return lines;
+}

package/dist/index.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
 import { advise } from "./commands/advise.js";
+import { ci } from "./commands/ci.js";
 import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
 import { connect } from "./commands/connect.js";
@@ -17,6 +18,7 @@ import { login } from "./commands/login.js";
 import { mcp } from "./commands/mcp.js";
 import { refit } from "./commands/refit.js";
 import { request } from "./commands/request.js";
+import { status } from "./commands/status.js";
 import { sync } from "./commands/sync.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
@@ -44,7 +46,7 @@ Usage - governance (deterministic, FREE):
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
   synthesisui import [--scope <p>] [--usage <p>]  read what you already have and make it a system
                                            your agent follows - without touching your CSS
-  synthesisui connect                      wire your agent: the check as an editor hook, the system
+  synthesisui connect [--ci]                      wire your agent: the check as an editor hook, the system
                                            as MCP tools, and a contract that stops repeating itself
   synthesisui doctor [paths…] [--verbose]  audit for DRIFT: every design value written by hand, the
                                            token your system already has for it, coherence, and the
@@ -58,6 +60,12 @@ Usage - governance (deterministic, FREE):
                                            reusing the reading you already authored, plus the local
                                            record - checks, fixes, open requests (--record-only skips
                                            the measurement, --yes skips the overwrite question)
+  synthesisui doctor --fix [--dry]          replace every hand-written value your system already
+                                           names with the token, in place
+  synthesisui status                       where this project stands: installed version, last check,
+                                           the ratchet, open requests - local first, no login needed
+  synthesisui ci [--write]                 the two steps that put drift in your PR - annotations on
+                                           the line, and a ratchet that fails only on regression
   synthesisui hook                         the check itself; installed by connect, run by your editor
   synthesisui mcp                          the system as tools; installed by connect, run by your agent
 
@@ -229,6 +237,7 @@ async function main() {
                 version: CLI_VERSION,
                 hook: flags.hook !== false,
                 mcp: flags.mcp !== false,
+                ci: flags.ci === true,
             });
             return;
         case "hook":
@@ -252,8 +261,31 @@ async function main() {
                 // written last week does not break.
                 verbose: flags.verbose === true || flags.all === true,
                 laws: flags.laws === true,
+                /**
+                 * A PIPELINE - ver `ci-format.ts`. `--format` decide a língua, `--baseline` decide o que
+                 * reprova: sem ele nada reprova por dívida herdada, com ele reprova só a regressão.
+                 */
+                ...(flags.format === "github" || flags.format === "sarif"
+                    ? { format: flags.format }
+                    : {}),
+                ...(typeof flags.baseline === "string"
+                    ? { baseline: flags.baseline }
+                    : {}),
+                ...(flags.baseline === true ? { compareBaseline: true } : {}),
+                ...(flags.fix === true ? { fix: true } : {}),
+                ...(flags.dry === true ? { dry: true } : {}),
+                ...(flags["write-baseline"] === true ? { writeBaseline: true } : {}),
+                cli: CLI_VERSION,
             });
             break;
+        case "status":
+            /** A resposta do dia a dia no terminal - ver `commands/status.ts`. Local primeiro. */
+            await status({ dir, registry, cli: CLI_VERSION });
+            break;
+        case "ci":
+            /** A governança dentro do PR - ver `commands/ci.ts`. Imprime, ou grava com `--write`. */
+            await ci({ dir, write: flags.write === true });
+            break;
         case "gaps":
             /**
              * O LEDGER JÁ ESTÁ NO CENSO - isto não mede nada, tria.

package/dist/skill-import.js

@@ -11,8 +11,8 @@
  * CLI no longer has.
  */
 export const IMPORT_SKILL = `---
-name: import-design-system
-description: Turn a codebase the user ALREADY has into a SynthesisUI design system. Use when someone points at an existing repo, app or component library and asks to import it, adopt it, bring it in, or "make a design system from this" (e.g. "/import-design-system", "importa o meu packages/ui", "turn this app into a design system"). Drives the full pipeline - census → your reading → import → v2 proposal - and answers the questions arithmetic cannot.
+name: sui-import-ds
+description: Turn a codebase the user ALREADY has into a SynthesisUI design system. Use when someone points at an existing repo, app or component library and asks to import it, adopt it, bring it in, or "make a design system from this" (e.g. "/sui-import-ds", "importa o meu packages/ui", "turn this app into a design system"). Drives the full pipeline - census → your reading → import → v2 proposal - and answers the questions arithmetic cannot.
 ---
 
 # Import Design System
@@ -1287,4 +1287,4 @@ Say so if it comes up, rather than implying otherwise:
   link and check.
 `;
 /** Where it lands in the consumer's repo. */
-export const IMPORT_SKILL_PATH = ".claude/skills/import-design-system/SKILL.md";
+export const IMPORT_SKILL_PATH = ".claude/skills/sui-import-ds/SKILL.md";