synthesisui 0.16.33 → 0.16.35

package/dist/commands/doctor.js

@@ -8,7 +8,7 @@ import { checkableName, readRequests, verifyAndCloseRequests, } from "../doctor/
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
-import { body, section, snippet } from "../output.js";
+import { body, paint, section, snippet } from "../output.js";
 /**
  * `synthesisui doctor` - the check nobody else ships.
  *
@@ -43,7 +43,11 @@ const SKIP = new Set([
     // Our own installed artifacts are the answer, not the problem.
     "_synthesisui",
 ]);
-export async function* walk(dir) {
+export async function* walk(dir, 
+/** Filled with nested projects that were SKIPPED - each speaks its own
+ *  system and must not be billed against this one (30/07: the monorepo
+ *  run charged aluna-landing's tokens against the root's harvest). */
+skippedProjects) {
     // `readdir`'s overloads infer a Buffer-named Dirent without an explicit
     // encoding; naming it keeps `e.name` a string.
     const entries = await readdir(dir, {
@@ -57,7 +61,14 @@ export async function* walk(dir) {
         if (e.isDirectory()) {
             if (SKIP.has(e.name))
                 continue;
-            yield* walk(full);
+            // A CHILD directory carrying its own _synthesisui is a separately
+            // governed project - its record, its doctor, its numbers.
+            const governed = await readdir(join(full, "_synthesisui")).then(() => true, () => false);
+            if (governed) {
+                skippedProjects?.push(full);
+                continue;
+            }
+            yield* walk(full, skippedProjects);
         }
         else if (EXTS.some((x) => e.name.endsWith(x))) {
             yield full;
@@ -199,7 +210,7 @@ const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 /** A bar you can read at a glance, in a font that is always monospace. */
 function meter(pct, width = 24) {
     const filled = Math.round((pct / 100) * width);
-    return `${"█".repeat(filled)}${"░".repeat(width - filled)}`;
+    return `${paint.blue("█".repeat(filled))}${paint.faint("░".repeat(width - filled))}`;
 }
 function verdict(d, hasSystem, overruled, conflicts) {
     // A system at war with itself outranks every other number here. The closing
@@ -368,7 +379,10 @@ export async function doctor(opts) {
      * Nobody debugs from 0%. They conclude the product does not work.
      */
     const wiring = await readWiring(root, table.slug);
-    for await (const file of scopes.length > 0 ? walkAll(scopes) : walk(root)) {
+    const skippedProjects = [];
+    for await (const file of scopes.length > 0
+        ? walkAll(scopes)
+        : walk(root, skippedProjects)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
@@ -442,7 +456,11 @@ export async function doctor(opts) {
         // `var(--ds-color-semantic-knob, #ffffff)` - is set aside for the opposite
         // reason: it is already tokenized. The summary said the false half out
         // loud and hid the true half behind a flag.
-        console.log(body(`set aside ${plural(asideTotal, "value")} that are not drift (--verbose for why)`));
+        console.log(body(`set aside ${plural(asideTotal, "value")} that are not drift` +
+            (skippedProjects.length > 0
+                ? ` and ${plural(skippedProjects.length, "nested project")} that speak their own systems`
+                : "") +
+            " (--verbose for why)"));
     }
     // 0 of 0 is not a perfect score, it is an empty measurement - printing a
     // full bar there would be the report's first lie.
@@ -522,8 +540,19 @@ export async function doctor(opts) {
     }
     if (hasSystem && measurable) {
         console.log("");
-        console.log(body(`Token coverage  ${meter(d.coverage)}  ${String(d.coverage).padStart(3)}%`));
-        console.log(body(`                ${d.tokenUses} from the system, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`));
+        console.log(body(`Token coverage  ${meter(d.coverage)}  ${paint.strong(`${String(d.coverage).padStart(3)}%`)}`));
+        console.log(body(paint.dim(`                ${d.tokenUses} from the system, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
+        // The strongest number leads, not trails: it used to sit two screens
+        // down, after the phantom list (30/07). For the reader who already owns
+        // a system - the ICP - THIS line is the report.
+        if (table.source === "yours" && d.findings.length > 0) {
+            const named = d.findings.filter((f) => f.token).length;
+            if (named > 0) {
+                console.log("");
+                console.log(body(`${paint.strong(String(named))} of the ${d.findings.length} hand-written values already have a name in YOUR system.`));
+                console.log(body(paint.dim("Your agent has no way to know: the tokens exist, the contract does not.")));
+            }
+        }
     }
     /**
      * THE RECORD - the layer that remembers, printed where the moment is shown.
@@ -635,13 +664,21 @@ export async function doctor(opts) {
         console.log(body(`${plural(phantoms.size, "name")} written as tokens that your system never declares.`));
         console.log(body("An undeclared custom property applies nothing at all."));
         console.log("");
-        for (const [name, at] of [...phantoms].sort()) {
+        // Capped like every other section: 99 lines is a report nobody reads,
+        // and it buried the strongest number two screens down (30/07). The full
+        // list keeps living behind --verbose.
+        const PHANTOM_CAP = 8;
+        const sorted = [...phantoms].sort();
+        for (const [name, at] of sorted.slice(0, PHANTOM_CAP)) {
             const where = [...at.files][0];
-            console.log(body(`${name}   ${where}:${at.line}${at.files.size > 1 ? ` +${at.files.size - 1} more` : ""}`));
+            console.log(body(`${name}   ${paint.dim(`${where}:${at.line}${at.files.size > 1 ? ` +${at.files.size - 1} more` : ""}`)}`));
             const kin = siblingTokens(name, table);
             if (kin.length > 0)
                 console.log(snippet([`your system has ${kin.join(", ")}`]));
         }
+        if (sorted.length > PHANTOM_CAP) {
+            console.log(body(paint.dim(`and ${sorted.length - PHANTOM_CAP} more · synthesisui doctor --verbose`)));
+        }
         console.log("");
         console.log(body("Add the name to the system, or use one it has. Do not leave it."));
     }
@@ -1009,11 +1046,16 @@ export async function doctor(opts) {
         }
         if (d.findings.length > 0 || overrides.length > 0) {
             console.log("");
-            console.log(body(`${plural(d.findings.length, "value")} by hand · ${d.named} already ${d.named === 1 ? "has" : "have"} a name`));
-            console.log(body(`${plural(overrides.length - lawKeepingCount, "override")} · ${offSystemCount} left the system` +
-                (lawKeepingCount > 0
-                    ? ` · ${lawKeepingCount} more kept a law`
-                    : "")));
+            if (table.source !== "yours") {
+                console.log(body(`${plural(d.findings.length, "value")} by hand · ${d.named} already ${d.named === 1 ? "has" : "have"} a name`));
+            }
+            // An all-zero status line is filler, not information.
+            if (overrides.length > 0 || offSystemCount > 0) {
+                console.log(body(`${plural(overrides.length - lawKeepingCount, "override")} · ${offSystemCount} left the system` +
+                    (lawKeepingCount > 0
+                        ? ` · ${lawKeepingCount} more kept a law`
+                        : "")));
+            }
         }
         if (plan.length > 0) {
             console.log("");
@@ -1021,7 +1063,7 @@ export async function doctor(opts) {
             const w = Math.min(52, Math.max(...plan.slice(0, 5).map((j) => j.what.length)));
             plan.slice(0, 5).forEach((j, i) => {
                 const what = j.what.length > w ? `${j.what.slice(0, w - 1)}…` : j.what.padEnd(w);
-                console.log(`      ${i + 1}. ${what}  ${j.size}${j.cheap ? "  (cheap)" : ""}`);
+                console.log(`      ${i + 1}. ${what}  ${paint.dim(`${j.size}${j.cheap ? "  (cheap)" : ""}`)}`);
             });
         }
         console.log("");
@@ -1040,15 +1082,6 @@ export async function doctor(opts) {
          * thread, which is the other job this paragraph does.
          */
         if (table.source === "yours") {
-            const named = d.findings.filter((f) => f.token).length;
-            const anonymous = d.findings.length - named;
-            console.log("");
-            console.log(body(named > 0
-                ? `${named} of these already have a name in your own system.`
-                : "None of these have a name in your system yet."));
-            if (anonymous > 0) {
-                console.log(body(`The other ${anonymous} do not - and your coding agent has no way to know they should.`));
-            }
             console.log("");
             // Careful about what is being offered. This reader ALREADY has a design
             // system, so "install ours" would mean replacing theirs, and a CTA that
@@ -1058,9 +1091,9 @@ export async function doctor(opts) {
             console.log(body("Your tokens exist. What your agent is missing is a contract:"));
             console.log(body("rules it reads BEFORE writing UI, and a manifest of what exists."));
             console.log("");
-            console.log(snippet(["npx synthesisui@latest init --ds <slug>"]));
-            console.log(body("starts you on a system that ships one - browse them at"));
-            console.log(body("https://www.synthesisui.com/gallery"));
+            console.log(paint.blue(snippet(["npx synthesisui@latest init --ds <slug>"])));
+            console.log(body(paint.dim("starts you on a system that ships one - browse them at")));
+            console.log(body(paint.blue("https://www.synthesisui.com/gallery")));
         }
         console.log("");
     }

package/dist/commands/import.js

@@ -0,0 +1,312 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { readToken, resolveRegistry } from "../config.js";
+import { diagnose, scanSource } from "../doctor/scan.js";
+import { buildTable } from "../doctor/tokens.js";
+import { body, paint, section } from "../output.js";
+import { walk, walkAll } from "./doctor.js";
+/** How many distinct values travel. A census is a vocabulary, not a log: past
+ *  the first few dozen repeats the tail is noise nobody will name. */
+const MAX_VALUES = 120;
+/**
+ * Dependencies as the project actually resolves them - which means reading
+ * ANCESTOR package.json files too.
+ *
+ * Measured on our own repo: `import --dir apps/web` reported "plain css" for a
+ * Next + React + Tailwind app, because a workspace hoists those to the root and
+ * the leaf package.json lists only its own icons. Three levels up covers every
+ * pnpm/npm workspace layout without wandering into someone's home directory.
+ */
+async function resolveDeps(root) {
+    const deps = {};
+    let dir = root;
+    for (let up = 0; up < 4; up++) {
+        const raw = await readFile(join(dir, "package.json"), "utf8").catch(() => null);
+        if (raw) {
+            try {
+                const p = JSON.parse(raw);
+                // The nearest package.json wins on a version clash; we only ever ask
+                // whether a name is present, so first-seen is enough.
+                for (const [k, v] of Object.entries({
+                    ...p.dependencies,
+                    ...p.devDependencies,
+                })) {
+                    if (deps[k] == null)
+                        deps[k] = String(v);
+                }
+            }
+            catch {
+                // unreadable manifest costs the detection, not the run
+            }
+        }
+        const parent = join(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return deps;
+}
+async function detectStack(root) {
+    const stack = [];
+    const has = async (f) => (await readFile(join(root, f), "utf8").catch(() => null)) !== null;
+    const deps = await resolveDeps(root);
+    if (await has("components.json"))
+        stack.push("shadcn/ui");
+    if (deps.next)
+        stack.push("next");
+    else if (deps.vite)
+        stack.push("vite");
+    if (deps.react)
+        stack.push("react");
+    else if (deps.vue)
+        stack.push("vue");
+    else if (deps.svelte)
+        stack.push("svelte");
+    if (deps.tailwindcss)
+        stack.push("tailwind");
+    if (await has("tokens.json"))
+        stack.push("tokens.json");
+    // Nothing recognised is itself a finding: plain CSS is a supported entrance,
+    // and saying so beats an empty list that reads like a failed detection.
+    if (stack.length === 0)
+        stack.push("plain css");
+    return stack;
+}
+/** Their own vocabulary, read from stylesheets - the same harvest the doctor
+ *  runs when nothing of ours is installed. */
+async function declaredTokens(root) {
+    let css = "";
+    for await (const file of walkAll([root])) {
+        if (!/\.(css|scss|sass|less)$/i.test(file))
+            continue;
+        css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+    }
+    const table = buildTable({ css, source: "yours" });
+    return Object.fromEntries(table.byName);
+}
+/**
+ * EVERY distinct design value, commonest first - not just the repeated ones.
+ *
+ * The doctor's `repeats` list deliberately drops single-use values, because as a
+ * to-do list "this appears once" is noise. A CENSUS is the opposite kind of
+ * document: it is a vocabulary, and a brand colour that lives in one reusable
+ * button is still the brand colour. Caught on a fake v0 app whose primary
+ * (#7c3aed) appeared exactly once and vanished from the payload.
+ */
+function distinctValues(d) {
+    const by = new Map();
+    for (const f of d.findings) {
+        const key = `${f.kind}:${f.literal.toLowerCase()}`;
+        const hit = by.get(key);
+        if (hit) {
+            hit.count += 1;
+            hit.files.add(f.file);
+            continue;
+        }
+        by.set(key, {
+            kind: f.kind,
+            value: f.literal,
+            count: 1,
+            files: new Set([f.file]),
+            token: f.token,
+        });
+    }
+    return [...by.values()]
+        .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value))
+        .slice(0, MAX_VALUES)
+        .map((v) => ({
+        kind: v.kind,
+        value: v.value,
+        count: v.count,
+        files: v.files.size,
+        token: v.token,
+    }));
+}
+export async function takeCensus(root) {
+    const table = buildTable({ css: "", source: "yours" });
+    const reports = [];
+    for await (const file of walk(root)) {
+        const src = await readFile(file, "utf8").catch(() => "");
+        if (!src)
+            continue;
+        reports.push(scanSource(relative(root, file), src, table));
+    }
+    const d = diagnose(reports);
+    const pkgRaw = await readFile(join(root, "package.json"), "utf8").catch(() => null);
+    let name = null;
+    if (pkgRaw) {
+        try {
+            name = JSON.parse(pkgRaw).name ?? null;
+        }
+        catch {
+            // an unreadable package.json costs the name, not the run
+        }
+    }
+    return {
+        census: 1,
+        project: { name, stack: await detectStack(root) },
+        declared: await declaredTokens(root),
+        observed: distinctValues(d),
+        totals: {
+            scanned: d.scanned,
+            values: d.findings.length,
+            named: d.named,
+            tokenUses: d.tokenUses,
+            coverage: d.coverage,
+        },
+    };
+}
+function summarize(c) {
+    const byKind = new Map();
+    for (const v of c.observed)
+        byKind.set(v.kind, (byKind.get(v.kind) ?? 0) + v.count);
+    const kinds = [...byKind.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, n]) => `${n} ${k}`)
+        .join(" · ");
+    console.log(section("What your project says"));
+    console.log(body(`${c.project.stack.join(" · ")}`));
+    console.log(body(`${c.totals.scanned} files · ${c.observed.length} distinct design values`));
+    if (kinds)
+        console.log(body(kinds));
+    if (Object.keys(c.declared).length > 0) {
+        console.log(body(`${Object.keys(c.declared).length} tokens you already declare - your names travel unchanged`));
+    }
+    const top = c.observed.slice(0, 5);
+    if (top.length > 0) {
+        console.log("");
+        for (const v of top) {
+            console.log(body(`${paint.strong(v.value)} ${paint.faint(`${v.kind}, ${v.count}× in ${v.files} file${v.files === 1 ? "" : "s"}`)}`));
+        }
+    }
+}
+/**
+ * The contract an agent needs, printed where an agent will read it.
+ *
+ * A skill file cannot help the FIRST import - it is not installed yet, and this
+ * is the moment before any relationship exists. Terminal output, though, is
+ * already in the agent's context: it ran the command. So the command teaches.
+ *
+ * What we ask for is strictly JUDGEMENT, never numbers. Which of three greys is
+ * the real grey, which family is the display voice, what this product is. The
+ * census stays arithmetic, and every value in `roles` must be one the census
+ * already found - the endpoint drops anything else.
+ */
+function printAgentContract() {
+    console.log("");
+    console.log(section("If you are an agent reading this"));
+    console.log(body("The census is deterministic and complete. What it cannot do is judge, so"));
+    console.log(body("add a `reading` object to the file and send that back to us:"));
+    console.log("");
+    console.log(body(paint.faint('  "reading": {')));
+    console.log(body(paint.faint('    "roles": { "canvas": "#…", "foreground": "#…", "primary": "#…" },')));
+    console.log(body(paint.faint('    "fonts": { "display": "…", "body": "…" },')));
+    console.log(body(paint.faint('    "concept": "one paragraph on what this product is"')));
+    console.log(body(paint.faint("  }")));
+    console.log("");
+    console.log(body("Every hex in `roles` must be one the census already observed - a value"));
+    console.log(body("we did not find in their code is dropped. Then send the file:"));
+    console.log("");
+    console.log(body(`    ${paint.strong("synthesisui import --census _synthesisui/census.json")}`));
+}
+export async function runImport(opts) {
+    const root = opts.root ?? process.cwd();
+    // A census handed to us (an agent annotated it) is sent as-is; the numbers
+    // inside were still ours to begin with.
+    let census;
+    if (opts.census) {
+        const raw = await readFile(opts.census, "utf8").catch(() => null);
+        if (!raw) {
+            console.log(section("Import"));
+            console.log(body(`Cannot read ${opts.census}.`));
+            return;
+        }
+        try {
+            census = JSON.parse(raw);
+        }
+        catch {
+            console.log(section("Import"));
+            console.log(body(`${opts.census} is not valid JSON.`));
+            return;
+        }
+        if (census.census !== 1) {
+            console.log(section("Import"));
+            console.log(body("That file is not a census this version can send."));
+            return;
+        }
+    }
+    else {
+        console.log(section("Reading your project"));
+        census = await takeCensus(root);
+    }
+    summarize(census);
+    const out = join(root, "_synthesisui", "census.json");
+    await mkdir(join(root, "_synthesisui"), { recursive: true });
+    await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");
+    console.log("");
+    console.log(body(`Written to ${paint.strong(relative(root, out))}`));
+    if (opts.dry) {
+        console.log(body("Nothing was sent. Read the file, then run it without --dry."));
+        printAgentContract();
+        console.log("");
+        return;
+    }
+    const token = await readToken();
+    if (!token) {
+        console.log("");
+        console.log(body("To turn this into a system on your account:"));
+        console.log(body(`    ${paint.strong("synthesisui login")}`));
+        console.log(body("    synthesisui import"));
+        console.log("");
+        return;
+    }
+    const base = resolveRegistry(opts.registry);
+    const res = await fetch(`${base}/api/onboarding/import`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ census, name: opts.name }),
+    }).catch(() => null);
+    if (!res || !res.ok) {
+        const detail = res
+            ? await res
+                .json()
+                .then((b) => b?.message ?? null)
+                .catch(() => null)
+            : null;
+        console.log("");
+        console.log(body(res
+            ? `The registry refused it (HTTP ${res.status})${detail ? `: ${detail}` : "."}`
+            : "Could not reach the registry. The census is on disk - try again later."));
+        console.log("");
+        return;
+    }
+    const payload = (await res.json().catch(() => null));
+    console.log("");
+    console.log(section("Your system exists"));
+    console.log(body(`${paint.strong(payload?.name ?? "Your system")} - v1 mirrors your tokens exactly, nothing improved yet.`));
+    for (const note of payload?.notes ?? [])
+        console.log(body(paint.dim(note)));
+    // What a v2 would be worth, in their own values. Said here because this is
+    // where the person is standing, and because a number they can check beats an
+    // invitation they have to trust.
+    const n = payload?.normalize;
+    if (n?.decisions && n.decisions > 0) {
+        console.log("");
+        console.log(section("What a v2 would normalize"));
+        console.log(body(`${paint.strong(String(n.decisions))} colour${n.decisions === 1 ? "" : "s"} in your code ${n.decisions === 1 ? "is" : "are"} the same decision typed twice - ${paint.strong(String(n.retires ?? 0))} uses would retire.`));
+        for (const line of n.lines ?? [])
+            console.log(body(paint.dim(line)));
+        console.log("");
+        console.log(body("Nothing was changed. You approve it there:"));
+    }
+    else if (payload?.url) {
+        console.log("");
+        console.log(body("Name it, see it, and govern it:"));
+    }
+    if (payload?.url)
+        console.log(body(`    ${paint.blue(payload.url)}`));
+    console.log("");
+}

package/dist/doctor/scan.js

@@ -231,7 +231,35 @@ function fallbackSpans(line, table) {
 const DECLARES_TOKEN = /^\s*(--[a-z0-9_-]+)\s*:/i;
 /** Under this, a radius or spacing value is idiom rather than a decision. */
 const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
+/** Test fixtures speak in example names on purpose - `--ds-nope` inside a
+ *  spec is the TEST, not drift. Every real project has these; accusing them
+ *  buried the report's real findings under 99 phantom lines the first time
+ *  the doctor ran on a repo with its own test suite (30/07). */
+const IS_FIXTURE = /(\.(spec|test)\.[a-z]+$|__tests__\/|\/fixtures?\/)/;
 export function scanSource(file, source, table) {
+    if (IS_FIXTURE.test(file)) {
+        const real = scanCore(file, source, table);
+        const aside = real.findings.length +
+            (real.phantoms?.length ?? 0) +
+            (real.setAside?.reduce((n, a) => n + a.count, 0) ?? 0);
+        return {
+            file,
+            findings: [],
+            // Neither accused nor credited: fixture var() uses would inflate
+            // coverage exactly as unfairly as fixture hexes would deflate it.
+            tokenUses: 0,
+            ...(aside > 0
+                ? {
+                    setAside: [
+                        { reason: "test fixtures speak in example names", count: aside },
+                    ],
+                }
+                : null),
+        };
+    }
+    return scanCore(file, source, table);
+}
+function scanCore(file, source, table) {
     const findings = [];
     const phantoms = [];
     let tokenUses = 0;

package/dist/index.js

@@ -9,6 +9,7 @@ import { connect } from "./commands/connect.js";
 import { doctor } from "./commands/doctor.js";
 import { generate } from "./commands/generate.js";
 import { hook } from "./commands/hook.js";
+import { runImport } from "./commands/import.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
@@ -40,6 +41,7 @@ Usage - deterministic, FREE:
 
 Usage - governance (deterministic, FREE):
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
+  synthesisui import [--dry]               read the app you already have and make it a system
                                            your agent follows - without touching your CSS
   synthesisui connect                      wire your agent: the check as an editor hook, the system
                                            as MCP tools, and a contract that stops repeating itself
@@ -86,6 +88,7 @@ Options:
 
 Examples:
   synthesisui adopt                        # you already have a system: start here
+  synthesisui import --dry                 # see the census before anything is sent
   synthesisui login
   synthesisui init --target next
   synthesisui init --target next --ds halogen   bootstrap + bring a system in
@@ -149,6 +152,16 @@ async function main() {
     const registry = typeof flags.registry === "string" ? flags.registry : undefined;
     const dir = typeof flags.dir === "string" ? flags.dir : undefined;
     switch (command) {
+        case "import":
+            // The census is arithmetic over their files; --dry keeps it on disk.
+            await runImport({
+                root: dir,
+                dry: flags.dry === true,
+                census: typeof flags.census === "string" ? flags.census : undefined,
+                name: typeof flags.name === "string" ? flags.name : undefined,
+                registry,
+            });
+            break;
         case "adopt":
             // Dry by default: `--write` is the only way anything lands on disk.
             await adopt({

package/dist/output.js

@@ -10,7 +10,7 @@ const WIDTH = 66;
 export function section(title) {
     const head = `── ${title} `;
     const rest = Math.max(4, WIDTH - head.length);
-    return `\n${head}${"─".repeat(rest)}\n`;
+    return `\n${head}${paint.faint("─".repeat(rest))}\n`;
 }
 /** Indented, copy-pasteable code block (empty lines stay truly empty). */
 export function snippet(lines) {
@@ -20,3 +20,27 @@ export function snippet(lines) {
 export function body(line) {
     return `  ${line}`;
 }
+/**
+ * Colour, used the way the product uses motion: a quiet base and a few
+ * deliberate accents (dono, 30/07: "um cinza mais escuro e um mais claro,
+ * e o coverage com um azul bem discreto"). Two grays carry hierarchy -
+ * chrome/meta in the darker one, secondary prose in the lighter - and one
+ * muted steel blue marks what is ALIVE: the coverage bar, commands, links.
+ *
+ * Off out of respect wherever colour is not wanted: piped output (no TTY),
+ * NO_COLOR, or a dumb terminal - assertions in tests never see a code.
+ */
+const COLOR_ON = Boolean(process.stdout.isTTY) &&
+    !process.env.NO_COLOR &&
+    process.env.TERM !== "dumb";
+const wrap = (code) => (s) => COLOR_ON ? `\x1b[${code}m${s}\x1b[0m` : s;
+export const paint = {
+    /** Lighter gray - secondary prose, explanations, counts. */
+    dim: wrap("38;5;246"),
+    /** Darker gray - chrome: rules, meters' empty track, set-aside notes. */
+    faint: wrap("38;5;240"),
+    /** Discreet steel blue - the coverage fill, commands, links. */
+    blue: wrap("38;5;67"),
+    /** Bold - the one or two numbers that carry the report. */
+    strong: wrap("1"),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.33",
+  "version": "0.16.35",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build",
     "test": "vitest run"