synthesisui 0.16.11 → 0.16.12

package/dist/agent-wiring.js

@@ -0,0 +1,104 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const HOOK_MATCHER = "Write|Edit|MultiEdit";
+const exists = (p) => access(p).then(() => true, () => false);
+async function readJson(path) {
+    const raw = await readFile(path, "utf8").catch(() => "");
+    if (!raw.trim())
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // A settings file we cannot parse is a file we must not rewrite. Throwing
+        // here is right: silently replacing somebody's broken JSON with ours would
+        // destroy the very thing they are in the middle of fixing.
+        throw new Error(`${path} is not valid JSON. Fix or move it, then run this again - I will not overwrite it.`);
+    }
+}
+/**
+ * HOW THE HOOK INVOKES THE CLI, AND WHY IT IS MEASURED.
+ *
+ * This runs after every Write and Edit, so the difference between paths is
+ * paid dozens of times a session. Measured 27/07: `npx synthesisui@latest hook`
+ * costs 720ms-1.5s, and pinning the version does not help - the overhead is
+ * npx itself, not the registry lookup. Running the CLI already present in
+ * node_modules is roughly ten times cheaper.
+ *
+ * So: use the local install when there is one, and fall back to npx pinned to
+ * the version being installed now. Pinned rather than `@latest` because a hook
+ * whose behaviour changes under you, on every edit, with no diff to read, is
+ * not something anyone should have to debug.
+ */
+export async function hookCommand(root, version) {
+    const local = join(root, "node_modules", ".bin", "synthesisui");
+    return (await exists(local))
+        ? "npx --no-install synthesisui hook"
+        : `npx synthesisui@${version} hook`;
+}
+async function wireHook(root, command) {
+    const dir = join(root, ".claude");
+    const path = join(dir, "settings.json");
+    const settings = await readJson(path);
+    const hooks = (settings.hooks ?? {});
+    const post = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+    // Idempotent on the COMMAND, not on the whole entry: someone may have
+    // widened the matcher or added a second hook beside ours, and running this
+    // again must not undo that.
+    const already = post.some((e) => (e.hooks ?? []).some((h) => (h.command ?? "").includes("synthesisui")));
+    if (already)
+        return "already there";
+    post.push({
+        matcher: HOOK_MATCHER,
+        hooks: [{ type: "command", command }],
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, `${JSON.stringify({ ...settings, hooks: { ...hooks, PostToolUse: post } }, null, 2)}\n`, "utf8");
+    return "added";
+}
+async function wireMcp(root, version) {
+    const path = join(root, ".mcp.json");
+    const config = await readJson(path);
+    const servers = (config.mcpServers ?? {});
+    if (servers.synthesisui)
+        return "already there";
+    const local = await exists(join(root, "node_modules", ".bin", "synthesisui"));
+    await writeFile(path, `${JSON.stringify({
+        ...config,
+        mcpServers: {
+            ...servers,
+            synthesisui: {
+                type: "stdio",
+                command: "npx",
+                args: local
+                    ? ["--no-install", "synthesisui", "mcp"]
+                    : [`synthesisui@${version}`, "mcp"],
+            },
+        },
+    }, null, 2)}\n`, "utf8");
+    return "added";
+}
+export async function wireAgent(root, version, want) {
+    const command = await hookCommand(root, version);
+    return {
+        command,
+        hook: want.hook ? await wireHook(root, command) : "skipped",
+        mcp: want.mcp ? await wireMcp(root, version) : "skipped",
+    };
+}
+/**
+ * Whether THIS project already has the hook.
+ *
+ * Read by the managed CLAUDE.md block, which must stop repeating an
+ * instruction the hook already guarantees. Two places asking for the same
+ * thing is drift in the instructions, which is a poor look for a tool that
+ * measures drift.
+ */
+export async function hasHook(root) {
+    const settings = await readJson(join(root, ".claude", "settings.json")).catch(() => ({}));
+    const post = (settings.hooks ?? {})
+        .PostToolUse;
+    if (!Array.isArray(post))
+        return false;
+    return post.some((e) => (e.hooks ?? []).some((h) => (h.command ?? "").includes("synthesisui")));
+}

package/dist/claude-md.js

@@ -1,5 +1,6 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { hasHook } from "./agent-wiring.js";
 const START = "<!-- synthesisui:start -->";
 const END = "<!-- synthesisui:end -->";
 /** Reads the installed DSs from the .lock files in _synthesisui/ds/<slug>/. */
@@ -93,7 +94,31 @@ async function readManifest(projectRoot, ds) {
  * Held in one constant on purpose: the same paragraph typed into two template
  * literals is two paragraphs that drift.
  */
-const SELF_CHECK = `
+/**
+ * WHAT THE BLOCK SAYS ABOUT CHECKING DEPENDS ON WHETHER THE HOOK IS THERE.
+ *
+ * The instruction below was measured being ignored: present, prominent, at
+ * line 24 of a 44-line file written three hours before the work started
+ * (my-test4, 27/07). "Do X after every Y" is a standing obligation that
+ * competes with the task, and 100k tokens in, the task wins.
+ *
+ * With the hook installed it is worse than useless. The check already runs
+ * after every write, so repeating the demand asks for something that has
+ * already happened - two places asking for the same thing, which is drift in
+ * the instructions, from a tool that measures drift.
+ *
+ * So the block says one of two things, decided by reading the project's own
+ * settings rather than by asking anybody. The refusal is in both, because it
+ * is the one rule no mechanism can enforce: a machine can tell you a value has
+ * no token, and only a person can decide what to call it.
+ */
+const REFUSAL = `
+
+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. An agent that quiets the report by
+adding a token is growing the system unsupervised, which is worse than the
+drift because it looks solved.`;
+const SELF_CHECK_MANUAL = `
 
 **After writing or editing any UI file, check it before moving on:**
 
@@ -102,10 +127,18 @@ const SELF_CHECK = `
 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.
+component found in a repo-wide audit next week is an archaeology exercise.${REFUSAL}
 
-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.`;
+Better than remembering: \`npx synthesisui@latest connect\` installs the check as
+an editor hook, so it runs on its own and this paragraph stops being your job.`;
+const SELF_CHECK_HOOKED = `
+
+**The check runs by itself.** A hook reports on every file you write, naming the
+token this project already has for anything hardcoded. You do not need to run
+\`doctor\` by hand, and you should not wait for a final pass.
+
+When it names something, fix it in that file before moving to the next one -
+you still have the context, so it is a two-line change.${REFUSAL}`;
 /**
  * THE INTERFACE LANGUAGE, READ FROM THE PROJECT RATHER THAN ASKED FOR.
  *
@@ -171,12 +204,15 @@ async function renderRegion(projectRoot, installed) {
     // `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 selfCheck = (await hasHook(projectRoot))
+        ? SELF_CHECK_HOOKED
+        : SELF_CHECK_MANUAL;
     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}`
+manifest for an adopted system - the tokens ARE the contract.${selfCheck}`
         : `**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.
@@ -193,7 +229,7 @@ names or type them; finding the right component is your job, not theirs.
 Only write something new when nothing in the manifest covers the purpose - and when you do,
 say which entry you considered and why it did not fit. 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.${SELF_CHECK}`;
+apply it to real production pages unless asked.${selfCheck}`;
     const locale = await readInterfaceLanguage(projectRoot);
     const language = locale === null
         ? ""

package/dist/commands/connect.js

@@ -0,0 +1,55 @@
+import { wireAgent } from "../agent-wiring.js";
+import { syncClaudeMd } from "../claude-md.js";
+import { body, section, snippet } from "../output.js";
+/**
+ * `synthesisui connect` - put the three layers where they actually run.
+ *
+ * They were all built before anything installed them, so a stranger got none
+ * of them and got, instead, the CLAUDE.md instruction we had already measured
+ * being ignored.
+ *
+ *   hook   guarantees   runs after every write, whether the agent likes it or not
+ *   mcp    audits       lets the agent ask the system instead of guessing
+ *   md     informs      and now stops repeating what the hook already ensures
+ *
+ * Separate from `init` on purpose. Installing a hook puts a command on
+ * somebody's machine that runs after every edit they make; that is a question,
+ * not a default, and it deserves its own answer rather than riding along inside
+ * a setup command.
+ */
+export async function connect(opts) {
+    const root = opts.dir ?? process.cwd();
+    // Both unless one is explicitly turned off - somebody who says `--no-hook`
+    // means it, and somebody who says nothing wants the thing to work.
+    const want = { hook: opts.hook !== false, mcp: opts.mcp !== false };
+    const wired = await wireAgent(root, opts.version, want);
+    // The block reads the settings we just wrote, so it must be regenerated
+    // after them, not before.
+    await syncClaudeMd(root);
+    console.log(section("Connected"));
+    if (want.hook) {
+        console.log(body(wired.hook === "added"
+            ? "✓ .claude/settings.json  the check now runs after every write"
+            : "· .claude/settings.json  already had it"));
+        console.log(snippet([wired.command]));
+    }
+    if (want.mcp) {
+        console.log(body(wired.mcp === "added"
+            ? "✓ .mcp.json              four tools, so the agent can ask instead of guess"
+            : "· .mcp.json              already had it"));
+    }
+    console.log(body("✓ CLAUDE.md              rewritten for what is installed"));
+    // The step that cost a round trip the first time this was tried by hand,
+    // and would cost every single person one.
+    console.log("");
+    console.log(body("Reopen your editor session - both are read at startup."));
+    if (want.mcp) {
+        console.log(body('A project MCP server needs approving once; say yes when it asks. Then "/mcp" lists synthesisui.'));
+    }
+    if (wired.command.startsWith("npx synthesisui@")) {
+        console.log("");
+        console.log(body("The hook runs through npx, which costs about 0.7s per edit. Adding"));
+        console.log(body("synthesisui to your devDependencies makes it roughly ten times faster;"));
+        console.log(body("run this again afterwards and it will switch by itself."));
+    }
+}

package/dist/commands/init.js

@@ -27,10 +27,15 @@ export async function init(opts) {
     if (opts.ds) {
         console.log("");
         await add(opts.ds, { registry: opts.registry, dir: root });
+        // The layers exist and nothing installs them unless this is said out loud.
+        console.log("");
+        console.log("  • synthesisui connect     so the check runs on its own, and your agent");
+        console.log("                            can ask this system instead of guessing");
         return;
     }
     console.log("");
     console.log("Next steps:");
+    console.log("  • synthesisui connect                 wire your agent to the system");
     console.log("  • synthesisui add <slug>              bring a design system in");
     console.log("  • synthesisui template <slug> <name>  materialize a full page");
 }

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 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";
+import { connect } from "./commands/connect.js";
 import { doctor } from "./commands/doctor.js";
 import { generate } from "./commands/generate.js";
 import { hook } from "./commands/hook.js";
@@ -16,6 +18,10 @@ import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
 import { use } from "./commands/use.js";
 import { RegistryError } from "./registry.js";
+/** Our own version, for pinning the hook and MCP commands we write into a
+ *  project. Read from the package we are running out of, so a pinned command
+ *  always names the version that produced it. */
+const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const HELP = `synthesisui - bring SynthesisUI design systems into your project
 
 Usage - deterministic, FREE:
@@ -137,6 +143,17 @@ async function main() {
             break;
         // Both of these read stdin and write a protocol frame to stdout, so
         // nothing that prints may run near them.
+        // Its own command, not a flag on init: installing a hook puts a command on
+        // somebody's machine that runs after every edit, and that is a question
+        // rather than a step that rides along inside setup.
+        case "connect":
+            await connect({
+                dir,
+                version: CLI_VERSION,
+                hook: flags.hook !== false,
+                mcp: flags.mcp !== false,
+            });
+            return;
         case "hook":
             await hook({ dir });
             return;

package/package.json

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