@godxjp/ui 32.12.1 → 32.14.0

package/dist/tokens/components/data-display.css

@@ -54,6 +54,14 @@
   --prose-quote-border-width: initial;
   --prose-quote-space-inline: var(--space-3);
   --prose-code-font-size: calc(1em / var(--font-size-ratio));
+  --prose-code-block-font-size: 1em;
+
+  --prose-heading-h1-font-size: calc(
+    1em * var(--font-size-ratio) * var(--font-size-ratio) * var(--font-size-ratio)
+  );
+  --prose-heading-h2-font-size: calc(1em * var(--font-size-ratio) * var(--font-size-ratio));
+  --prose-heading-h3-font-size: calc(1em * var(--font-size-ratio));
+  --prose-heading-h4-font-size: 1em;
   --prose-code-space-inline: var(--space-1);
 
   --prose-cell-image-max-inline-size: 20rem;
@@ -63,6 +71,8 @@
   --block-editor-gutter-inline-size: calc(2 * var(--control-height-xs) + var(--space-2));
 
   --block-editor-compact-gutter-inline-size: var(--block-editor-frame-padding);
+
+  --block-editor-raw-block-head-font-size: calc(1em / var(--font-size-ratio));
   --block-editor-min-height: var(--band-height-3xl);
 
   --block-editor-frame-padding: var(--space-3);

package/dist/tokens/semantic/layout.css

@@ -56,7 +56,7 @@
   --page-header-extra-max-measure: initial;
 
   --page-toolbar-background: transparent;
-  --page-toolbar-pad-block: 0px;
+  --page-toolbar-pad-block: initial;
   --page-toolbar-divider: initial;
 
   --page-footer-divider: initial;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "32.12.1",
-  "godxUiMcp": "32.12.1",
+  "version": "32.14.0",
+  "godxUiMcp": "32.14.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -38,6 +38,9 @@
     "scripts/visual-audit-rules.mjs",
     "scripts/brand-accent.generated.mjs",
     "scripts/audit-hook.mjs",
+    "scripts/agent-guard.mjs",
+    "scripts/user-guard.mjs",
+    "scripts/mcp-call.mjs",
     "scripts/init-agent-kit.mjs",
     "scripts/init-guinea-pig.mjs",
     "scripts/guinea-pig-skill.md",

package/scripts/_agent-setup.mjs

@@ -234,6 +234,9 @@ Before any JSX for a screen:
 3. \`get_exemplar\` (no argument lists the archetypes: list, detail, editor, reader, settings,
    dashboard, approval-queue) — match its structure.
 
+No \`mcp__godx-ui__*\` tools (the session started outside this repo)? The same catalog over stdio:
+\`npx --no-install @godxjp/ui mcp-call search_components '{"query":"<area>"}'\` (no tool lists them).
+
 After building:
 4. \`npx @godxjp/ui audit <files>\` and \`npx @godxjp/ui visual-audit <url> <routes>\` (6 widths) — zero.
 5. Inspect every screenshot at every width, region by region; no top-N cap. Report "probes passed;
@@ -566,6 +569,121 @@ export function ensureClaudeHooks(root) {
   return added;
 }
 
+/**
+ * The nearest `.mcp.json` at or above `fromDir` that serves the catalog: `{ dir, key, entry }`, or
+ * null. Read-only; a malformed file reads as "no catalog here".
+ */
+export function findUiMcpConfig(fromDir) {
+  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
+    const read = readJsonFile(join(dir, ".mcp.json"));
+    if (read.state === "ok") {
+      const servers = read.json.mcpServers;
+      if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+        // The `godx-ui` key under any launcher (a local `node …/mcp/dist/index.js` link included),
+        // else whichever key launches @godxjp/ui-mcp.
+        const key = servers[MCP_KEY]
+          ? MCP_KEY
+          : Object.keys(servers).find((name) => runsUiMcp(servers[name]));
+        if (key) return { dir, key, entry: servers[key] };
+      }
+    }
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/** Where `init-agent --user` puts the guard shim, under Claude Code's user config dir. */
+export const USER_GUARD_FILE = "godxjp-ui-guard.mjs";
+const USER_GUARD_SOURCE = join(SELF_ROOT, "scripts", "user-guard.mjs");
+
+/** Claude Code's user config dir: `$CLAUDE_CONFIG_DIR`, else `~/.claude` (HOME-relative). */
+export function userConfigDir(env = process.env) {
+  return env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+
+/**
+ * `init-agent --user` (gh#1324): copy the guard shim to `<config>/hooks/godxjp-ui-guard.mjs` and
+ * register it in `<config>/settings.json` for PreToolUse and PostToolUse on Write|Edit|MultiEdit.
+ * Merges: every other key and hook is kept, an existing godxjp-ui-guard entry is left as it is,
+ * and the file is only rewritten when something was added. A settings.json that cannot be read,
+ * parsed or recognised is refused with a sidecar, like the project files.
+ * Returns the lines to print.
+ */
+export function ensureUserGuard(configDir = userConfigDir()) {
+  const lines = [];
+  const shim = join(configDir, "hooks", USER_GUARD_FILE);
+  const source = readFileSync(USER_GUARD_SOURCE, "utf8");
+  let current = null;
+  try {
+    current = readFileSync(shim, "utf8");
+  } catch {
+    // Not installed yet.
+  }
+  if (current === source) lines.push(`${shim} — present`);
+  else {
+    mkdirp(dirname(shim));
+    writeFileAtomic(shim, source);
+    lines.push(`${shim} — ${current === null ? "created" : "updated"}`);
+  }
+
+  const path = join(configDir, "settings.json");
+  const group = (event) => ({
+    matcher: "Write|Edit|MultiEdit",
+    hooks: [{ type: "command", command: `node "${shim}" ${event}` }],
+  });
+  const suggested = {
+    hooks: { PreToolUse: [group("pre")], PostToolUse: [group("post")] },
+  };
+  const read = readJsonFile(path);
+  if (read.state !== "ok" && read.state !== "missing") {
+    lines.push(
+      `${path} — ` +
+        refuseAndSuggest(path, JSON.stringify(suggested, null, 2) + "\n", READ_FAILURE[read.state]),
+    );
+    return lines;
+  }
+  const json = read.state === "ok" ? read.json : {};
+  if (
+    json.hooks !== undefined &&
+    (json.hooks === null || typeof json.hooks !== "object" || Array.isArray(json.hooks))
+  ) {
+    lines.push(
+      `${path} — ` +
+        refuseAndSuggest(
+          path,
+          JSON.stringify(suggested, null, 2) + "\n",
+          "`hooks` is not an object",
+        ),
+    );
+    return lines;
+  }
+  json.hooks = json.hooks ?? {};
+  const added = [];
+  for (const [event, arg] of [
+    ["PreToolUse", "pre"],
+    ["PostToolUse", "post"],
+  ]) {
+    const groups = json.hooks[event] ?? [];
+    if (!Array.isArray(groups)) {
+      lines.push(`${path} — hooks.${event} is not an array, left untouched`);
+      continue;
+    }
+    const has = groups.some((g) =>
+      (g?.hooks ?? []).some((h) => String(h?.command ?? "").includes(USER_GUARD_FILE)),
+    );
+    if (has) continue;
+    json.hooks[event] = [...groups, group(arg)];
+    added.push(event);
+  }
+  if (added.length === 0) {
+    lines.push(`${path} — guard hooks already present`);
+    return lines;
+  }
+  mkdirp(dirname(path));
+  writeFileAtomic(path, JSON.stringify(json, null, read.state === "ok" ? read.indent : 2) + "\n");
+  lines.push(`${path} — added ${added.join(" + ")} (Write|Edit|MultiEdit)`);
+  return lines;
+}
+
 /** Write the workflow mandate the SessionStart hook reads (only if absent). */
 export function writeWorkflowMd(root) {
   const path = join(root, ".claude", "godxjp-ui-workflow.md");

package/scripts/agent-guard.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * agent-guard — the logic behind the user-level shim (scripts/user-guard.mjs, installed by
+ * `npx godxjp-ui init-agent --user`; gh#1324). Usage, from the shim only:
+ *
+ *   node agent-guard.mjs pre|post <repo root>   < Claude Code hook payload on stdin
+ *
+ * The shim has already established that the edited .tsx/.jsx sits in <repo root> and that the
+ * repo's `.mcp.json` mounts @godxjp/ui-mcp.
+ *
+ *   pre   BLOCK (exit 2) unless the agent's own transcript shows it consulted the catalog: a tool
+ *         call to `mcp__<key>__*` for the repo's catalog key, or a Bash call to the stdio fallback
+ *         (`godxjp-ui mcp-call …`, or `godx-ui-mcp call …`). A subagent is judged by ITS transcript
+ *         (`agent_transcript_path`), so a parent's lookup does not license a subagent's write.
+ *   post  When the session did not start in <repo root>, the repo's own PostToolUse audit hook
+ *         never loaded: run this package's audit-hook.mjs in its place. Otherwise do nothing, so
+ *         a session that did start there is not audited twice.
+ *
+ * No network. FAIL OPEN: an internal error — unreadable payload, missing or unparseable
+ * transcript, a crash — exits 0. Only the deliberate "not consulted" verdict blocks.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Same test as runsUiMcp in _agent-setup.mjs — the catalog server under any key. */
+const runsUiMcp = (entry) =>
+  [entry?.command, ...(Array.isArray(entry?.args) ? entry.args : [])].some(
+    (part) => typeof part === "string" && /(^|\/)@godxjp\/ui-mcp(@|$)/.test(part),
+  );
+
+/** The `.mcp.json` keys that serve the catalog — the `<key>` in `mcp__<key>__<tool>`. */
+export function catalogKeys(root) {
+  const servers = JSON.parse(readFileSync(join(root, ".mcp.json"), "utf8"))?.mcpServers ?? {};
+  const keys = Object.keys(servers).filter((k) => k === "godx-ui" || runsUiMcp(servers[k]));
+  return keys.length ? keys : ["godx-ui"];
+}
+
+/** A Bash command that queries the catalog over the stdio fallback. */
+const CLI_CALL =
+  /\bmcp-call\s+[a-z_]+|\bui-mcp(?:@\S+)?\s+call\s+[a-z_]+|\bgodx-ui-mcp\s+call\s+[a-z_]+/;
+
+/**
+ * True when the transcript (JSONL) holds a tool_use that consulted the catalog. Only tool_use
+ * blocks count: the block message itself quotes the fallback command, and a transcript that
+ * merely CONTAINS that text (in a tool result, in the agent's prose) has not run it.
+ */
+export function consulted(transcript, keys) {
+  const prefixes = keys.map((k) => `mcp__${k}__`);
+  for (const line of transcript.split("\n")) {
+    if (!line.includes('"tool_use"')) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // a torn last line while the session is still writing
+    }
+    const content = entry?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block?.type !== "tool_use" || typeof block.name !== "string") continue;
+      if (prefixes.some((p) => block.name.startsWith(p))) return true;
+      if (block.name === "Bash" && CLI_CALL.test(String(block.input?.command ?? ""))) return true;
+    }
+  }
+  return false;
+}
+
+const realOrSelf = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+};
+
+/**
+ * Did the session START in <root>? Claude Code loads project hooks from the start directory and
+ * hands hooks `CLAUDE_PROJECT_DIR`; without it, the transcript's project folder is the start
+ * directory with every non-alphanumeric character turned into "-" (the measured layout:
+ * ~/.claude/projects/<slug>/<session>.jsonl, a subagent's under <session>/subagents/). A write in
+ * <top>/.claude/worktrees/<x> of a session started at <top> counts as started there: <top>'s
+ * hooks are the ones that loaded.
+ */
+export function startedIn(root, payload, env = process.env) {
+  const roots = new Set([resolve(root), realOrSelf(root)]);
+  for (const r of [...roots]) {
+    const at = r.indexOf(`${sep}.claude${sep}worktrees${sep}`);
+    if (at > 0) roots.add(r.slice(0, at));
+  }
+  if (env.CLAUDE_PROJECT_DIR) {
+    const start = env.CLAUDE_PROJECT_DIR;
+    return roots.has(resolve(start)) || roots.has(realOrSelf(start));
+  }
+  let transcript = String(payload?.transcript_path ?? "");
+  if (!transcript) return false;
+  if (transcript.includes(`${sep}subagents${sep}`)) transcript = dirname(dirname(transcript));
+  const slug = (p) => p.replace(/[^A-Za-z0-9]/g, "-");
+  return [...roots].some((r) => basename(dirname(transcript)) === slug(r));
+}
+
+/** The @godxjp/ui repo itself builds primitives from raw elements; the guard is for consumers. */
+function isLibrary(root) {
+  try {
+    const name = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))?.name;
+    return name === "@godxjp/ui" || name === "@godxjp/ui-mcp";
+  } catch {
+    return false;
+  }
+}
+
+export function blockMessage(file, root, keys, started) {
+  const at = /^[\w./@-]+$/.test(root) ? root : `'${root.replace(/'/g, "'\\''")}'`;
+  const key = keys[0];
+  return [
+    `godxjp-ui guard: ${file} was NOT written.`,
+    `${root} builds its UI with @godxjp/ui, and this agent has not consulted the catalog yet.`,
+    started
+      ? null
+      : `- This session did not start in ${root}, so its .mcp.json (the ${key} MCP), CLAUDE.md and hooks are NOT loaded.`,
+    `- Consult the catalog first: call mcp__${key}__search_components, then get_component for each component you use.`,
+    `  No mcp__${key}__* tools in this session? Query the same catalog over stdio:`,
+    `    cd ${at} && npx --no-install @godxjp/ui mcp-call search_components '{"query":"<what you are building>"}'`,
+    `    cd ${at} && npx --no-install @godxjp/ui mcp-call get_component '{"name":"<Component>"}'`,
+    `  (\`npx --no-install @godxjp/ui mcp-call\` with no tool lists every tool.)`,
+    `- Read ${join(root, "CLAUDE.md")} (the @godxjp/ui section), then retry the write.`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function main() {
+  const [event, root] = process.argv.slice(2);
+  if (!root || (event !== "pre" && event !== "post") || isLibrary(root)) process.exit(0);
+  const raw = readFileSync(0, "utf8");
+  const payload = JSON.parse(raw);
+  const file = payload?.tool_input?.file_path ?? payload?.tool_input?.filePath;
+  if (typeof file !== "string" || /\.(test|stories)\.[jt]sx$/.test(file)) process.exit(0);
+  const started = startedIn(root, payload);
+
+  if (event === "post") {
+    if (started) process.exit(0); // the repo's own PostToolUse audit hook already ran
+    const hook = join(HERE, "audit-hook.mjs");
+    if (!existsSync(hook)) process.exit(0);
+    const r = spawnSync(process.execPath, [hook], {
+      input: raw,
+      cwd: root,
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    if (r.error || r.status === null) process.exit(0);
+    if (r.stdout) process.stdout.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+    process.exit(r.status === 2 ? 2 : 0);
+  }
+
+  const transcriptPath = payload.agent_transcript_path ?? payload.transcript_path;
+  if (!transcriptPath || !existsSync(transcriptPath)) process.exit(0); // nothing to judge by
+  const keys = catalogKeys(root);
+  if (consulted(readFileSync(transcriptPath, "utf8"), keys)) process.exit(0);
+  process.stderr.write(blockMessage(file, root, keys, started) + "\n");
+  process.exit(2); // exit 2 on PreToolUse → Claude Code blocks the call and shows stderr
+}
+
+// Run only as a script, so tests can import the helpers.
+if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) {
+  process.on("uncaughtException", () => process.exit(0)); // fail open, see the header
+  try {
+    main();
+  } catch {
+    process.exit(0); // fail open
+  }
+}

package/scripts/cli.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
  * @godxjp/ui CLI — `npx @godxjp/ui <command>`.
- *   init-agent     scaffold the agent forcing-kit (MCP + auto-audit hook + mandate)
+ *   init-agent     scaffold the agent forcing-kit (MCP + auto-audit hook + mandate); --user: guard
+ *   mcp-call       query the godx-ui catalog over plain stdio, for a session without the MCP
  *   sync-rules     write/refresh package-owned agent rules (--dry-run previews)
  *   audit          static UI audit (regex over source)
  *   visual-audit   runtime audit (Playwright) against a running app, at six widths
@@ -17,6 +18,7 @@ const MAP = {
   "init-agent": "init-agent-kit.mjs",
   audit: "ui-audit.mjs",
   "audit-hook": "audit-hook.mjs",
+  "mcp-call": "mcp-call.mjs",
   "visual-audit": "visual-audit.mjs",
   "prune-css": "prune-css.mjs",
   codemod: "codemod.mjs",
@@ -32,7 +34,18 @@ const HELP = {
     .claude/settings.json      a PostToolUse hook that audits every Write/Edit of a .tsx file
     .claude/godxjp-ui-workflow.md
     CLAUDE.md                  the godxjp-ui mandate block
-  Idempotent. Refuses inside the @godxjp/ui repo itself. Restart the agent afterwards.`,
+  Idempotent. Refuses inside the @godxjp/ui repo itself. Restart the agent afterwards.
+
+    --user   install the USER-level guard instead (gh#1324), for sessions that start outside the
+             app: the project files above load only when Claude Code starts in the app, so a
+             session started elsewhere has no MCP, no CLAUDE.md and no audit hook. Writes
+               ~/.claude/hooks/godxjp-ui-guard.mjs   ($CLAUDE_CONFIG_DIR/hooks when set)
+               ~/.claude/settings.json               PreToolUse + PostToolUse on Write|Edit|MultiEdit
+             PreToolUse blocks a .tsx/.jsx write in a repo whose .mcp.json mounts @godxjp/ui-mcp
+             until the agent has consulted the catalog (an mcp__<key>__* call, or mcp-call).
+             PostToolUse runs that repo's audit hook when the session did not start there.
+             Merges into existing settings, idempotent, no network; the guard fails open on its
+             own errors. Remove the two entries and the file to uninstall.`,
   "sync-rules": `godxjp-ui sync-rules
 
   Refresh the package-owned agent files for the installed @godxjp/ui version: the godx-ui entry in
@@ -60,6 +73,14 @@ const HELP = {
     --rules         print the rule catalog as JSON and exit
     --consumer      inside the @godxjp/ui repo only: apply the consumer rules (always on in an app)
   Pre-commit:  npx godxjp-ui audit resources/js || exit 1`,
+  "mcp-call": `godxjp-ui mcp-call [tool] ['{"arg":"value"}']
+
+  Query the godx-ui catalog without an MCP client — for a session that did not load the app's
+  .mcp.json. Launches the app's own .mcp.json catalog entry (the pinned @godxjp/ui-mcp, its env)
+  with \`call <tool> <json>\` appended, so the text is what the MCP tool returns. No tool: list them.
+    npx --no-install @godxjp/ui mcp-call search_components '{"query":"settings page"}'
+    npx --no-install @godxjp/ui mcp-call get_component '{"name":"Segmented"}'
+  Network: as the MCP itself — npx may fetch the pinned server once on a cold cache.`,
   "audit-hook": `godxjp-ui audit-hook
 
   The Claude Code PostToolUse hook init-agent wires in: reads the hook payload on stdin and audits
@@ -114,6 +135,8 @@ const USAGE = `usage: godxjp-ui <command> [args]
 
 commands:
   init-agent     install the agent forcing-kit (MCP + auto-audit hook + CLAUDE.md mandate)
+                 --user: the user-level guard for sessions started outside the app
+  mcp-call       query the godx-ui catalog over plain stdio (no MCP client needed)
   sync-rules     write/refresh package-owned agent rules (--dry-run previews)
   audit          static UI audit over source
   audit-hook     the per-edit audit hook (wired by init-agent)