synthesisui 0.16.204 → 0.16.205

package/dist/commands/align.js

@@ -2,8 +2,10 @@ 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 { isOlderCli } from "../cli-version.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
+import { CHECKER_SINCE, MATERIALISER_SINCE } from "../install-marks.js";
 import { measuredScope } from "../measured-scope.js";
 import { READER } from "../reader-version.js";
 /**
@@ -59,6 +61,28 @@ async function credentials(home) {
  *
  * Separada de propósito: ela é a que sempre roda, e é testável sem servidor nenhum.
  */
+/**
+ * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
+ *
+ * `installed` é a versão que escreveu a coisa (a pasta, ou o pin do hook); `running` é o CLI de hoje;
+ * `since` é a última versão em que aquilo mudou de verdade - ver `install-marks.ts`.
+ *
+ * As duas condições, e nenhuma delas basta sozinha:
+ *
+ *     o que está instalado é ANTERIOR à última mudança    senão `upgrade` reescreve bytes idênticos
+ *     o CLI de hoje já ALCANÇOU essa mudança              senão `upgrade` escreve a mesma coisa velha
+ *
+ * A segunda é a que quase escapou: quem roda um CLI antigo com uma pasta da mesma época não ganha
+ * nada com `upgrade` - o comando usa o CLI que ela tem. Mandar rodar ali é gastar a atenção dela num
+ * comando que não pode mudar nada, e o caminho de verdade é outro (`connect`).
+ */
+function behind(installed, running, since) {
+    if (!installed || !running)
+        return null;
+    if (!isOlderCli(installed, since))
+        return null;
+    return isOlderCli(running, since) ? null : installed;
+}
 export async function localMisalignments(root, 
 /**
  * `home` é injetável porque a SESSÃO mora nele e não no repo - e uma verificação que lê o home da
@@ -147,8 +171,12 @@ opts = {}) {
      * 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.
+     *
+     * COMPARA `MATERIALISER_SINCE`, E NÃO A STRING DO CLI - a mesma correção que o `READER` recebeu do
+     * lado da medição, e que este lado não tinha. Medido: de 79 bumps, 10 mudaram o que vai para esta
+     * pasta. Os outros 69 mandavam rodar `upgrade` para reescrever bytes idênticos.
      */
-    const folderBehind = cli && lock.cli && lock.cli !== cli ? lock.cli : null;
+    const folderBehind = behind(lock.cli, cli, MATERIALISER_SINCE);
     /**
      * O HOOK, MEDIDO NELE MESMO - e não pelo `.lock`, que é um proxy que se move sozinho.
      *
@@ -159,9 +187,13 @@ opts = {}) {
      *
      * `pinnedHookVersion` devolve `null` numa instalação local, onde o hook segue o `node_modules` e
      * nunca está atrás por si.
+     *
+     * E COMPARA `CHECKER_SINCE` pelo mesmo motivo da linha acima: o hook estar pinado numa versão
+     * anterior só importa quando o checador de hoje veria algo que o pinado não vê. De 79 bumps, 34
+     * mudaram o checador - nos outros 45 esta linha acusava um pin que se comporta igual.
      */
     const pinned = await pinnedHookVersion(root).catch(() => null);
-    const hookBehind = cli && pinned && pinned !== cli ? pinned : null;
+    const hookBehind = behind(pinned, cli, CHECKER_SINCE);
     /**
      * UMA CAUSA, UMA LINHA - e as duas metades nomeadas dentro dela.
      *

package/dist/install-marks.js

@@ -0,0 +1,66 @@
+/**
+ * QUANDO O QUE ESTÁ INSTALADO NESTA MÁQUINA FICOU PARA TRÁS DE VERDADE.
+ *
+ * Duas coisas do CLI vivem no repositório de quem usa e NÃO se atualizam sozinhas: os arquivos que o
+ * `add` escreve em `_synthesisui/ds/<slug>`, e o hook que roda depois de cada escrita do agente - que
+ * fica pinado de propósito, porque comportamento que muda sob você é indebugável.
+ *
+ * O `align` avisava sobre as duas comparando a STRING DA VERSÃO do CLI. É a mesma armadilha que o
+ * `READER` já tinha resolvido do lado da medição, e que ninguém tinha aplicado aqui. Medido em 11/08
+ * sobre os 79 últimos bumps deste repositório:
+ *
+ *     mudaram o que o `upgrade` ESCREVE     20 (25%)
+ *     mudaram o que o HOOK roda             34 (43%)
+ *     não mudaram NENHUM dos dois           27 (34%)
+ *
+ * Um terço dos bumps mandava a pessoa rodar `upgrade` por absolutamente nada, com as DUAS linhas na
+ * tela. E o custo não é o incômodo: um alarme que toca quando está tudo certo é o alarme que ela
+ * aprende a pular no dia em que ele estiver dizendo a verdade.
+ *
+ * O dono nomeou isso em 11/08 pela pergunta certa - *"por que foi necessário atualizar o CLI dessa
+ * vez?"* - sobre um bump que mexeu no `clean` e numa frase, e não tocou a pasta de ninguém.
+ *
+ * ESTAS MARCAS SÃO VERSÕES, e não números de série, por um motivo prático: elas comparam contra o que
+ * já está gravado no `.lock` e no hook dos installs QUE JÁ EXISTEM. Um contador novo precisaria ser
+ * escrito primeiro, e o primeiro contato com ele acusaria todo mundo uma vez - exatamente o alarme à
+ * toa que isto remove.
+ *
+ * A família inteira, e o que cada uma alcança:
+ *
+ *     READER              a medição na máquina dela         ->  npx synthesisui sync
+ *     COMPILER            o CSS de uma versão já instalada  ->  npx synthesisui connect
+ *     INTERPRETATION      a nossa metade, no servidor       ->  sem comando
+ *     MATERIALISER_SINCE  os arquivos da pasta dele         ->  npx synthesisui upgrade
+ *     CHECKER_SINCE       o hook que lê o que o agente faz  ->  npx synthesisui upgrade
+ *
+ * COMO SE MEXE NELAS: não se lembra, o spec cobra. `install-marks.spec.ts` guarda o fingerprint dos
+ * arquivos que decidem cada marca e fica vermelho quando eles mudam sem a marca acompanhar. O
+ * `READER` nasceu sem esse portão em 07/08 e a disciplina falhou na primeira oportunidade que teve:
+ * `d90260cb` acrescentou 47 linhas a `anatomy-from-sketch.ts` - uma mudança que muda o censo dos
+ * mesmos arquivos - e o `READER` continua em 1 até hoje. Uma marca mantida à mão sem portão é uma
+ * marca errada esperando a hora.
+ */
+/**
+ * A ÚLTIMA VERSÃO EM QUE O QUE O `upgrade` ESCREVE NO REPO DELE MUDOU.
+ *
+ * Um install escrito por um CLI ANTERIOR a esta está velho de verdade; escrito por qualquer versão a
+ * partir daqui, tem exatamente os mesmos bytes que o `upgrade` de hoje escreveria.
+ *
+ * CONJUNTO COMPLETO, e a primeira tentativa errou por incompleta: `add.ts` chama `claude-md.ts`,
+ * `fonts.ts`, `rule-filter.ts` e `stack.ts`, e o `upgrade.ts` escreve o `UPGRADE.md` por conta
+ * própria. Deixar qualquer um de fora produz FALSO NEGATIVO - a marca fica parada enquanto o
+ * conteúdo anda, e o alarme cala no dia em que ele é verdade. Foi exatamente o que quase aconteceu:
+ * o `claude-md.ts` mudou em 0.16.204 e o conjunto de quatro arquivos não via.
+ *
+ * O resto da pasta vem do servidor e já é coberto pela versão do DS.
+ */
+export const MATERIALISER_SINCE = "0.16.204";
+/**
+ * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
+ *
+ * O hook fica pinado, então ele só anda quando alguém roda `upgrade`. Isso é de propósito - mas só
+ * vale a pena dizer quando o checador de hoje veria algo que o pinado não vê.
+ *
+ * Os arquivos que decidem: `doctor/` inteiro e `commands/hook.ts`.
+ */
+export const CHECKER_SINCE = "0.16.202";

package/package.json

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