synthesisui 0.16.21 → 0.16.23

package/dist/claude-md.js

@@ -114,10 +114,13 @@ async function readManifest(projectRoot, ds) {
  */
 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.`;
+If it reports a value with no token, do NOT invent one. FILE it: the
+\`request_token\` MCP tool, or \`npx synthesisui@latest request token --value
+"<value>" --name "<what you would call it>" --for "<what it is for>"\`. A person
+decides from that queue. 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 - and a refusal that lives only in this chat evaporates, which wastes the
+best reasoning you produce.`;
 /**
  * TWO THINGS AN AGENT GOT WRONG ON 28/07, BOTH CHEAP TO SAY OUT LOUD.
  *
@@ -288,7 +291,10 @@ If an override is ignored, that component predates the resolver: regenerate it w
 \`npx synthesisui@latest component <slug> <name>\` rather than reaching for \`!\`.
 
 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
+say which entry you considered and why it did not fit, then FILE it while the reasoning is
+still yours: the \`request_component\` MCP tool, or \`npx synthesisui@latest request component
+--name "<name>" --for "<the use case>" --considered "<entries and why not>"\`. That queue is
+what the system's author works from - a refusal said only in chat evaporates. 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.${selfCheck}`;
     const locale = await readInterfaceLanguage(projectRoot);

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { findDivergences } from "../doctor/coherence.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
 import { appendEvent, readEvents, summarize } from "../doctor/ledger.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
+import { readRequests } from "../doctor/requests.js";
 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";
@@ -563,6 +564,33 @@ export async function doctor(opts) {
             }
         }
     }
+    /**
+     * RECUSA → PEDIDO, the person's side of the queue.
+     *
+     * Every request here was written by the agent at the moment it needed
+     * something the system refused to invent - which makes this list the best
+     * possible answer to "what should this system have next?": the use case and
+     * the considered-and-rejected entries arrive already argued, by the party
+     * that actually hit the gap.
+     */
+    if (hasSystem && scopes.length === 0) {
+        const requests = await readRequests(root);
+        if (requests.length > 0) {
+            console.log("");
+            console.log(section("What your agent asked for"));
+            for (const r of requests.slice(0, 8)) {
+                console.log(body(`  ${r.id}  ${r.kind === "token" ? `token ${r.value} as ${r.name}` : `component "${r.name}"`}`));
+                console.log(body(`          for: ${r.purpose}`));
+                if (r.considered)
+                    console.log(body(`          considered: ${r.considered}`));
+            }
+            if (requests.length > 8) {
+                console.log(body(`  and ${requests.length - 8} more.`));
+            }
+            console.log("");
+            console.log(body("Author it in the studio, or close it: synthesisui request --done <id>"));
+        }
+    }
     /**
      * Its own section, above drift, because it is a worse problem wearing a
      * better disguise.

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
+import { fileRequest } from "../doctor/requests.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { nearestToken, tokenFor } from "../doctor/tokens.js";
 import { component } from "./component.js";
@@ -78,6 +79,52 @@ const TOOLS = [
             required: ["name"],
         },
     },
+    {
+        name: "request_component",
+        description: "File a component request when nothing in the catalogue covers what you need. This is the OTHER HALF of the refusal rule: you already say which entry you considered and why it did not fit - said in chat, that reasoning evaporates; filed here, it becomes the queue the system's author works from. File it at the moment you build the workaround, while the reasoning is still yours.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "What you would call it, kebab-case: keyboard-hint",
+                },
+                purpose: {
+                    type: "string",
+                    description: "What you needed it for, concretely: 'a drawn key cap (⌘K) in a shortcut legend'.",
+                },
+                considered: {
+                    type: "string",
+                    description: "Which catalogue entries you considered and why each did not fit.",
+                },
+                file: {
+                    type: "string",
+                    description: "Where your workaround lives, so authoring can replace it.",
+                },
+            },
+            required: ["name", "purpose"],
+        },
+    },
+    {
+        name: "request_token",
+        description: "File a token request for a value this system has no name for. Do NOT invent a token - an agent that quiets a report by growing the system is worse than the drift. Filing is the correct move: the value, what you would call it, and what it is for, decided later by a person.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                value: {
+                    type: "string",
+                    description: "The concrete value: #ffffff, 4.5rem…",
+                },
+                name: {
+                    type: "string",
+                    description: "What you would call it: color-semantic-on-primary",
+                },
+                purpose: { type: "string", description: "What it is for." },
+                file: { type: "string", description: "Where the need arose." },
+            },
+            required: ["value", "name", "purpose"],
+        },
+    },
 ];
 async function checkFile(root, path) {
     const { table } = await loadSystem(root);
@@ -162,6 +209,26 @@ async function callTool(root, name, args) {
             return text(await listComponents(root));
         case "add_component":
             return text(await addComponent(root, String(args.name ?? "")));
+        case "request_component": {
+            const r = await fileRequest(root, {
+                kind: "component",
+                name: String(args.name ?? ""),
+                purpose: String(args.purpose ?? ""),
+                considered: args.considered ? String(args.considered) : undefined,
+                file: args.file ? String(args.file) : undefined,
+            });
+            return text(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it - keep building with your workaround, and say in your summary that the request exists.`);
+        }
+        case "request_token": {
+            const r = await fileRequest(root, {
+                kind: "token",
+                name: String(args.name ?? ""),
+                purpose: String(args.purpose ?? ""),
+                value: String(args.value ?? ""),
+                file: args.file ? String(args.file) : undefined,
+            });
+            return text(`Filed as ${r.id}. Do not add the token yourself - the request shows up in \`synthesisui doctor\` for a person to decide.`);
+        }
         default:
             return text(`No tool named ${name}.`, true);
     }

package/dist/commands/request.js

@@ -0,0 +1,62 @@
+import { resolve } from "node:path";
+import { closeRequest, fileRequest, readRequests } from "../doctor/requests.js";
+import { body, section } from "../output.js";
+/**
+ * `synthesisui request` - the queue of what the agent needed and was refused.
+ *
+ * The MCP tools are the front door (the agent files at the moment of the
+ * workaround, reasoning still warm). This command is the fallback for agents
+ * without the MCP connected, and the PERSON's half: listing the queue and
+ * closing what was authored or declined.
+ *
+ * Closing is deliberately explicit. A request nobody got to is still a
+ * request; nothing here expires.
+ */
+export async function request(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    if (opts.done) {
+        const closed = await closeRequest(root, opts.done);
+        console.log(closed
+            ? `✓ ${opts.done} closed.`
+            : `Nothing here has the id ${opts.done} - synthesisui request --list shows the queue.`);
+        return;
+    }
+    if (opts.list || !opts.kind) {
+        const all = await readRequests(root);
+        console.log(section("What your agent asked for"));
+        if (all.length === 0) {
+            console.log(body("Nothing yet. When the agent needs something the system does not have, it files the gap here instead of inventing."));
+            return;
+        }
+        for (const r of all) {
+            console.log(body(`  ${r.id}  ${r.kind === "token" ? `token ${r.value} as ${r.name}` : `component "${r.name}"`}`));
+            console.log(body(`          for: ${r.purpose}`));
+            if (r.considered)
+                console.log(body(`          considered: ${r.considered}`));
+            if (r.file)
+                console.log(body(`          workaround in: ${r.file}`));
+        }
+        console.log("");
+        console.log(body("Close one: synthesisui request --done <id>"));
+        return;
+    }
+    if (opts.kind !== "component" && opts.kind !== "token") {
+        console.log(`Unknown kind "${opts.kind}" - component or token.`);
+        return;
+    }
+    if (!opts.name || !opts.purpose || (opts.kind === "token" && !opts.value)) {
+        console.log(opts.kind === "token"
+            ? "A token request needs --value, --name and --for."
+            : "A component request needs --name and --for.");
+        return;
+    }
+    const r = await fileRequest(root, {
+        kind: opts.kind,
+        name: opts.name,
+        purpose: opts.purpose,
+        considered: opts.considered,
+        value: opts.value,
+        file: opts.file,
+    });
+    console.log(`✓ Filed as ${r.id}. It shows up in synthesisui doctor.`);
+}

package/dist/commands/sync.js

@@ -0,0 +1,98 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { readToken, resolveRegistry } from "../config.js";
+import { readEvents } from "../doctor/ledger.js";
+import { readRequests } from "../doctor/requests.js";
+import { body, section } from "../output.js";
+/**
+ * `synthesisui sync` - the ledger travels, because a person said so.
+ *
+ * The hook writes the ledger and NEVER touches the network; the doctor reads
+ * it and never sends it. This command is the one place the record leaves the
+ * machine, and it only runs by hand. That split is load-bearing: a check that
+ * phones home is a check that gets uninstalled, and the entire governance
+ * stack stands on the check staying installed.
+ *
+ * What it buys: the dashboard answer to the question a design-system lead
+ * asks before paying for anything - is my team's drift going up or down? Run
+ * it after a session, from CI after a merge, or never; the local record is
+ * complete either way.
+ *
+ * Re-running is free and safe. The server dedupes events on their identity
+ * and treats the request queue as a snapshot, so the local files remain the
+ * single source of truth.
+ */
+export async function sync(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const base = resolveRegistry(opts.registry);
+    const token = await readToken();
+    if (!token) {
+        console.log(section("Sync"));
+        console.log(body("Not logged in. The record stays local until you say so:"));
+        console.log(body("    synthesisui login"));
+        return;
+    }
+    // Which system does this project's record belong to? The .lock says.
+    const dsDir = join(root, "_synthesisui", "ds");
+    let slug = null;
+    try {
+        const slugs = (await readdir(dsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+        for (const s of slugs) {
+            const raw = await readFile(join(dsDir, s, ".lock"), "utf8").catch(() => "");
+            try {
+                const lock = JSON.parse(raw);
+                // An adopted system is described, not owned on the platform - there is
+                // no dashboard row to sync into (yet).
+                if (lock.slug && !lock.adopted) {
+                    slug = lock.slug;
+                    break;
+                }
+            }
+            catch {
+                // unreadable lock - try the next
+            }
+        }
+    }
+    catch {
+        // no _synthesisui at all
+    }
+    if (!slug) {
+        console.log(section("Sync"));
+        console.log(body("No installed system here, so there is nowhere to sync to."));
+        return;
+    }
+    const events = await readEvents(root);
+    const requests = await readRequests(root);
+    if (events.length === 0 && requests.length === 0) {
+        console.log(section("Sync"));
+        console.log(body("Nothing recorded yet. The record fills as the hook checks writes and doctor runs."));
+        return;
+    }
+    const res = await fetch(`${base}/api/ledger`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ slug, events, requests }),
+    }).catch(() => null);
+    if (!res) {
+        console.log(section("Sync"));
+        console.log(body("Could not reach the registry. The record is safe locally."));
+        return;
+    }
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        console.log(section("Sync"));
+        console.log(body(err.message ?? `The registry answered ${res.status}.`));
+        return;
+    }
+    const out = (await res.json());
+    console.log(section("Sync"));
+    console.log(body(`${out.eventsReceived} checks sent, ${out.eventsNew} new. ${out.requestsNow} open request${out.requestsNow === 1 ? "" : "s"}.`));
+    console.log("");
+    console.log(body(`The record lives on your system's overview:`));
+    console.log(body(`    ${base}/dashboard/mine/${slug}`));
+}

package/dist/doctor/requests.js

@@ -0,0 +1,74 @@
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * RECUSA → PEDIDO: the refusal becomes the request queue.
+ *
+ * The contract's proudest rule is the refusal: when the agent needs something
+ * the system does not have, it must not invent - it names the gap and stops.
+ * And then the naming EVAPORATES. It happens in a chat message: "I considered
+ * ds-readout (it is a HUD instrument, not a key legend) and composed with
+ * Row + Text instead" - which is a complete, well-argued component request,
+ * written by the party that actually needed the component, read once by one
+ * person, and gone.
+ *
+ * Nobody authors components in a vacuum. The best possible input for "what
+ * should this system have next?" is the list of things its own agent needed
+ * and was refused, each with the use case and the considered-and-rejected
+ * alternatives already written down. That list was being generated every day
+ * and stored nowhere.
+ *
+ * Same file discipline as the ledger, and the same locality argument: one
+ * JSONL inside `_synthesisui/`, nothing leaves the machine, committing it is
+ * how a team shares a queue.
+ */
+export const REQUESTS_FILE = "requests.jsonl";
+const path = (root) => join(root, "_synthesisui", REQUESTS_FILE);
+/** Stable-enough id from content: 6 chars, collision-safe at queue scale. */
+function idOf(kind, name, at) {
+    let h = 0;
+    for (const c of `${kind}:${name}:${at}`)
+        h = (h * 31 + c.charCodeAt(0)) | 0;
+    return (h >>> 0).toString(36).slice(0, 6).padStart(6, "0");
+}
+export async function fileRequest(root, req) {
+    const at = req.at ?? new Date().toISOString();
+    const full = { ...req, at, id: idOf(req.kind, req.name, at) };
+    try {
+        await appendFile(path(root), `${JSON.stringify(full)}\n`, "utf8");
+    }
+    catch {
+        // A queue that can break the caller is a queue that gets bypassed. The
+        // request is still returned, so the tool's answer can carry it.
+    }
+    return full;
+}
+export async function readRequests(root) {
+    const raw = await readFile(path(root), "utf8").catch(() => "");
+    if (!raw)
+        return [];
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (r?.id && r.name && (r.kind === "component" || r.kind === "token"))
+                out.push(r);
+        }
+        catch {
+            // A corrupt line loses itself, not the queue.
+        }
+    }
+    return out;
+}
+/** Closing is a PERSON's act - authored it, or decided against it. Either way
+ *  the queue shrinks by explicit hand, never by timeout: a request nobody got
+ *  to is still a request. */
+export async function closeRequest(root, id) {
+    const all = await readRequests(root);
+    const keep = all.filter((r) => r.id !== id);
+    if (keep.length === all.length)
+        return false;
+    await writeFile(path(root), keep.length ? `${keep.map((r) => JSON.stringify(r)).join("\n")}\n` : "", "utf8");
+    return true;
+}

package/dist/index.js

@@ -14,6 +14,8 @@ import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
 import { mcp } from "./commands/mcp.js";
 import { refit } from "./commands/refit.js";
+import { request } from "./commands/request.js";
+import { sync } from "./commands/sync.js";
 import { template } from "./commands/template.js";
 import { upgrade } from "./commands/upgrade.js";
 import { use } from "./commands/use.js";
@@ -330,6 +332,26 @@ async function main() {
         case "clean":
             await clean({ dir, force: flags.force === true });
             break;
+        case "sync":
+            await sync({ dir, registry });
+            break;
+        case "request": {
+            // `synthesisui request` lists; `request component --name x --for "..."`
+            // files; `request --done <id>` closes. The agent's front door is the MCP
+            // tool - this is the fallback and the person's half.
+            await request({
+                dir,
+                kind: args[0],
+                name: typeof flags.name === "string" ? flags.name : undefined,
+                purpose: typeof flags.for === "string" ? flags.for : undefined,
+                considered: typeof flags.considered === "string" ? flags.considered : undefined,
+                value: typeof flags.value === "string" ? flags.value : undefined,
+                file: typeof flags.file === "string" ? flags.file : undefined,
+                done: typeof flags.done === "string" ? flags.done : undefined,
+                list: flags.list === true,
+            });
+            break;
+        }
         case "advise": {
             const valueProp = args.join(" ").trim();
             if (!valueProp) {

package/package.json

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