synthesisui 0.16.158 → 0.16.160

package/dist/agent-wiring.js

@@ -36,6 +36,22 @@ export async function hookCommand(root, version) {
         ? "npx --no-install synthesisui hook"
         : `npx synthesisui@${version} hook`;
 }
+/**
+ * COMO A SESSÃO CHAMA O CLI, e por que este NÃO é pinado.
+ *
+ * O hook de escrita é pinado porque roda dezenas de vezes por sessão e um verificador que muda sob
+ * você a cada edit é indebugável. Este roda UMA vez, e o trabalho dele é justamente dizer o que está
+ * atrasado - inclusive o próprio CLI. Um `align` pinado no dia do `connect` não conhece nenhuma
+ * verificação escrita depois, e passa a garantir silêncio em vez de alinho.
+ *
+ * O custo do `npx` (720ms-1.5s, medido em 27/07) é pago uma vez na abertura, não por escrita.
+ */
+export async function alignCommand(root) {
+    const local = join(root, "node_modules", ".bin", "synthesisui");
+    return (await exists(local))
+        ? "npx --no-install synthesisui align"
+        : "npx synthesisui@latest align";
+}
 /**
  * Returns the command that IS in the file, not the one we would have written.
  *
@@ -211,9 +227,45 @@ export async function wireAgent(root, version, want) {
         command: hook.command,
         hook: hook.status,
         ...(hook.was ? { was: hook.was } : {}),
+        /**
+         * A VERIFICAÇÃO DE ABERTURA vai junto do hook de escrita, e por um motivo medido: as onze
+         * ferramentas MCP são todas PULL, o agente só descobre um desalinho se resolver perguntar, e o
+         * único hook instalado rodava DEPOIS de uma escrita - tarde demais para dizer "você não está
+         * logado" ou "este sistema não sabe de onde foi medido".
+         */
+        session: want.hook
+            ? await wireSessionStart(root, await alignCommand(root))
+            : "skipped",
         mcp: want.mcp ? await wireMcp(root, version) : "skipped",
     };
 }
+/**
+ * O hook `SessionStart`, escrito com a mesma disciplina do de escrita: vizinho nenhum é tocado, e um
+ * comando escrito à mão fica como está. Só um `align` nosso apontando para outro lugar é substituído.
+ */
+async function wireSessionStart(root, command) {
+    const dir = join(root, ".claude");
+    const path = join(dir, "settings.json");
+    const settings = await readJson(path);
+    const hooks = (settings.hooks ?? {});
+    const entries = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    for (const entry of entries)
+        for (const h of entry.hooks ?? []) {
+            const was = h.command ?? "";
+            if (!/synthesisui(@[\w.-]+)?\s+align/.test(was))
+                continue;
+            if (was === command)
+                return "already there";
+            h.command = command;
+            await mkdir(dir, { recursive: true });
+            await writeFile(path, `${JSON.stringify({ ...settings, hooks: { ...hooks, SessionStart: entries } }, null, 2)}\n`, "utf8");
+            return "updated";
+        }
+    entries.push({ hooks: [{ type: "command", command }] });
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, `${JSON.stringify({ ...settings, hooks: { ...hooks, SessionStart: entries } }, null, 2)}\n`, "utf8");
+    return "added";
+}
 /**
  * Whether THIS project already has the hook.
  *

package/dist/commands/add.js

@@ -4,10 +4,43 @@ import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
 import { buildGuide } from "../guide.js";
+import { censusScope } from "../measured-scope.js";
 import { body as line, section, snippet } from "../output.js";
 import { fetchDesignSystem } from "../registry.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
 import { detectStack } from "../stack.js";
+/**
+ * QUAL METADE DESTA PASTA UM TIME COMMITA.
+ *
+ * Medido no repo do dono em 06/08: `_synthesisui/` não estava no gitignore E não tinha um único
+ * arquivo rastreado. Ou seja, a pasta existia só na máquina de quem rodou o import - todo clone, e
+ * todo colega, começava sem governança nenhuma, e nada dizia isso a ninguém.
+ *
+ * A divisão não é gosto, é o que cada arquivo É:
+ *
+ *     .lock, ds/<slug>/**   a IDENTIDADE e o CSS que a app importa. Sem eles o build de um colega
+ *                           não tem tokens. Versionar.
+ *     census.json           0,5 MB, regravado inteiro a cada medição. Versionar é conflito toda vez.
+ *     ledger.jsonl          registro local, append-only, uma linha por escrita. Conflito garantido.
+ *
+ * Escrito uma vez e nunca reescrito: um arquivo que alguém ajustou é decisão dele.
+ */
+async function writeGovernanceIgnore(projectRoot) {
+    const path = join(projectRoot, "_synthesisui", ".gitignore");
+    try {
+        await access(path);
+        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" +
+        "not-expressed.md\n", "utf8");
+}
 async function readRootLock(path) {
     try {
         return JSON.parse(await readFile(path, "utf8"));
@@ -62,14 +95,25 @@ export async function add(slug, opts) {
             `@import "./v${payload.version}/${filename}";\n`, "utf8");
     }
     // 5. root pointer
+    /**
+     * A medição FRESCA vence a cópia anterior, e por isso lê o censo em vez do lock: um `--scope` novo
+     * chega pelo censo que acabou de rodar, e ler o lock aqui congelaria o primeiro para sempre. Sem
+     * censo (um `add` puro, sem import antes), o que o lock já dizia é preservado.
+     */
+    const measured = await censusScope(projectRoot);
+    const scope = measured.system ?? prev?.scope ?? null;
+    const usage = measured.usage.length > 0 ? measured.usage : (prev?.usage ?? []);
     const lock = {
         slug: payload.slug,
         name: payload.name,
         version: payload.version,
         registry: base,
         fetchedAt: new Date().toISOString(),
+        ...(scope ? { scope } : {}),
+        ...(usage.length > 0 ? { usage } : {}),
     };
     await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    await writeGovernanceIgnore(projectRoot);
     // 5b. governance rules (personal DS) → rules.md at the slug root (stable path,
     //     highest authority; the GUIDE tells the agent to read it first)
     /**

package/dist/commands/align.js

@@ -0,0 +1,125 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { readEvents } from "../doctor/ledger.js";
+import { measuredScope } from "../measured-scope.js";
+async function locksIn(root) {
+    const dsDir = join(root, "_synthesisui", "ds");
+    const entries = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const raw = await readFile(join(dsDir, entry.name, ".lock"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        try {
+            out.push(JSON.parse(raw));
+        }
+        catch {
+            // lock ilegível - o `status` já reporta isso com o nome do arquivo
+        }
+    }
+    return out;
+}
+async function credentials(home) {
+    const raw = await readFile(join(home, ".synthesisui", "credentials.json"), "utf8").catch(() => null);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A metade que não depende de rede.
+ *
+ * Separada de propósito: ela é a que sempre roda, e é testável sem servidor nenhum.
+ */
+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
+ * máquina que roda o teste não é verificável: ela passa ou falha conforme quem está logado ali.
+ */
+opts = {}) {
+    const { cli, home = homedir() } = opts;
+    const out = [];
+    const locks = (await locksIn(root)).filter((l) => l.slug && !l.adopted);
+    /** Sem sistema instalado não há alinho a cobrar - não é desalinho, é um repo sem DS. */
+    if (locks.length === 0)
+        return out;
+    if (locks.length > 1)
+        out.push({
+            says: `${locks.length} design systems are installed here (${locks
+                .map((l) => l.slug)
+                .join(", ")}) - commands act on the first, so one of them is not being governed`,
+        });
+    const lock = locks[0];
+    const creds = await credentials(home);
+    if (!creds)
+        out.push({
+            says: "No session on this machine. A token belongs to the machine, not to the repo, so a fresh clone always lands here.",
+            run: "npx synthesisui login",
+        });
+    else if (creds.registry && lock.registry && creds.registry !== lock.registry)
+        out.push({
+            says: `Your session is for ${creds.registry} and this system came from ${lock.registry}. That answers 401, which reads as an expired session on a host that never issued one.`,
+            run: `npx synthesisui login --registry ${lock.registry}`,
+        });
+    /**
+     * O ESCOPO, que é o desalinho mais caro e o mais silencioso: sem ele o `sync` mede o repo inteiro
+     * e manda os componentes de todos os apps para um sistema que é uma biblioteca (06/08, 338 num
+     * sistema de 36).
+     */
+    const scope = await measuredScope(root);
+    if (!scope.system && scope.usage.length === 0)
+        out.push({
+            says: `"${lock.slug}" does not record where it was measured, so a re-measure would read this whole repo instead of the folder the system came from.`,
+            run: "npx synthesisui import --dry --scope <folder>",
+        });
+    const events = await readEvents(root).catch(() => []);
+    if (events.length > 0)
+        out.push({
+            says: `${events.length} checked write${events.length === 1 ? "" : "s"} recorded here and not sent - the platform is scoring this repo on older evidence.`,
+            run: "npx synthesisui sync",
+        });
+    if (cli && lock.version == null)
+        out.push({
+            says: `"${lock.slug}" has no version recorded, so nothing can tell whether the CSS in this repo is the one the platform publishes.`,
+            run: "npx synthesisui upgrade",
+        });
+    return out;
+}
+/**
+ * A linha que a sessão vê.
+ *
+ * Uma frase por desalinho e o comando ao lado - sem cabeçalho, sem contagem, sem moldura. Isto é
+ * injetado no contexto de um agente, e cada linha decorativa é contexto que não é sobre o trabalho
+ * dele.
+ */
+export function describeMisalignments(items) {
+    if (items.length === 0)
+        return "";
+    return [
+        "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");
+}
+/**
+ * `synthesisui align` - o comando que o hook de sessão roda.
+ *
+ * Sai silencioso e com código 0 quando está tudo alinhado, porque um hook que fala toda vez deixa de
+ * 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());
+    const items = await localMisalignments(root, {
+        ...(opts.cli ? { cli: opts.cli } : {}),
+    }).catch(() => []);
+    const text = describeMisalignments(items);
+    if (text)
+        console.log(text);
+}

package/dist/commands/connect.js

@@ -50,6 +50,15 @@ export async function connect(opts) {
                     `✓ .claude/settings.json  the check moved from ${wired.was?.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? "an older version"} to this one`
                 : "· .claude/settings.json  already had it"));
         console.log(snippet([wired.command]));
+        /**
+         * A SEGUNDA COSTURA, dita por nome. As onze ferramentas MCP são PULL e o hook de escrita roda
+         * DEPOIS de uma escrita - nenhum dos dois chega a tempo de dizer "você não está logado nesta
+         * máquina" ou "este sistema não sabe de onde foi medido". O `SessionStart` é o único que chega.
+         */
+        if (wired.session !== "skipped")
+            console.log(body(wired.session === "already there"
+                ? "· .claude/settings.json  the session check was already there"
+                : `✓ .claude/settings.json  every session now opens with what this environment is missing${wired.session === "updated" ? ", pointed at this version" : ""}`));
     }
     /**
      * OS CAMINHOS DE MCP, POR NOME - e o número vem da LISTA, não da minha memória.

package/dist/commands/import.js

@@ -1674,6 +1674,22 @@ export async function takeCensus(root, opts) {
                 },
             }
             : {}),
+        /**
+         * O ESCOPO VIAJA COM O CENSO, e até 06/08 só o `usage` viajava.
+         *
+         * `census.scope` era escrito pelo comando `import` (o `runImport`, mais abaixo neste arquivo) e não
+         * aqui - então todo censo produzido por uma RE-MEDIÇÃO nascia sem escopo, mesmo tendo lido a pasta
+         * certa. Um veneno de ação lenta, medido no repo do dono:
+         *
+         *     1a re-medicao   le o escopo guardado, mede `packages/ui` certo (36 looks),
+         *                     e envia um censo SEM escopo
+         *     2a re-medicao   nao acha escopo -> mede o repo INTEIRO -> 340 looks, 324
+         *                     componentes, e o rascunho curado de 37 vira 339
+         *
+         * A primeira parece perfeita, e é isso que faz o defeito sobreviver. O `usage` estava dois campos
+         * acima o tempo todo, gravado por este mesmo objeto - os dois chegam juntos e só um sobrevivia.
+         */
+        ...(scopeLabel ? { scope: scopeLabel } : {}),
         ...((opts?.usage ?? []).length > 0
             ? { usage: (opts?.usage ?? []).map((u) => u.label) }
             : {}),

package/dist/commands/mcp.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { pinnedHookVersion } from "../agent-wiring.js";
@@ -1057,4 +1058,20 @@ export async function mcp(opts) {
         }
     }
 }
-const VERSION = "0.16.9";
+/**
+ * A NOSSA VERSÃO, LIDA DO `package.json` - e ela era uma string cravada em "0.16.9".
+ *
+ * 149 versões atrás. O `index.ts` já lia a dele do arquivo desde sempre; esta cópia envelheceu em
+ * silêncio e apareceu de três formas no mesmo dia (dono, 06/08):
+ *
+ *   1. `serverInfo.version` dizia 0.16.9, então o agente reportava "as ferramentas que estou segurando
+ *      são 0.16.9" - e estava repetindo o nosso número, não medindo nada
+ *   2. a comparação nova (`pinned !== VERSION`) ficava SEMPRE verdadeira, então o "atualize o ds antes
+ *      de continuar" apareceria para sempre, inclusive um segundo depois de um `connect` bem-sucedido
+ *   3. `remeasure({ cli: VERSION })` gravou `ledger.cli: "0.16.9"` no censo e no relatório dele, e a
+ *      plataforma passou a achar que aquele sistema está 149 versões atrás
+ *
+ * É a mesma lição que `MCP_TOOL_COUNT` já carrega neste arquivo - "um número que alguém digita
+ * envelhece" - escrita duas vezes e aprendida uma.
+ */
+const VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;

package/dist/commands/sync.js

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { checkableName, closeRequest, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
+import { measuredScope } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { repoStateOf } from "../repo-state.js";
 import { resolveReadParts, takeCensus } from "./import.js";
@@ -191,13 +192,31 @@ export async function remeasure(args) {
         console.log(paint.blue(snippet(["npx synthesisui@latest connect"])));
         console.log(body(paint.faint("That rewires the hook and the tools to the new version - the editor picks them up on the next session.")));
     }
+    /**
+     * O ESCOPO SAI DO DISCO ANTES DE SAIR DO SERVIDOR.
+     *
+     * Ele mora nos dois lugares, e o do disco é o que não pode se perder: o censo local É a foto da
+     * última medição e carrega o `scope` que a mediu. O servidor guarda uma cópia, e uma cópia pode
+     * ser sobrescrita - em 06/08 foi, e o sistema ficou sem escopo nenhum lá.
+     *
+     * O preço daquilo não foi um número errado, foi um LOOP: sem escopo, esta linha media o repo
+     * inteiro, mandava 338 componentes de app para um sistema de 36, e o `sync` seguinte fazia de
+     * novo. Perguntar ao servidor uma coisa que está do lado de cá é o que fechava o ciclo.
+     *
+     * O servidor continua valendo como segunda fonte: um clone fresco tem o `.lock` e não tem censo.
+     */
+    const local = await measuredScope(root);
+    const scope = local.system ?? stored.scope ?? null;
+    const usage = local.usage.length > 0 ? local.usage : (stored.usage ?? []);
     console.log(section("Measuring your repository again"));
-    console.log(body(paint.faint(`${stored.scope ? `scope ${stored.scope}` : "the whole repo"} · the reading you already authored travels unchanged`)));
-    const census = await takeCensus(stored.scope ? join(root, stored.scope) : root, {
-        ...(stored.scope ? { scopeLabel: stored.scope } : {}),
+    console.log(body(paint.faint(`${scope ? `scope ${scope}` : "the whole repo"}${local.system && local.system !== stored.scope
+        ? " · read from your own census, which is where the last measurement recorded it"
+        : ""} · the reading you already authored travels unchanged`)));
+    const census = await takeCensus(scope ? join(root, scope) : root, {
+        ...(scope ? { scopeLabel: scope } : {}),
         ...(args.cli ? { cli: args.cli } : {}),
         /** O `--usage` é EVIDÊNCIA e leva rótulo: sem ele o censo não sabe de que app o número veio. */
-        usage: (stored.usage ?? []).map((u) => ({
+        usage: usage.map((u) => ({
             path: join(root, u),
             label: u,
         })),

package/dist/index.js

@@ -4,6 +4,7 @@ import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
 import { advise } from "./commands/advise.js";
+import { align } from "./commands/align.js";
 import { ci } from "./commands/ci.js";
 import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
@@ -547,6 +548,13 @@ async function main() {
                 yes: args.includes("--yes"),
             });
             break;
+        /**
+         * O que o hook `SessionStart` roda. Silencioso quando está alinhado, e nunca falha - ver
+         * `align.ts` para os nove estados e por que sete deles não tinham verificação nenhuma.
+         */
+        case "align":
+            await align({ dir, cli: CLI_VERSION });
+            break;
         case "request": {
             // `synthesisui request` lists; `request component --name x --for "..."`
             // files; `request --done <id>` closes. The agent's front door is the MCP

package/dist/measured-scope.js

@@ -1,6 +1,51 @@
-import { readFile, stat } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 const EMPTY = { system: null, usage: [], from: "none" };
+/**
+ * O ESCOPO NO PONTEIRO DO SISTEMA, que é onde ele não se perde.
+ *
+ * O censo é grande (0,5 MB), é regravado a cada medição e ninguém versiona um arquivo assim sem
+ * pagar conflito. O `.lock` tem cinco campos e é o arquivo desta pasta que um time COMMITA - então é
+ * ele que faz um clone fresco saber de onde este sistema foi medido, sem uma ida à rede e sem
+ * depender de uma cópia no servidor que já foi sobrescrita uma vez (06/08).
+ *
+ * Um lock sem `scope` é o caso de todo sistema instalado antes disto: cai no censo, como antes.
+ */
+async function scopeInLock(root) {
+    const dsDir = join(root, "_synthesisui", "ds");
+    const names = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
+    for (const entry of names) {
+        if (!entry.isDirectory())
+            continue;
+        const raw = await readFile(join(dsDir, entry.name, ".lock"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        let lock;
+        try {
+            lock = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const scope = typeof lock.scope === "string" && lock.scope.trim()
+            ? lock.scope.trim()
+            : null;
+        const usage = Array.isArray(lock.usage)
+            ? lock.usage.filter((u) => typeof u === "string" && !!u.trim())
+            : [];
+        if (!scope && usage.length === 0)
+            continue;
+        const system = scope && (await present(root, scope)) ? scope : null;
+        const kept = [];
+        for (const u of usage)
+            if (await present(root, u))
+                kept.push(u);
+        if (!system && kept.length === 0)
+            continue;
+        return { system, usage: kept, from: "lock" };
+    }
+    return null;
+}
 /** Existe como diretório? Um escopo gravado e depois renomeado não pode derrubar o comando. */
 async function present(root, rel) {
     return stat(resolve(root, rel)).then((s) => s.isDirectory(), () => false);
@@ -13,6 +58,19 @@ async function present(root, rel) {
  * comportamento antigo (a raiz).
  */
 export async function measuredScope(root) {
+    const fromLock = await scopeInLock(root);
+    if (fromLock)
+        return fromLock;
+    return censusScope(root);
+}
+/**
+ * O que o CENSO diz sobre onde, sem olhar o lock.
+ *
+ * Quem ESCREVE o lock lê por aqui, e a ordem é o contrário da leitura de propósito: o censo é a
+ * medição fresca que acabou de rodar, e o lock é a cópia da anterior. Ler o lock para escrever o
+ * lock congelaria o primeiro escopo para sempre, e um `--scope` novo nunca chegaria lá.
+ */
+export async function censusScope(root) {
     const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => null);
     if (!raw)
         return EMPTY;

package/package.json

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