@palate/cli 0.0.0-stage → 0.0.1

package/src/copy.mjs

@@ -0,0 +1,188 @@
+// `palate copy`: reads the words a page shows (from its source, no browser) and flags phrasing that reads as
+// written by a model rather than by the company. Each finding says why it reads that way and what to write
+// instead. Three weights:
+//   stop   one is enough: hype, filler, placeholder copy, proof with no source. The guard won't let a page finish on one.
+//   habit  fine once, a habit when it comes back (two fragment slogans, a third "powerful"). Flagged past its limit.
+//   hint   a soft sign, only listed. Four or more on one page read as generated together, and the report says so.
+// Words inside the project's own name or a waiver (.palate/waivers.json) are skipped.
+import fs from "node:fs";
+import path from "node:path";
+
+const word = (list) => new RegExp(`\\b(?:${list})\\b`, "i");
+
+export const TELLS = [
+  // stop
+  { id: "copy-hype", weight: "stop", re: word("unlock(?:s|ing)?|unleash(?:es|ing)?|supercharg(?:e|es|ing)|turbocharg(?:e|es|ing)|elevat(?:e|es|ing) your|empower(?:s|ing)?|revolutioni[sz](?:e|es|ing)|reimagin(?:e|ed|es|ing)|redefin(?:e|es|ing)|transform(?:s)? (?:the way|how) you|streamlin(?:e|es|ing)|leverag(?:e|es|ing)"), why: "A hype verb promises a feeling, not a result.", fix: "Say what changes for the reader, with a number or an example." },
+  { id: "copy-inflated", weight: "stop", re: word("seamless(?:ly)?|effortless(?:ly)?|cutting[- ]edge|next[- ]level|world[- ]class|best[- ]in[- ]class|state[- ]of[- ]the[- ]art|game[- ]chang(?:er|ing)|groundbreaking|innovative|blazing(?:ly)?[- ]fast|lightning[- ]fast|unparalleled|unrivall?ed"), why: "Inflated adjectives are what every page says, so they say nothing.", fix: "Replace it with the fact behind it (how fast, how many, compared with what)." },
+  { id: "copy-filler", weight: "stop", re: word("delve|tapestry|a testament to|embark on|in today'?s (?:fast[- ]paced|digital|modern) (?:world|landscape|age)|ever[- ]evolving|navigat(?:e|ing) the (?:complexities|world) of|look no further|we'?ve got you covered|say goodbye to|harness(?:ing)? the power|the power of|take (?:your|it) to the next level|at the intersection of|in the realm of"), why: "Stock phrasing that models reach for and people rarely write.", fix: "Cut it and start with the specific thing." },
+  { id: "copy-placeholder", weight: "stop", re: /lorem ipsum|dolor sit amet|your (?:tagline|headline|company|logo) here|\b(?:john|jane) doe\b|\bacme (?:inc|corp|co)\b|\bexample company\b|\bTBD\b|\bcoming soon\b(?![^.]{0,40}\d)/i, why: "Placeholder copy left on the page.", fix: "Use the project's real words, or remove the block until they exist." },
+  { id: "copy-vague-proof", weight: "stop", re: /\b(?:thousands|millions|hundreds|tons) of (?:happy |satisfied |delighted )?(?:users|customers|teams|companies|developers|creators|businesses)\b|\btrusted by (?:thousands|millions|teams worldwide|the best|leading)\b|\bloved by (?:thousands|millions|teams|developers|everyone)\b|\bindustry[- ]leading\b/i, why: "Proof with no number or source reads as invented.", fix: "Give the real count and where it comes from, or name the customers, or cut it." },
+  { id: "copy-not-just", weight: "stop", re: /\bnot just (?:an?|another|the)?\s*[\w-]+(?:\s[\w-]+)?\s*[,.;:—–-]+\s*(?:it'?s|but|we'?re|this is)\b|\bmore than just (?:an?|another)\b|\bisn'?t just (?:an?|another)\b/i, why: "The \"not just X, it's Y\" turn is a model habit; it argues with a claim nobody made.", fix: "State what it is, plainly, once." },
+  { id: "copy-click-here", weight: "stop", re: /^\s*(?:click here|tap here)\s*$/i, short: true, why: "\"Click here\" names the gesture, not the destination, and reads badly to screen readers.", fix: "Name what the link opens: \"Read the pricing\", \"Download the report\"." },
+  // habit
+  { id: "copy-intensifier", weight: "habit", limit: 2, re: word("powerful|robust|simple|simply|easy|easily|instantly|truly|incredibly|amazing|beautiful(?:ly)?|stunning|intuitive"), why: "Intensifiers stand in for evidence; past two on a page they read as filler.", fix: "Keep the one you can show; show the rest (a timing, a screenshot, a step count)." },
+  { id: "copy-everything", weight: "habit", limit: 1, re: word("everything you need|all[- ]in[- ]one|in one place|one platform|one tool for|a single source of truth"), why: "\"Everything in one place\" is the default pitch of every tool.", fix: "Name the two or three things it actually does." },
+  { id: "copy-slogan-trio", weight: "habit", limit: 1, re: /^\s*(?:[\p{Lu}][\p{L}'’]*(?:\s[\p{L}'’]+){0,2}[.!]\s*){3}$/u, short: true, why: "Three clipped fragments (\"Plan. Build. Ship.\") are fine once; twice is a template.", fix: "Write one of them as a sentence." },
+  { id: "copy-adjective-trio", weight: "habit", limit: 1, re: /^\s*[\p{L}-]+,\s+[\p{L}-]+,?\s+and\s+[\p{L}-]+[.!]?\s*$/iu, short: true, why: "\"Fast, simple, and secure\" lists virtues no one would argue against.", fix: "Keep the one that's true and different, and prove it." },
+  { id: "copy-exclaim", weight: "habit", limit: 1, re: /\w!(?:\s|$)/, why: "Exclamation marks in interface copy read as forced enthusiasm.", fix: "End on a full stop; let the content carry it." },
+  { id: "copy-vague-cta", weight: "habit", limit: 1, re: /^\s*(?:learn more|read more|discover more|find out more|explore|see more|get started now)\s*[→›>]?\s*$/i, short: true, why: "A vague button text repeated across sections; nobody knows where each one goes.", fix: "Verb plus object: \"See the pricing\", \"Read the API docs\"." },
+  // hint
+  { id: "copy-question-hook", weight: "hint", re: /\b(?:ready to|want to|looking to|tired of|struggling (?:to|with)|ever wish(?:ed)?)\b[^?]{0,80}\?/i, why: "A rhetorical question as a hook is a stock opener.", fix: "Answer it instead: say what the reader gets." },
+  { id: "copy-announce", weight: "hint", re: /^\s*(?:introducing|meet|say hello to)\b|\bwe'?re (?:excited|thrilled|proud) to\b/i, why: "Announcing the product instead of describing it.", fix: "Lead with what it does." },
+  { id: "copy-future-of", weight: "hint", re: /\bthe future of\b|\bbuilt for (?:the )?(?:modern|next generation|tomorrow)\b|\bfor the (?:modern|AI) era\b/i, why: "\"The future of X\" claims a category instead of describing a product.", fix: "Describe what someone can do with it today." },
+  { id: "copy-solution", weight: "hint", re: word("solutions?|a suite of|end[- ]to[- ]end|at scale|unlock(?:s)? value|actionable insights|drive (?:growth|results|engagement)"), why: "Consultant nouns hide what the thing is.", fix: "Use the plain noun: an app, a report, a checker." },
+  { id: "copy-title-case", weight: "hint", re: null, why: "Every Word Capitalised reads as a template heading.", fix: "Sentence case: capitalise the first word and names only." },
+  { id: "copy-dash-aside", weight: "hint", re: /\s[—–]\s.+\s[—–]\s|\w—\w.*\w—\w/, why: "A pair of dashes around an aside is a strong model habit in prose.", fix: "Use commas, brackets or two sentences." },
+];
+
+const UI = /\.(tsx|jsx|vue|svelte|astro|html|mdx)$/i; // .md is notes and docs, not page copy
+const CONTENT = /\.(ts|js|mjs|json)$/i; // copy kept in content files (content.ts, strings.json)
+const SKIP = /(^|\/)(node_modules|\.next|dist|out|build|\.palate|\.git|coverage|public)\//;
+const NOT_COPY = /\.(test|spec|stories|d)\.[a-z]+$/i;
+
+// Text a reader sees, with its line: JSX/HTML text between tags, readable attributes, and prose string literals.
+export function extractCopy(source, file = "") {
+  const out = [];
+  const lines = source.split("\n");
+  const at = (index) => source.slice(0, index).split("\n").length;
+  const push = (text, index, tag) => {
+    const t = text.replace(/ | /g, " ").replace(/&/g, "&").replace(/’|'|'/g, "'").replace(/\{\s*["'`]\s*["'`]\s*\}/g, " ").replace(/\s+/g, " ").trim();
+    if (t && /\p{L}{2}/u.test(t) && !/^[{}()[\];,.:<>=/\\|&*+-]+$/.test(t)) out.push({ text: t, line: at(index), at: index, ...(tag ? { tag } : {}) });
+  };
+  let body = source;
+  // Comments never count.
+  body = body.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/(^|[^:"'`\\])\/\/[^\n]*/g, (m, p) => p + " ".repeat(m.length - p.length)).replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " ")).replace(/\{\/\*[\s\S]*?\*\/\}/g, (m) => m.replace(/[^\n]/g, " "));
+  if (UI.test(file)) {
+    // Code blocks and style/script bodies aren't copy.
+    const masked = body.replace(/<(script|style|code|pre)\b[\s\S]*?<\/\1>/gi, (m) => m.replace(/[^\n]/g, " "));
+    if (/\.mdx$/i.test(file)) {
+      masked.split("\n").forEach((l, i) => {
+        if (!/^\s*(```|import |export |<|\|)/.test(l) && /\p{L}{2}/u.test(l)) out.push({ text: l.replace(/^#+\s*|[*_`]/g, "").trim(), line: i + 1, ...(/^\s*#/.test(l) ? { tag: "h" } : {}) });
+      });
+    } else {
+      for (const m of masked.matchAll(/>([^<>{}]*(?:\{["'`][^"'`{}]*["'`]\}[^<>{}]*)*)</g)) {
+        if (!/\p{L}{2}/u.test(m[1])) continue;
+        // The element this text sits in: a heading gets the heading-only checks.
+        const open = masked.lastIndexOf("<", m.index);
+        const tag = /^<\s*([A-Za-z][\w.-]*)/.exec(masked.slice(open, m.index + 1))?.[1]?.toLowerCase();
+        push(m[1], m.index + 1, tag && /^h[1-6]$/.test(tag) ? "h" : undefined);
+      }
+      for (const m of masked.matchAll(/\b(alt|title|aria-label|placeholder|label|content)=(["'])([^"'\n]{3,})\2/g)) push(m[3], m.index);
+    }
+  }
+  if (UI.test(file) || CONTENT.test(file)) {
+    for (const m of body.matchAll(/(["'`])((?:(?!\1)[^\\\n]|\\.){12,})\1/g)) {
+      const s = m[2];
+      if (/\$\{|^\s*[./@#]|https?:|\.(png|jpe?g|svg|webp|mp4|css|tsx?|mjs)\b/i.test(s)) continue;
+      if (!proseLike(s)) continue;
+      const text = s.replace(/\\(["'`n])/g, (_, c) => (c === "n" ? " " : c)).replace(/\s+/g, " ").trim();
+      // The tag pass already read this one (an attribute value or a quoted child).
+      if (out.some((c) => c.line === at(m.index) && c.text === text)) continue;
+      push(text, m.index);
+    }
+  }
+  return out.filter((c) => c.line <= lines.length + 1).map(({ at: _, ...c }) => c);
+}
+
+// A string a person reads: three or more words, mostly words, not a class list, a key path or a regex.
+export function proseLike(s) {
+  const words = s.trim().split(/\s+/);
+  if (words.length < 3) return false;
+  const codey = words.filter((w) => /[-:[\]/=_]{1}/.test(w) && /^[a-z0-9:[\]/#%.()!_=-]+$/.test(w)).length;
+  if (codey / words.length > 0.25) return false;
+  if (/[{};=<>]|=>|\b(function|return|const|import)\b/.test(s)) return false;
+  const real = words.filter((w) => /^[\p{L}'’,.!?:;"()-]+$/u.test(w) && /\p{L}{2}/u.test(w)).length;
+  return real / words.length >= 0.6;
+}
+
+const TITLE_SMALL = new Set(["a", "an", "and", "as", "at", "but", "by", "for", "in", "nor", "of", "on", "or", "the", "to", "vs", "via", "with", "from", "into"]);
+export function titleCased(text) {
+  const words = text.replace(/[.!?:]+$/, "").split(/\s+/).filter(Boolean);
+  if (words.length < 4 || words.length > 12 || /[.!?]\s/.test(text)) return false;
+  const big = words.slice(1).filter((w) => /^\p{L}/u.test(w) && !TITLE_SMALL.has(w.toLowerCase()));
+  if (big.length < 3) return false;
+  return big.every((w) => /^\p{Lu}\p{Ll}/u.test(w)) && !big.every((w) => /^\p{Lu}+$/u.test(w));
+}
+
+// Lint a list of copy entries ({ text, line, file }). Returns findings with weight; habits only past their limit.
+export function lintCopy(entries, { name = "" } = {}) {
+  const own = name ? new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "gi") : null;
+  const hits = [];
+  for (const e of entries) {
+    const text = own ? e.text.replace(own, " ") : e.text;
+    const short = text.length <= 60;
+    for (const t of TELLS) {
+      if (t.id === "copy-title-case") {
+        if (e.tag === "h" && short && titleCased(text)) hits.push({ ...pick(t), file: e.file, line: e.line, text: e.text });
+        continue;
+      }
+      if (t.short && !short) continue;
+      // A habit counts every use; the others one finding per line.
+      const ms = t.weight === "habit" ? [...text.matchAll(new RegExp(t.re.source, t.re.flags.includes("g") ? t.re.flags : t.re.flags + "g"))] : [t.re.exec(text)].filter(Boolean);
+      for (const m of ms) {
+        // A capitalised word mid-sentence is a name ("Simple Icons", "Robust Labs"), not the adjective.
+        if (t.id === "copy-intensifier" && m.index > 0 && /^\p{Lu}/u.test(m[0]) && !/[.!?:]\s*$/.test(text.slice(0, m.index))) continue;
+        hits.push({ ...pick(t), file: e.file, line: e.line, text: e.text, match: m[0].trim() });
+      }
+    }
+  }
+  // Habits: the first `limit` uses are fine; the rest are findings (each listed with the earlier ones as context).
+  const out = [];
+  const byId = new Map();
+  for (const h of hits) (byId.get(h.id) ?? byId.set(h.id, []).get(h.id)).push(h);
+  for (const [, list] of byId) {
+    const t = TELLS.find((x) => x.id === list[0].id);
+    if (t.weight === "habit") { if (list.length > t.limit) out.push(...list.map((h, i) => ({ ...h, over: i >= t.limit }))); }
+    else out.push(...list);
+  }
+  return out;
+}
+const pick = ({ id, weight, why, fix, limit }) => ({ id, weight, why, fix, ...(limit ? { limit } : {}) });
+
+// The project's name, so its own words ("Seamless Inc.") aren't flagged: package.json name, else the folder.
+export function projectName(dir) {
+  try {
+    const n = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).name;
+    if (n && !/^@?[\w-]+\/(app|web|site)$/.test(n)) return String(n).replace(/^@[\w-]+\//, "").replace(/[-_]+/g, " ");
+  } catch {}
+  return path.basename(dir).replace(/[-_]+/g, " ");
+}
+
+export const isCopyFile = (f) => (UI.test(f) || CONTENT.test(f)) && !SKIP.test(`/${f.replace(/\\/g, "/")}`) && !NOT_COPY.test(f) && !/(^|\/)(package|tsconfig|components)\.json$|lock|config\.|\.config\./i.test(f);
+
+// Lint files (relative to dir). Content files only count their prose strings.
+export function lintFiles(dir, files, opts = {}) {
+  const entries = [];
+  for (const f of files.filter(isCopyFile)) {
+    let src;
+    try { src = fs.readFileSync(path.join(dir, f), "utf8"); } catch { continue; }
+    if (src.length > 400_000) continue;
+    for (const c of extractCopy(src, f)) entries.push({ ...c, file: f.replace(/\\/g, "/") });
+  }
+  return { entries: entries.length, findings: lintCopy(entries, { name: opts.name ?? projectName(dir) }) };
+}
+
+// The report palate prints.
+export function copyReport({ entries, findings }, { files = 0 } = {}) {
+  const real = findings.filter((f) => f.weight !== "habit" || f.over);
+  if (!real.length) return `palate copy: ${entries} line${entries === 1 ? "" : "s"} of copy in ${files} file${files === 1 ? "" : "s"}, nothing reads as generated.`;
+  const stops = real.filter((f) => f.weight === "stop").length;
+  const habits = new Set(real.filter((f) => f.weight === "habit").map((f) => f.id)).size;
+  const hints = real.filter((f) => f.weight === "hint").length;
+  const out = [`palate copy: ${[stops && `${stops} to fix`, habits && `${habits} repeated habit${habits > 1 ? "s" : ""}`, hints && `${hints} hint${hints > 1 ? "s" : ""}`].filter(Boolean).join(", ")} in ${entries} lines of copy`];
+  if (hints >= 4) out.push("Four or more soft signs together: this copy reads as generated. Rewrite it in the project's own voice, not just the flagged words.");
+  out.push("");
+  const byId = new Map();
+  for (const f of findings) (byId.get(f.id) ?? byId.set(f.id, []).get(f.id)).push(f);
+  for (const w of ["stop", "habit", "hint"])
+    for (const [id, list] of byId) {
+      if (list[0].weight !== w) continue;
+      const head = w === "habit" ? `${list.length} uses, ${list[0].limit} is the limit` : `${list.length}`;
+      out.push(`## ${id} (${w}, ${head}): ${list[0].why} ${list[0].fix}`);
+      for (const f of list.slice(0, 6)) out.push(`- ${f.file}:${f.line} "${f.text.slice(0, 90)}"${f.match && f.match.length < f.text.length ? ` (${f.match})` : ""}`);
+      if (list.length > 6) out.push(`- … ${list.length - 6} more`);
+      out.push("");
+    }
+  out.push("Your own brand words are fine: waive one with a reason (palate waive <id> --file <file> --reason \"…\").");
+  return out.join("\n").trimEnd();
+}

package/src/devserver.mjs

@@ -0,0 +1,135 @@
+// Starts the project's own dev server on a free port, whatever the stack: palate needs a live page to
+// screenshot. Known frameworks are started directly from node_modules with an explicit port; anything else
+// runs the project's "dev" (or "start") script with PORT set, and palate reads the URL it prints.
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+
+export const freePort = () =>
+  new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.on("error", reject);
+    s.listen(0, "127.0.0.1", () => {
+      const p = s.address().port;
+      s.close(() => resolve(p));
+    });
+  });
+
+export async function waitFor(url, ms) {
+  const until = Date.now() + ms;
+  while (Date.now() < until) {
+    try {
+      if ((await fetch(url)).status < 500) return true;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return false;
+}
+
+export function kill(child) {
+  if (!child || child.exitCode !== null) return;
+  if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+  else child.kill("SIGTERM");
+}
+
+const bin = (dir, ...p) => path.join(dir, "node_modules", ...p);
+
+// The first framework whose package is installed wins. Each entry: the script to run with node, and its args.
+const FRAMEWORKS = [
+  { name: "Next.js", pkg: "next", script: ["next", "dist", "bin", "next"], args: (port) => ["dev", "-p", String(port), "-H", "127.0.0.1"] },
+  { name: "Nuxt", pkg: "nuxt", script: ["nuxi", "bin", "nuxi.mjs"], args: (port) => ["dev", "--port", String(port), "--host", "127.0.0.1"] },
+  { name: "Astro", pkg: "astro", script: ["astro", "astro.js"], args: (port) => ["dev", "--port", String(port), "--host", "127.0.0.1"] },
+  { name: "React Router", pkg: "@react-router/dev", script: ["@react-router", "dev", "bin.js"], args: (port) => ["dev", "--port", String(port), "--host", "127.0.0.1"] },
+  { name: "Remix", pkg: "@remix-run/dev", script: ["@remix-run", "dev", "dist", "cli.js"], args: (port) => ["vite:dev", "--port", String(port), "--host", "127.0.0.1"] },
+  { name: "Angular", pkg: "@angular/cli", script: ["@angular", "cli", "bin", "ng.js"], args: (port) => ["serve", "--port", String(port), "--host", "127.0.0.1"] },
+  { name: "Vite", pkg: "vite", script: ["vite", "bin", "vite.js"], args: (port) => ["--port", String(port), "--strictPort", "--host", "127.0.0.1"] },
+  { name: "Create React App", pkg: "react-scripts", script: ["react-scripts", "bin", "react-scripts.js"], args: () => ["start"], env: (port) => ({ PORT: String(port), BROWSER: "none", HOST: "127.0.0.1" }) },
+];
+
+export function detectStack(dir) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  } catch {}
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const fw = FRAMEWORKS.find((f) => f.pkg in deps && fs.existsSync(bin(dir, ...f.script)));
+  return { framework: fw, scripts: pkg.scripts ?? {} };
+}
+
+// A dev server that was already running (the user's, or another agent's) is remembered in
+// .palate/devserver.json, so the next command uses it at once instead of spawning a server to find it.
+const cacheFile = (dir) => path.join(dir, ".palate", "devserver.json");
+function rememberRunning(dir, base, name) {
+  try {
+    fs.mkdirSync(path.join(dir, ".palate"), { recursive: true });
+    fs.writeFileSync(cacheFile(dir), JSON.stringify({ base, name, at: new Date().toISOString() }));
+  } catch {}
+}
+async function cachedRunning(dir) {
+  try {
+    const c = JSON.parse(fs.readFileSync(cacheFile(dir), "utf8"));
+    if (Date.now() - Date.parse(c.at) > 12 * 3600_000) return null;
+    const r = await fetch(c.base, { signal: AbortSignal.timeout(4000) });
+    return r.status < 500 ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+// Returns { base, stop, name }. With `url`, uses an already-running server instead.
+export async function startDevServer(dir, { url, timeout = 120_000 } = {}) {
+  if (url) return { base: url.replace(/\/$/, ""), stop: () => {}, name: "your running server" };
+  const cached = await cachedRunning(dir);
+  if (cached) return { base: cached.base, stop: () => {}, name: `${cached.name} (already running)` };
+  const { framework, scripts } = detectStack(dir);
+  const port = await freePort();
+  const log = [];
+  let child;
+  let base = `http://127.0.0.1:${port}`;
+  if (framework) {
+    child = spawn(process.execPath, [bin(dir, ...framework.script), ...framework.args(port)], { cwd: dir, windowsHide: true, env: { ...process.env, ...(framework.env?.(port) ?? {}) } });
+  } else {
+    const script = scripts.dev ? "dev" : scripts.start ? "start" : null;
+    if (!script) throw new Error("palate can't tell how to start this project's dev server. Start it yourself and pass --url http://localhost:PORT");
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    child = spawn(npm, ["run", script], { cwd: dir, windowsHide: true, shell: process.platform === "win32", env: { ...process.env, PORT: String(port), BROWSER: "none" } });
+    base = null;
+  }
+  child.stdout.on("data", (d) => log.push(String(d)));
+  child.stderr.on("data", (d) => log.push(String(d)));
+  let exited = false;
+  child.on("exit", () => (exited = true));
+  // Next.js 16 allows one dev server per project; when one is running (another agent's, or the user's), use it.
+  const running = () => {
+    const t = log.join("");
+    const i = t.search(/already running/i);
+    return i < 0 ? null : (t.slice(i).match(/Local:\s*(https?:\/\/[^\s]+)/)?.[1].replace(/\/$/, "") ?? null);
+  };
+  const until = Date.now() + timeout;
+  let up = false;
+  while (!up && Date.now() < until) {
+    const other = running();
+    if (other) {
+      kill(child);
+      rememberRunning(dir, other, framework?.name ?? "dev server");
+      return { base: other, stop: () => {}, name: `${framework?.name ?? "dev server"} (already running)` };
+    }
+    // Unknown stacks print where they listen; known ones listen where we told them.
+    const m = !base && log.join("").match(/https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0):(\d+)/);
+    if (m) base = `http://127.0.0.1:${m[1]}`;
+    if (base) up = await waitFor(base, 1000);
+    else await new Promise((r) => setTimeout(r, 250));
+    // Next answers briefly before it notices the other server and exits, so let it settle once.
+    if (up) {
+      await new Promise((r) => setTimeout(r, 1500));
+      up = !exited && !running();
+    }
+    if (exited && !up && !running()) break;
+  }
+  if (!up) {
+    kill(child);
+    throw new Error(`The dev server did not start (${framework?.name ?? "npm run dev"}):\n${log.join("").slice(-1500)}\nStart it yourself and pass --url http://localhost:PORT`);
+  }
+  return { base, stop: () => kill(child), name: framework?.name ?? "npm run dev" };
+}

package/src/fontgenre.mjs

@@ -0,0 +1,44 @@
+// What kind of typeface a family is: serif, sans, slab, mono, display or script. palate's look check uses it to
+// tell when pages share a visual language (every page in a serif headline over a grotesque body reads as one
+// house style, whatever the exact faces). Known Google Fonts / OFL families first, then the name's own words.
+
+const LISTS = {
+  serif: ["fraunces", "young serif", "gloock", "instrument serif", "playfair display", "playfair", "eb garamond", "cormorant", "cormorant garamond", "libre baskerville", "libre caslon text", "libre caslon display", "lora", "merriweather", "newsreader", "spectral", "crimson pro", "crimson text", "source serif 4", "source serif pro", "pt serif", "noto serif", "dm serif display", "dm serif text", "bodoni moda", "literata", "petrona", "gelasio", "domine", "vollkorn", "alegreya", "cardo", "old standard tt", "rufina", "marcellus", "cinzel", "prata", "roboto serif", "ibm plex serif", "besley", "brygada 1918", "castoro", "fanwood text", "gilda display", "italiana", "junicode", "linden hill", "ovo", "piazzolla", "radley", "sorts mill goudy", "tenor sans", "trirong", "unna", "yrsa", "rasa", "georgia", "times new roman", "tiempos", "recoleta", "canela", "editorial new", "ui-serif"],
+  slab: ["roboto slab", "zilla slab", "arvo", "bitter", "josefin slab", "rokkitt", "aleo", "crete round", "kameron", "noticia text", "podkova", "slabo 27px", "patua one", "ultra", "alfa slab one", "ibm plex mono slab"],
+  mono: ["jetbrains mono", "ibm plex mono", "space mono", "dm mono", "fira code", "fira mono", "source code pro", "roboto mono", "inconsolata", "martian mono", "commit mono", "geist mono", "ubuntu mono", "courier prime", "courier new", "overpass mono", "red hat mono", "azeret mono", "major mono display", "xanh mono", "ui-monospace", "menlo", "consolas"],
+  script: ["caveat", "dancing script", "pacifico", "great vibes", "satisfy", "homemade apple", "kalam", "shadows into light", "indie flower", "permanent marker", "sacramento", "allura", "parisienne", "nothing you could do", "reenie beanie", "la belle aurore", "covered by your grace", "nanum pen script", "gochi hand", "patrick hand", "architects daughter"],
+  display: ["bricolage grotesque", "syne", "unbounded", "bebas neue", "anton", "archivo black", "big shoulders display", "climate crisis", "dela gothic one", "abril fatface", "rubik mono one", "monoton", "bungee", "righteous", "fredoka", "lobster", "chivo mono", "darker grotesque", "familjen grotesk", "hanken grotesk display", "migra", "clash display", "cabinet grotesk", "gambetta", "bowlby one", "titan one", "staatliches", "oswald", "league gothic", "six caps", "londrina solid", "shrikhand", "yeseva one", "bagel fat one", "rammetto one", "averia sans libre", "averia serif libre"],
+  sans: ["inter", "geist", "roboto", "open sans", "lato", "montserrat", "poppins", "nunito", "nunito sans", "work sans", "public sans", "ibm plex sans", "hanken grotesk", "instrument sans", "dm sans", "manrope", "plus jakarta sans", "outfit", "sora", "space grotesk", "karla", "rubik", "figtree", "onest", "archivo", "be vietnam pro", "albert sans", "schibsted grotesk", "red hat display", "red hat text", "source sans 3", "source sans pro", "pt sans", "noto sans", "atkinson hyperlegible", "lexend", "mulish", "urbanist", "epilogue", "chivo", "barlow", "fira sans", "heebo", "jost", "kumbh sans", "overpass", "raleway", "ubuntu", "work sans", "satoshi", "general sans", "switzer", "helvetica", "helvetica neue", "arial", "system-ui", "ui-sans-serif", "segoe ui", "sf pro", "-apple-system"],
+};
+const INDEX = new Map();
+for (const [genre, names] of Object.entries(LISTS)) for (const n of names) if (!INDEX.has(n)) INDEX.set(n, genre);
+
+const clean = (f) => String(f ?? "").split(",")[0].replace(/["']/g, "").trim().toLowerCase();
+
+// genre of one family name (the first of a font-family list), or "unknown".
+export function fontGenre(family) {
+  const f = clean(family);
+  if (!f) return "unknown";
+  if (INDEX.has(f)) return INDEX.get(f);
+  if (/\bmono|code\b/.test(f)) return "mono";
+  if (/\bslab\b/.test(f)) return "slab";
+  if (/script|hand|brush|marker/.test(f)) return "script";
+  if (/serif/.test(f) && !/sans/.test(f)) return "serif";
+  if (/display|poster|black|fatface|grotesque display/.test(f)) return "display";
+  if (/sans|grotesk|grotesque|gothic/.test(f)) return "sans";
+  return "unknown";
+}
+
+// The family's genre from a CSS font-family stack: the first known family wins, else the generic family.
+export function stackGenre(stack) {
+  const parts = String(stack ?? "").split(",").map((x) => x.replace(/["']/g, "").trim()).filter(Boolean);
+  for (const p of parts) {
+    const g = fontGenre(p);
+    if (g !== "unknown") return g;
+  }
+  const generic = parts.find((p) => /^(serif|sans-serif|monospace|cursive|fantasy)$/i.test(p));
+  return generic ? { serif: "serif", "sans-serif": "sans", monospace: "mono", cursive: "script", fantasy: "display" }[generic.toLowerCase()] : "unknown";
+}
+
+// For the in-page scripts: the lists as plain data (they can't import modules).
+export const FONT_GENRES = LISTS;

package/src/guard-agents.mjs

@@ -0,0 +1,213 @@
+// The guard for every agent that can hold its own stop: where each one keeps its hooks, what it sends the hook,
+// and how the hook says "not done yet". One guard (guard.mjs decide), one adapter per agent.
+//
+//   agent    file (project · global)                                 event       not done yet
+//   claude   .claude/settings.json · ~/.claude/settings.json          Stop        {"decision":"block","reason"}
+//   codex    .codex/hooks.json · ~/.codex/hooks.json                  Stop        {"decision":"block","reason"}
+//   cursor   .cursor/hooks.json · ~/.cursor/hooks.json                stop        {"followup_message"}
+//   gemini   .gemini/settings.json · ~/.gemini/settings.json          AfterAgent  {"decision":"deny","reason"}
+//   copilot  .github/hooks/palate-guard.json · ~/.copilot/hooks/…     Stop        {"decision":"block","reason"} (+ VS Code's hookSpecificOutput)
+//   git      .git/hooks/pre-commit (any agent, or a person)           commit      exit 1 with the report
+//
+// Copilot (CLI and VS Code) also reads the project's .claude/settings.json, so with the Claude hook in place it is
+// covered already and palate doesn't add a second one. Windsurf's after-response hook runs in the background and
+// Cline's task-complete hook can't continue a task, so neither can hold a stop: those agents get the guard through
+// palate's MCP instructions (palate_guard before saying done) and, if wanted, the git hook.
+// Each agent's own loop cap is set where it has one (Cursor loop_limit 3); palate's own cap (3 per session) holds
+// for all of them.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const AGENTS = ["claude", "codex", "cursor", "gemini", "copilot", "git"];
+export const NO_STOP_HOOK = { windsurf: "Windsurf's after-response hook runs in the background, so it can't hold a stop", cline: "Cline's task-complete hook can't send a task back" };
+
+const readJson = (f, d) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return d;
+  }
+};
+const home = (h) => h ?? os.homedir();
+
+// The command a hook runs: this checkout's bin when palate runs from its repo, else npx.
+export function hookCommand(agent = "claude") {
+  const bin = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "bin", "palate.mjs");
+  const dev = /[\\/]packages[\\/]palate[\\/]bin[\\/]palate\.mjs$/.test(bin) && fs.existsSync(bin);
+  const base = dev ? `node "${bin.replace(/\\/g, "/")}"` : "npx @palate/cli";
+  return `${base} guard --hook${agent === "claude" ? "" : ` --agent ${agent}`}`;
+}
+const ours = (cmd) => typeof cmd === "string" && /palate(\.mjs"?)?\s+guard\s+--hook/.test(cmd);
+
+// ---------- what each agent sends ----------
+// Normalised to { session_id, cwd, transcript_path, skip? }.
+export function parseInput(agent, raw = {}) {
+  switch (agent) {
+    case "cursor":
+      return {
+        session_id: raw.conversation_id ?? raw.session_id,
+        cwd: raw.workspace_roots?.[0] ?? raw.cwd,
+        transcript_path: raw.transcript_path ?? undefined,
+        // Only a finished turn is checked; an aborted or failed one is the person's to handle.
+        ...(raw.status && raw.status !== "completed" ? { skip: `turn ${raw.status}` } : {}),
+      };
+    case "copilot":
+      return { session_id: raw.session_id ?? raw.sessionId, cwd: raw.cwd, transcript_path: raw.transcript_path ?? raw.transcriptPath };
+    default:
+      return { session_id: raw.session_id, cwd: raw.cwd, transcript_path: raw.transcript_path ?? undefined };
+  }
+}
+
+// ---------- how each agent is told ----------
+// The stdout text for a decision ({ decision: "block"|"allow", reason?, message? }); "" when there's nothing to say.
+export function formatOutput(agent, d) {
+  const block = d.decision === "block";
+  switch (agent) {
+    case "cursor":
+      return JSON.stringify(block ? { followup_message: d.reason } : {});
+    case "gemini":
+      return block ? JSON.stringify({ decision: "deny", reason: d.reason }) : d.message ? JSON.stringify({ systemMessage: d.message }) : "";
+    case "copilot":
+      // The Copilot CLI reads decision/reason; VS Code's local harness reads hookSpecificOutput.
+      return block ? JSON.stringify({ decision: "block", reason: d.reason, hookSpecificOutput: { hookEventName: "Stop", decision: "block", reason: d.reason } }) : "";
+    case "codex":
+    case "claude":
+    default:
+      return block ? JSON.stringify({ decision: "block", reason: d.reason }) : d.message ? JSON.stringify({ systemMessage: d.message }) : "";
+  }
+}
+
+// ---------- install ----------
+const FILES = {
+  claude: (dir, g, h) => (g ? path.join(home(h), ".claude", "settings.json") : path.join(dir, ".claude", "settings.json")),
+  codex: (dir, g, h) => (g ? path.join(home(h), ".codex", "hooks.json") : path.join(dir, ".codex", "hooks.json")),
+  cursor: (dir, g, h) => (g ? path.join(home(h), ".cursor", "hooks.json") : path.join(dir, ".cursor", "hooks.json")),
+  gemini: (dir, g, h) => (g ? path.join(home(h), ".gemini", "settings.json") : path.join(dir, ".gemini", "settings.json")),
+  copilot: (dir, g, h) => (g ? path.join(home(h), ".copilot", "hooks", "palate-guard.json") : path.join(dir, ".github", "hooks", "palate-guard.json")),
+  git: (dir) => path.join(dir, ".git", "hooks", "pre-commit"),
+};
+
+// Claude-style nesting (event → groups → hooks), used by Claude Code, Codex and Gemini.
+function nested(settings, event, entry, remove) {
+  const hooks = settings.hooks ?? {};
+  const groups = (hooks[event] ?? []).map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !ours(h.command)) })).filter((g) => g.hooks.length);
+  if (!remove) groups.push({ hooks: [entry] });
+  const next = { ...settings, hooks: { ...hooks, [event]: groups } };
+  if (!groups.length) delete next.hooks[event];
+  if (!Object.keys(next.hooks).length) delete next.hooks;
+  return next;
+}
+
+const GIT_MARK = "# palate guard (palate guard --uninstall --agent git removes it)";
+
+function installOne(agent, dir, { global = false, home: h, remove = false } = {}) {
+  const file = FILES[agent](dir, global, h);
+  const cmd = hookCommand(agent);
+  if (agent === "git") {
+    if (global) return { agent, file, note: "The git hook is per project; run it without --global." };
+    if (!fs.existsSync(path.join(dir, ".git"))) return { agent, file, note: "Not a git repository here." };
+    const had = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const stripped = had.split(GIT_MARK)[0].trimEnd();
+    if (remove) {
+      if (stripped && stripped !== "#!/bin/sh") fs.writeFileSync(file, stripped + "\n");
+      else if (had.includes(GIT_MARK)) fs.rmSync(file);
+      return { agent, file, done: true };
+    }
+    const body = `${stripped || "#!/bin/sh"}\n${GIT_MARK}\n${cmd.replace(" --hook --agent git", " --commit")} || exit 1\n`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, body, { mode: 0o755 });
+    return { agent, file, done: true };
+  }
+  if (fs.existsSync(file) && fs.readFileSync(file, "utf8").trim() && readJson(file, null) === null) return { agent, file, note: `${file} isn't valid JSON, so palate left it alone.` };
+  const settings = readJson(file, {});
+  let next;
+  if (agent === "cursor") {
+    const stop = (settings.hooks?.stop ?? []).filter((h) => !ours(h.command));
+    if (!remove) stop.push({ command: cmd, timeout: 60, loop_limit: 3 });
+    next = { version: settings.version ?? 1, ...settings, hooks: { ...(settings.hooks ?? {}), stop } };
+    if (!stop.length) delete next.hooks.stop;
+  } else if (agent === "copilot") {
+    if (remove) {
+      fs.rmSync(file, { force: true });
+      return { agent, file, done: true };
+    }
+    if (!global && hasOurs("claude", dir)) return { agent, file, note: "Copilot reads this project's .claude/settings.json, where the guard already is." };
+    next = { version: 1, hooks: { Stop: [{ type: "command", command: cmd, bash: cmd, powershell: cmd, timeout: 60, timeoutSec: 60 }] } };
+  } else if (agent === "codex") {
+    // A layer uses one format: with [hooks] already in config.toml, hooks.json would draw a warning.
+    const toml = path.join(path.dirname(file), "config.toml");
+    if (!remove && fs.existsSync(toml) && /^\s*\[\[?hooks[.\]]/m.test(fs.readFileSync(toml, "utf8"))) return { agent, file, note: `${toml} already defines hooks; add palate there: [[hooks.Stop]] with [[hooks.Stop.hooks]] type = "command", command = '${cmd}', timeout = 60.` };
+    next = nested(settings, "Stop", { type: "command", command: cmd, timeout: 60 }, remove);
+  } else if (agent === "gemini") {
+    next = nested(settings, "AfterAgent", { type: "command", command: cmd, name: "palate-guard", description: "palate: UI work isn't done until palate has looked at it", timeout: 60_000 }, remove);
+  } else {
+    next = nested(settings, "Stop", { type: "command", command: cmd, timeout: 60 }, remove);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { agent, file, done: true };
+}
+
+function hasOurs(agent, dir, { global = false, home: h } = {}) {
+  const file = FILES[agent](dir, global, h);
+  if (!fs.existsSync(file)) return false;
+  if (agent === "git") return fs.readFileSync(file, "utf8").includes(GIT_MARK);
+  const s = readJson(file, {});
+  const all = JSON.stringify(s.hooks ?? {});
+  return ours(all) || /palate(\.mjs\\?"?)?\s+guard\s+--hook/.test(all);
+}
+
+// The agents this project (or machine) uses: their folder in the project, or in the home folder.
+export function detectAgents(dir, { home: h } = {}) {
+  const found = new Set(["claude"]);
+  const at = (p) => fs.existsSync(p);
+  if (at(path.join(dir, ".codex")) || at(path.join(home(h), ".codex"))) found.add("codex");
+  if (at(path.join(dir, ".cursor")) || at(path.join(home(h), ".cursor"))) found.add("cursor");
+  if (at(path.join(dir, ".gemini")) || at(path.join(home(h), ".gemini"))) found.add("gemini");
+  return [...found];
+}
+
+const AFTER = {
+  codex: "Codex runs a new project hook only after you trust it: open /hooks in Codex once (it also needs the project's .codex folder trusted).",
+  gemini: "Gemini CLI asks before it runs a new hook the first time.",
+  cursor: "Cursor picks it up on its next agent turn (Settings → Hooks shows it).",
+  copilot: "Copilot CLI and VS Code load .github/hooks on their next session.",
+  git: "A commit with open items stops with the report; git commit --no-verify skips it once.",
+};
+const LABEL = { claude: "Claude Code", codex: "Codex", cursor: "Cursor", gemini: "Gemini CLI", copilot: "GitHub Copilot", git: "git pre-commit" };
+
+// install / uninstall for a list of agents (or every one this project uses). Returns the lines to print.
+export function install(dir, { agents, global = false, home: h, remove = false } = {}) {
+  const asked = (agents?.length ? agents : remove ? AGENTS : detectAgents(dir, { home: h })).map((a) => String(a).toLowerCase().trim());
+  const lines = [];
+  for (const a of asked) {
+    if (NO_STOP_HOOK[a]) {
+      lines.push(`- ${a}: ${NO_STOP_HOOK[a]}. It still gets the guard through palate's MCP tools (palate_guard before saying done); add --agent git for a commit check.`);
+      continue;
+    }
+    if (!FILES[a]) {
+      lines.push(`- ${a}: not an agent palate knows (${AGENTS.join(", ")}).`);
+      continue;
+    }
+    if (remove && !hasOurs(a, dir, { global, home: h })) continue;
+    const r = installOne(a, dir, { global, home: h, remove });
+    if (r.note) lines.push(`- ${LABEL[a]}: ${r.note}`);
+    else lines.push(`- ${LABEL[a]}: ${remove ? "removed from" : "on, in"} ${r.file}${!remove && AFTER[a] ? `. ${AFTER[a]}` : ""}`);
+  }
+  if (remove) return lines.length ? [`palate guard is off for:`, ...lines].join("\n") : "palate guard wasn't on here.";
+  const head = `palate guard is on: when the agent stops, palate checks the UI it changed (looked at, copy, code tells, credits, gates) and sends it back with what is open, three rounds a session at most.${asked.includes("claude") && !asked.includes("copilot") ? " Copilot reads the Claude hook too." : ""}`;
+  return [head, ...lines, `Off: palate guard --uninstall${global ? " --global" : ""} (--agent to pick).`].join("\n");
+}
+
+// Where the guard is on for this project: [{ agent, file }].
+export function installedAgents(dir, { home: h } = {}) {
+  const out = [];
+  for (const a of AGENTS)
+    for (const g of a === "git" ? [false] : [false, true]) if (hasOurs(a, dir, { global: g, home: h })) out.push({ agent: a, file: FILES[a](dir, g, h) });
+  // Claude Code's local settings file counts too.
+  if (!out.some((o) => o.agent === "claude") && JSON.stringify(readJson(path.join(dir, ".claude", "settings.local.json"), {}).hooks ?? {}).match(/palate[^"]*guard\s+--hook/)) out.push({ agent: "claude", file: path.join(dir, ".claude", "settings.local.json") });
+  return out;
+}
+export const agentLabel = (a) => LABEL[a] ?? a;