synthesisui 0.16.179 → 0.16.182

package/dist/commands/align.js

@@ -1,6 +1,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { pinnedHookVersion } from "../agent-wiring.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
 import { measuredScope } from "../measured-scope.js";
@@ -143,13 +144,31 @@ 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",
+        });
+    /**
+     * O HOOK, MEDIDO NELE MESMO - e não pelo `.lock`, que é um proxy que se move sozinho.
+     *
+     * A linha acima compara o CLI que escreveu a PASTA. Desde que o `upgrade` passou a rematerializá-la
+     * (07/08), ela volta a bater sem que a fiação tenha sido refeita: o `.lock` dizia 0.16.180 e o
+     * `PostToolUse` continuava pinado em 0.16.178, com o `status` anunciando "In step". Um alarme
+     * desligado por um conserto parcial é pior que alarme nenhum.
+     *
+     * `pinnedHookVersion` devolve `null` numa instalação local, onde o hook segue o `node_modules` e
+     * nunca está atrás por si.
+     */
+    const pinned = await pinnedHookVersion(root).catch(() => null);
+    if (cli && pinned && pinned !== cli)
+        out.push({
+            says: `the check that runs after every write is pinned to CLI ${pinned} and you are running ${cli} - your agent's edits are being checked by an older reader than the one measuring this repo.`,
+            run: "npx synthesisui upgrade",
         });
     if (cli && lock.version == null)
         out.push({
@@ -208,7 +227,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 +245,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 +268,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 +283,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 +299,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.
  *
@@ -139,11 +140,45 @@ export async function status(opts) {
         : `${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.")));
-    /** E a distância até o leitor publicado, com o comando que a fecha - ver `sync`. */
-    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"])));
+    /**
+     * A DISTÂNCIA ATÉ O LEITOR PUBLICADO - e ela desce para o veredito, em vez de ser um parágrafo solto.
+     *
+     * Isto imprimia acima e o veredito abaixo dizia "In step", no MESMO comando: duas seções
+     * discordando com três linhas de distância (dono, 07/08). Um comando que se contradiz não é meio
+     * certo, é inutilizável - quem lê passa a não acreditar em nenhuma das duas.
+     *
+     * Não vira um item do `align`: o CLI subiu seis vezes num dia e nenhuma delas mudou um leitor, e a
+     * verificação de abertura tem que ficar muda nesses casos. Aqui é diferente - a pessoa PERGUNTOU.
+     */
+    const behindCli = remote.publishedCli && opts.cli && remote.publishedCli !== opts.cli
+        ? {
+            says: `your CLI is ${opts.cli} and ${remote.publishedCli} is published - a newer reader sees styles this one cannot.`,
+            run: "npx synthesisui@latest upgrade",
+        }
+        : null;
+    /**
+     * 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 } : {})),
+        ...(behindCli ? [behindCli] : []),
+    ];
+    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, the measurement and this CLI 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

@@ -1,5 +1,6 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { pinnedHookVersion, wireAgent } from "../agent-wiring.js";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
@@ -7,6 +8,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 +82,75 @@ 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;
+}
+/**
+ * A FIAÇÃO DO AGENTE, refeita quando ela ficou para trás.
+ *
+ * `upgrade` diz que traz para o dia tudo que está instalado aqui, e a pasta do DS é só metade: o hook
+ * `PostToolUse` é PINADO numa versão, então ele não anda sozinho. Em 07/08 o primeiro `upgrade` com o
+ * papel novo gravou `cli: 0.16.180` no `.lock` e deixou o hook em 0.16.178 - e como a verificação
+ * comparava o `.lock`, o `status` passou a dizer "In step" com a fiação duas versões atrás. Uma
+ * promessa pela metade que ainda por cima desliga o alarme.
+ *
+ * `wireAgent` é um merge idempotente: quando já está na versão certa, não escreve nada.
+ */
+async function rewireIfBehind(root, cli) {
+    if (!cli)
+        return;
+    const pinned = await pinnedHookVersion(root).catch(() => null);
+    if (!pinned || pinned === cli)
+        return;
+    await wireAgent(root, cli, { hook: true, mcp: true }).catch(() => null);
+    console.log(`↻ the check after every write moved from ${pinned} to ${cli}`);
+    console.log("  Reopen your editor session - hooks are read at startup.");
+}
+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 +166,34 @@ 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 rewireIfBehind(root, 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 +356,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.179",
+  "version": "0.16.182",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {