synthesisui 0.16.421 → 0.16.423

package/dist/claude-md.js

@@ -158,34 +158,21 @@ best reasoning you produce.`;
  * agent is pointed at the harmless half and told to ask for the other.
  */
 /**
- * THE ONE THING MOST LIKELY TO ALREADY BE IN THE PROJECT.
+ * A PONTE DO SHADCN SAIU DAQUI EM 11/09 - `INV-GERAL-13`.
  *
- * Every system compiles a `shadcn.css` mapping shadcn's whole variable contract
- * onto its own tokens. It has been generated into every project since it was
- * built and nothing ever mentioned it, so the feature that answers "why not just
- * use shadcn" was sitting unimported in the repo of the person who asked.
+ * O QUE ESTE PARÁGRAFO FAZIA: mandava o agente dele colar `@import "_synthesisui/ds/<slug>/shadcn.css"`
+ * na folha dele, para que os componentes shadcn do projeto vestissem o sistema em vez dos defaults
+ * do shadcn. O valor é real - era a resposta para *"por que não só usar shadcn?"* -, e a forma
+ * estava errada: um bloco escrito no `CLAUDE.md` dele, que ele lê a cada sessão, pedindo um import
+ * da nossa folha.
  *
- * Told to the AGENT and not only to the person, because the agent is who reaches
- * for a shadcn block. Left to guess, it installs `dashboard-01` and gets a
- * sidebar on shadcn's defaults next to components wearing the system, which
- * reads as a broken product rather than a missing import.
+ * ERA O PIOR LUGAR PARA A INSTRUÇÃO EXISTIR. Um comentário no terminal rola; este bloco é lido por
+ * todo agente em toda sessão, e um agente obediente cola a linha sem que uma pessoa decida nada.
  *
- * Conditional on `components.json`: a project without shadcn must not carry a
- * paragraph about it.
+ * A ponte continua sendo compilada e continua caindo em `_synthesisui/ds/<slug>/`, como insumo
+ * nosso. Vestir os componentes shadcn dele é uma frente própria, e ela se resolve como o resto do
+ * produto: escrevendo no vocabulário DELE, não pedindo que ele carregue o nosso.
  */
-const SHADCN = (slug) => `
-
-**This project has shadcn, and this system already speaks its language.** A
-generated bridge maps shadcn's whole variable contract - colour, charts, radius,
-the sidebar family - onto this system's tokens, in both schemes:
-
-    @import "_synthesisui/ds/${slug}/shadcn.css";
-
-after the tokens.css import, in the same stylesheet. With that line in place,
-shadcn components wear this system and need no edits from you. Without it they
-stay on shadcn's defaults, which looks like the design system failing rather than
-one import missing - so check for it before you add a shadcn component, and add
-it if it is not there.`;
 /**
  * A REGRA QUE TIRA O "O DEV FAZ ALGO", e ela vale para todo agente que lê este bloco.
  *
@@ -462,9 +449,9 @@ is no component index for an adopted system: the tokens ARE the contract.
 \`system_doctrine\` for the rules and the voice, \`find_token\` for a value you are about to write.${memoryLine}${selfCheck}`
             : `**These are true without asking anyone:**
 
-- Semantic tokens only - \`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`. No raw values outside this
-  system's scale.
-- Scope the UI with \`data-ds="<slug>"\` and reuse the \`.ds-*\` classes.
+- The system's vocabulary only - and it is written in the names THIS project declares. \`find_token\`
+  answers with the exact name for a value you are about to write. No raw values outside the scale,
+  and never a name from a stylesheet this project does not have.
 - To override a style a component already sets, use this system's semantic role class - never \`!\`.
   If the override is ignored, regenerate that component: older ones predate the resolver.
 - Motion is selection, not improvisation. The base is quiet: nothing moves until a person asks, and
@@ -489,9 +476,10 @@ project's OWN custom properties, exactly as the guide lists them. Do not write r
 spacings or radii that a token already covers, and do not invent a new token silently - say so
 instead, because a new token is a decision for a person to make. There is no component
 manifest for an adopted system - the tokens ARE the contract.${selfCheck}`
-            : `**When creating or editing components, read the system's GUIDE.md and follow it:** use only semantic tokens
-(\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), scope the UI with \`data-ds="<slug>"\`,
-and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale.
+            : `**When creating or editing components, read the system's GUIDE.md and follow it:** use the
+vocabulary it lists - every name in it is a name THIS project already declares, written exactly as
+you would write it. Do not use raw values outside the system's scale, and never a name from a
+stylesheet this project does not have.
 
 **Before creating any UI element, look it up in the manifest below.** If something there
 already covers the purpose, do not write it from scratch - run
@@ -539,16 +527,9 @@ element. Write every user-facing string in that language - labels, empty states,
 \`alt\`. A screen reader pronounces \`aria-label\` using \`lang\`, so a mixed-language interface is
 worse than an untranslated one. If the attribute is wrong, change it rather than writing against
 it.`;
-    // Named for the first installed system: the bridge is per-system, and a
-    // project with two of them has already chosen which one dresses the app.
-    const bridgeable = installed.find((d) => !d.adopted);
-    const shadcn = bridgeable &&
-        (await readFile(join(projectRoot, "components.json"), "utf8").then(() => true, () => false))
-        ? SHADCN(bridgeable.slug)
-        : "";
     const body = `## Design Systems (via SynthesisUI)
 
-This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}${shadcn}
+This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}
 
 ${sections.join("\n")}
 

package/dist/commands/add.js

@@ -5,7 +5,7 @@ import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, readToken, resolveRegistry } from "../config.js";
 import { parseRules } from "../doctrine.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
-import { detectAppDirs, globalSheetOf, prefixFrom } from "../global-sheet.js";
+import { detectAppDirs } from "../global-sheet.js";
 import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
 import { censusScope } from "../measured-scope.js";
@@ -17,6 +17,7 @@ import { repoStateOf } from "../repo-state.js";
 import { describeFiltered, ruleApplies, rulesForProject, } from "../rule-filter.js";
 import { detectStack } from "../stack.js";
 import { onlyWhatMatched } from "../their-theme.js";
+import { tongueOf } from "../their-tongue.js";
 import { pointTokensAtTheirNames } from "../their-vars.js";
 import { tracksAnyOf } from "../tracked.js";
 /**
@@ -225,6 +226,19 @@ export async function add(slug, opts) {
      * componente em vez de por arquivo.
      */
     await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document)}\n`, "utf8");
+    /**
+     * E A CÓPIA DO QUE FOI INSTALADO, ao lado - é ela que faz o `sync` saber o que o agente dele
+     * mudou depois.
+     *
+     * O que o cliente ganha: o ciclo fecha sem uma ida à rede. Ele cola o prompt que a plataforma
+     * montou, o agente edita `design-system.json`, roda o `sync` - e o comando compara os dois
+     * arquivos aqui mesmo. Sem este baseline, a única forma de saber o que mudou seria perguntar
+     * ao servidor a cada `sync`, e um `sync` offline não conseguiria nem isso.
+     *
+     * O PONTO NA FRENTE não é estética: `.installed.json` é registro nosso desta pasta, como o
+     * `.lock`, e não um artefato que ele lê. Ver `local-edits.ts`.
+     */
+    await writeFile(join(versionDir, ".installed.json"), `${JSON.stringify(payload.document)}\n`, "utf8");
     /**
      * 3. O GUIA - e o catálogo só é COPIADO onde não há caminho de volta.
      *
@@ -245,7 +259,16 @@ export async function add(slug, opts) {
      * certa, não uma falha - lá não existe `next/font` para ter peso nenhum.
      */
     const fontFacts = await nextFontFacts(projectRoot);
-    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload, tools.available, fontFacts), "utf8");
+    /**
+     * O GUIA FALA A LÍNGUA DELE - `INV-GERAL-13`, e a folha REESCRITA é a fonte.
+     *
+     * `theirVars.css` é o `tokens.css` já apontado para o vocabulário dele nesta máquina, que é
+     * exatamente o que caiu na pasta um passo acima. Ler dali, e não do payload cru, é o que garante
+     * que o guia e o componente materializado digam o MESMO nome para o mesmo valor - duas leituras
+     * da mesma folha, uma delas livre para discordar, é a forma de dois textos nossos ensinarem dois
+     * vocabulários.
+     */
+    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload, tools.available, fontFacts, tongueOf(theirVars.pairs, theirVars.css)), "utf8");
     // 4. stable root re-exports for each CSS artifact → always the active version,
     //    so the consumer's @import path never changes across updates
     const cssArtifacts = Object.keys(payload.artifacts).filter((f) => f.endsWith(".css") && !(f === "shadcn.css" && !wantsShadcn));
@@ -461,8 +484,18 @@ export async function add(slug, opts) {
         ...Object.keys(payload.artifacts).filter((f) => !(f === "shadcn.css" && skipped)),
         "design-system.json",
         "GUIDE.md",
+        ".installed.json",
     ];
     console.log(`  v${v}/: ${files.join(", ")}`);
+    /**
+     * O ARQUIVO NOVO É ANUNCIADO, e não plantado em silêncio - lei 8.
+     *
+     * Ele é versionado junto com o resto da pasta de propósito: assim um colega que clona tem o
+     * baseline e o `sync` dele funciona. Mas um arquivo de ponto que nasce sem aviso e reaparece
+     * no `git status` a cada sync é o atrito que a régua do `census.json` foi desenhada para
+     * evitar - e a diferença entre os dois é uma frase.
+     */
+    console.log(`  (.installed.json records what was installed, so \`sync\` can tell what you changed)`);
     /**
      * O QUE NÃO FOI ESCRITO, DITO EM VOZ ALTA - lei 8, e ela vale nos dois sentidos.
      *
@@ -585,106 +618,40 @@ export async function add(slug, opts) {
         : `  CLAUDE.md updated - your file is intact, with our block inside it (${claudeMd.count} system(s) indexed)`);
     if (opts.setupHints === false)
         return;
-    const hasTheme = cssArtifacts.includes("theme.css");
     // ── DX: concrete paths + copy-pasteable snippets, with breathing room ──
-    // Where the app actually lives (app/ vs src/app/) drives every printed
-    // path: the @import depth, the layout example, and where fonts.ts lands.
+    // Where the app actually lives (app/ vs src/app/) still drives where `fonts.ts`
+    // lands and which layout the snippet names. The @import depth went with the
+    // setup block - see the comment below.
     const projectConfig = await readProjectConfig(projectRoot);
     const appDirs = await detectAppDirs(projectRoot, projectConfig.pagesDir);
     /** Nenhuma pasta encontrada: os caminhos viram exemplo, e o texto abaixo diz isso. */
     const appDir = appDirs[0] ?? projectConfig.pagesDir;
     const appDirFound = appDirs.length > 0;
     /**
-     * A FOLHA GLOBAL QUE ELE DE FATO CARREGA - ver `globalSheetOf`.
+     * O SETUP SAIU DAQUI EM 11/09 - `INV-GERAL-13`, e eram os dois `@import` mais o `data-ds`.
      *
-     * A instrução mandava editar `<appDir>/globals.css`. MEDIDO em 01/09 no `codelevel`: os dois apps
-     * dele fazem `@import "@repo/ui/styles/globals.css"`, e o `globals.css` do app diz em comentário
-     * *"Do not redeclare tokens or fonts here"*. O arquivo certo era o do pacote, e a gente apontava
-     * para o do app - com o caminho relativo do app, que dali não resolve.
-     */
-    const sheet = await globalSheetOf(projectRoot, `${appDir}/globals.css`);
-    const importPrefix = prefixFrom(sheet);
-    console.log(section("One-time setup (once per app)"));
-    /**
-     * QUANDO O SETUP É NECESSÁRIO, E QUANDO ELE É UMA ESCOLHA - a última porta onde a pergunta faltava.
+     * O QUE O DONO VIU, e é o que abriu esta etapa: o `upgrade` imprimiu
      *
-     * O `doctor` e o `component` passaram a perguntar antes de cobrar (ver `sheet-needed.ts`, 07/09,
-     * a partir da objeção do dono: *"esse import gera dependência ao design system, e a gente quer
-     * isolar os dois pontos - o nosso deve ser apenas uma REFERÊNCIA"*). Aqui a pergunta não tem como
-     * ser respondida da mesma forma: o sistema acabou de ser instalado e não há código gerado para
-     * medir.
+     *     @import "../../../../_synthesisui/ds/codelevel/tokens.css";
+     *     @import "../../../../_synthesisui/ds/codelevel/theme.css";
      *
-     * O QUE MUDA É A HONESTIDADE DO ENUNCIADO. "One-time setup" lido logo após a instalação soa como
-     * obrigação, e para metade dos casos ele não é: quem vai trazer componentes como CÓDIGO SEU não
-     * precisa de folha nenhuma - o `component` traduz para o vocabulário do próprio repositório e diz,
-     * arquivo a arquivo, se sobrou algo. Quem vai ESCREVER as classes do sistema (`bg-brand`,
-     * `rounded-lg` no valor dele) precisa, porque só o `@theme` do adaptador as gera.
+     * e a resposta dele foi *"não! isso nunca deve acontecer, a gente havia combinado isso"*.
      *
-     * Então a instrução continua inteira - suprimi-la entregaria um projeto sem as classes - e ganha a
-     * linha que diz QUAL dos dois casos exige cada coisa. A escolha volta a ser dele, informada.
-     */
-    console.log(line("(needed if you will WRITE this system's utility classes - only its @theme generates them."));
-    console.log(line(" Bringing components in as YOUR code needs none of it: `component` translates them into"));
-    console.log(line(" your own vocabulary and tells you, per file, if anything is left.)"));
-    console.log("");
-    /**
-     * "ONCE PER APP" É LITERAL NUM MONOREPO, e calar os outros apps entrega metade da fiação. Os
-     * caminhos abaixo são de um só; sem esta linha o cliente conclui que o repositório inteiro está
-     * ligado quando só o primeiro está.
+     * A INSTRUÇÃO EXISTIA POR UMA RAZÃO REAL, e a razão acabou. Sem a folha carregada, o
+     * `var(--ds-*)` que a plataforma escrevia não resolvia e o componente chegava sem cor. Nada que
+     * a plataforma escreve carrega mais uma variável nossa (`their-tongue.ts`) nem um utilitário que
+     * dependa do nosso `@theme` (`theirThemeVars`), então não há nada para o app dele carregar.
+     *
+     * O QUE A PASTA PASSA A SER, e é o que ele descreveu em 07/09: *"só pra gente ter uma base para
+     * interpretar o design da pessoa e replicar no nosso lado"*. `tokens.css` e `theme.css` continuam
+     * caindo em `_synthesisui/ds/<slug>/` como INSUMO - o hook, o doctor e o MCP os leem para
+     * interpretar o design dele. O que muda é que aquilo deixou de ser folha que o app dele importa.
      */
-    if (appDirs.length > 1)
-        console.log(line(`(${appDirs.length} apps here: ${appDirs.join(", ")} - the paths below are for ${appDir}; repeat for the others.)`));
-    console.log(line(sheet === `${appDir}/globals.css`
-        ? `1. Import the system in your GLOBAL stylesheet, e.g. ${sheet}`
-        : `1. Import the system in ${sheet} - that is the sheet your apps load (${appDir}/globals.css only re-exports it, so tokens put there would not reach the package's own components):`));
-    console.log(line(`   (the path is relative to that file - hence the leading ${importPrefix}):`));
-    console.log("");
-    // THE BRIDGE ONLY EXISTS FOR PEOPLE WHO ALREADY HAVE SHADCN, so it only
-    // appears for them. Every system compiles a `shadcn.css` mapping shadcn's
-    // whole variable contract onto its own tokens, and until 28/07 nothing said
-    // so - not this output, not the managed block, not the GUIDE beyond a filename
-    // in a list. The person it mattered most to asked "I don't get the use case, I
-    // can just build a design system with shadcn", with the answer sitting
-    // unimported in his own repo. Naming it to everybody would be noise; naming it
-    // to whoever has `components.json` is the whole feature arriving.
-    /** A MESMA pergunta que decide a ESCRITA - ver `wantsShadcn`. Duas leituras seriam duas regras. */
-    const hasShadcn = await wearsShadcn(projectRoot);
-    console.log(snippet([
-        ...(hasTheme ? [`@import "tailwindcss";`] : []),
-        `@import "${importPrefix}_synthesisui/ds/${payload.slug}/tokens.css";`,
-        ...(hasTheme
-            ? [
-                `@import "${importPrefix}_synthesisui/ds/${payload.slug}/theme.css";  /* Tailwind utilities on your tokens */`,
-            ]
-            : []),
-        ...(hasShadcn
-            ? [
-                `@import "${importPrefix}_synthesisui/ds/${payload.slug}/shadcn.css";  /* your shadcn components, wearing this system */`,
-            ]
-            : []),
-    ]));
-    if (hasShadcn) {
-        console.log("");
-        console.log(line(`   You have shadcn here. That third line maps its whole variable contract`));
-        console.log(line(`   onto this system - colour, charts, radius and the sidebar - so its`));
-        console.log(line(`   components stop using shadcn's defaults. Both schemes included.`));
-    }
-    console.log("");
-    console.log(line(`2. Scope your app: add data-ds="${payload.slug}" to a ROOT element, e.g. ${appDir}/layout.tsx:`));
-    console.log("");
-    console.log(snippet([
-        `<body data-ds="${payload.slug}" className="bg-canvas">{children}</body>`,
-    ]));
-    // THE SCOPE DELIBERATELY DOES NOT PAINT A BACKGROUND, and every project hits
-    // it. `[data-ds]` sets ink and body family only, because scopes NEST: a dark
-    // contrast section over a photograph carries its own nested `data-ds` so its
-    // tokens remap, and a background on every scope would paint over the picture.
-    // So the page background is the root element's job, and saying so here is the
-    // fix - an agent found this by reading rendered CSS on 28/07 and had to
-    // deduce it.
-    console.log(line(`   \`bg-canvas\` is not optional: the scope sets text colour and type, not the page`));
-    console.log(line(`   background. Scopes nest (a dark section carries its own), so painting every one`));
-    console.log(line(`   would cover whatever is behind it.`));
+    console.log(section("What landed, and what it is for"));
+    console.log(line(`_synthesisui/ds/${payload.slug}/ is ours to READ - the check, the doctor and the MCP`));
+    console.log(line(`server use it to interpret your design. Nothing in your app imports it, and nothing`));
+    console.log(line(`we write into your repository needs it at runtime: a component arrives speaking the`));
+    console.log(line(`names YOUR code declares, or carrying the value itself.`));
     // 3. Load the type - the DS ships token NAMES, not the fonts themselves.
     //    Next apps get fonts.ts MATERIALIZED (deterministic does, not teaches):
     //    next/font = self-hosted + preloaded + adjusted fallback, no FOUT
@@ -700,9 +667,7 @@ export async function add(slug, opts) {
     const fontPlan = projectConfig.target === "next"
         ? nextFontSnippet({
             families,
-            slug: payload.slug,
             appDir,
-            seam: payload.fontSeam,
             facts: fontFacts,
             declaredWeights: payload.document.foundations.typography.weights,
         })
@@ -778,9 +743,7 @@ export async function add(slug, opts) {
                 continue;
             const plan = nextFontSnippet({
                 families,
-                slug: payload.slug,
                 appDir: dir,
-                seam: payload.fontSeam,
                 facts: fontFacts,
                 declaredWeights: payload.document.foundations.typography.weights,
             });