synthesisui 0.16.34 → 0.16.36

package/dist/commands/import.js

@@ -0,0 +1,353 @@
+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, PER KIND.
+ *
+ * It was one global cap of 120, and a real app broke it (30/07): 2876 files,
+ * 3976 findings, and the payload came back holding exactly 120 - ranked by
+ * frequency with every kind competing for the same slots. Two things went wrong
+ * there, and the second is the serious one:
+ *
+ *   - radius and spacing lost their slots to colour, so the scale downstream
+ *     would have been built from a partial set
+ *   - the NEAR-DUPLICATE colours - a fifth grey used three times, the twin of
+ *     the brand blue - are by definition low-frequency, which is exactly what a
+ *     frequency-ranked cut throws away first. The collapse that justifies the
+ *     whole v2 lives in that tail.
+ *
+ * So colour gets a deep budget and the dimensional families get their own. The
+ * worst case is ~380 entries, about 30KB of json - cheap for the one payload
+ * that describes somebody's entire vocabulary.
+ */
+const MAX_PER_KIND = {
+    color: 250,
+    radius: 60,
+    spacing: 60,
+    motion: 40,
+    font: 30,
+};
+/**
+ * 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,
+        });
+    }
+    // Per-kind budgets, each family ranked inside its own: colour never starves
+    // radius, and the low-frequency tail of colour (where near-duplicates live)
+    // survives a cut that a global cap would have made first.
+    const kept = [];
+    const dropped = new Map();
+    for (const kind of Object.keys(MAX_PER_KIND)) {
+        const family = [...by.values()]
+            .filter((v) => v.kind === kind)
+            .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+        const budget = MAX_PER_KIND[kind];
+        if (family.length > budget)
+            dropped.set(kind, family.length - budget);
+        for (const v of family.slice(0, budget)) {
+            kept.push({
+                kind: v.kind,
+                value: v.value,
+                count: v.count,
+                files: v.files.size,
+                token: v.token,
+            });
+        }
+    }
+    // NO SILENT CAPS: a payload that quietly stops at a budget reads as "this is
+    // everything you have", which is the one thing a census must never imply.
+    for (const [kind, n] of dropped) {
+        console.log(body(paint.faint(`(${n} more ${kind} value${n === 1 ? "" : "s"} exist below the ${MAX_PER_KIND[kind]} we carry - each used less often than the ones above)`)));
+    }
+    return kept.sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+}
+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/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/package.json

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