synthesisui 0.16.422 → 0.16.423

package/dist/commands/add.js

@@ -226,6 +226,19 @@ export async function add(slug, opts) {
      * componente em vez de por arquivo.
      */
     await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document)}\n`, "utf8");
+    /**
+     * E A CÓPIA DO QUE FOI INSTALADO, ao lado - é ela que faz o `sync` saber o que o agente dele
+     * mudou depois.
+     *
+     * O que o cliente ganha: o ciclo fecha sem uma ida à rede. Ele cola o prompt que a plataforma
+     * montou, o agente edita `design-system.json`, roda o `sync` - e o comando compara os dois
+     * arquivos aqui mesmo. Sem este baseline, a única forma de saber o que mudou seria perguntar
+     * ao servidor a cada `sync`, e um `sync` offline não conseguiria nem isso.
+     *
+     * O PONTO NA FRENTE não é estética: `.installed.json` é registro nosso desta pasta, como o
+     * `.lock`, e não um artefato que ele lê. Ver `local-edits.ts`.
+     */
+    await writeFile(join(versionDir, ".installed.json"), `${JSON.stringify(payload.document)}\n`, "utf8");
     /**
      * 3. O GUIA - e o catálogo só é COPIADO onde não há caminho de volta.
      *
@@ -471,8 +484,18 @@ export async function add(slug, opts) {
         ...Object.keys(payload.artifacts).filter((f) => !(f === "shadcn.css" && skipped)),
         "design-system.json",
         "GUIDE.md",
+        ".installed.json",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
+    /**
+     * O ARQUIVO NOVO É ANUNCIADO, e não plantado em silêncio - lei 8.
+     *
+     * Ele é versionado junto com o resto da pasta de propósito: assim um colega que clona tem o
+     * baseline e o `sync` dele funciona. Mas um arquivo de ponto que nasce sem aviso e reaparece
+     * no `git status` a cada sync é o atrito que a régua do `census.json` foi desenhada para
+     * evitar - e a diferença entre os dois é uma frase.
+     */
+    console.log(`  (.installed.json records what was installed, so \`sync\` can tell what you changed)`);
     /**
      * O QUE NÃO FOI ESCRITO, DITO EM VOZ ALTA - lei 8, e ela vale nos dois sentidos.
      *

package/dist/commands/sync.js

@@ -8,6 +8,7 @@ import { markSent, readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { sampledForUpload } from "../doctor/style-ledger.js";
 import { describeDelta, fingerprintReadings, readSyncMark, writeSyncMark, } from "../last-sync.js";
+import { installedVersion, landedLine, localEdits, readInstalledPair, sentLine, settleBaseline, } from "../local-edits.js";
 import { measuredScope, rememberScope } from "../measured-scope.js";
 import { fromCensus } from "../memory/observation.js";
 import { reportMeasurement } from "../memory/report.js";
@@ -551,6 +552,43 @@ export async function remeasure(args) {
             return;
         }
     }
+    /**
+     * O QUE ELE MUDOU NO DESIGN SYSTEM INSTALADO, lido do disco e sem rede.
+     *
+     * A comparação é contra `.installed.json`, a cópia que o `add` deixa ao lado. Um sistema
+     * instalado antes desta etapa não a tem, e aí o comando DIZ o que falta em vez de tratar o
+     * documento inteiro como mudado - ver `readInstalledPair`.
+     */
+    let edits = [];
+    let localDocument = null;
+    let localSaid = null;
+    {
+        const version = await installedVersion(root, slug);
+        /**
+         * UM ERRO INESPERADO AQUI É DITO, e não engolido. A primeira escrita caía em
+         * "not-installed" para qualquer exceção - um disco cheio, uma permissão, um link quebrado -
+         * e a saída ficava idêntica à de um repositório sem sistema instalado.
+         */
+        const pair = version
+            ? await readInstalledPair(root, slug, version).catch((error) => ({
+                kind: "unreadable",
+                where: `_synthesisui/ds/${slug}/v${version}`,
+                why: error instanceof Error ? error.message : String(error),
+            }))
+            : { kind: "not-installed" };
+        if (pair.kind === "pair") {
+            edits = localEdits(pair.installed, pair.local);
+            if (edits.length > 0)
+                localDocument = pair.local;
+            localSaid = sentLine(edits, slug);
+        }
+        else if (pair.kind === "unreadable") {
+            localSaid = `your local ${slug} could not be read, so nothing of it went up: ${pair.why}\n      ${pair.where}`;
+        }
+        else if (pair.kind === "no-baseline") {
+            localSaid = `we cannot tell what changed in your local ${slug}: ${pair.why}`;
+        }
+    }
     const res = await fetch(`${base}/api/registry/ds/${slug}/census`, {
         method: "POST",
         headers: {
@@ -568,6 +606,17 @@ export async function remeasure(args) {
             census: census.ledger
                 ? { ...census, ledger: sampledForUpload(census.ledger) }
                 : census,
+            /**
+             * E O QUE O AGENTE DELE MUDOU NOS ARQUIVOS DO DESIGN SYSTEM - a outra metade do ciclo.
+             *
+             * O prompt que a plataforma monta termina mandando rodar este comando, e até aqui ele
+             * media só o CÓDIGO dele: o design system instalado aparecia apenas para descobrir quais
+             * slugs existem. O documento só sobe quando há diferença de verdade contra o que o `add`
+             * instalou - sem edição, este campo não existe e nada muda do lado de lá.
+             */
+            ...(edits.length > 0 && localDocument
+                ? { document: localDocument, edits }
+                : {}),
         }),
     }).catch(() => null);
     if (!res?.ok) {
@@ -580,6 +629,20 @@ export async function remeasure(args) {
     console.log("");
     console.log(section("Sent"));
     console.log(body(`${out.written ?? 0} of ${out.total ?? 0} components written.`));
+    /**
+     * O QUE VEIO DOS ARQUIVOS DELE, DITO - e antes de qualquer outra nota, porque é a única parte
+     * desta saída que fala do trabalho que ELE acabou de fazer.
+     *
+     * Um "ok" mudo depois de um agente ter mexido em doze peças é pior que nenhuma saída: ele não
+     * tem como saber se o comando entendeu o trabalho, e roda de novo para conferir.
+     */
+    if (localSaid)
+        console.log(body(localSaid));
+    /** A única frase no passado, e ela vem DEPOIS da resposta do servidor. */
+    if (out.hisEdits?.applied)
+        console.log(body(landedLine(out.hisEdits.applied, slug)));
+    if (out.hisEdits?.refused)
+        console.log(body(paint.strong(`  ✕ your local changes were refused, and nothing of them was written: ${out.hisEdits.refused}`)));
     for (const note of out.notes ?? [])
         console.log(body(paint.faint(note)));
     /**
@@ -662,6 +725,27 @@ export async function remeasure(args) {
         ...(args.cli ? { cli: args.cli } : {}),
         readings: fingerprintReadings(census.components),
     };
+    /**
+     * E O BASELINE PASSA A SER O QUE ESTÁ NO DISCO - a metade que fecha o ciclo.
+     *
+     * Sem esta linha, todo `sync` reenviaria a mesma alteração para sempre, e o documento na
+     * plataforma ganharia uma revisão nova a cada rodada sem nada ter mudado. Só depois de o
+     * servidor ter aceitado: uma recusa mantém o baseline velho, para a próxima rodada tentar de
+     * novo em vez de esquecer o que ele fez.
+     */
+    /**
+     * A CONDIÇÃO É `applied`, e não "não recusou" - a diferença apaga o trabalho dele.
+     *
+     * Um servidor que responde 200 SEM o campo `hisEdits` é todo deploy anterior a esta etapa, e
+     * essa janela existe de verdade: o CLI é publicado antes de a plataforma subir. Com
+     * `!refused`, o CLI dava o baseline por assentado, o disco esquecia o que o agente fez, e a
+     * plataforma nunca tinha recebido. A alteração some dos dois lados.
+     */
+    if (out.hisEdits?.applied && localDocument) {
+        const version = await installedVersion(root, slug);
+        if (version)
+            await settleBaseline(root, slug, version, localDocument).catch(() => { });
+    }
     console.log(body(paint.faint(describeDelta(mark, await readSyncMark(root)))));
     await writeSyncMark(root, mark);
     /**

package/dist/install-marks.js

@@ -235,7 +235,7 @@
  * chama `wireAgent`, então rodar o comando é o caminho de volta - e ele só alarga a string que era
  * nossa, nunca um filtro que uma pessoa escreveu.
  */
-export const MATERIALISER_SINCE = "0.16.422";
+export const MATERIALISER_SINCE = "0.16.423";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/local-edits.js

@@ -0,0 +1,257 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** A forma mínima que faz de um objeto um design system - abaixo disto não há o que comparar. */
+function shapeOf(value) {
+    if (!value || typeof value !== "object")
+        return "it is not an object";
+    const doc = value;
+    if (!doc.meta || typeof doc.meta !== "object")
+        return "it has no `meta` - a design system always carries its name and slug";
+    if (!doc.foundations || typeof doc.foundations !== "object")
+        return "it has no `foundations` - a design system always carries its tokens";
+    return null;
+}
+async function readDocument(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            why: error instanceof Error ? error.message : "it is not valid JSON",
+        };
+    }
+    const wrong = shapeOf(parsed);
+    if (wrong)
+        return { ok: false, why: wrong };
+    return { ok: true, document: parsed };
+}
+/**
+ * QUAL VERSÃO ESTÁ MATERIALIZADA NESTE REPOSITÓRIO - a que o `.lock` registra.
+ *
+ * Ler a pasta `v*` mais alta seria adivinhar: um `add --version N` deixa as duas no disco, e o
+ * `.lock` é o que diz qual delas o repositório está usando. `null` quando não há install.
+ */
+export async function installedVersion(root, slug) {
+    try {
+        const raw = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8");
+        const lock = JSON.parse(raw);
+        return typeof lock.version === "number" ? lock.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** O par que a comparação precisa: o que foi instalado, e o que está no disco agora. */
+export async function readInstalledPair(root, slug, version) {
+    const dir = join(root, "_synthesisui", "ds", slug, `v${version}`);
+    const local = await readDocument(join(dir, "design-system.json"));
+    if (local === null)
+        return { kind: "not-installed" };
+    if (!local.ok)
+        return {
+            kind: "unreadable",
+            where: join(dir, "design-system.json"),
+            why: local.why,
+        };
+    const installed = await readDocument(join(dir, ".installed.json"));
+    if (installed === null)
+        return {
+            kind: "no-baseline",
+            /**
+             * O CAMINHO DE SAÍDA AVISA DO RISCO ANTES DO COMANDO.
+             *
+             * `add` reescreve `design-system.json` sem comparar nada. Mandar rodá-lo sem dizer isso
+             * apagaria, em silêncio, exatamente a edição que este recurso existe para preservar - e a
+             * pessoa teria seguido o passo que a plataforma recomendou.
+             */
+            why: `this install predates the file that tracks your edits, and \`add\` rewrites design-system.json. If you already edited it, copy it first (cp _synthesisui/ds/${slug}/v<n>/design-system.json /tmp/${slug}-before-add.json), then run \`npx synthesisui@latest add ${slug}\` once - every edit made after that comes up with the next sync.`,
+        };
+    if (!installed.ok)
+        return {
+            kind: "unreadable",
+            where: join(dir, ".installed.json"),
+            why: installed.why,
+        };
+    return { kind: "pair", installed: installed.document, local: local.document };
+}
+/** Achata fundação e motion em `caminho → valor`, na mesma gramática do documento. */
+function flatten(value, prefix, into) {
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, inner] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (typeof inner === "string" || typeof inner === "number")
+            into.set(path, String(inner));
+        else
+            flatten(inner, path, into);
+    }
+}
+/**
+ * O QUE NÃO VIAJA, DITO EM VOZ ALTA - lei 8, e a lista é curta de propósito.
+ *
+ * `meta` é a identidade do sistema (nome, slug, tagline): mudá-la é ato dela na plataforma, não
+ * do agente dele. `philosophy` e `analyses` são texto que a plataforma escreve e nenhum prompt
+ * pede para editar. Os três ficam fora porque não são decisão do código dele - e é por isso que
+ * a ausência deles aqui é uma escolha, e não um esquecimento.
+ */
+export const NOT_FROM_HIS_FILES = ["meta", "philosophy", "analyses"];
+const RECIPE_MAPS = [
+    ["components", "component"],
+    ["blocks", "block"],
+    ["layouts", "layout"],
+    ["charts", "chart"],
+];
+/**
+ * A PROCEDÊNCIA NÃO É UM TOKEN, e o mesmo defeito já custou uma sessão do outro lado.
+ *
+ * `foundations.source` guarda quem escreveu cada caminho. Sem esta linha, um carimbo mudado por
+ * um comando nosso apareceria como "o agente dele trocou um valor de design".
+ */
+function tokensOf(doc) {
+    const out = new Map();
+    const { source: _source, ...rest } = doc.foundations;
+    flatten(rest, "", out);
+    /**
+     * E TODO EIXO DE RAIZ QUE NÃO É RECEITA, varrido pelo que o documento TEM - e não por uma
+     * lista escrita à mão.
+     *
+     * A primeira escrita enumerava `foundations` e `motion`, e deixava de fora `icons` e
+     * `globals` - este último carrega a folha de projeto inteira, 107 declarações num cliente
+     * real. O agente editava, o `sync` dizia "nothing new", e a alteração morria no disco.
+     * Varrer o que existe faz um eixo NOVO do contrato entrar sozinho, em vez de esperar alguém
+     * lembrar.
+     */
+    const root = doc;
+    const recipes = new Set(RECIPE_MAPS.map(([key]) => key));
+    for (const key of Object.keys(root)) {
+        if (key === "foundations")
+            continue;
+        if (recipes.has(key))
+            continue;
+        if (NOT_FROM_HIS_FILES.includes(key))
+            continue;
+        flatten(root[key], key, out);
+    }
+    return out;
+}
+function fileOf(recipe) {
+    return recipe?.source?.file;
+}
+/**
+ * O QUE MUDOU ENTRE O QUE FOI INSTALADO E O QUE ESTÁ NO DISCO.
+ *
+ * Puro sobre os dois documentos. Uma receita conta como UMA alteração, e não uma por declaração:
+ * o que o cliente lê no terminal é "o agente mexeu no Button", e a lista de declarações mora no
+ * documento que sobe junto.
+ */
+export function localEdits(installed, local) {
+    const out = [];
+    const was = tokensOf(installed);
+    const now = tokensOf(local);
+    for (const path of [...new Set([...was.keys(), ...now.keys()])].sort()) {
+        const from = was.get(path);
+        const to = now.get(path);
+        if (from === to)
+            continue;
+        out.push({
+            what: path,
+            of: "token",
+            kind: from === undefined ? "added" : to === undefined ? "removed" : "changed",
+            ...(from !== undefined ? { from } : {}),
+            ...(to !== undefined ? { to } : {}),
+        });
+    }
+    for (const [key, of_] of RECIPE_MAPS) {
+        const before = installed[key];
+        const after = local[key];
+        const names = [
+            ...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]),
+        ].sort();
+        for (const name of names) {
+            const from = before?.[name];
+            const to = after?.[name];
+            if (from === undefined && to === undefined)
+                continue;
+            if (from !== undefined && to !== undefined) {
+                if (JSON.stringify(from) === JSON.stringify(to))
+                    continue;
+                const file = fileOf(to) ?? fileOf(from);
+                out.push({
+                    what: name,
+                    of: of_,
+                    kind: "changed",
+                    ...(file ? { file } : {}),
+                });
+                continue;
+            }
+            const file = fileOf(to ?? from);
+            out.push({
+                what: name,
+                of: of_,
+                kind: from === undefined ? "added" : "removed",
+                ...(file ? { file } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * QUANTAS LINHAS O TERMINAL NOMEIA ANTES DE DIZER QUANTAS SOBRARAM.
+ *
+ * Doze é o que cabe numa tela sem rolagem depois do resto da saída do `sync`, e o que não couber
+ * é DITO - uma lista cortada em silêncio faz doze alterações parecerem doze quando são quarenta.
+ */
+const NAMED = 12;
+/**
+ * O QUE O `sync` DIZ SOBRE O QUE ELE ENCONTROU NOS ARQUIVOS - nunca um "ok" mudo, e nunca uma
+ * afirmação de sucesso antes de o servidor responder.
+ *
+ * A primeira escrita dizia *"N changes from your files WENT UP"*, e ela era montada antes do
+ * envio: quando o servidor recusava, a saída afirmava sucesso numa linha e fracasso na seguinte,
+ * na mesma tela. Quem lê rápido carrega a primeira. Esta frase relata o que foi ENCONTRADO; quem
+ * diz que chegou é `landedLine`, depois da resposta.
+ */
+export function sentLine(edits, slug) {
+    if (edits.length === 0)
+        return `nothing new in ${slug} - the design system on this machine matches what the platform has`;
+    const head = `${edits.length} change${edits.length === 1 ? "" : "s"} found in your files, from ${slug}:`;
+    const lines = edits.slice(0, NAMED).map((edit) => {
+        const where = edit.file ? ` · ${edit.file}` : "";
+        const move = edit.from !== undefined && edit.to !== undefined
+            ? ` ${edit.from} → ${edit.to}`
+            : edit.kind === "added"
+                ? " (new)"
+                : edit.kind === "removed"
+                    ? " (gone)"
+                    : "";
+        return `      ${edit.what}${move}${where}`;
+    });
+    const rest = edits.length > NAMED ? [`      and ${edits.length - NAMED} more`] : [];
+    return [head, ...lines, ...rest].join("\n");
+}
+/**
+ * DEPOIS DE SUBIR, O BASELINE PASSA A SER O QUE ESTÁ NO DISCO - a metade que fecha o ciclo.
+ *
+ * Sem isto, todo `sync` reenviaria a mesma alteração para sempre e o documento na plataforma
+ * ganharia uma revisão nova a cada rodada, sem nada ter mudado. É a outra metade de A4, e ela
+ * mora aqui - e não no corpo do comando - para poder ser exercida por spec sem subir nada.
+ *
+ * SÓ DEPOIS DE O SERVIDOR TER ACEITADO: uma recusa mantém o baseline velho, para a próxima
+ * rodada tentar de novo em vez de esquecer o que ele fez.
+ */
+/** E a confirmação, depois de o servidor ter aceitado - a única frase no passado. */
+export function landedLine(applied, slug) {
+    return `${applied} change${applied === 1 ? "" : "s"} from your files went up to ${slug}`;
+}
+export async function settleBaseline(root, slug, version, document) {
+    await writeFile(join(root, "_synthesisui", "ds", slug, `v${version}`, ".installed.json"), `${JSON.stringify(document)}\n`, "utf8");
+}

package/package.json

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