synthesisui 0.16.479 → 0.16.481

package/dist/colour-names.js

@@ -0,0 +1,206 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { blockMarks, readVocabulary } from "./new-project-theme.js";
+/**
+ * A VOLTA PARA O CÓDIGO - etapa 05 da jornada "o projeto sem cor escolhe as suas", 28/09.
+ *
+ * Depois do "Use these colours", ele sai com UM comando e UM prompt. O comando escreve os seis nomes no CSS global
+ * dele, NA GRAFIA DELE - o prefixo que o projeto já usa, ou uma neutra quando não usa nenhum -, e pergunta uma vez
+ * antes. O prompt manda o agente trocar os valores escritos à mão pelos nomes. As cores não são do agente: foram
+ * decididas na tela.
+ */
+export const SIX_ROLES = [
+    "primary",
+    "canvas",
+    "surface",
+    "foreground",
+    "muted",
+    "border",
+];
+/** A palavra de cada papel no código dele - a que ele escreveria, e não o nosso identificador. */
+const WORD = {
+    primary: { word: "primary", job: "buttons, links, what you click" },
+    canvas: { word: "background", job: "the page itself" },
+    surface: { word: "surface", job: "cards and panels" },
+    foreground: { word: "text", job: "what people read" },
+    muted: { word: "text-muted", job: "hints, captions, labels" },
+    border: { word: "border", job: "lines and edges" },
+};
+/**
+ * O PREFIXO DELE: quando a maioria dos nomes que ele declara começa pelo mesmo segmento (`--fn-space-1`,
+ * `--fn-radius-s`), é ali que os nomes novos entram (`--fn-primary`). Sem nome nenhum, ou sem um segmento que a
+ * maioria divida, a grafia é a neutra `--color-*` - a mesma que o `init` escreve num projeto novo.
+ */
+function prefixOf(own) {
+    if (own.length < 2)
+        return "--color-";
+    const counts = new Map();
+    for (const n of own) {
+        const m = /^--([a-z0-9]+)-/i.exec(n);
+        if (m)
+            counts.set(m[1], (counts.get(m[1]) ?? 0) + 1);
+    }
+    const [top, n] = [...counts].sort((a, b) => b[1] - a[1])[0] ?? ["", 0];
+    const generic = new Set([
+        "color",
+        "colors",
+        "space",
+        "spacing",
+        "radius",
+        "font",
+        "text",
+        "shadow",
+    ]);
+    return n > own.length / 2 && !generic.has(top) ? `--${top}-` : "--color-";
+}
+/** O que cada papel pinta - o uso em que a troca vale. A principal vale em qualquer um. */
+const KIND = {
+    primary: "any",
+    canvas: "background",
+    surface: "background",
+    foreground: "text",
+    muted: "text",
+    border: "border",
+};
+const kindOf = (prop) => /^(background|bg)/i.test(prop)
+    ? "background"
+    : /^color$/i.test(prop)
+        ? "text"
+        : /(border|outline)/i.test(prop)
+            ? "border"
+            : "other";
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    "out",
+    "_synthesisui",
+    ".git",
+    "coverage",
+]);
+/** As cores escritas à mão no código dele, com a propriedade que as pinta - CSS e objetos de estilo. */
+async function usesIn(root, slug) {
+    const { readdir } = await import("node:fs/promises");
+    const { relative } = await import("node:path");
+    const out = [];
+    const walk = async (dir) => {
+        for (const e of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            if (e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+                continue;
+            const path = join(dir, e.name);
+            if (e.isDirectory())
+                await walk(path);
+            else if (/\.(css|scss|tsx|jsx)$/i.test(e.name)) {
+                const src = (await readFile(path, "utf8").catch(() => "")).replace(blockMarks.END_RE(slug), "\n");
+                const file = relative(root, path).split("\\").join("/");
+                for (const m of src.matchAll(/([a-zA-Z-]+)\s*:\s*["']?[^;{}\n"']*?(#[0-9a-fA-F]{6})\b/g))
+                    if (!m[1].startsWith("--"))
+                        out.push({
+                            hex: m[2].toLowerCase(),
+                            kind: kindOf(m[1]),
+                            file,
+                        });
+            }
+        }
+    };
+    await walk(root);
+    return out;
+}
+export async function planColourNames(root, slug, roleHex, 
+/** As cores de cada papel ANTES da escolha - a versão instalada antes do `add`. Sem ela, vale a cor nova. */
+before = {}) {
+    const v = await readVocabulary(root, slug);
+    const prefix = prefixOf([...v.own.keys()]);
+    const uses = await usesIn(root, slug);
+    const low = (x) => (x ?? "").trim().toLowerCase();
+    const taken = new Set();
+    const names = SIX_ROLES.filter((r) => roleHex[r]).map((role) => {
+        const value = roleHex[role];
+        const old = low(before[role] ?? value);
+        /**
+         * O NOME DELE PRIMEIRO - o b1 declara `--accent: #c2410c`, e `--color-primary` com o mesmo valor ao lado seria o
+         * vocabulário dele duplicado pelo nosso. Vale o nome que segura a cor de hoje, ou a nova.
+         */
+        const his = [...v.own].find(([n, val]) => !taken.has(n) && (low(val) === old || low(val) === low(value)))?.[0];
+        const name = his ?? `${prefix}${WORD[role].word}`;
+        taken.add(name);
+        const have = v.own.get(name);
+        const kind = KIND[role];
+        const painted = uses.some((u) => u.hex === old && (kind === "any" || u.kind === kind));
+        return {
+            role,
+            name,
+            value,
+            job: WORD[role].job,
+            exists: have != null && low(have) === low(value),
+            theirs: his != null,
+            was: painted ? old : null,
+        };
+    });
+    return { file: v.global, prefix, names, css: v.css, uses };
+}
+/** Escreve o bloco depois do sim dele - `ask` devolve a resposta; com o não, o arquivo fica como estava. */
+export async function writeColourNames(root, slug, plan, ask) {
+    if (!plan.file)
+        return { written: false, reason: "no-file" };
+    const fresh = plan.names.filter((n) => !n.exists);
+    if (fresh.length === 0)
+        return { written: false, reason: "nothing-new" };
+    if (!(await ask()))
+        return { written: false, reason: "declined" };
+    const { begin, end, open, END_RE } = blockMarks;
+    const path = join(root, plan.file);
+    const css = await readFile(path, "utf8");
+    const block = [
+        begin(slug),
+        open(`${slug}: the six colours you chose, under names your code can use - var(${fresh[0]?.name}). They are yours.`),
+        ":root {",
+        ...fresh.map((n) => `  ${n.name}: ${n.value};`),
+        "}",
+        end(slug),
+    ].join("\n");
+    const base = css.replace(END_RE(slug), "\n").replace(/\n*$/, "\n");
+    await writeFile(path, `${base}\n${block}\n`, "utf8");
+    return { written: true };
+}
+/**
+ * O PROMPT PRONTO - o que ele cola no agente.
+ *
+ * A TROCA É PELA COR DE HOJE, e não pela nova: pela galeria, a cor nova não existe no código dele (medido em 28/09 com
+ * a Onyx no e06-galeria), e o que precisa mudar é o teal que ele escreve à mão. E É PELO USO: o branco do b2 é o fundo
+ * do cartão e o texto do botão ao mesmo tempo, e só o primeiro é a superfície.
+ */
+export function agentPrompt(plan) {
+    const where = {
+        any: "",
+        background: "as a background - ",
+        text: "as text - ",
+        border: "as a border - ",
+        other: "",
+    };
+    const lines = plan.names
+        .filter((n) => n.was)
+        .map((n) => `  ${n.was} -> var(${n.name})   (${where[KIND[n.role]]}${n.job})`);
+    const leave = [];
+    for (const n of plan.names) {
+        if (!n.was || KIND[n.role] === "any")
+            continue;
+        const claimed = new Set(plan.names.filter((m) => m.was === n.was).map((m) => KIND[m.role]));
+        const other = plan.uses.filter((u) => u.hex === n.was && !claimed.has(u.kind) && u.kind !== "other");
+        for (const kind of new Set(other.map((u) => u.kind))) {
+            const files = [
+                ...new Set(other.filter((u) => u.kind === kind).map((u) => u.file)),
+            ];
+            leave.push(`  leave ${n.was} where it is ${kind} (${files.join(", ")}) - that is not the ${WORD[n.role].word}`);
+        }
+    }
+    return [
+        `Replace the colours written by hand in this project with the names declared in ${plan.file ?? "the global stylesheet"}:`,
+        ...(lines.length > 0
+            ? lines
+            : ["  (your code writes none of these by hand - nothing to replace)"]),
+        ...leave,
+        "Change a value only where it is used as the line says. Leave every other colour as it is, and do not add or invent a name or a colour - these six were chosen by the person.",
+    ].join("\n");
+}

package/dist/commands/colours.js

@@ -0,0 +1,113 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { agentPrompt, planColourNames, SIX_ROLES, writeColourNames, } from "../colour-names.js";
+import { body, section } from "../output.js";
+import { RegistryError } from "../registry.js";
+import { add } from "./add.js";
+/**
+ * `synthesisui colours` - A VOLTA PARA O CÓDIGO, etapa 05 da jornada "o projeto sem cor escolhe as suas", 28/09.
+ *
+ * O comando que a tela de escolher cores entrega depois do "Use these colours". Ele traz a versão nova do sistema,
+ * mostra as seis cores com os nomes que vão entrar no CSS global dele, PERGUNTA UMA VEZ, escreve - e imprime o prompt
+ * que manda o agente trocar os valores escritos à mão pelos nomes. Com o não, nada muda no arquivo.
+ */
+export async function colours(asked, opts) {
+    const root = opts.dir ?? process.cwd();
+    const slug = asked ?? (await onlyInstalled(root));
+    const slugDir = join(root, "_synthesisui", "ds", slug);
+    /**
+     * AS CORES DE ANTES, lidas antes do `add` - é o que o código dele pinta hoje. Pela galeria, a cor nova não existe no
+     * código dele, e a troca que o prompt pede é da antiga (etapa 01 de "as cores voltam certas", 28/09).
+     */
+    const before = await installedRoles(slugDir);
+    /** A versão publicada pelo "Use these colours" - a instalada aqui ainda é a de antes. */
+    await add(slug, { registry: opts.registry, dir: root, setupHints: false });
+    const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
+    const tokens = typeof lock.version === "number"
+        ? await readFile(join(slugDir, `v${lock.version}`, "tokens.css"), "utf8").catch(() => "")
+        : "";
+    const roleHex = roleColours(tokens);
+    const plan = await planColourNames(root, slug, roleHex, before);
+    console.log("");
+    console.log(section("Your six colours, back in your code"));
+    if (!plan.file) {
+        console.log(body("No global stylesheet was found here (a globals.css, or a single stylesheet that is not a module) - nothing was written. The prompt below still works: point your agent at the file where your colours should live."));
+    }
+    else {
+        console.log(body(`These go into ${plan.file}, under names your code can use:`));
+        for (const n of plan.names)
+            console.log(body(`    ${n.name}: ${n.value}   ${n.exists ? "(already there, your name)" : n.theirs ? `(your name, new value) - ${n.job}` : `- ${n.job}`}`));
+    }
+    const result = await writeColourNames(root, slug, plan, () => opts.yes
+        ? Promise.resolve(true)
+        : askOnce(`  Write them into ${plan.file}? [y/N] `));
+    console.log("");
+    if (result.written)
+        console.log(body(`✓ ${plan.file}: the six colours are declared, in your names.`));
+    else if (result.reason === "declined")
+        console.log(body(`Nothing was written - ${plan.file} is as it was. Run this again with --yes when you want them there.`));
+    else if (result.reason === "nothing-new")
+        console.log(body(`${plan.file} already declares all six with these values - nothing to write.`));
+    console.log("");
+    console.log(section("Paste this to your agent"));
+    for (const line of agentPrompt(plan).split("\n"))
+        console.log(body(line));
+}
+/** As seis cores do sistema, pelos papéis - seguindo as referências da folha até o valor. */
+export function roleColours(tokensCss) {
+    const base = /\[data-ds="[^"]+"\]\s*\{([^}]*)\}/.exec(tokensCss)?.[1] ?? tokensCss;
+    const decl = new Map();
+    for (const m of base.matchAll(/(--ds-[a-z0-9-]+)\s*:\s*([^;]+);/gi))
+        decl.set(m[1], m[2].trim());
+    const resolve = (value, seen = new Set()) => {
+        const ref = /^var\(\s*(--ds-[a-z0-9-]+)\s*\)$/i.exec(value);
+        if (!ref || seen.has(ref[1]))
+            return value;
+        seen.add(ref[1]);
+        const next = decl.get(ref[1]);
+        return next ? resolve(next, seen) : value;
+    };
+    const out = {};
+    for (const role of SIX_ROLES) {
+        const v = decl.get(`--ds-color-semantic-${role}`);
+        if (v) {
+            const hex = resolve(v);
+            if (!hex.includes("var("))
+                out[role] = hex;
+        }
+    }
+    return out;
+}
+/** As seis cores da versão que está instalada agora - `{}` quando ainda não há nenhuma. */
+async function installedRoles(slugDir) {
+    const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
+    if (typeof lock.version !== "number")
+        return {};
+    return roleColours(await readFile(join(slugDir, `v${lock.version}`, "tokens.css"), "utf8").catch(() => ""));
+}
+async function onlyInstalled(root) {
+    const entries = await readdir(join(root, "_synthesisui", "ds"), {
+        withFileTypes: true,
+    }).catch(() => []);
+    const slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    if (slugs.length === 1)
+        return slugs[0];
+    if (slugs.length === 0)
+        throw new RegistryError("No design system is installed here - run `synthesisui add <slug>` first.");
+    throw new RegistryError(`More than one system is installed here (${slugs.join(", ")}) - name the one: \`synthesisui colours <slug>\`.`);
+}
+async function askOnce(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await rl.question(question)).trim());
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/commands/import.js

@@ -5209,6 +5209,8 @@ export async function runImport(opts) {
     // where the person is standing, and because a number they can check beats an
     // invitation they have to trust.
     const n = payload?.normalize;
+    /** Com uma v2 para aprovar, o link é o lugar da decisão, e ele fica mesmo com a porta das cores. */
+    const approveThere = Boolean(n?.decisions && n.decisions > 0);
     if (n?.decisions && n.decisions > 0) {
         console.log("");
         console.log(section("What a v2 would normalize"));
@@ -5223,11 +5225,15 @@ export async function runImport(opts) {
         console.log("");
         console.log(body("Nothing was changed. You approve it there:"));
     }
-    else if (payload?.url) {
+    else if (payload?.url && !payload?.coloursDoor) {
         console.log("");
         console.log(body("Name it, see it, and govern it:"));
     }
-    if (payload?.url)
+    /**
+     * UM CONVITE SÓ (etapa 04 de "as cores voltam certas", 28/09): com a porta das cores, o próximo passo é escolher as
+     * cores, e o link do tour competia com ele no fim da saída.
+     */
+    if (payload?.url && (approveThere || !payload?.coloursDoor))
         console.log(body(`    ${paint.blue(payload.url)}`));
     console.log("");
     /**

package/dist/commands/init.js

@@ -4,7 +4,7 @@ import { resolveDeps, stylesFor, tailwindMajor } from "../stack.js";
 import { formMix, measuredStyle } from "../styles-flavour.js";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { readProjectTheme, writeBesideTheirs, writeNewProjectTheme } from "../new-project-theme.js";
+import { readProjectTheme, writeBesideTheirs, writeNewProjectRoot, writeNewProjectTheme } from "../new-project-theme.js";
 import { add } from "./add.js";
 const whereOf = (answer) => answer === "file" || answer === "1"
     ? "file"
@@ -216,6 +216,22 @@ export async function init(opts) {
                 }
             }
         }
+        /**
+         * E O PROJETO SEM TAILWIND TAMBÉM - etapa 05 da jornada "o projeto sem cor escolhe as suas" (28/09). No b10 da
+         * bateria o `init --ds` com CSS puro não escrevia nome nenhum, e o agente escreveu 79 valores crus. Mesma trava do
+         * caminho acima: só no projeto que ainda não nomeia nada seu.
+         */
+        if (project !== "tailwind") {
+            const slugDir = join(root, "_synthesisui", "ds", opts.ds);
+            const lock = JSON.parse(await readFile(join(slugDir, ".lock"), "utf8").catch(() => "{}"));
+            const version = typeof lock.version === "number" ? lock.version : null;
+            const tokens = version !== null ? await readFile(join(slugDir, `v${version}`, "tokens.css"), "utf8").catch(() => "") : "";
+            const theme = tokens && version !== null ? await writeNewProjectRoot(root, tokens, opts.ds, version) : null;
+            if (theme?.written) {
+                console.log("");
+                console.log(`✓ ${theme.written}: ${theme.count} names of ${opts.ds} declared in your own :root, with the values written - your project had none of its own. They are yours: var(--color-primary) and var(--spacing-md) now paint the system.`);
+            }
+        }
         /**
          * ERAM DOIS PASSOS E É UM - `INV-GERAL-13`, 11/09.
          *

package/dist/index.js

@@ -31,6 +31,7 @@ import { summary } from "./commands/summary.js";
 import { sync } from "./commands/sync.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
+import { colours } from "./commands/colours.js";
 import { use } from "./commands/use.js";
 import { appendEvent } from "./doctor/ledger.js";
 import { blueprintTarget, installedSlugs } from "./installed.js";
@@ -57,6 +58,7 @@ Usage - deterministic, FREE:
   synthesisui template <slug> <name>       materialize a whole page from a DS template
                                            (--as landing-home names the output - multi-page safe)
   synthesisui upgrade <slug>               update an installed DS + regenerate your components + migration brief
+  synthesisui colours [slug]               write the colours you chose on the site into your CSS, in your names (asks first)
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui clean [--force]              strip create-next-app boilerplate (dry run without --force)
 
@@ -680,6 +682,17 @@ async function main() {
             });
             break;
         }
+        case "colours":
+        case "colors": {
+            /** Etapa 05 da jornada "o projeto sem cor escolhe as suas" (28/09): o comando que a tela de cores entrega. */
+            /** `--yes teste-b2` chega com o nome como valor da flag - ver `boolFlag`. */
+            await colours(args[0] ?? (typeof flags.yes === "string" ? flags.yes : undefined), {
+                registry,
+                dir,
+                yes: boolFlag(flags, "yes"),
+            });
+            break;
+        }
         case "upgrade": {
             /**
              * O SLUG É OPCIONAL desde 07/08: `upgrade` deixou de ser ocasional e virou O comando de

package/dist/new-project-theme.js

@@ -106,6 +106,70 @@ export async function writeNewProjectTheme(root, tokensCss, slug, version) {
     await writeFile(path, `${base}\n${block}\n`, "utf8");
     return { written: relative(root, path).split("\\").join("/"), count: lines.length };
 }
+/**
+ * O VOCABULÁRIO DELE E O CSS GLOBAL, para quem escreve nomes fora do `init` - o `colours` (etapa 05, 28/09). A mesma
+ * leitura de `readTheirs`, com a mesma regra de qual folha é a global.
+ */
+export async function readVocabulary(root, slug) {
+    const r = await readTheirs(root, slug);
+    const own = new Map([...r.own].map((n) => [n, r.values.get(n) ?? ""]));
+    const path = globalSheetOf(r.sheets);
+    return {
+        own,
+        global: path ? relative(root, path).split("\\").join("/") : null,
+        css: path ? (r.sheets.get(path) ?? "") : "",
+    };
+}
+function globalSheetOf(sheets) {
+    const globals = [...sheets.keys()].filter((p) => !/\.module\.css$/i.test(p));
+    const named = globals
+        .filter((p) => /(^|[\\/])globals\.css$/i.test(p))
+        .sort((a, b) => a.split(/[\\/]/).length - b.split(/[\\/]/).length);
+    return named[0] ?? (globals.length === 1 ? globals[0] : undefined);
+}
+/** Os marcadores do bloco, para o `colours` escrever e reescrever o seu no mesmo lugar. */
+export const blockMarks = { begin, end, open, END_RE };
+/**
+ * O MESMO TEMA NO PROJETO NOVO COM CSS PURO - etapa 05 da jornada "o projeto sem cor escolhe as suas", 28/09.
+ *
+ * O item 5 da triagem da bateria: no b10 (`init --ds` num Next sem Tailwind) nenhum nome foi escrito, e o agente
+ * escreveu 79 valores crus; com Tailwind (b11) o mesmo init escrevia 92 nomes no `@theme`. Aqui vai um `:root` no CSS
+ * global dele, com os MESMOS nomes (`--color-primary`, `--spacing-md`) e os valores escritos. Sem o `@theme` eles não
+ * viram utilitário - num projeto de CSS puro, o uso é `var(--color-primary)`, que é o que ele escreveria.
+ *
+ * A MESMA TRAVA: só no projeto que não nomeia nada próprio. O CSS global é o `globals.css` (o mais raso, se houver
+ * mais de um), ou a única folha que não é módulo.
+ */
+export async function writeNewProjectRoot(root, tokensCss, slug, version) {
+    const r = await readTheirs(root, slug);
+    if (r.own.size > 0)
+        return { written: null, count: 0, reason: "own-vocabulary" };
+    const path = globalSheetOf(r.sheets);
+    if (!path)
+        return { written: null, count: 0, reason: "no-tailwind-entry" };
+    const css = r.sheets.get(path) ?? "";
+    const system = new Map(systemNames(tokensCss, r.every));
+    const lines = [...system].map(([n, v]) => `  ${n}: ${v};`);
+    if (lines.length === 0)
+        return { written: null, count: 0, reason: "empty-sheet" };
+    const canvas = system.get("--color-canvas") ?? system.get("--color-surface");
+    const text = system.get("--color-foreground");
+    if (canvas && /--background\s*:/.test(css))
+        lines.push(`  --background: ${canvas};`);
+    if (text && /--foreground\s*:/.test(css))
+        lines.push(`  --foreground: ${text};`);
+    const block = [
+        begin(slug),
+        open(`${slug} v${version}: the system's values under plain names - use them as var(--color-primary). They are yours now: change a value here and every component follows. Written by \`init\`, because this project had no tokens of its own.`),
+        ":root {",
+        ...lines,
+        "}",
+        end(slug),
+    ].join("\n");
+    const base = css.replace(END_RE(slug), "\n").replace(/\n*$/, "\n");
+    await writeFile(path, `${base}\n${block}\n`, "utf8");
+    return { written: relative(root, path).split("\\").join("/"), count: lines.length };
+}
 const importLine = (slug) => `@import "./${slug}.css";`;
 /** O CSS dele sem nada nosso: sem o bloco e sem a linha que importa o arquivo à parte. */
 const withoutOurs = (css, slug) => css.replace(END_RE(slug), "\n").replace(new RegExp(`^${escape(importLine(slug))}\\n`, "m"), "");

package/package.json

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