synthesisui 0.16.479 → 0.16.480

package/dist/colour-names.js

@@ -0,0 +1,104 @@
+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-";
+}
+export async function planColourNames(root, slug, roleHex) {
+    const v = await readVocabulary(root, slug);
+    const prefix = prefixOf([...v.own.keys()]);
+    const names = SIX_ROLES.filter((r) => roleHex[r]).map((role) => {
+        const name = `${prefix}${WORD[role].word}`;
+        const value = roleHex[role];
+        const have = v.own.get(name);
+        return {
+            role,
+            name,
+            value,
+            job: WORD[role].job,
+            exists: have != null && have.toLowerCase() === value.toLowerCase(),
+        };
+    });
+    return { file: v.global, prefix, names, css: v.css };
+}
+/** 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. Cada valor à mão vira o nome; nenhuma cor nova, nenhum nome novo. */
+export function agentPrompt(plan) {
+    return [
+        `Replace the colours written by hand in this project with the names declared in ${plan.file ?? "the global stylesheet"}:`,
+        ...plan.names.map((n) => `  ${n.value} -> var(${n.name})   (${n.job})`),
+        "Change only a value that is exactly one of these. 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,101 @@
+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));
+    /** 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 slugDir = join(root, "_synthesisui", "ds", slug);
+    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);
+    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)" : `- ${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;
+}
+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/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.480",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {