synthesisui 0.16.280 → 0.16.282

package/dist/commands/add.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, rm, writeFile, } from "node:fs/promises";
 import { join } from "node:path";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
@@ -126,16 +126,55 @@ async function readRootLock(path) {
 }
 const exists = (path) => access(path).then(() => true, () => false);
 /**
- * Where the app's routes live: the configured pagesDir at the project root
- * (`app/`) or nested under `src/` (`src/app/` - create-next-app's other
- * layout). Null when neither exists (instructions-only mode).
+ * ONDE AS ROTAS DELE MORAM DE VERDADE - e num monorepo elas não moram na raiz.
+ *
+ * Olhava só `app/` e `src/app/` na raiz. O `codelevel-monorepo` tem `apps/web/app` e
+ * `apps/landing/app`, então a busca voltava null, o `appDir` caía no default `"app"`, e TODO caminho
+ * impresso no setup apontava para uma pasta que não existe: `app/globals.css`, `app/layout.tsx`,
+ * `app/fonts.ts`. O cliente lê três instruções e nenhuma serve para o repositório dele.
+ *
+ * O que faz uma pasta ser raiz de app é o `layout` do App Router morar dentro dela - por isso o
+ * `apps/api` do Nest, que também é um workspace, não entra na lista.
+ *
+ * DEVOLVE TODAS, em ordem determinística: o setup é "once per app" e num monorepo isso é literal.
+ * Escolher uma calada seria acertar uma e errar a outra sem dizer qual.
  */
-async function detectAppDir(root, pagesDir) {
-    if (await exists(join(root, pagesDir)))
-        return pagesDir;
-    if (await exists(join(root, "src", pagesDir)))
-        return `src/${pagesDir}`;
-    return null;
+export async function detectAppDirs(root, pagesDir) {
+    const isAppRoot = async (dir) => {
+        if (!(await exists(join(root, dir))))
+            return false;
+        for (const ext of ["tsx", "jsx", "ts", "js"])
+            if (await exists(join(root, dir, `layout.${ext}`)))
+                return true;
+        return false;
+    };
+    const here = [pagesDir, `src/${pagesDir}`];
+    const nested = [];
+    for (const group of ["apps", "packages"]) {
+        let entries;
+        try {
+            entries = await readdir(join(root, group));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort())
+            nested.push(`${group}/${entry}/${pagesDir}`, `${group}/${entry}/src/${pagesDir}`);
+    }
+    const found = [];
+    for (const dir of [...here, ...nested])
+        if (await isAppRoot(dir))
+            found.push(dir);
+    /**
+     * A RAIZ QUE EXISTE MAS NÃO TEM LAYOUT ainda é o melhor palpite de um app avulso - é o caso de um
+     * `create-next-app` no meio de uma migração. Sem isto, um projeto de app único perderia a detecção
+     * que já funcionava.
+     */
+    if (found.length === 0)
+        for (const dir of here)
+            if (await exists(join(root, dir)))
+                return [dir];
+    return found;
 }
 /**
  * Materializes a published DS into `_synthesisui/ds/<slug>/v<version>/`, points
@@ -355,10 +394,19 @@ export async function add(slug, opts) {
     // Where the app actually lives (app/ vs src/app/) drives every printed
     // path: the @import depth, the layout example, and where fonts.ts lands.
     const projectConfig = await readProjectConfig(projectRoot);
-    const appDir = (await detectAppDir(projectRoot, projectConfig.pagesDir)) ??
-        projectConfig.pagesDir;
+    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;
     const importPrefix = "../".repeat(appDir.split("/").length);
     console.log(section("One-time setup (once per app)"));
+    /**
+     * "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á.
+     */
+    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(`1. Import the system in your GLOBAL stylesheet, e.g. ${appDir}/globals.css`));
     console.log(line(`   (the path is relative to that file - hence the leading ${importPrefix}):`));
     console.log("");
@@ -434,7 +482,14 @@ export async function add(slug, opts) {
             console.log(line("   Finish the wiring with two small edits:"));
         }
         else {
-            console.log(line(`3. Load the type via next/font (${appDir}/fonts.ts already exists - left untouched; it should export:)`));
+            console.log(line(appDirFound
+                ? `3. Load the type via next/font (${appDir}/fonts.ts already exists - left untouched; it should export:)`
+                : /**
+                   * A FRASE DIZIA "already exists" PARA DOIS ESTADOS DIFERENTES, e um deles é o contrário
+                   * disso: não achei a pasta do app. No monorepo dele o arquivo não existia e o terminal
+                   * dizia que existia - o cliente não tem como saber que os caminhos acima são chute.
+                   */
+                    `3. Load the type via next/font (I could not find your app folder from here, so the paths above are examples - create ${appDir}/fonts.ts wherever your app router lives):`));
             console.log("");
             console.log(snippet(nextFonts.fontsFile));
             console.log("");

package/dist/commands/mcp.js

@@ -184,14 +184,14 @@ const TOOLS = [
     },
     {
         name: "playbook",
-        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.",
+        description: "The skill playbooks (init, import, adapt, compose, configure) - 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", "compose"],
-                    description: "Which playbook. `compose` is the one for building something this system has no recipe for.",
+                    enum: ["init", "import", "adapt", "compose", "configure"],
+                    description: "Which playbook. `compose` is the one for building something this system has no recipe for; `configure` is the one for wiring an installed system into the app when its tokens are not reaching the browser.",
                 },
                 section: {
                     type: "string",

package/dist/fonts.js

@@ -12,6 +12,22 @@ const GENERIC_FAMILIES = new Set([
     "inherit",
     "initial",
 ]);
+/**
+ * A PRIMEIRA FAMÍLIA DE UMA PILHA - `"Geist Mono", ui-monospace, monospace` é `Geist Mono`.
+ *
+ * O DOCUMENTO GUARDA A PILHA INTEIRA DE PROPÓSITO: é o que o código dele declara, e a lei 12 diz que
+ * o que ele declarou vence. O que não pode é a pilha virar NOME - e era o que acontecia aqui. O `add`
+ * do codelevel-ui imprimiu, em 22/08, um `fonts.ts` que não compila:
+ *
+ *     export const mono = "Geist_Mono",_ui-monospace,_monospace({   // ← não é JavaScript
+ *
+ * e um href com `family="Geist+Mono",+ui-monospace,+monospace`, que o Google Fonts não resolve. Duas
+ * das quatro vagas do sistema dele saíam quebradas, e o cliente só descobriria colando o snippet.
+ *
+ * Um download pede UM nome de família; a pilha é o fallback do navegador e não viaja na URL. A mesma
+ * regra já existia em `read-unread.ts` na plataforma - existia num lugar e faltava neste.
+ */
+const firstFamily = (value) => (value.split(",")[0] ?? "").trim().replace(/^["']|["']$/g, "");
 /**
  * TODA VAGA DE FONTE DO DOCUMENTO, dedup e sem os genéricos.
  *
@@ -36,7 +52,7 @@ export function customFontFamilies(families) {
     const seen = new Set();
     const names = [];
     for (const slot of familySlots(families)) {
-        const name = families[slot]?.trim();
+        const name = firstFamily(families[slot] ?? "");
         if (!name)
             continue;
         const key = name.toLowerCase();
@@ -68,17 +84,17 @@ export function googleFontsHref(families) {
 export function nextFontSnippet(families, slug, appDir = "app") {
     /** Toda vaga que o documento tem, não só as nossas três - ver `customFontFamilies`. */
     const roles = familySlots(families).filter((role) => {
-        const name = families[role]?.trim();
+        const name = firstFamily(families[role] ?? "");
         return name && !GENERIC_FAMILIES.has(name.toLowerCase());
     });
     if (roles.length === 0)
         return null;
-    const importName = (name) => name.trim().replace(/ /g, "_");
+    const importName = (name) => firstFamily(name).replace(/ /g, "_");
     const seen = new Map(); // family name -> const name
     const importNames = [];
     const consts = [];
     for (const role of roles) {
-        const name = (families[role] ?? "").trim();
+        const name = firstFamily(families[role] ?? "");
         if (!seen.has(name)) {
             seen.set(name, role);
             importNames.push(importName(name));
@@ -101,13 +117,13 @@ export function nextFontSnippet(families, slug, appDir = "app") {
         ...consts,
     ];
     const roleVar = (role) => {
-        const name = (families[role] ?? "").trim();
+        const name = firstFamily(families[role] ?? "");
         return `--font-ds-${seen.get(name)}`;
     };
     const layout = [
         `// ${appDir}/layout.tsx`,
-        `import { ${[...new Set(roles.map((r) => seen.get((families[r] ?? "").trim())))].join(", ")} } from "./fonts";`,
-        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get((families[r] ?? "").trim())}.variable}`))].join(" ")}\`}>`,
+        `import { ${[...new Set(roles.map((r) => seen.get(firstFamily(families[r] ?? ""))))].join(", ")} } from "./fonts";`,
+        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get(firstFamily(families[r] ?? ""))}.variable}`))].join(" ")}\`}>`,
     ];
     const css = [
         `/* ${appDir}/globals.css - AFTER the tokens.css import */`,

package/dist/install-marks.js

@@ -128,7 +128,7 @@
  * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
  * publicar no meio.
  */
-export const MATERIALISER_SINCE = "0.16.278";
+export const MATERIALISER_SINCE = "0.16.281";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/skill-configure.js

@@ -0,0 +1,13 @@
+/**
+ * O STUB DA SKILL - o corpo é SERVIDO, não embarcado (R1, dono 16/08).
+ *
+ * Mesma doutrina das outras quatro: o frontmatter fica inteiro aqui, porque é a `description` que
+ * faz a skill ser invocada e ela não é segredo; a esteira mora em `apps/web/src/lib/ds/playbooks.ts`
+ * e chega pelo catalogue autenticado.
+ *
+ * O QUE ELA RESOLVE: um sistema instalado e sincronizado pode não mudar um pixel na tela dele. Até
+ * uma folha de estilo importar os tokens e um elemento carregar `data-ds`, nada chega ao navegador -
+ * e essa era a única parte da instalação que ninguém escrevia, só imprimia.
+ */
+export const CONFIGURE_SKILL_PATH = ".claude/skills/sui-configure-ds/SKILL.md";
+export const CONFIGURE_SKILL = '---\nname: sui-configure-ds\ndescription: Wire an installed design system into the app so its tokens actually reach the browser - the stylesheet import, the data-ds scope, and the type. Use when a system is installed and the app does not look themed, when `doctor` reports "installed - but not wired up yet", or when somebody asks to set up / connect / configure the design system in their app ("configura o design system aqui", "why aren\'t the tokens working", "/sui-configure-ds"). Asks the doctor first and does nothing when the three checks already pass.\n---\n\n# Wiring the system into the app - 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": "configure" } - you get the framing and a table of contents.\n2. Fetch ONLY the chapter for the step you are on:\n   { "skill": "configure", "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\nStart by running `npx synthesisui doctor`: the three lines it prints are what\ndecide the work, and three ticks means there is nothing to do.\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,5 +1,6 @@
 import { ADAPT_SKILL, ADAPT_SKILL_PATH } from "./skill-adapt.js";
 import { COMPOSE_SKILL, COMPOSE_SKILL_PATH } from "./skill-compose.js";
+import { CONFIGURE_SKILL, CONFIGURE_SKILL_PATH } from "./skill-configure.js";
 import { IMPORT_SKILL, IMPORT_SKILL_PATH } from "./skill-import.js";
 import { INIT_SKILL, INIT_SKILL_PATH } from "./skill-init.js";
 /**
@@ -53,4 +54,19 @@ export const SKILLS = [
         label: "/sui-compose",
         what: "build what the system does not have, layer by layer",
     },
+    /**
+     * A DE LIGAR O SISTEMA NO APP, e ela é a única aqui que fecha um passo que a esteira já sabia
+     * diagnosticar e não sabia resolver.
+     *
+     * O `add` IMPRIME a fiação, o `doctor` CONFERE a fiação com três ✓/✗, e nada a ESCREVE. Enquanto
+     * ela falta, os tokens não chegam ao navegador e o `doctor --fix` fica recusado de propósito - um
+     * fix num projeto sem fiação trocou 210 literais por variáveis que o navegador não resolvia e mudou
+     * a página (06/08).
+     */
+    {
+        path: CONFIGURE_SKILL_PATH,
+        source: CONFIGURE_SKILL,
+        label: "/sui-configure-ds",
+        what: "the system wired into the app, so the tokens reach the browser",
+    },
 ];

package/package.json

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