synthesisui 0.16.203 → 0.16.205

package/dist/claude-md.js

@@ -350,9 +350,10 @@ Only write something new when nothing in the manifest covers the purpose - and w
 say which entry you considered and why it did not fit, then FILE it while the reasoning is
 still yours: the \`request_component\` MCP tool, or \`npx synthesisui@latest request component
 --name "<name>" --for "<the use case>" --considered "<entries and why not>"\`. That queue is
-what the system's author works from - a refusal said only in chat evaporates. To review a
-component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
-apply it to real production pages unless asked.${selfCheck}`;
+what the system's author works from - a refusal said only in chat evaporates. If you want to eyeball a
+component on its own, an isolated scratch page is optional and never required - and if you make
+one, put it somewhere that does not become a route in this app, and delete it when you are done.
+Do not apply a component to real production pages unless asked.${selfCheck}`;
     const locale = await readInterfaceLanguage(projectRoot);
     const language = locale === null
         ? ""

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/commands/clean.js

@@ -1,4 +1,4 @@
-import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { body, section } from "../output.js";
 // The five SVGs create-next-app drops into public/. Filenames are specific
@@ -100,6 +100,35 @@ export async function clean(opts) {
             run: () => rm(readmePath),
         });
     }
+    /**
+     * O RASCUNHO QUE A NOSSA PRÓPRIA INSTRUÇÃO PEDIU - e que ninguém sabia remover.
+     *
+     * O `CLAUDE.md` que este CLI escreve sugere uma página isolada para olhar um componente sozinho,
+     * e o agente da pessoa a cria. Nada aqui a escreve, e nada aqui a apagava: ela ficava numa rota
+     * de VERDADE do app dela (`src/app/synthesisui-samples/<x>` é URL acessível), sem dono e sem
+     * saída, até alguém commitar sem querer. Encontrada no repo do dono em 11/08.
+     *
+     * É a mesma assimetria do bloco de shell: fácil de entrar, sem porta de saída. Aqui a saída é
+     * este comando, e ele mantém o contrato que já tem - seco por padrão, cada caminho nomeado antes
+     * de qualquer escrita, `--force` para aplicar.
+     *
+     * UMA AÇÃO POR PÁGINA, e não uma pela pasta: um destrutivo que anuncia um e remove seis faz mais
+     * do que diz, e essa lei já foi paga uma vez na poda de órfãos.
+     */
+    const samplesDir = join(appDir, "synthesisui-samples");
+    for (const entry of await readdir(samplesDir, {
+        withFileTypes: true,
+    }).catch(() => [])) {
+        if (!entry.isDirectory())
+            continue;
+        const p = join(samplesDir, entry.name);
+        actions.push({
+            verb: "remove",
+            path: rel(p),
+            why: "scratch page for eyeballing a component - nothing depends on it",
+            run: () => rm(p, { recursive: true }),
+        });
+    }
     if (actions.length === 0) {
         console.log(section("Clean up scaffold"));
         console.log(body("Nothing to clean - this project is already tidy."));

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/dist/last-sync.js

@@ -24,7 +24,14 @@ export const LAST_SYNC_FILE = ".last-sync.json";
  *
  * `name` sai do valor porque já É a chave - hasheá-lo junto só gastaria bytes.
  */
-export function fingerprintReadings(components) {
+export function fingerprintReadings(
+/**
+ * A LINHA INTEIRA, e o tipo tem que dizer isso: `{ name?: unknown }` prometia menos do que esta
+ * função aceita, e o próprio spec precisou de um `as never` para passar uma linha real. Um tipo
+ * que obriga a burlá-lo está errado - e o `as never` que ele forçava é exatamente o que faria a
+ * impressão parar de ver um campo novo sem ninguém notar.
+ */
+components) {
     const out = {};
     for (const c of components ?? []) {
         const name = typeof c?.name === "string" ? c.name : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.203",
+  "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": {
@@ -32,7 +32,8 @@
     "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build",
-    "test": "vitest run"
+    "test": "vitest run",
+    "check": "tsc -p tsconfig.check.json"
   },
   "license": "MIT"
 }