synthesisui 0.14.0 → 0.16.0

package/dist/claude-md.js

@@ -18,7 +18,12 @@ async function readInstalled(projectRoot) {
         try {
             const raw = await readFile(join(dsDir, slug, ".lock"), "utf8");
             const lock = JSON.parse(raw);
-            locks.push({ slug: lock.slug, name: lock.name, version: lock.version });
+            locks.push({
+                slug: lock.slug,
+                name: lock.name,
+                version: lock.version,
+                adopted: lock.adopted === true,
+            });
         }
         catch {
             // folder without a valid .lock - ignore
@@ -81,30 +86,70 @@ async function readManifest(projectRoot, ds) {
         return null;
     }
 }
+/**
+ * The loop that closes itself, and the one paragraph both kinds of system share.
+ *
+ * The contract said what to write and never said to check, so verification
+ * happened days later, by a human, across a whole repo - archaeology rather
+ * than a fix. `doctor <file> --verbose` already existed; nobody was pointing
+ * the agent at it.
+ *
+ * Held in one constant on purpose: the same paragraph typed into two template
+ * literals is two paragraphs that drift.
+ */
+const SELF_CHECK = `
+
+**After writing or editing any UI file, check it before moving on:**
+
+    npx synthesisui@latest doctor <the file you just wrote> --verbose
+
+It names the token for every hardcoded value it finds. Fix what it names, run it
+again, and only then move to the next thing. Do not batch this up for the end -
+a component checked while you still have its context is a two-line fix; the same
+component found in a repo-wide audit next week is an archaeology exercise.
+
+If it reports a value with no token, do NOT invent one. Say which value and what
+you would call it, and let a person decide.`;
 async function renderRegion(projectRoot, installed) {
     if (installed.length === 0) {
         return `${START}\n${END}`;
     }
     const sections = [];
     for (const ds of installed) {
-        const head = `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``;
+        // An adopted system has no published version and therefore no `v<n>/`
+        // folder - pointing the agent at one points it at a file that does not
+        // exist (caught by running it, 27/07).
+        const head = ds.adopted
+            ? `- **${ds.name}** (\`${ds.slug}\`, adopted from this repo) - guide: \`_synthesisui/ds/${ds.slug}/GUIDE.md\``
+            : `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``;
         const manifest = await readManifest(projectRoot, ds);
         sections.push(manifest ? `${head}\n${manifest}` : head);
     }
-    const body = `## Design Systems (via SynthesisUI)
-
-This project uses design system(s) brought in by the \`synthesisui\` CLI. **When creating or editing
-components, read the system's GUIDE.md and follow it:** use only semantic tokens
+    // Two truths, and asserting the wrong one misleads the agent every time it
+    // writes a line. An INSTALLED system speaks `--ds-*` and is scoped with
+    // `data-ds`; an ADOPTED one is the project's own vocabulary, already wired,
+    // with no `data-ds` anywhere to scope to.
+    const onlyAdopted = installed.every((d) => d.adopted);
+    const rule = onlyAdopted
+        ? `**When creating or editing components, read the system's GUIDE.md and follow it:** use the
+project's OWN custom properties, exactly as the guide lists them. Do not write raw colours,
+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.${SELF_CHECK}`
+        : `**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. **Before
 creating any UI element, check the component manifest below - if it exists, use or extend
 it (\`synthesisui component <slug> <name>\` materializes it as your code).** To review a
 component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
-apply it to real production pages unless asked.
+apply it to real production pages unless asked.${SELF_CHECK}`;
+    const body = `## Design Systems (via SynthesisUI)
+
+This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}
 
 ${sections.join("\n")}
 
-_Block managed by the CLI - do not edit by hand; run \`synthesisui add <slug>\` to update._`;
+_Block managed by the CLI - do not edit by hand; run \`synthesisui ${onlyAdopted ? "adopt --write" : "add <slug>"}\` to update._`;
     return `${START}\n${body}\n${END}`;
 }
 /**

package/dist/commands/adopt.js

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { syncClaudeMd } from "../claude-md.js";
+import { parseRootTokens } from "../doctor/tokens.js";
+import { body, section, snippet } from "../output.js";
+import { walk } from "./doctor.js";
+/**
+ * `synthesisui adopt` - the system somebody ALREADY has, made legible.
+ *
+ * The whole product assumed you start from nothing. `init` installs OUR tokens
+ * and therefore needs four manual edits - import, scope with data-ds, wire
+ * fonts - which is where people give up (walked 27/07, the next run reads 0%).
+ *
+ * The reader who feels our pitch hardest does not need any of that. Their
+ * `--acme-*` tokens are already in `:root` and already painting the screen.
+ * What is missing is not code, it is the CONTRACT: the file their coding agent
+ * reads before writing UI.
+ *
+ * So this command writes NO CSS, and that is the point rather than a
+ * limitation:
+ *
+ *     init     writes CSS  → needs wiring → 4 edits → 0% if one is wrong
+ *     adopt    writes none → no wiring    → works on the first command
+ *
+ * THE PROMISE, printed rather than buried in docs: it reads your code and
+ * rewrites none of it; everything it creates lives in `_synthesisui/` and
+ * leaves with `clean`; your tokens keep your names.
+ *
+ * Dry by default. A command that edits somebody's repository on first run is
+ * not a command that people with a system in production ever try.
+ */
+const SCOPE_HINT = ":root, html, :host and @theme";
+/** Group by the prefix an author actually used, which is how they think of it. */
+function byKind(tokens) {
+    const kinds = new Map();
+    const guess = (n) => /color|colour|bg|background|fg|foreground|surface|canvas|ink|brand/.test(n)
+        ? "colour"
+        : /space|spacing|gap|inset/.test(n)
+            ? "spacing"
+            : /radius|round|corner/.test(n)
+                ? "radius"
+                : /font|type|text|leading|tracking|weight/.test(n)
+                    ? "type"
+                    : /shadow|elevation/.test(n)
+                        ? "shadow"
+                        : /duration|ease|motion|transition/.test(n)
+                            ? "motion"
+                            : "other";
+    for (const name of tokens.keys()) {
+        const k = guess(name);
+        kinds.set(k, (kinds.get(k) ?? 0) + 1);
+    }
+    return [...kinds.entries()].sort((a, b) => b[1] - a[1]);
+}
+/** The commonest `--<prefix>-` in their own names - the slug they already use. */
+function guessSlug(tokens, pkgName) {
+    const counts = new Map();
+    for (const n of tokens.keys()) {
+        const m = /^--([a-z0-9]+)-/.exec(n);
+        if (m)
+            counts.set(m[1], (counts.get(m[1]) ?? 0) + 1);
+    }
+    const top = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    // Only trust the prefix when it actually dominates; a repo whose tokens are
+    // `--color-*`, `--space-*` has no brand prefix and the package name is the
+    // better answer.
+    if (top &&
+        top[1] >= tokens.size * 0.5 &&
+        !/^(color|space|font|size)$/.test(top[0])) {
+        return top[0];
+    }
+    return (pkgName
+        .replace(/^@[^/]+\//, "")
+        .replace(/[^a-z0-9]+/gi, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase() || "my-system");
+}
+async function findTokens(root, only) {
+    let files = 0;
+    const from = [];
+    const all = new Map();
+    const take = async (file) => {
+        const css = await readFile(file, "utf8").catch(() => "");
+        if (!css)
+            return;
+        files++;
+        const found = parseRootTokens(css);
+        if (found.size === 0)
+            return;
+        from.push(`${relative(root, file)} (${found.size})`);
+        for (const [k, v] of found)
+            if (!all.has(k))
+                all.set(k, v);
+    };
+    if (only) {
+        await take(resolve(root, only));
+    }
+    else {
+        for await (const f of walk(root)) {
+            if (/\.(css|scss|sass|less)$/i.test(f))
+                await take(f);
+        }
+    }
+    return { tokens: all, files, from };
+}
+/** The contract. Names THEIR tokens - there is no translation layer. */
+function guide(name, slug, tokens) {
+    const lines = [...tokens.entries()].map(([k, v]) => `  ${k}: ${v};`);
+    return `# ${name} - the contract your agent follows
+
+Adopted from this repository by \`synthesisui adopt\`. These are YOUR tokens,
+under YOUR names - nothing was renamed and no stylesheet was rewritten.
+
+## The rule
+
+When writing or editing UI in this project, use these custom properties.
+Do not write raw colours, spacings or radii that a token already covers.
+
+    ✗  background: #3b82f6
+    ✓  background: var(--${slug}-color-primary)
+
+If a value has no token, say so instead of inventing one silently - a new
+token is a decision for a person to make.
+
+## The tokens (${tokens.size})
+
+\`\`\`css
+:root {
+${lines.join("\n")}
+}
+\`\`\`
+
+## Checking your work
+
+    npx synthesisui@latest doctor
+
+Reports how much of the shipped UI resolves to these tokens, and names the
+token for any hardcoded value that already has one.
+`;
+}
+export async function adopt(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const pkg = await readFile(join(root, "package.json"), "utf8")
+        .then((r) => JSON.parse(r))
+        .catch(() => ({ name: undefined }));
+    const found = await findTokens(root, opts.tokens);
+    console.log(section("Adopt"));
+    if (found.tokens.size === 0) {
+        // Never "failed to adopt". Always: what was looked for, where, and the
+        // next thing to type. Being stuck with no move is the worst outcome.
+        console.log(body(`Looked in ${SCOPE_HINT} across ${found.files} stylesheet${found.files === 1 ? "" : "s"} and found no custom properties.`));
+        console.log("");
+        console.log(body("If your tokens live somewhere this did not reach:"));
+        console.log(snippet(["npx synthesisui@latest adopt --tokens <path/to.css>"]));
+        console.log("");
+        console.log(body("If you do not have a system yet, start from one:"));
+        console.log(body("https://www.synthesisui.com/gallery"));
+        return;
+    }
+    const slug = opts.slug ?? guessSlug(found.tokens, pkg.name ?? "");
+    const name = (pkg.name ?? slug).replace(/^@[^/]+\//, "");
+    const dir = join(root, "_synthesisui", "ds", slug);
+    console.log(body(`Reading your system … ${found.files} stylesheet${found.files === 1 ? "" : "s"}, ${found.tokens.size} tokens found`));
+    console.log("");
+    for (const [kind, n] of byKind(found.tokens)) {
+        console.log(body(`  ${kind.padEnd(10)} ${String(n).padStart(3)}`));
+    }
+    console.log("");
+    for (const f of found.from.slice(0, 4))
+        console.log(body(`  from ${f}`));
+    if (found.from.length > 4)
+        console.log(body(`  and ${found.from.length - 4} more`));
+    if (!opts.write) {
+        console.log("");
+        console.log(body("Would create (nothing written yet):"));
+        console.log(body(`  _synthesisui/ds/${slug}/system.json    your system, described`));
+        console.log(body(`  _synthesisui/ds/${slug}/GUIDE.md       what your agent reads`));
+        console.log(body("  CLAUDE.md                              a managed block pointing at it"));
+        console.log("");
+        console.log(body("Your stylesheets are not touched. Nothing outside"));
+        console.log(body("_synthesisui/ is written, and `clean` removes all of it."));
+        console.log("");
+        console.log(snippet([
+            `npx synthesisui@latest adopt --write${opts.slug ? ` --slug ${slug}` : ""}`,
+        ]));
+        console.log(body(`writes it as "${slug}" - pass --slug to name it differently`));
+        return;
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "system.json"), `${JSON.stringify({
+        meta: { name, slug, adopted: true, source: "repository" },
+        tokens: Object.fromEntries(found.tokens),
+    }, null, 2)}\n`, "utf8");
+    await writeFile(join(dir, "GUIDE.md"), guide(name, slug, found.tokens), "utf8");
+    // `version: 0` marks a system nobody published - the doctor and CLAUDE.md
+    // read this to know it is adopted rather than installed.
+    await writeFile(join(dir, ".lock"), `${JSON.stringify({ slug, name, version: 0, adopted: true }, null, 2)}\n`, "utf8");
+    await syncClaudeMd(root);
+    console.log("");
+    console.log(body(`✓ _synthesisui/ds/${slug}/  written`));
+    console.log(body("✓ CLAUDE.md              managed block added"));
+    console.log("");
+    console.log(body("Your agent now knows your system. Nothing of yours changed."));
+    console.log("");
+    console.log(snippet(["npx synthesisui@latest doctor"]));
+    console.log(body("see what it makes measurable"));
+}

package/dist/commands/doctor.js

@@ -40,7 +40,7 @@ const SKIP = new Set([
     // Our own installed artifacts are the answer, not the problem.
     "_synthesisui",
 ]);
-async function* walk(dir) {
+export async function* walk(dir) {
     // `readdir`'s overloads infer a Buffer-named Dirent without an explicit
     // encoding; naming it keeps `e.name` a string.
     const entries = await readdir(dir, {
@@ -63,7 +63,7 @@ async function* walk(dir) {
 }
 /** The same walk over several roots, in the order the caller named them. A
  *  single file passed as a scope is read as itself. */
-async function* walkAll(roots) {
+export async function* walkAll(roots) {
     for (const r of roots) {
         if (EXTS.some((x) => r.endsWith(x))) {
             yield r;
@@ -91,6 +91,7 @@ async function loadSystem(root) {
     // reading them all is both correct and what the running app actually sees.
     let css = "";
     let lock = null;
+    let adopted = false;
     const recipes = new Map();
     const documents = [];
     for (const slug of slugs) {
@@ -118,6 +119,24 @@ async function loadSystem(root) {
             }
         }
         css += `\n${real || root}`;
+        // An ADOPTED system has no tokens.css of ours - `adopt` deliberately
+        // writes no CSS, because the project's own stylesheet already works. Its
+        // vocabulary lives in system.json, and without this the doctor falls
+        // through to harvesting and then offers to install a system to somebody
+        // who just adopted one (caught running it, 27/07).
+        if (mine?.adopted) {
+            const raw = await readFile(join(dir, "system.json"), "utf8").catch(() => "");
+            try {
+                const parsed = JSON.parse(raw);
+                for (const [k, v] of Object.entries(parsed.tokens ?? {})) {
+                    css += `\n:root { ${k}: ${v}; }`;
+                }
+                adopted = true;
+            }
+            catch {
+                // Unreadable system.json costs the naming, not the run.
+            }
+        }
         const docRaw = mine?.version
             ? await readFile(join(dir, `v${mine.version}`, "design-system.json"), "utf8").catch(() => "")
             : "";
@@ -135,7 +154,11 @@ async function loadSystem(root) {
             }
         }
     }
-    return { table: buildTable({ css, lock }), recipes, documents };
+    return {
+        table: buildTable({ css, lock, source: adopted ? "adopted" : "installed" }),
+        recipes,
+        documents,
+    };
 }
 /**
  * The project's OWN vocabulary, when we did not put one there.
@@ -321,9 +344,11 @@ export async function doctor(opts) {
     // possible first line.
     table.source === "installed"
         ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${plural(table.byName.size, "token")}, ${plural(d.scanned, "file")} read`
-        : table.source === "yours"
-            ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
-            : `No system installed - ${plural(d.scanned, "file")} read`));
+        : table.source === "adopted"
+            ? `${table.name ?? table.slug} (adopted) - ${plural(table.byName.size, "token")}, ${plural(d.scanned, "file")} read`
+            : table.source === "yours"
+                ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
+                : `No system installed - ${plural(d.scanned, "file")} read`));
     if (scopes.length > 0) {
         console.log(body(`scope: ${opts.scopes?.join(", ")}`));
     }

package/dist/doctor/tokens.js

@@ -212,7 +212,9 @@ export function parseRootTokens(css) {
 }
 export function buildTable(input) {
     const source = input.source ?? "installed";
-    const byName = source === "yours" ? parseRootTokens(input.css) : parseTokens(input.css);
+    const byName = source === "installed"
+        ? parseTokens(input.css)
+        : parseRootTokens(input.css);
     const byValue = new Map();
     for (const [name, value] of byName) {
         const key = normalizeValue(value);

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { add } from "./commands/add.js";
+import { adopt } from "./commands/adopt.js";
 import { advise } from "./commands/advise.js";
 import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
@@ -123,6 +124,15 @@ async function main() {
     const registry = typeof flags.registry === "string" ? flags.registry : undefined;
     const dir = typeof flags.dir === "string" ? flags.dir : undefined;
     switch (command) {
+        case "adopt":
+            // Dry by default: `--write` is the only way anything lands on disk.
+            await adopt({
+                dir,
+                write: flags.write === true,
+                tokens: typeof flags.tokens === "string" ? flags.tokens : undefined,
+                slug: typeof flags.slug === "string" ? flags.slug : undefined,
+            });
+            break;
         case "doctor":
             // positional paths scope the READING (the system is still found from the
             // root): `doctor apps/web packages/ui` in a monorepo

package/package.json

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