roast-my-design-system 8.6.2 → 8.7.0

package/README.md

@@ -8,7 +8,7 @@
 
 ## Your AI can write the UI. This makes sure it writes *your* UI.
 
-A free CLI tool, and a Claude Code plugin with two skills and a bundled local MCP server, that roasts your repo's design system with real data, reviews what you change against it, and generates the rules that keep your AI agent on-system.
+A free CLI tool, and a Claude Code plugin with two skills, a bundled local MCP server and an edit hook, that roasts your repo's design system with real data, reviews what you change against it, and generates the rules that keep your AI agent on-system.
 
 > **New in 8.0: support for the four big component kits.**
 >
@@ -97,6 +97,7 @@ These need an agent.
 |---|---|
 | <code>...&nbsp;--notes&nbsp;&lt;file.md&gt;</code> | The agent's read of this scan, embedded in the report as **"What the numbers mean"**: which findings matter, which good numbers are accidents, what to fix first. Labelled as written by AI and kept apart from the measured numbers. The Claude Code skill writes and passes it automatically; the flag is here so any agent can |
 | <code>...&nbsp;--section&nbsp;"Title"&nbsp;&lt;file.md&gt;</code> | A further agent-written chapter after the notes, same styling, same label, sub-headings allowed. Repeatable, so analysis that outgrows the notes still lives inside the report instead of a hand-built page |
+| `... --hook` | The check the Claude Code plugin runs after every edit, for hand-installed setups: reads the hook event on stdin, checks the one file that changed, prints only the findings the edit added as JSON. Always exits 0 |
 | `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, from "is there a Button already?" to "review my changes", plus the `roast-fix` prompt that serves the top fix from a fresh scan. See [Live answers over MCP](#live-answers-over-mcp) |
 | <code>/roast-my-design-system</code> (in&nbsp;Claude&nbsp;Code) | The full experience: the roast in chat *and* embedded in the report as "What the numbers mean", the rules offer, and the fix loop with Claude on your own numbers |
 
@@ -285,7 +286,7 @@ Run it inside any repo. Same scanner, same report, straight from npm. The Claude
 /plugin install roast-my-design-system@roast-my-design-system
 ```
 
-What it installs: two skills and one local MCP server, nothing else. **roast** (`/roast-my-design-system`, or "roast my design system") scans the whole repo and writes the report with Claude's read of the numbers inside it, then walks the fixes with you. **review** (`/roast-my-design-system:review`, or "review my UI changes") checks only what changed, in about a second. The bundled server gives your agent five read-only tools while it writes UI. Local, no network, no telemetry.
+What it installs: two skills, one local MCP server and one edit hook, nothing else. **roast** (`/roast-my-design-system`, or "roast my design system") scans the whole repo and writes the report with Claude's read of the numbers inside it, then walks the fixes with you. **review** (`/roast-my-design-system:review`, or "review my UI changes") checks only what changed, in about a second. The bundled server gives your agent five read-only tools while it writes UI. The hook runs after every file the agent edits and hands back the findings that edit added, so the check happens whether or not the agent thought to ask; a file with nothing new gets no message. Local, no network, no telemetry.
 
 If those commands error, your Claude Code is likely older than the plugin marketplace feature. Update Claude Code and retry, or use the manual route below: it works everywhere and installs the same skill.
 

package/cli/roast.mjs

@@ -90,6 +90,8 @@ Run it yourself
                   number of files it removed, so a scoped scan says so
   --json          print the scan summary as JSON on stdout (implies --no-open)
   --check         check the working tree's changed files (git diff + untracked)
+  --hook          Claude Code edit hook: reads the PostToolUse event on stdin,
+                  checks the one file that changed, answers with findings
                   against the design system and print the findings; exits 1
                   when something is over the line, so it composes with scripts
 
@@ -123,6 +125,20 @@ if (argv.includes('--mcp')) {
   // the server owns the process now; readline keeps it alive until the client
   // closes stdin, and nothing below (the report pipeline) may run
   await new Promise(() => {});
+} else if (argv.includes('--hook')) {
+  // Claude Code's PostToolUse hook: the event arrives as JSON on stdin, the
+  // findings leave as JSON on stdout. Exit 0 whatever happens — a hook that
+  // fails must never stop the agent editing; it only loses one check.
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  try {
+    const { hookResult } = await import(pathToFileURL(join(SCRIPTS, 'mcp/hook.mjs')).href);
+    const r = hookResult(raw.trim() ? JSON.parse(raw) : {});
+    if (r) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: r.text } }));
+  } catch (e) {
+    console.error(`roast-my-design-system --hook: ${e.message}`);
+  }
+  process.exit(0);
 } else if (argv.includes('--check')) {
   argv.splice(argv.indexOf('--check'), 1);
   const root = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.6.2",
+  "version": "8.7.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 112 public repos, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,7 +1,7 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '8.6.2';
+export const VERSION = '8.7.0';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

package/skills/roast-my-design-system/scripts/mcp/hook.mjs

@@ -0,0 +1,119 @@
+/**
+ * The edit hook — roast_validate without the agent having to ask.
+ *
+ * The MCP tools only help when the agent decides to call them. In the
+ * September 2026 runs Sonnet asked in about a third of sessions and Haiku
+ * never did, so the drift it would have caught went straight into the
+ * diff. A Claude Code plugin can also register a hook that runs after every
+ * Edit or Write; this is that hook. It reads the event, judges the one file
+ * that changed with the same engine and the same words as roast_validate,
+ * and hands the findings back as context. Silent when there is nothing to
+ * say: a hook that talks on every edit is a hook people switch off.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { validateContent } from './engine.mjs';
+import { loadKnowledge } from './knowledge.mjs';
+import { RELEVANT, beforeOf, findingLines } from './tools.mjs';
+
+const gitTop = (dir) => {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { return null; }
+};
+
+// The files a shell command may have written: everything changed or untracked
+// in the repo that the review would judge. Cheap (two git calls), and the
+// mtime ledger below keeps it from re-judging what the hook already saw.
+function changedFiles(root) {
+  try {
+    const git = (...a) => execFileSync('git', a, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const top = realpathSync.native(git('rev-parse', '--show-toplevel').trim());
+    const names = [...git('diff', 'HEAD', '--name-only').split('\n'), ...git('ls-files', '--others', '--exclude-standard', '--full-name').split('\n')];
+    return [...new Set(names.map((s) => s.trim()).filter((f) => f && RELEVANT.test(f)))].map((f) => join(top, f));
+  } catch { return []; }
+}
+
+// What the hook has judged this session, file → mtime, so a file is judged
+// once per change however it was written, and never twice for one save.
+const ledgerPath = (session) => join(tmpdir(), `roast-hook-${String(session).replace(/[^A-Za-z0-9_-]/g, '')}.json`);
+function readLedger(session) {
+  if (!session) return {};
+  try { return JSON.parse(readFileSync(ledgerPath(session), 'utf8')); } catch { return {}; }
+}
+function writeLedger(session, ledger) {
+  if (!session) return;
+  try { writeFileSync(ledgerPath(session), JSON.stringify(ledger)); } catch { /* a lost ledger costs one repeat, nothing more */ }
+}
+
+const keyOf = (f) => `${f.rule}|${f.message}`;
+/** The findings in `now` that `prior` does not account for, kind by kind. */
+export function newSince(now, prior) {
+  const budget = new Map();
+  for (const f of prior) budget.set(keyOf(f), (budget.get(keyOf(f)) ?? 0) + 1);
+  return now.filter((f) => {
+    const n = budget.get(keyOf(f)) ?? 0;
+    if (!n) return true;
+    budget.set(keyOf(f), n - 1);
+    return false;
+  });
+}
+
+/**
+ * @param payload the PostToolUse event Claude Code writes to stdin
+ * @returns { text, total } when a changed file has new findings, else null
+ */
+export function hookResult(payload) {
+  const cwd = typeof payload?.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const named = payload?.tool_input?.file_path;
+  const fromEditor = typeof named === 'string' && RELEVANT.test(named);
+  // An Edit or Write names its file. A shell command (cat > file, sed -i, a
+  // generator) names nothing, so every changed UI file is a candidate and
+  // the ledger decides which ones are new since the hook last looked.
+  const candidates = fromEditor
+    ? [isAbsolute(named) ? named : resolve(cwd, named)]
+    : payload?.tool_name === 'Bash' ? changedFiles(cwd) : [];
+  const session = payload?.session_id;
+  const ledger = readLedger(session);
+  const blocks = [];
+  let total = 0, knowledge = null;
+  for (const abs of candidates) {
+    if (!existsSync(abs)) continue;
+    const real = realpathSync.native(abs);
+    const mtime = statSync(real).mtimeMs;
+    if (!fromEditor && ledger[real] === mtime) continue;
+    ledger[real] = mtime;
+    // The repo is the session's working directory when the file lives under
+    // it (the same root the MCP server would be pointed at); a file edited
+    // elsewhere is judged against its own repository.
+    const under = (root) => root && real.startsWith(realpathSync.native(root) + '/');
+    const root = under(cwd) ? cwd : gitTop(dirname(real));
+    if (!root) continue;
+    const k = knowledge?.root === root ? knowledge : (knowledge = loadKnowledge(root));
+    const r = judge(real, root, k);
+    if (r) { blocks.push(r.text); total += r.total; }
+  }
+  writeLedger(session, ledger);
+  if (!blocks.length) return null;
+  blocks.push('Fix these now, in the repo\'s own vocabulary as each fix says (a token, a spacing step, a theme path), not by deleting the code. A value that is deliberate stays, with a one-line comment saying why.');
+  return { text: blocks.join('\n'), total };
+}
+
+/** One file against the system: only what the working copy added since HEAD. */
+function judge(real, root, k) {
+  const rel = relative(realpathSync.native(root), real).split('\\').join('/');
+  const text = readFileSync(real, 'utf8');
+  const before = beforeOf(k, rel);
+  const { findings: all, exempt } = validateContent({ text, file: rel, before }, k);
+  if (exempt || !all.length) return null;
+  // Only what this edit added. A legacy file carries its old findings on
+  // every touch; repeating them after each edit is noise, and the review
+  // (--check, roast_review) already reports them once at the end. Same rule
+  // as the September runs measured by: a finding is new when the file has
+  // more of it than the committed version did.
+  const findings = typeof before === 'string' ? newSince(all, validateContent({ text: before, file: rel }, k).findings) : all;
+  if (!findings.length) return null;
+  return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k).join('\n')}`, total: findings.length };
+}

package/skills/roast-my-design-system/scripts/mcp/tools.mjs

@@ -15,6 +15,8 @@ import { hexRgb } from '../lib/nearpairs.mjs';
 import { distinctTypefaces } from '../lib/typefaces.mjs';
 
 const CONTEXT_BUDGET = 1600; // chars ≈ 400 tokens
+// the files a review or an edit hook judges; everything else is not UI
+export const RELEVANT = /\.(tsx|jsx|ts|js|vue|svelte|css|scss|sass|less)$/i;
 const MAX_VALIDATE_CHARS = 200_000; // a whole file, not a whole bundle
 const approxTokens = (s) => Math.ceil(s.length / 4);
 
@@ -288,7 +290,7 @@ function headVersion(gitRoot, gitPath) {
     } catch { return undefined; }
   }
 }
-function beforeOf(k, file) {
+export function beforeOf(k, file) {
   if (!file) return undefined;
   try {
     const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: k.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
@@ -304,13 +306,18 @@ export function validate(k, { code, file = null } = {}) {
   const { findings, exempt } = validateContent({ text: code, file, before: beforeOf(k, file) }, k);
   if (exempt) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
   if (!findings.length) return cleanResultText(k);
+  return findingLines(findings, k).join('\n');
+}
+
+/** The finding list as roast_validate prints it; the edit hook prints the same. */
+export function findingLines(findings, k) {
   const L = [`${findings.length} finding${findings.length === 1 ? '' : 's'}:`];
   for (const f of findings.slice(0, 12)) {
     L.push(`${f.severity === 'violation' ? '✕' : '⚠'} L${f.line} ${f.message}${f.fix ? `\n   Fix: ${f.fix}` : ''}`);
   }
   if (findings.length > 12) L.push(`(+${findings.length - 12} more of the same kinds)`);
   L.push(`Checked: ${checksFor(k).join(', ')}.`);
-  return L.join('\n');
+  return L;
 }
 
 // ---------- roast_review ----------
@@ -336,7 +343,6 @@ export function reviewData(k) {
   } catch {
     return { text: 'Not a git repository (or git is unavailable), so there is no diff to review. Use roast_validate with the code instead.', total: 0 };
   }
-  const RELEVANT = /\.(tsx|jsx|ts|js|vue|svelte|css|scss|sass|less)$/i;
   const changed = names.filter((f) => RELEVANT.test(f));
   if (!changed.length) return { text: 'No changed UI or style files in the working tree. Nothing to review.', total: 0 };