synthesisui 0.16.178 → 0.16.180

package/dist/commands/add.js

@@ -25,23 +25,45 @@ import { detectStack } from "../stack.js";
  *
  * Escrito uma vez e nunca reescrito: um arquivo que alguém ajustou é decisão dele.
  */
+/**
+ * O que NÃO é do repositório: a medição e o registro local. Ambos são reescritos por inteiro a cada
+ * rodada e conflitariam em todo merge; o `.ledger-sent` descreve este clone e mais nada.
+ */
+const IGNORED = [
+    "census.json",
+    "ledger.jsonl",
+    ".ledger-sent",
+    "not-expressed.md",
+];
+const IGNORE_HEADER = "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +
+    "# clone is governed; the measurement and the local record are not, because\n" +
+    "# both are rewritten in full on every run and would conflict on every merge.\n";
 async function writeGovernanceIgnore(projectRoot) {
     const path = join(projectRoot, "_synthesisui", ".gitignore");
-    try {
-        await access(path);
+    const existing = await readFile(path, "utf8").catch(() => null);
+    /**
+     * O ARQUIVO DIZ "Managed by synthesisui", E ELE PRECISA SER.
+     *
+     * Isto saía na primeira linha quando o arquivo já existia, então ele era escrito UMA vez e nunca
+     * mais. A consequência aparece na primeira vez que a gente acrescenta um registro local: em 07/08
+     * nasceu o `.ledger-sent`, e todo repositório que já tinha o `.gitignore` passaria a commitar um
+     * cursor que descreve a máquina de UMA pessoa. Um arquivo que se declara gerenciado e não é
+     * reconciliado é uma promessa quebrada com o time de alguém.
+     *
+     * ACRESCENTA, NUNCA REMOVE: uma linha que a pessoa escreveu ali é decisão dela, e some no dia em
+     * que a gente reescrevesse o arquivo inteiro. E só grava quando falta algo - um comando que sempre
+     * produz diff é um comando que o time para de rodar.
+     */
+    if (existing == null) {
+        await writeFile(path, `${IGNORE_HEADER}${IGNORED.map((l) => `${l}\n`).join("")}`, "utf8");
         return;
     }
-    catch {
-        // não existe - escrever
-    }
-    await writeFile(path, "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +
-        "# clone is governed; the measurement and the local record are not, because\n" +
-        "# both are rewritten in full on every run and would conflict on every merge.\n" +
-        "census.json\n" +
-        "ledger.jsonl\n" +
-        /** O cursor de envio descreve ESTE clone, não o repositório - ver `markSent`. */
-        ".ledger-sent\n" +
-        "not-expressed.md\n", "utf8");
+    const lines = new Set(existing.split("\n").map((l) => l.trim()));
+    const missing = IGNORED.filter((l) => !lines.has(l));
+    if (missing.length === 0)
+        return;
+    const sep = existing.endsWith("\n") ? "" : "\n";
+    await writeFile(path, `${existing}${sep}${missing.map((l) => `${l}\n`).join("")}`, "utf8");
 }
 /**
  * APAGA A PROSA QUE ESTA VERSÃO DEIXOU DE ESCREVER.

package/dist/commands/align.js

@@ -143,13 +143,14 @@ opts = {}) {
      * de hoje escreve `doctrine.json` e o de ontem materializava dois `.md` -, e o `upgrade` sai sem
      * fazer nada quando não há gap de versão, então nenhum comando alcançava aquele estado.
      *
-     * O `connect` conserta na hora (ver `refreshInstall`), e esta linha existe para quem ainda não
-     * rodou: a verificação de abertura é o único lugar que fala sem ser perguntado.
+     * O `upgrade` conserta, e esta linha existe para quem ainda não rodou: a verificação de abertura é
+     * o único lugar que fala sem ser perguntado. Apontava `connect` até 07/08, quando o dono nomeou a
+     * incoerência - a palavra que significa atualizar era a única que não atualizava.
      */
     if (cli && lock.cli && lock.cli !== cli)
         out.push({
             says: `the files under _synthesisui/ds/${lock.slug} were written by CLI ${lock.cli} and you are running ${cli} - the design system's version has not changed, but what this CLI writes into that folder has.`,
-            run: "npx synthesisui connect",
+            run: "npx synthesisui upgrade",
         });
     if (cli && lock.version == null)
         out.push({
@@ -208,7 +209,11 @@ export async function versionBehind(root, opts = {}) {
         body.compiler !== (lock.compiler ?? null))
         return {
             says: `the css for "${lock.slug}" v${lock.version} is compiled differently now - same version, same document, a fix on our side. The files in this repo were written before it.`,
-            run: "npx synthesisui connect",
+            /**
+             * `upgrade` E NÃO `connect` - a palavra que significa atualizar passa a ser a que atualiza.
+             * Ver a redistribuição em `upgrade`: `connect` volta a ser a fiação, uma vez.
+             */
+            run: "npx synthesisui upgrade",
         };
     /**
      * AS REGRAS MUDARAM - e nem a versão nem o CLI diziam isso.
@@ -222,7 +227,7 @@ export async function versionBehind(root, opts = {}) {
     if (body.rulesStamp && body.rulesStamp !== (lock.rules ?? null))
         return {
             says: `the rules that govern "${lock.slug}" changed since this repo materialized them - your agent reads the copy on disk, so it is still following the previous set.`,
-            run: "npx synthesisui connect",
+            run: "npx synthesisui upgrade",
         };
     return null;
 }
@@ -245,9 +250,11 @@ from = "session") {
     if (items.length === 0)
         return "";
     return [
-        from === "shell"
-            ? "This repo is out of alignment with the design system that governs it:"
-            : "Before this session starts, this environment is out of alignment with the design system that governs it:",
+        from === "after"
+            ? "Still out of alignment:"
+            : from === "shell"
+                ? "This repo is out of alignment with the design system that governs it:"
+                : "Before this session starts, this environment is out of alignment with the design system that governs it:",
         ...items.map((m) => `  - ${m.says}${m.run ? `\n      ${m.run}` : ""}`),
     ].join("\n");
 }
@@ -258,8 +265,15 @@ from = "session") {
  * ser lido. E nunca falha: um ambiente que não dá para verificar não pode impedir alguém de
  * trabalhar.
  */
-export async function align(opts) {
-    const root = resolve(opts.dir ?? process.cwd());
+/**
+ * TUDO QUE ESTÁ FORA DE ALINHO, local e remoto - a lista, sem imprimir nada.
+ *
+ * Extraída para os comandos que TERMINAM poderem fechar dizendo o que ainda falta. Sem isso, cada um
+ * teria a própria versão da pergunta: o `status` já tinha, lendo `.lock`, ledger e requests por conta
+ * própria e sem saber de defasagem nenhuma - duas portas para a mesma sala, e uma delas cega
+ * (dono, 07/08).
+ */
+export async function misalignments(root, opts = {}) {
     const items = await localMisalignments(root, {
         ...(opts.cli ? { cli: opts.cli } : {}),
     }).catch(() => []);
@@ -267,6 +281,27 @@ export async function align(opts) {
     const remote = await versionBehind(root).catch(() => null);
     if (remote)
         items.push(remote);
+    return items;
+}
+/**
+ * A CAUDA DE UM COMANDO QUE TERMINOU: o que ainda está fora, ou nada.
+ *
+ * Muda quando não falta nada, que é o caso normal e é o que a mantém legível. Ela existe porque
+ * `sync`, `connect` e `upgrade` deixavam a pessoa sem saber se tinha acabado - e a resposta exigia
+ * lembrar de um sexto comando (dono, 07/08).
+ */
+export async function reportWhatIsLeft(root, opts = {}) {
+    const items = await misalignments(root, opts).catch(() => []);
+    if (items.length === 0)
+        return;
+    console.log("");
+    console.log(describeMisalignments(items, "after"));
+}
+export async function align(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const items = await misalignments(root, {
+        ...(opts.cli ? { cli: opts.cli } : {}),
+    });
     const text = describeMisalignments(items, opts.shell ? "shell" : "session");
     if (text)
         console.log(text);

package/dist/commands/connect.js

@@ -8,6 +8,7 @@ import { hasHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "../skill-import.js";
 import { INIT_SKILL, INIT_SKILL_PATH } from "../skill-init.js";
 import { add } from "./add.js";
+import { reportWhatIsLeft } from "./align.js";
 import { ci } from "./ci.js";
 import { MCP_TOOL_COUNT } from "./mcp.js";
 /**
@@ -343,6 +344,7 @@ export async function connect(opts) {
             console.log(body('A project MCP server needs approving once; say yes when it asks. Then "/mcp" lists synthesisui.'));
         }
     }
+    await reportWhatIsLeft(root, { cli: opts.version });
     if (wired.command.startsWith("npx synthesisui@")) {
         console.log("");
         console.log(body("The hook runs through npx, which costs about 0.7s per edit. Adding"));

package/dist/commands/status.js

@@ -4,6 +4,7 @@ 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";
+import { misalignments } from "./align.js";
 /**
  * `synthesisui status` - a resposta do dia a dia, no terminal.
  *
@@ -143,7 +144,28 @@ export async function status(opts) {
     if (remote.publishedCli && opts.cli && remote.publishedCli !== opts.cli) {
         console.log("");
         console.log(body(`Your CLI is ${opts.cli} and ${remote.publishedCli} is published - a newer reader sees styles this one cannot.`));
-        console.log(paint.blue(snippet(["npx synthesisui@latest connect"])));
+        console.log(paint.blue(snippet(["npx synthesisui@latest upgrade"])));
+    }
+    /**
+     * O QUE ESTÁ FORA DE ALINHO - e este comando era CEGO para isso.
+     *
+     * `status` nasceu antes do `align` e lia `.lock`, ledger e requests por conta própria: duas portas
+     * para a mesma sala, e a que a pessoa digita era a que não sabia de defasagem. Aqui ele passa a
+     * usar a mesma medição do gancho, então `align` deixa de ser algo que alguém precisa conhecer -
+     * ele continua existindo, chamado pelo `SessionStart` e pelo terminal (dono, 07/08).
+     */
+    const off = await misalignments(root, opts.cli ? { cli: opts.cli } : {});
+    console.log("");
+    if (off.length === 0) {
+        console.log(section("In step"));
+        console.log(body(paint.faint("Nothing here is behind the system that governs it - version, css, rules and the measurement all line up.")));
+        return;
+    }
+    console.log(section("Out of step"));
+    for (const item of off) {
+        console.log(body(item.says));
+        if (item.run)
+            console.log(paint.blue(snippet([item.run])));
     }
 }
 /** "2 hours ago", sem dependência - e `Invalid Date` nunca chega à tela. */

package/dist/commands/sync.js

@@ -6,6 +6,7 @@ import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } fr
 import { measuredScope, rememberScope } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
+import { reportWhatIsLeft } from "./align.js";
 import { resolveReadParts, siblingProjects, takeCensus } from "./import.js";
 /**
  * What each decision means ON THIS MACHINE - the card decides, the sync
@@ -146,6 +147,15 @@ export async function sync(opts) {
     console.log("");
     console.log(body(`The record lives on your system's overview:`));
     console.log(body(`    ${base}/dashboard/mine/${slug}`));
+    /**
+     * O QUE AINDA FALTA, no fim do comando que a pessoa acabou de rodar.
+     *
+     * `sync` e `align` respondem perguntas diferentes e as duas palavras se pareciam demais (dono,
+     * 07/08). Fundir era impossível - um escreve e o outro roda sozinho a cada sessão -, mas terminar
+     * dizendo o que sobrou resolve o que a dúvida realmente era: acabou ou não? Mudo quando não sobrou
+     * nada, que é o caso normal.
+     */
+    await reportWhatIsLeft(root);
 }
 /**
  * MEDE DE NOVO, AVISA, E ENVIA - o corpo do `sync` que faz um leitor novo chegar num sistema.

package/dist/commands/upgrade.js

@@ -7,6 +7,7 @@ import { body, section, snippet } from "../output.js";
 import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
+import { reportWhatIsLeft } from "./align.js";
 import { doctor } from "./doctor.js";
 /**
  * The highest `v<n>` below `installed` among the folder names given, or the one
@@ -80,9 +81,54 @@ async function rewriteBrief(slug, slugDir, from, to) {
  *    to `_synthesisui/ds/<slug>/UPGRADE.md` - the migration brief your agent
  *    walks to update the app (breaking changes first).
  */
-export async function upgrade(slug, opts) {
+/**
+ * O ÚNICO SISTEMA INSTALADO AQUI, quando ninguém nomeou um.
+ *
+ * O slug era obrigatório porque `upgrade` era um comando ocasional - só valia quando saía versão
+ * nova. Ao virar O comando de atualizar (ver abaixo), ele passa a ser rodado toda semana, e exigir um
+ * nome que a pessoa não decorou é atrito por nada. Com mais de um sistema o nome volta a ser
+ * necessário, e aí a mensagem lista os que existem. Mesma regra que o `sync` já segue.
+ */
+/**
+ * O QUE ESTÁ DEFASADO NESTA INSTALAÇÃO, em uma frase - ou `null` quando nada está.
+ *
+ * As três formas de ficar para trás sem a versão andar. `?meta=1` custa algumas centenas de bytes, e
+ * falhar nele não pode custar o comando: sem resposta, a leitura honesta é "não sei", e não se
+ * rematerializa por suposição.
+ */
+async function staleInstall(root, slug, version, base, cli) {
+    const lock = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    if (!lock)
+        return null;
+    const res = await fetch(`${base}/api/registry/ds/${slug}?version=${version}&meta=1`).catch(() => null);
+    const meta = res?.ok
+        ? (await res.json().catch(() => null))
+        : null;
+    const why = [];
+    if (meta?.compiler != null && meta.compiler !== (lock.compiler ?? null))
+        why.push("the css is compiled differently now");
+    if (meta?.rulesStamp != null && meta.rulesStamp !== (lock.rules ?? null))
+        why.push("the rules that govern it changed");
+    if (cli && lock.cli && lock.cli !== cli)
+        why.push(`these files were written by CLI ${lock.cli}`);
+    return why.length > 0 ? `${why.join(", ")} - re-materializing` : null;
+}
+async function theOnlyInstalled(root) {
+    const dsDir = join(root, "_synthesisui", "ds");
+    const entries = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
+    const slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    if (slugs.length === 1)
+        return slugs[0];
+    if (slugs.length === 0)
+        throw new RegistryError("No design system is installed here - run `synthesisui add <slug>` first.");
+    throw new RegistryError(`More than one system is installed here (${slugs.join(", ")}) - name the one to update: \`synthesisui upgrade <slug>\`.`);
+}
+export async function upgrade(asked, opts) {
     const base = resolveRegistry(opts.registry);
     const root = opts.dir ?? process.cwd();
+    const slug = asked ?? (await theOnlyInstalled(root));
     const slugDir = join(root, "_synthesisui", "ds", slug);
     // installed version - upgrade only makes sense over an existing install
     let installed;
@@ -98,8 +144,33 @@ export async function upgrade(slug, opts) {
     console.log(`→ checking "${slug}" (installed: v${installed}) …`);
     const latest = await fetchDesignSystem(base, slug);
     if (latest.version === installed) {
+        /**
+         * MESMA VERSÃO NÃO SIGNIFICA EM DIA - e essa confusão era a nossa, não da pessoa.
+         *
+         * `upgrade` só agia sobre gap de VERSÃO. Mas o CSS é compilado a cada busca, as regras valem no
+         * instante em que são escritas, e os arquivos da pasta são escritos pelo CLI - três formas de
+         * ficar defasado sem a versão andar. Quem consertava isso era o `connect`, o que deixava a
+         * palavra que significa atualizar como a única que não atualizava (dono, 07/08).
+         *
+         * Então aqui ele rematerializa quando qualquer uma das três se moveu, e sai em silêncio quando
+         * nenhuma se moveu - que é o caso normal.
+         */
+        const drift = await staleInstall(root, slug, installed, base, opts.cli);
+        if (drift) {
+            console.log(`↻ ${slug} v${installed} - ${drift}`);
+            await add(slug, {
+                registry: opts.registry,
+                dir: root,
+                version: installed,
+                setupHints: false,
+                ...(opts.cli ? { cli: opts.cli } : {}),
+            });
+            await reportWhatIsLeft(root, opts.cli ? { cli: opts.cli } : {});
+            return;
+        }
         if (!opts.force) {
             console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+            await reportWhatIsLeft(root, opts.cli ? { cli: opts.cli } : {});
             return;
         }
         // The brief is a PHOTOGRAPH: written once, at the moment of the upgrade,
@@ -262,5 +333,6 @@ export async function upgrade(slug, opts) {
     ]));
     console.log("");
     console.log(body(`(rollback: synthesisui add ${slug} --version ${installed})`));
+    await reportWhatIsLeft(root, opts.cli ? { cli: opts.cli } : {});
     console.log("");
 }

package/dist/index.js

@@ -505,13 +505,12 @@ async function main() {
             break;
         }
         case "upgrade": {
-            const slug = args[0];
-            if (!slug) {
-                console.error("error: provide the slug - `synthesisui upgrade <slug>`");
-                process.exitCode = 1;
-                return;
-            }
-            await upgrade(slug, {
+            /**
+             * O SLUG É OPCIONAL desde 07/08: `upgrade` deixou de ser ocasional e virou O comando de
+             * atualizar, então exigir um nome que a pessoa não decorou é atrito por nada. Com mais de um
+             * sistema instalado, `theOnlyInstalled` recusa e lista os que existem.
+             */
+            await upgrade(args[0], {
                 registry,
                 dir,
                 cli: CLI_VERSION,

package/package.json

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