synthesisui 0.16.162 → 0.16.164

package/dist/commands/add.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
@@ -41,6 +41,33 @@ async function writeGovernanceIgnore(projectRoot) {
         "ledger.jsonl\n" +
         "not-expressed.md\n", "utf8");
 }
+/**
+ * APAGA A PROSA QUE ESTA VERSÃO DEIXOU DE ESCREVER.
+ *
+ * `rules.md` e `philosophy.md` eram materializados só pelo `add`, então quem instalou antes disto
+ * tem dois arquivos que nada mais atualiza - e um deles se apresenta como "Max authority - follow
+ * these first". Um arquivo que afirma autoridade máxima sobre a regra de uma versão qualquer do
+ * passado é pior que arquivo nenhum, e deixá-lo lá esperando alguém lembrar de apagar é exatamente
+ * a administração manual que esta esteira existe para não pedir (dono, 06/08).
+ *
+ * É a NOSSA pasta - o `.gitignore` que este mesmo comando escreve já a declara gerenciada -, então
+ * isto não toca em código dele. E é dito na saída, porque apagar em silêncio é a outra metade do
+ * mesmo erro.
+ */
+async function retireMaterializedDoctrine(slugDir) {
+    const gone = [];
+    for (const name of ["rules.md", "philosophy.md"]) {
+        const path = join(slugDir, name);
+        try {
+            await access(path);
+        }
+        catch {
+            continue;
+        }
+        await rm(path).then(() => gone.push(name), () => { });
+    }
+    return gone;
+}
 async function readRootLock(path) {
     try {
         return JSON.parse(await readFile(path, "utf8"));
@@ -114,7 +141,8 @@ export async function add(slug, opts) {
     };
     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,
+    const retired = await retireMaterializedDoctrine(slugDir);
+    // 5b. governance rules (personal DS) → doctrine.json at the slug root (stable path,
     //     highest authority; the GUIDE tells the agent to read it first)
     /**
      * The structured set wins when the registry sent one, because only this side
@@ -129,13 +157,21 @@ export async function add(slug, opts) {
     const leftOut = payload.ruleSet
         ? describeFiltered(payload.ruleSet, stack)
         : null;
+    /**
+     * AS REGRAS VIAJAM COMO DADO, e não como prosa materializada.
+     *
+     * `rules.md` e `philosophy.md` eram escritos SÓ pelo `add` (e o `upgrade` chama o `add`), então
+     * entre um upgrade e outro eles eram uma cópia velha de um dado que é VERSIONADO do nosso lado - e
+     * o GUIDE chamava um deles de "maximum authority". Uma autoridade máxima que envelhece em silêncio
+     * é pior que nenhuma (dono, 06/08).
+     *
+     * O conteúdo não sai do disco, porque o agente precisa dele offline e sem aprovar servidor nenhum.
+     * O que muda é a FORMA e quem o apresenta: aqui fica o dado pinado na versão instalada, e o
+     * `system_doctrine` do MCP é quem o serve - dizendo qual versão ele está lendo e se existe uma mais
+     * nova, em vez de deixar a pessoa descobrir pela ausência.
+     */
     if (rules.length > 0) {
-        const body = `# ${payload.name} - Rules\n\n` +
-            "> Accumulated rules for this design system. **Max authority - follow these first.**\n" +
-            `> Managed by synthesisui (edit in the studio). ${rules.length} rule(s).\n\n${rules
-                .map((r) => `- ${r}`)
-                .join("\n")}\n`;
-        await writeFile(join(slugDir, "rules.md"), body, "utf8");
+        await writeFile(join(slugDir, "doctrine.json"), `${JSON.stringify({ version: payload.version, name: payload.name, rules }, null, 2)}\n`, "utf8");
     }
     // NO SILENT DROPS. A rule removed because it belongs to another environment is
     // a thing the person should hear once, not discover by its absence.
@@ -163,22 +199,17 @@ export async function add(slug, opts) {
     if (required.length > 0) {
         await writeFile(join(slugDir, "requires.json"), `${JSON.stringify(required, null, 2)}\n`, "utf8");
     }
-    // 5c. structured philosophy (personal DS) → philosophy.md at the slug root.
-    //     Narrative guidance (mission, principles, voice, motion doctrine…); the
-    //     GUIDE points the agent here right after rules.md.
+    /** A filosofia continua sendo CONTADA na saída, e ela vive no documento - ver abaixo. */
     const philosophy = payload.document.philosophy;
     const sections = philosophy?.sections ?? [];
-    if (sections.length > 0 || philosophy?.context) {
-        const parts = [`# ${payload.name} - Philosophy`, ""];
-        parts.push("> The voice and principles behind this system. Read after rules.md;", "> let it shape every screen. Managed by synthesisui (edit in the studio).", "");
-        if (philosophy?.context) {
-            parts.push("## What this product is", "", philosophy.context, "");
-        }
-        for (const s of sections) {
-            parts.push(`## ${s.title}`, "", s.body, "");
-        }
-        await writeFile(join(slugDir, "philosophy.md"), `${parts.join("\n")}\n`, "utf8");
-    }
+    /**
+     * 5c. A FILOSOFIA NÃO É MATERIALIZADA - ela já está aqui.
+     *
+     * `philosophy` é campo do DOCUMENTO versionado (`design-system.ts`), e o `design-system.json`
+     * escrito no passo 2 a carrega inteira. O `philosophy.md` era uma segunda cópia do mesmo dado, no
+     * mesmo commit, que só era reescrita no upgrade seguinte - dois caminhos para uma verdade é como
+     * um deles começa a discordar do outro. O `system_doctrine` lê do documento.
+     */
     // 6. discovery by the agent
     const claudeMd = await syncClaudeMd(projectRoot);
     // outcome line
@@ -201,12 +232,21 @@ export async function add(slug, opts) {
         "GUIDE.md",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
-    if (rules.length > 0) {
-        console.log(`  rules.md → ${rules.length} rule(s) (read these first)`);
-    }
-    if (sections.length > 0 || philosophy?.context) {
-        console.log(`  philosophy.md → ${sections.length} section(s) (read after rules)`);
-    }
+    /**
+     * O QUE O AGENTE VAI LER, e por qual porta - nomear o arquivo quando a porta é uma ferramenta
+     * mandaria alguém procurar um caminho que não existe mais.
+     */
+    const doctrine = [
+        ...(rules.length > 0 ? [`${rules.length} rule(s)`] : []),
+        ...(sections.length > 0 || philosophy?.context
+            ? [`${sections.length} section(s) of philosophy`]
+            : []),
+    ];
+    if (doctrine.length > 0)
+        console.log(`  ${doctrine.join(" and ")} → your agent reads them with \`system_doctrine\`, pinned to v${v}`);
+    /** Nomeado, nunca em silêncio: apagar arquivo no repo de alguém se diz em voz alta. */
+    if (retired.length > 0)
+        console.log(`  removed ${retired.join(" and ")} - nothing rewrote them after an install, so they stated an older version's rules as current`);
     console.log(`  CLAUDE.md ${claudeMd.created ? "created" : "updated"} (${claudeMd.count} system(s) installed)`);
     if (opts.setupHints === false)
         return;

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 { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { measuredScope } from "../measured-scope.js";
 async function locksIn(root) {
@@ -100,6 +101,38 @@ opts = {}) {
         });
     return out;
 }
+/**
+ * A VERSÃO PUBLICADA CONTRA A INSTALADA - o estado que nenhuma verificação cobria.
+ *
+ * É o que faz disto um produto de TIME e não de uma pessoa: alguém edita o sistema no estúdio e
+ * publica, e o repo de todo mundo continua com o CSS e as regras da versão anterior, sem nada dizer.
+ * A doutrina que o agente lê é a da versão instalada de propósito (ver `system_doctrine`), então as
+ * duas metades andam juntas - e é justamente por isso que a defasagem precisa ser DITA.
+ *
+ * Melhor esforço: offline, sem sessão, ou registry fora do ar não produzem linha nenhuma. Uma
+ * verificação de abertura não pode transformar um voo sem internet num aviso.
+ */
+export async function versionBehind(root, opts = {}) {
+    const locks = (await locksIn(root)).filter((l) => l.slug && !l.adopted);
+    const lock = locks[0];
+    if (!lock?.slug || lock.version == null)
+        return null;
+    if (!(await credentials(opts.home ?? homedir())))
+        return null;
+    const token = await readToken();
+    if (!token)
+        return null;
+    const res = await fetch(`${lock.registry ?? resolveRegistry()}/api/registry/ds/${lock.slug}`, { headers: { Authorization: `Bearer ${token}` } }).catch(() => null);
+    if (!res?.ok)
+        return null;
+    const body = (await res.json().catch(() => null));
+    if (!body?.version || body.version <= lock.version)
+        return null;
+    return {
+        says: `v${body.version} of "${lock.slug}" is published and this repo is on v${lock.version}. The CSS here and the rules your agent reads are both v${lock.version} - they move together, which is why this is worth saying rather than applying.`,
+        run: `npx synthesisui upgrade ${lock.slug}`,
+    };
+}
 /**
  * A linha que a sessão vê.
  *
@@ -127,6 +160,10 @@ export async function align(opts) {
     const items = await localMisalignments(root, {
         ...(opts.cli ? { cli: opts.cli } : {}),
     }).catch(() => []);
+    /** A única linha que custa rede, e ela some inteira quando não há rede. */
+    const remote = await versionBehind(root).catch(() => null);
+    if (remote)
+        items.push(remote);
     const text = describeMisalignments(items);
     if (text)
         console.log(text);

package/dist/commands/doctor.js

@@ -144,6 +144,7 @@ export async function loadSystem(root) {
             recipes: new Map(),
             documents: [],
             requires: [],
+            doctrines: [],
         };
     }
     // Several systems can live side by side; every token is prefixed --ds-, so
@@ -154,6 +155,7 @@ export async function loadSystem(root) {
     const recipes = new Map();
     const documents = [];
     const requires = [];
+    const doctrines = [];
     for (const slug of slugs) {
         const dir = join(dsDir, slug);
         const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");
@@ -226,12 +228,31 @@ export async function loadSystem(root) {
                 // Unreadable costs this check, not the run.
             }
         }
+        /** Ausente é o caso normal: um sistema sem regra nenhuma não deixa arquivo. */
+        const doctrineRaw = await readFile(join(dir, "doctrine.json"), "utf8").catch(() => "");
+        if (doctrineRaw) {
+            try {
+                const parsed = JSON.parse(doctrineRaw);
+                if (Array.isArray(parsed.rules))
+                    doctrines.push({
+                        ...(typeof parsed.version === "number"
+                            ? { version: parsed.version }
+                            : {}),
+                        ...(typeof parsed.name === "string" ? { name: parsed.name } : {}),
+                        rules: parsed.rules.filter((r) => typeof r === "string"),
+                    });
+            }
+            catch {
+                // Ilegível custa a doutrina, nunca a rodada.
+            }
+        }
     }
     return {
         table: buildTable({ css, lock, source: adopted ? "adopted" : "installed" }),
         recipes,
         documents,
         requires,
+        doctrines,
     };
 }
 /**

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { pinnedHookVersion } from "../agent-wiring.js";
 import { readToken, resolveRegistry } from "../config.js";
+import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { nearestToken, tokenFor } from "../doctor/tokens.js";
@@ -70,6 +71,11 @@ const TOOLS = [
             required: ["value"],
         },
     },
+    {
+        name: "system_doctrine",
+        description: "The rules and the philosophy of the installed system - maximum authority, read this BEFORE building anything. It answers from the version this project has pinned, which is the same version whose tokens are on disk, so the rules you follow and the values you write come from one place. It also says when a newer version has been published, without applying it.",
+        inputSchema: { type: "object", properties: {} },
+    },
     {
         name: "list_components",
         description: "The components this design system defines, with what each is for. Look here BEFORE writing any UI element from scratch - if something covers the purpose, materialize it with add_component instead.",
@@ -252,6 +258,94 @@ async function findToken(root, value) {
     // same refusal every time.
     return `No token in this system holds ${value}, and nothing is close. Do NOT invent one. Say which value you need and what you would call it, and let a person decide.`;
 }
+/**
+ * A DOUTRINA DO SISTEMA - as regras e a filosofia, servidas em vez de materializadas.
+ *
+ * `rules.md` e `philosophy.md` eram escritos SÓ pelo `add` (e o `upgrade` chama o `add`), então entre
+ * um upgrade e outro eram uma cópia velha de dado que é VERSIONADO do nosso lado - e o GUIDE chamava
+ * um deles de "maximum authority". Uma autoridade máxima que envelhece em silêncio é pior que
+ * nenhuma (dono, 06/08).
+ *
+ * DA VERSÃO PINADA, e essa é a decisão que mantém as duas metades coerentes: os tokens no disco são
+ * os da v2, então a regra que o agente segue tem que ser a da v2. Servir o rascunho faria o agente
+ * escrever contra uma regra que ainda não está instalada.
+ *
+ * A existência de uma versão mais nova é DITA, nunca aplicada - aplicar é o `upgrade`, que é uma
+ * palavra que a pessoa já tem. Sem rede, a doutrina responde igual e a checagem é que se cala: o
+ * dado é local justamente para não depender de servidor nenhum.
+ */
+async function systemDoctrine(root) {
+    const { documents, doctrines } = await loadSystem(root);
+    const rules = doctrines.flatMap((d) => d.rules);
+    const parts = [];
+    const pinned = doctrines[0]?.version;
+    for (const doc of documents) {
+        const p = doc.philosophy;
+        if (p?.context)
+            parts.push(`## What this product is\n\n${p.context}`);
+        for (const sec of p?.sections ?? [])
+            parts.push(`## ${sec.title}\n\n${sec.body}`);
+    }
+    if (rules.length === 0 && parts.length === 0)
+        return "This system carries no rules and no philosophy yet. Nothing here overrides your judgement - build with its tokens and its components, and say what you needed and could not find.";
+    const head = [
+        rules.length > 0
+            ? `# Rules - maximum authority, ${rules.length} of them${pinned ? `, as of v${pinned}` : ""}`
+            : "",
+        ...rules.map((r) => `- ${r}`),
+    ].filter(Boolean);
+    const pulse = await sessionPulse(root, pinned);
+    return [
+        ...head,
+        ...(parts.length > 0 ? ["", "# Philosophy", "", ...parts] : []),
+        ...(pulse.length > 0 ? ["", ...pulse] : []),
+    ].join("\n");
+}
+/**
+ * O PULSO DE UMA SESSÃO LONGA.
+ *
+ * A verificação de abertura (`align`) roda UMA vez, no minuto zero. Numa sessão de seis horas tudo o
+ * que ela achou é uma foto: a sessão expira na hora três, um colega publica na hora quatro, e o
+ * registro local cresce a tarde inteira sem subir. Nada disso volta a ser dito (dono, 06/08).
+ *
+ * Esta ferramenta é o lugar certo para o pulso porque o agente a chama ANTES de construir - que é
+ * exatamente o momento em que a consistência importa. Um `setInterval` avisaria no meio de outra
+ * coisa; isto avisa na fronteira de uma decisão.
+ *
+ * SÓ FALA QUANDO HÁ O QUE DIZER. Uma linha que aparece em toda chamada vira papel de parede numa
+ * ferramenta chamada dezenas de vezes por sessão, e aí ela não serve para a vez que importa.
+ */
+async function sessionPulse(root, pinned) {
+    const out = [];
+    const slug = await installedSlug(root);
+    const token = await readToken();
+    if (slug && token && pinned != null) {
+        const res = await fetch(`${resolveRegistry()}/api/registry/ds/${slug}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        }).catch(() => null);
+        /**
+         * 401 é a sessão que morreu no meio da sessão de trabalho, e é o pior silêncio possível: daqui
+         * em diante toda ferramenta falha e nenhuma diz por quê. Offline não produz linha - `res` nulo
+         * não distingue "sem rede" de "servidor fora", e nenhum dos dois é problema da pessoa.
+         */
+        if (res?.status === 401)
+            out.push("> Your session on this machine has expired, so anything that needs the platform will fail from here on. A person has to run `npx synthesisui login` once in the terminal - I cannot complete it. What is on disk still governs: the rules above are the installed version's.");
+        else if (res?.ok) {
+            const body = (await res.json().catch(() => null));
+            if (body?.version && body.version > pinned)
+                out.push(`> v${body.version} of this system has been published and this project is on v${pinned}. These rules are v${pinned}'s, and so are the tokens on disk - the two move together. \`npx synthesisui upgrade ${slug}\` brings both.`);
+        }
+    }
+    /**
+     * O REGISTRO QUE NÃO SUBIU. Ele cresce a cada escrita verificada e só o `sync` o manda, então uma
+     * tarde inteira de trabalho fica invisível para a plataforma - e a tela do dono pontua o repo com
+     * evidência de ontem. Cinquenta é onde uma sessão de verdade chega; abaixo disso é ruído.
+     */
+    const events = await readEvents(root).catch(() => []);
+    if (events.length >= 50)
+        out.push(`> ${events.length} checked writes are recorded here and have not been sent, so this repo is being scored on older evidence. \`npx synthesisui sync\` ships them.`);
+    return out;
+}
 async function listComponents(root) {
     const { documents } = await loadSystem(root);
     const rows = [];
@@ -839,6 +933,8 @@ cli) {
             return text(await checkFile(root, String(args.path ?? ".")));
         case "find_token":
             return text(await findToken(root, String(args.value ?? "")));
+        case "system_doctrine":
+            return text(await systemDoctrine(root));
         case "list_components":
             return text(await listComponents(root));
         case "describe_component":

package/dist/commands/use.js

@@ -43,15 +43,17 @@ export async function use(slug, intent, opts) {
     const config = await readProjectConfig(root);
     const { version, name } = lock;
     const base = `_synthesisui/ds/${slug}`;
-    // Highest-authority guidance first; only list files that actually exist.
-    const hasRules = await exists(join(slugDir, "rules.md"));
-    const hasPhilosophy = await exists(join(slugDir, "philosophy.md"));
+    /**
+     * A AUTORIDADE MÁXIMA VEM DE UMA FERRAMENTA, e o resto continua sendo caminho.
+     *
+     * `rules.md` e `philosophy.md` eram cópias velhas de dado versionado entre um upgrade e outro -
+     * ver `system_doctrine`. Um prompt que manda alguém abrir um arquivo que não existe mais é pior
+     * que um prompt sem a linha, então a condição passou a ser o DADO e não o arquivo.
+     */
+    const hasDoctrine = await exists(join(slugDir, "doctrine.json"));
     const readFirst = [
-        hasRules
-            ? `- ${base}/rules.md — project rules for this system; obey them above everything else`
-            : "",
-        hasPhilosophy
-            ? `- ${base}/philosophy.md — the mission, voice and principles; let it shape every screen`
+        hasDoctrine
+            ? "- Call `system_doctrine` first — this system's rules and philosophy, pinned to the installed version; obey them above everything else. Without MCP, the same data is `doctrine.json` and the `philosophy` of `design-system.json`"
             : "",
         `- ${base}/v${version}/GUIDE.md — how to apply the system, the recipes and the token vocabulary`,
     ].filter(Boolean);

package/dist/guide.js

@@ -426,14 +426,21 @@ own entry below says so.
     const hasRules = (payload.rules?.length ?? 0) > 0;
     const philosophy = payload.document.philosophy;
     const hasPhilosophy = (philosophy?.sections?.length ?? 0) > 0 || !!philosophy?.context;
-    const readFirst = [
-        hasRules
-            ? `**Read \`_synthesisui/ds/${slug}/rules.md\` FIRST and obey it above everything else** - it carries this system's accumulated, project-specific rules; on any conflict they win.`
-            : "",
-        hasPhilosophy
-            ? `**${hasRules ? "Then read" : "Read"} \`_synthesisui/ds/${slug}/philosophy.md\`** - the mission, principles, voice and motion doctrine. Let it shape every screen you build.`
-            : "",
-    ].filter(Boolean);
+    /**
+     * UMA PORTA SÓ, e ela é uma FERRAMENTA e não um caminho.
+     *
+     * Isto apontava para `rules.md` e `philosophy.md`, escritos apenas pelo `add` - então entre um
+     * upgrade e outro o agente lia uma cópia velha de dado versionado, sob a etiqueta "highest
+     * authority". `system_doctrine` serve os dois da versão PINADA (a mesma dos tokens no disco) e diz
+     * quando existe uma mais nova, em vez de deixar a defasagem ser descoberta pela ausência.
+     */
+    const readFirst = hasRules || hasPhilosophy
+        ? [
+            `**Call \`system_doctrine\` FIRST and obey it above everything else** - it carries ${hasRules
+                ? "this system's accumulated, project-specific rules"
+                : "this system's mission, principles, voice and motion doctrine"}${hasRules && hasPhilosophy ? " and its philosophy" : ""}, pinned to the version installed here. On any conflict they win. **Without that tool, read \`_synthesisui/ds/${slug}/doctrine.json\` and the \`philosophy\` of \`design-system.json\` beside it** - the same data, and the reason it stays on disk.`,
+        ]
+        : [];
     const rulesNote = readFirst.length > 0
         ? `
 ## Read first - highest authority

package/package.json

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