synthesisui 0.16.140 → 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/commands/sync.js

@@ -3,8 +3,9 @@ import { join, resolve } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
-import { body, section } from "../output.js";
+import { body, paint, section } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
+import { resolveReadParts, takeCensus } from "./import.js";
 /**
  * What each decision means ON THIS MACHINE - the card decides, the sync
  * enacts. The web never touches the local file; this line is printed right
@@ -83,6 +84,19 @@ export async function sync(opts) {
         console.log(body("No installed system here, so there is nowhere to sync to."));
         return;
     }
+    /**
+     * A MEDIÇÃO NOVA, ANTES DO REGISTRO - e é isto que faz um conserto de leitura alcançar alguém.
+     *
+     * Um leitor novo do CLI precisa OLHAR o repo: o que a plataforma guarda é o censo, e o fonte fica
+     * aqui por decisão de privacidade. Essa passada é irredutível. O que era redutível é a cerimônia -
+     * até hoje "re-importar" significava a skill inteira, seis perguntas, e um agente reescrevendo 261
+     * anatomias que já estavam gravadas (dono, 05/08).
+     *
+     * Então: a plataforma devolve o que já foi decidido (o escopo e a leitura), o CLI mede com o leitor
+     * ATUAL, funde a leitura no censo fresco, AVISA o que seria reescrito, e envia. Sem entrevista.
+     */
+    if (!opts.recordOnly)
+        await remeasure({ root, base, token, slug, cli: opts.cli });
     // Verification first, so the snapshot never reports "open" about something
     // the installed css already delivers - a request closes because a machine
     // CHECKED, not because someone remembered to say so (dono, 29/07).
@@ -152,3 +166,133 @@ export async function sync(opts) {
     console.log(body(`The record lives on your system's overview:`));
     console.log(body(`    ${base}/dashboard/mine/${slug}`));
 }
+/**
+ * MEDE DE NOVO, AVISA, E ENVIA - o corpo do `sync` que faz um leitor novo chegar num sistema.
+ *
+ * A ordem é a lei aqui, e cada passo existe por um caso real:
+ *
+ *   1. a plataforma devolve o ESCOPO e a LEITURA já gravados. Sem isto, o `sync` teria que
+ *      perguntar de novo o que já foi decidido, e um agente reescreveria 261 anatomias.
+ *   2. mede com o leitor ATUAL - é o único passo que precisa estar nesta máquina, porque o fonte
+ *      dele não sai daqui.
+ *   3. funde a leitura gravada no censo fresco. A anatomia é do agente; a medição é nossa.
+ *   4. AVISA antes de enviar o que seria reescrito, e pergunta. Avisar depois de escrever não é
+ *      avisar.
+ *   5. envia para a rota que atualiza o RASCUNHO pelo slug - nada publicado se move.
+ */
+async function remeasure(args) {
+    const { root, base, token, slug } = args;
+    const head = await fetch(`${base}/api/registry/ds/${slug}/reading`, {
+        headers: { Authorization: `Bearer ${token}` },
+    }).catch(() => null);
+    if (!head?.ok) {
+        console.log(section("Sync"));
+        console.log(body(head
+            ? `The registry answered ${head.status} for this system's reading, so nothing was re-measured. The record below still travels.`
+            : "Could not reach the registry, so nothing was re-measured. The record below still travels."));
+        return;
+    }
+    const stored = (await head.json());
+    /**
+     * SEM CENSO GRAVADO NÃO HÁ O QUE REMEDIR CONTRA. Um sistema que nasceu da galeria não tem escopo
+     * nem leitura, e medir o repo dele produziria um censo de um projeto que ninguém mapeou para ele.
+     */
+    if (!stored.hasCensus) {
+        console.log(section("Sync"));
+        console.log(body(`"${slug}" did not come from an import, so there is no measurement to refresh. Import it first: npx synthesisui import`));
+        return;
+    }
+    console.log(section("Measuring your repository again"));
+    console.log(body(paint.faint(`${stored.scope ? `scope ${stored.scope}` : "the whole repo"} · the reading you already authored travels unchanged`)));
+    const census = await takeCensus(stored.scope ? join(root, stored.scope) : root, {
+        ...(stored.scope ? { scopeLabel: stored.scope } : {}),
+        ...(args.cli ? { cli: args.cli } : {}),
+        /** O `--usage` é EVIDÊNCIA e leva rótulo: sem ele o censo não sabe de que app o número veio. */
+        usage: (stored.usage ?? []).map((u) => ({
+            path: join(root, u),
+            label: u,
+        })),
+    }).catch(() => null);
+    if (!census) {
+        console.log(body("The measurement failed, so nothing was sent."));
+        return;
+    }
+    /** A LEITURA GRAVADA ENTRA NO CENSO FRESCO - ver a rota `reading`. */
+    if (stored.reading)
+        census.reading = stored.reading;
+    await resolveReadParts(census, root).catch(() => { });
+    /**
+     * O AVISO, ANTES DE ENVIAR. `edited` são as receitas que uma pessoa escreveu na tela; o cruzamento
+     * com o que acabou de ser medido é uma interseção de conjuntos, e é por isso que ele mora aqui em
+     * vez de virar um gêmeo da regra que vive na plataforma.
+     */
+    const slugOf = (name) => name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+    const arriving = new Set(Object.keys(census.looks ?? {}).map(slugOf));
+    /**
+     * SÓ O QUE ESTE ENVIO TOCA. Uma receita que a pessoa editou e que a medição não traz fica onde
+     * está, e listá-la seria assustar sem motivo - o erro mais fácil de cometer neste aviso.
+     */
+    const hit = (stored.draft?.edited ?? []).filter((e) => arriving.has(e.component));
+    if (hit.length > 0) {
+        console.log("");
+        console.log(section("You have an active draft"));
+        console.log(body(stored.draft?.warning ??
+            `${hit.length} of the ${stored.draft?.components ?? "?"} components in it were written on the screen, and this send would rewrite them.`));
+        console.log(body(paint.faint(hit
+            .slice(0, 6)
+            .map((e) => `${e.component}${e.at ? ` (${e.at.slice(0, 10)})` : ""}`)
+            .join(" · "))));
+        if (!(await askToOverwrite())) {
+            console.log(body("Nothing was sent. Your draft is untouched."));
+            return;
+        }
+    }
+    const res = await fetch(`${base}/api/registry/ds/${slug}/census`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ census }),
+    }).catch(() => null);
+    if (!res?.ok) {
+        console.log(body(res
+            ? `The registry answered ${res.status}. Nothing was written.`
+            : "Could not reach the registry. Nothing was written."));
+        return;
+    }
+    const out = (await res.json());
+    console.log("");
+    console.log(section("Sent"));
+    console.log(body(`${out.written ?? 0} of ${out.total ?? 0} components written.`));
+    for (const note of out.notes ?? [])
+        console.log(body(paint.faint(note)));
+    if (out.url)
+        console.log(body(out.url));
+}
+/**
+ * Pergunta uma vez, e só num terminal de verdade.
+ *
+ * Sem TTY a resposta é NÃO: uma invocação por script que sobrescreve trabalho de alguém porque
+ * ninguém estava lá para dizer não é o pior default possível. `--yes` é o caminho explícito.
+ */
+async function askToOverwrite() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question("  send anyway? [y/N]: ");
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}

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;
+}