synthesisui 0.16.244 → 0.16.247

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { provenanceAction, toolSlug, withSource, } from "../agent-provenance.js";
 import { pinnedHookVersion } from "../agent-wiring.js";
+import { composePlan, FAMILIES, isFamily, noFamilyAnswer, renderPlan, } from "../compose-context.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
 import { fileRequest } from "../doctor/requests.js";
@@ -122,14 +123,14 @@ const TOOLS = [
     },
     {
         name: "playbook",
-        description: "The skill playbooks (init, import, adapt) - SERVED, not shipped, so they are always current and your context only carries the step you are on. Call with { skill } to get the framing and a table of contents; then fetch ONLY the chapter for your current step with { skill, section }. Never fetch more than the step needs.",
+        description: "The skill playbooks (init, import, adapt, compose) - SERVED, not shipped, so they are always current and your context only carries the step you are on. Call with { skill } to get the framing and a table of contents; then fetch ONLY the chapter for your current step with { skill, section }. Never fetch more than the step needs. `compose` is the hierarchy to walk when this system has no recipe for what you were asked to build - the layers it DOES have, in order.",
         inputSchema: {
             type: "object",
             properties: {
                 skill: {
                     type: "string",
-                    enum: ["init", "import", "adapt"],
-                    description: "Which playbook.",
+                    enum: ["init", "import", "adapt", "compose"],
+                    description: "Which playbook. `compose` is the one for building something this system has no recipe for.",
                 },
                 section: {
                     type: "string",
@@ -184,6 +185,24 @@ const TOOLS = [
             required: ["recipes"],
         },
     },
+    {
+        name: "compose_context",
+        description: "The layers to build something this system has NO recipe for, in one call: the recipes of that family to copy from, the tokens they already use with their values, the system's rules, and the floor and checklist for the family. YOU say which family it is - you just read the request, and a keyword guess of ours would be worse. Call this instead of asking for doctrine, vocabulary and each token separately; the laws of markup and the voice are named in the answer with the one fetch each needs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                family: {
+                    type: "string",
+                    description: `Which family this behaves like: ${FAMILIES.join(", ")}. Pick by BEHAVIOUR, never by the name in the request. If a part fits none of them, send what you would call it and the answer says what to do.`,
+                },
+                intent: {
+                    type: "string",
+                    description: "What you are building, in a few words - it is echoed back so your summary can name it.",
+                },
+            },
+            required: ["family"],
+        },
+    },
     {
         name: "request_component",
         description: "File a component request when nothing in the catalogue covers what you need. This is the OTHER HALF of the refusal rule: you already say which entry you considered and why it did not fit - said in chat, that reasoning evaporates; filed here, it becomes the queue the system's author works from. File it at the moment you build the workaround, while the reasoning is still yours.",
@@ -962,7 +981,16 @@ async function describeComponent(root, name) {
          * vale ser construído, e para quais famílias primeiro.
          */
         return {
-            body: `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`,
+            /**
+             * ANTES ESTA FRASE TERMINAVA EM "não escreva do zero" E DEIXAVA O AGENTE
+             * SOZINHO - e o `request_component` completava com "siga com a sua solução
+             * alternativa". Juntas, elas diziam à esteira para registrar o improviso
+             * em vez de guiá-lo (dono, 18/08).
+             *
+             * Não ter a receita não é cair no zero: as camadas base existem, e agora
+             * há um playbook que as percorre em ordem. A frase aponta para ele.
+             */
+            body: `This system has no component called "${name}". Run list_components to see what it does have - a near miss still means composing WITH it rather than around it.\n\nIf nothing covers it, do not write from scratch and do not improvise: call playbook { "skill": "compose" }. It walks what this system DOES have, in order - its rules and voice, its tokens, the family this belongs to and what that family requires, and the laws that decide the markup. File request_component along the way so the gap becomes a decision somebody can make.`,
             source: {
                 kind: "none",
                 reason: "recipe",
@@ -1186,6 +1214,74 @@ async function runTool(root, name, args) {
             return fromContract(await validateRecipes(root, Array.isArray(args.recipes)
                 ? args.recipes
                 : []));
+        case "compose_context": {
+            /**
+             * A ORQUESTRAÇÃO - e o que ela reúne é do SISTEMA DELE, com o nosso
+             * esqueleto de julgamento por cima.
+             *
+             * Uma chamada em vez de cinco, e a procedência disto é `composed`: o
+             * primeiro caminho da esteira que emite esse kind, que até aqui existia no
+             * vocabulário e não em resposta nenhuma.
+             */
+            const asked = String(args.family ?? "")
+                .trim()
+                .toLowerCase();
+            const intent = String(args.intent ?? "").trim();
+            if (!isFamily(asked)) {
+                return {
+                    body: noFamilyAnswer(asked || "(nothing)"),
+                    source: {
+                        kind: "none",
+                        reason: "family",
+                        detail: `no family fits "${asked}"`,
+                    },
+                };
+            }
+            const { documents, table, doctrines, requires } = await loadSystem(root);
+            if (documents.length === 0) {
+                return {
+                    body: "No design system installed here, so there is nothing to compose from. Run `synthesisui add <slug>` first - composing against nothing would be inventing.",
+                    source: {
+                        kind: "none",
+                        reason: "system",
+                        detail: "no system installed",
+                    },
+                };
+            }
+            const plan = composePlan({
+                documents,
+                table,
+                rules: doctrines.flatMap((d) => d.rules),
+                /**
+                 * A regra tem a FRASE e o PACOTE em campos separados (`text`,
+                 * `requires`) - mandar a frase sozinha esconderia o que instalar, e
+                 * mandar só o pacote esconderia o porquê.
+                 */
+                requires: requires.map((r) => ({
+                    rule: r.requires ? `${r.requires} - ${r.text}` : r.text,
+                })),
+                family: asked,
+                intent,
+            });
+            /** O checklist é servido; sem rede o resto do plano continua valendo. */
+            const answer = await askCatalogue("vocabulary");
+            const v = answer.ok
+                ? answer.body
+                : null;
+            const vocabulary = v
+                ? {
+                    floor: v.floor?.[asked] ?? [],
+                    checklist: v.checklist?.[asked] ?? [],
+                }
+                : null;
+            return {
+                body: renderPlan(plan, vocabulary),
+                source: {
+                    kind: "composed",
+                    detail: `${asked} · ${plan.siblings.length} recipe${plan.siblings.length === 1 ? "" : "s"} and ${plan.tokens.length} token${plan.tokens.length === 1 ? "" : "s"} from this system`,
+                },
+            };
+        }
         case "request_component": {
             const r = await fileRequest(root, {
                 kind: "component",
@@ -1194,7 +1290,7 @@ async function runTool(root, name, args) {
                 considered: args.considered ? String(args.considered) : undefined,
                 file: args.file ? String(args.file) : undefined,
             });
-            return fromContract(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it - keep building with your workaround, and say in your summary that the request exists.`);
+            return fromContract(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it.\n\nNow build it properly rather than working around it: playbook { "skill": "compose" } walks the layers this system already declares, so what you hand back matches it even without a recipe. Say in your summary that the request exists, and which parts were composed rather than taken from the system.`);
         }
         case "refresh_system": {
             /**

package/dist/compose-context.js

@@ -0,0 +1,210 @@
+/**
+ * O CONTEXTO MÍNIMO PARA CONSTRUIR ALGO QUE O SISTEMA NÃO TEM.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * AS DUAS FONTES, E A PROPORÇÃO ENTRE ELAS SE INVERTE SOZINHA
+ *
+ * O material que enche este contexto é DELE - os tokens que as receitas dele já
+ * usam, as regras que ele declarou, as bibliotecas que o repositório dele
+ * carrega. É isso que faz o componente novo nascer parecido com o sistema dele
+ * em vez de parecido com o nosso gosto.
+ *
+ * O que é NOSSO é pequeno de propósito e não fala de nenhum componente
+ * específico: as sete famílias, o checklist de cada uma e as leis de marcação.
+ * Sem essa metade, um sistema de dois componentes - e existem quatro deles em
+ * produção, medido em 18/08 - não teria nada a oferecer justamente a quem mais
+ * precisa de orientação.
+ *
+ * Sistema maduro: "o seu input usa estes sete tokens, use os mesmos" (paridade).
+ * Sistema novo: "um campo precisa destas cinco coisas, o seu sistema ainda não
+ * nomeia três delas" (orientação, com a lacuna declarada).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * A FAMÍLIA VEM DE QUEM PEDE, e a plataforma valida (decisão do dono, 18/08)
+ *
+ * Quem chama esta ferramenta é um modelo que acabou de ler o pedido em linguagem
+ * natural. Ele classifica melhor que qualquer heurística de palavras que a gente
+ * escrevesse aqui, e classificar com IA hospedada gastaria Ink para responder o
+ * que já foi respondido do outro lado da chamada.
+ *
+ * Então o agente informa a família, a gente confere contra o contrato, e quando
+ * ela não é nenhuma das sete isso não é erro: é uma lacuna de FAMÍLIA, que é uma
+ * decisão diferente de um componente faltando.
+ */
+/** As sete que o contrato conhece - o mesmo enum de `componentPreviewKind`. */
+export const FAMILIES = [
+    "action",
+    "control",
+    "field",
+    "surface",
+    "pill",
+    "indicator",
+    "text",
+];
+export function isFamily(value) {
+    return FAMILIES.includes(value);
+}
+/**
+ * OS TOKENS QUE ESTA FAMÍLIA JÁ USA, lidos das receitas dela.
+ *
+ * Uma referência de token num documento é `{color.semantic.canvas}` - a mesma
+ * forma que o compilador resolve. Então "quais tokens um campo usa neste
+ * sistema" é uma pergunta que o próprio documento responde, sem tabela nossa e
+ * sem palpite.
+ *
+ * MEDIDO no signalui (37 componentes, 74 referências no total): field 37,
+ * surface 37, control 33, action 24, pill 17, text 15, indicator 12. O corte por
+ * volume é modesto num sistema pequeno - o valor aqui não é economia de
+ * contexto, é PARIDADE: o agente copia o que existe em vez de escolher.
+ */
+export function tokensOfFamily(documents, family) {
+    const refs = new Set();
+    for (const doc of documents) {
+        const components = doc
+            .components;
+        if (!components)
+            continue;
+        for (const recipe of Object.values(components)) {
+            if (recipe?.preview?.kind !== family)
+                continue;
+            for (const ref of JSON.stringify(recipe).match(/\{[a-z0-9.]+\}/gi) ??
+                []) {
+                /**
+                 * `{onPressedChange}` e afins aparecem no mesmo formato e NÃO são
+                 * tokens - são nomes de prop que a receita cita. Um token tem caminho:
+                 * família, e depois pelo menos um degrau.
+                 */
+                if (ref.includes("."))
+                    refs.add(ref);
+            }
+        }
+    }
+    return [...refs].sort();
+}
+/** As receitas desta família que o sistema já tem - de onde copiar. */
+export function recipesOfFamily(documents, family) {
+    const out = [];
+    for (const doc of documents) {
+        const components = doc
+            .components;
+        if (!components)
+            continue;
+        for (const [name, recipe] of Object.entries(components)) {
+            if (recipe?.preview?.kind === family) {
+                out.push({
+                    name,
+                    ...(recipe.description ? { description: recipe.description } : null),
+                });
+            }
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * O VALOR DE CADA REFERÊNCIA, quando a tabela o conhece.
+ *
+ * `{radius.md}` sozinho não diz nada a quem vai escrever css; `{radius.md} =
+ * 0.5rem` diz. A tabela de tokens é a mesma que o `find_token` consulta, então
+ * a resposta aqui e a resposta dele nunca divergem.
+ */
+export function valueOf(table, ref) {
+    const path = ref.slice(1, -1);
+    /** `color.semantic.canvas` -> `--ds-color-semantic-canvas`. */
+    const name = `--ds-${path.replace(/\./g, "-")}`;
+    return table.byName.get(name) ?? null;
+}
+/**
+ * A MONTAGEM - pura, e é por isso que ela mora fora do handler.
+ *
+ * O handler faz I/O (`loadSystem`, a rede do catalogue). O que decide o que
+ * entra no contexto é isto, e é o que um spec consegue exercer com um documento
+ * de verdade sem subir nada.
+ */
+export function composePlan(input) {
+    const refs = tokensOfFamily(input.documents, input.family);
+    return {
+        family: input.family,
+        intent: input.intent,
+        siblings: recipesOfFamily(input.documents, input.family),
+        tokens: refs.map((ref) => ({ ref, value: valueOf(input.table, ref) })),
+        rules: [...input.rules],
+        requires: [...input.requires],
+    };
+}
+/**
+ * O PLANO COMO O AGENTE O LÊ - e a ordem é a das camadas, não a da comodidade.
+ *
+ * Cada bloco diz de onde veio: o que é do sistema dele, o que é checklist nosso,
+ * e o que ninguém decidiu ainda. É a mesma gramática da linha `Source:` que toda
+ * resposta carrega, um nível abaixo - e é o que permite ao agente relatar
+ * procedência por parte em vez de por resposta.
+ */
+export function renderPlan(plan, 
+/** O checklist e o piso desta família, servidos do catálogo. `null` sem rede. */
+vocabulary) {
+    const out = [
+        `COMPOSING: ${plan.intent || plan.family}`,
+        `FAMILY: ${plan.family} - every part below answers to this family's checklist.`,
+        "",
+    ];
+    out.push("── FROM THIS SYSTEM ────────────────────────────────────────");
+    if (plan.siblings.length > 0) {
+        out.push(`Recipes in this family, to copy from rather than to choose against (${plan.siblings.length}):`, ...plan.siblings.map((s) => `  ${s.name}${s.description ? ` - ${s.description}` : ""}`));
+    }
+    else {
+        out.push("This system has NO recipe in this family yet. Nothing here to copy, so", "every decision below is one you are making for the first time - name them", "in your summary, and file what the system should have named.");
+    }
+    out.push("");
+    if (plan.tokens.length > 0) {
+        out.push(`Tokens those recipes already use (${plan.tokens.length}) - use these before any literal:`, ...plan.tokens.map((t) => `  ${t.ref}${t.value ? ` = ${t.value}` : " (name declared, value not on disk)"}`));
+    }
+    else {
+        out.push("No token is used by this family yet. Ask `find_token` for each value you", "need, and file `request_token` for the ones nothing holds - never invent a name.");
+    }
+    if (plan.rules.length > 0) {
+        out.push("", `Rules - maximum authority, ${plan.rules.length} of them:`, ...plan.rules.map((r) => `  - ${r}`));
+    }
+    if (plan.requires.length > 0) {
+        out.push("", "Packages this system says the project needs:", ...plan.requires.map((r) => `  - ${r.rule}`));
+    }
+    out.push("", "── THE FLOOR FOR THIS FAMILY ───────────────────────────────");
+    if (vocabulary) {
+        if (vocabulary.floor.length > 0) {
+            out.push("Below this it cannot be told apart from the page:");
+            out.push(...vocabulary.floor.map((f) => `  ${f}`));
+        }
+        out.push("", "Work this list and say which items this system's own recipes answer:", ...vocabulary.checklist.map((c) => `  - ${c}`));
+    }
+    else {
+        out.push("The checklist is served from the platform and could not be reached right", "now. Everything above still holds - fetch it with `recipe_vocabulary`", "before you call the component finished.");
+    }
+    out.push("", "── WHAT IS NOT HERE ────────────────────────────────────────", "The laws that decide the markup (which tag, whose layout wins, why", "accessibility moves the ink) are one fetch away and not repeated here:", '  playbook { "skill": "compose", "section": "path-2-layer-3-the-laws-that-decide-the-markup" }', "", "The voice - how this product speaks - is not in this answer either. Call", "`system_doctrine` before writing any user-facing copy inside this component.", "", "When you are done: `validate_recipe` if you are writing one, then", "`request_component` for what the system should have had, and report which", "parts came from the system and which you composed.");
+    return out.join("\n");
+}
+/**
+ * A RESPOSTA QUANDO A FAMÍLIA NÃO É NENHUMA DAS SETE.
+ *
+ * Não é erro e não é uma lista de sugestões parecidas: é um fato sobre o
+ * contrato, e o pedido de quem o lê é diferente do pedido de um componente. Um
+ * gráfico, um mapa, uma grade de calendário não são `surface` mal classificado -
+ * forçá-los ali produziria um piso que não significa nada.
+ */
+export function noFamilyAnswer(asked) {
+    return [
+        `"${asked}" is not one of the seven families this contract can draw: ${FAMILIES.join(", ")}.`,
+        "",
+        "That is a real answer, not a rejection. Two things are true at once:",
+        "",
+        "  1. Everything ABOVE the family layer still holds in full - the system's",
+        "     rules, its tokens, and the laws of markup. Ask `find_token` per value,",
+        "     `system_doctrine` for the rules, and fetch the laws chapter of the",
+        "     compose playbook.",
+        "  2. What is missing is a KIND, not a component - and that is a different",
+        "     decision for the system's owner. File it:",
+        "     request_component with what the thing is and why no family fits.",
+        "",
+        "Then decompose: parts of it probably DO have families. A region that holds",
+        "things is a surface, a control inside it is a control - ask again for those",
+        "parts, and compose the rest without a family, saying so.",
+    ].join("\n");
+}

package/dist/skill-compose.js

@@ -0,0 +1,22 @@
+/**
+ * O STUB DA SKILL DE COMPOSIÇÃO - o corpo é SERVIDO, como os outros três.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * POR QUE ESTA SKILL EXISTE (dono, 18/08)
+ *
+ * As três primeiras cobrem trazer um sistema para dentro e mantê-lo. Nenhuma
+ * cobria o gesto mais comum do dia a dia: alguém pede um componente que o
+ * sistema não tem.
+ *
+ * E o que a plataforma respondia nesse caso eram duas frases, medidas:
+ * `describe_component` dizia *"não escreva do zero"* e `request_component`
+ * dizia, na frase seguinte, *"siga com a sua solução alternativa"*. Ou seja, a
+ * esteira registrava que o agente improvisou em vez de guiar a composição - o
+ * oposto de uma hierarquia de conhecimento.
+ *
+ * A tese do dono: não ter a receita não é cair no zero. As camadas base
+ * existem - tokens, regras, a família e o que o tipo dela exige, as leis de
+ * marcação - e compor a partir delas é tão valioso quanto ter a receita pronta.
+ */
+export const COMPOSE_SKILL_PATH = ".claude/skills/sui-compose/SKILL.md";
+export const COMPOSE_SKILL = '---\nname: sui-compose\ndescription: Build ANY UI element the installed design system has no recipe for - without inventing values, tags or accessibility. Use whenever you are about to write a UI element from scratch, when `describe_component` answers that the system does not have it, or when what was asked for is a composite nobody has written yet - whatever it is called (an editor, a palette, a table, a chart, a layout region: the playbook does not care which). Walks the layers the system DOES have, in order, decomposes the request into families, and declares what it could not cover.\n---\n\n# Compose what the system does not have - served live\n\nThis playbook is served from the platform, not shipped in this file - it is\nalways current, and your context only carries the step you are on.\n\n1. Call the `playbook` tool on the `synthesisui` MCP server with\n   { "skill": "compose" } - you get the framing and a table of contents.\n2. Fetch ONLY the chapter for the step you are on:\n   { "skill": "compose", "section": "<id from the toc>" }. Never fetch more\n   than the current step needs.\n3. Follow it exactly. When the step is done, fetch the next chapter.\n\nThe first chapter tells you which of the two paths you are on - the system has\na recipe, or nobody has written one yet - and the rest walk the layers in order.\n\nIf the tool answers that you are not signed in, run `npx synthesisui login`\nin the terminal and call it again. If the `synthesisui` MCP server is not\navailable at all, run `npx synthesisui connect`, restart the session, and\ninvoke this skill again.\n';

package/dist/skills.js

@@ -1,4 +1,5 @@
 import { ADAPT_SKILL, ADAPT_SKILL_PATH } from "./skill-adapt.js";
+import { COMPOSE_SKILL, COMPOSE_SKILL_PATH } from "./skill-compose.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "./skill-import.js";
 import { INIT_SKILL, INIT_SKILL_PATH } from "./skill-init.js";
 /**
@@ -36,4 +37,20 @@ export const SKILLS = [
         label: "/sui-adapt",
         what: "one component against the system, and what to do about it",
     },
+    /**
+     * A DE CONSTRUÇÃO, e ela é a que responde ao pedido mais comum de todos:
+     * "faz um componente X" quando o sistema não tem X.
+     *
+     * As três acima são sobre o sistema - trazer, manter, conferir. Esta é sobre o
+     * TRABALHO de quem usa o sistema, e é a única que roda todo dia. Ela existe
+     * porque a resposta anterior a esse pedido era o agente improvisar sozinho: a
+     * esteira dizia "não escreva do zero" e, na frase seguinte, "siga com a sua
+     * solução alternativa" (dono, 18/08).
+     */
+    {
+        path: COMPOSE_SKILL_PATH,
+        source: COMPOSE_SKILL,
+        label: "/sui-compose",
+        what: "build what the system does not have, layer by layer",
+    },
 ];

package/package.json

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