synthesisui 0.16.162 → 0.16.163

package/dist/commands/add.js

@@ -129,13 +129,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 +171,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 +204,18 @@ 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}`);
     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

@@ -70,6 +70,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 +257,73 @@ 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 behind = await newerVersion(root, pinned);
+    return [
+        ...head,
+        ...(parts.length > 0 ? ["", "# Philosophy", "", ...parts] : []),
+        ...(behind ? ["", behind] : []),
+    ].join("\n");
+}
+/**
+ * Existe versão publicada acima da instalada?
+ *
+ * Melhor esforço e nunca bloqueante: offline, sem sessão, ou registry fora do ar devolvem `null` e a
+ * doutrina responde igual. Dizer "não consegui checar" a cada chamada seria ruído numa ferramenta que
+ * o agente chama antes de cada trabalho.
+ */
+async function newerVersion(root, pinned) {
+    if (pinned == null)
+        return null;
+    const slug = await installedSlug(root);
+    const token = await readToken();
+    if (!slug || !token)
+        return null;
+    const res = await fetch(`${resolveRegistry()}/api/registry/ds/${slug}`, {
+        headers: { Authorization: `Bearer ${token}` },
+    }).catch(() => null);
+    if (!res?.ok)
+        return null;
+    const body = (await res.json().catch(() => null));
+    if (!body?.version || body.version <= pinned)
+        return null;
+    return `> 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.`;
+}
 async function listComponents(root) {
     const { documents } = await loadSystem(root);
     const rows = [];
@@ -839,6 +911,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"
             : "",
         `- ${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.`,
+        ]
+        : [];
     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.163",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {