@gemboss/website-ui 0.0.0-stage → 0.2.0

package/bin/lib/gap.mjs

@@ -0,0 +1,189 @@
+// `gemboss-website gap`: report something the kit is missing, as a GitHub issue in the kit's repo (gh), or as
+// kit-gaps/<slug>.md for the person to send when gh is not there.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { PKG, PKG_NAME, UsageError, installedKit, parseArgs, projectPackage, rel } from "./util.mjs";
+
+export const KINDS = ["token", "component", "section", "behavior", "doc", "other"];
+const TITLE_PREFIX = "[website-ui gap]";
+const LABELS = ["gap", "website-ui"];
+const MAX_LINES = 120, MAX_CHARS = 6000;
+
+export function slugify(title) {
+  const s = title.normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[đĐ]/g, "d").toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/, "");
+  return s || `gap-${Date.now()}`;
+}
+
+function trimCode(text) {
+  let lines = text.replace(/\s+$/, "").split("\n");
+  let note = "";
+  if (lines.length > MAX_LINES) { note = `(trimmed: first ${MAX_LINES} of ${lines.length} lines)`; lines = lines.slice(0, MAX_LINES); }
+  let out = lines.join("\n");
+  if (out.length > MAX_CHARS) { out = out.slice(0, MAX_CHARS); note = `(trimmed to ${MAX_CHARS} characters)`; }
+  return { code: out, note };
+}
+
+function reporter(cwd) {
+  try {
+    const r = spawnSync("git", ["config", "user.name"], { cwd, encoding: "utf8", timeout: 5000 });
+    const name = (r.stdout || "").trim();
+    if (r.status === 0 && name) return name;
+  } catch { /* no git */ }
+  return "(unknown: git config user.name is not set)";
+}
+
+/** The issue body, from answered fields. */
+export function buildBody(f) {
+  const fence = (lang, code) => {
+    const ticks = code.includes("```") ? "````" : "```";
+    return `${ticks}${lang}\n${code}\n${ticks}`;
+  };
+  const out = [
+    "## What is missing", "", f.need, "", `Kind: **${f.kind}**`, "",
+    "## Where it is needed", "", `- Site: ${f.site}`, `- Page: ${f.page}`, "",
+    "## Why existing kit parts do not cover it", "", f.why, "",
+    "## Current stopgap", "",
+  ];
+  if (f.stopgap) {
+    out.push(`\`${f.stopgap.path}\`${f.stopgap.note ? ` ${f.stopgap.note}` : ""}:`, "", fence(f.stopgap.lang, f.stopgap.code), "");
+  } else out.push("None yet.", "");
+  out.push("## Proposed shape (optional)", "", f.shape || "Not given.", "");
+  if (f.screenshot) {
+    out.push("## Screenshot", "", /^https?:\/\//i.test(f.screenshot)
+      ? `![screenshot](${f.screenshot})`
+      : `Local file \`${f.screenshot}\`: attach it to this issue by hand (drop it into a comment).`, "");
+  }
+  out.push("## Kit version", "", f.kitVersion, "", "## Reporter", "", `${f.reporter}, with \`npx gemboss-website gap\` (${PKG_NAME} CLI ${PKG.version})`, "");
+  return out.join("\n");
+}
+
+async function ask(fields, missing) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const q = {
+    title: ["Short title of what is missing (e.g. \"Tabs component\")", true],
+    kind: [`Kind (${KINDS.join("/")})`, true],
+    need: ["What is missing: what should the kit give you?", true],
+    why: ["Why existing kit parts (demo/, docs/components.md) do not cover it", false],
+    site: ["Site (domain or name)", false],
+    page: ["Page URL where it is needed", false],
+    shape: ["Proposed shape: class names, markup or behaviour (optional, Enter to skip)", false],
+    stopgap: ["Stopgap file, e.g. kit-gaps.css (optional, Enter to skip)", false],
+    screenshot: ["Screenshot path or URL (optional, Enter to skip)", false],
+  };
+  try {
+    for (const k of missing) {
+      const [prompt, required] = q[k];
+      let v = "";
+      do v = (await rl.question(`${prompt}: `)).trim(); while (required && !v);
+      if (v) fields[k] = v;
+    }
+  } finally { rl.close(); }
+}
+
+function ghCall(gh, args, cwd) {
+  try {
+    const r = spawnSync(gh, args, { cwd, encoding: "utf8", timeout: 60000 });
+    if (r.error) return { ok: false, missing: r.error.code === "ENOENT", err: String(r.error.message || r.error) };
+    return { ok: r.status === 0, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+  } catch (e) { return { ok: false, err: String(e.message || e) }; }
+}
+
+export async function cmdGap(argv) {
+  const opts = parseArgs(argv, {
+    title: "string", need: "string", page: "string", kind: "string", stopgap: "string", site: "string",
+    screenshot: "string", why: "string", shape: "string", "dry-run": "bool",
+  });
+  if (opts._.length) throw new UsageError(`gap takes options, not words (got "${opts._.join(" ")}"); try --title "${opts._.join(" ")}"`);
+  const cwd = process.cwd();
+  const f = { title: opts.title, need: opts.need, page: opts.page, kind: opts.kind, stopgap: opts.stopgap, site: opts.site, screenshot: opts.screenshot, why: opts.why, shape: opts.shape };
+  const order = ["title", "kind", "need", "why", "site", "page", "shape", "stopgap", "screenshot"];
+  const missing = order.filter((k) => !f[k]);
+  if (missing.length && process.stdin.isTTY && process.stdout.isTTY) await ask(f, missing);
+  const lacking = ["title", "need"].filter((k) => !f[k]);
+  if (lacking.length) throw new UsageError(`gap needs ${lacking.map((k) => "--" + k).join(" and ")} (no terminal to ask in). Example:\n  npx gemboss-website gap --title "Tabs component" --kind component --need "Tabs to switch between three code samples" --page https://example.com/docs --stopgap kit-gaps.css`);
+
+  f.title = f.title.replace(/^\s*\[website-ui gap\]\s*/i, "").trim();
+  f.kind = (f.kind || "other").toLowerCase().replace(/^behaviour$/, "behavior");
+  if (!KINDS.includes(f.kind)) throw new UsageError(`--kind must be one of ${KINDS.join(", ")} (got "${f.kind}")`);
+  const pj = projectPackage(cwd);
+  f.site = f.site || (pj && (pj.homepage || pj.name) ? `${pj.homepage || pj.name} (from package.json)` : `${basename(cwd)} (folder name)`);
+  f.page = f.page || "Not given.";
+  f.why = f.why || "Not given.";
+  if (f.stopgap) {
+    const p = resolve(cwd, f.stopgap);
+    if (!existsSync(p)) throw new UsageError(`--stopgap: no such file ${f.stopgap}`);
+    const { code, note } = trimCode(readFileSync(p, "utf8"));
+    f.stopgap = { path: rel(p, cwd), code, note, lang: (extname(p).slice(1) || "text").replace(/^htm$/, "html").replace(/^mjs$/, "js") };
+  }
+  const kit = installedKit(cwd);
+  f.kitVersion = kit ? `${PKG_NAME} ${kit.version}` : `${PKG_NAME} is not installed in this project (CLI ${PKG.version})`;
+  f.reporter = reporter(cwd);
+
+  const repo = (PKG.gemboss && PKG.gemboss.gapRepo) || "chriskoh26/gemboss-www";
+  const fullTitle = `${TITLE_PREFIX} ${f.title}`;
+  const body = buildBody(f);
+  const gh = process.env.GEMBOSS_WEBSITE_GH || "gh";
+
+  if (!opts["dry-run"]) {
+    const auth = ghCall(gh, ["auth", "status"], cwd);
+    if (auth.ok) {
+      const tmp = join(tmpdir(), `gemboss-gap-${process.pid}-${Date.now()}.md`);
+      writeFileSync(tmp, body);
+      try {
+        const base = ["issue", "create", "-R", repo, "--title", fullTitle, "--body-file", tmp];
+        let r = ghCall(gh, [...base.slice(0, 6), ...LABELS.flatMap((l) => ["--label", l]), ...base.slice(6)], cwd);
+        if (!r.ok) {
+          console.error(`gh could not file it with labels (${(r.err || "").split("\n")[0]}); trying once without labels.`);
+          r = ghCall(gh, base, cwd);
+        }
+        if (r.ok) {
+          const url = (r.out.match(/https?:\/\/\S+/g) || []).pop() || r.out;
+          const num = (/\/issues\/(\d+)/.exec(url) || [])[1];
+          console.log(`Gap reported: ${url}`);
+          if (num) {
+            console.log(`Name it above your stopgap so \`upgrade\` can tell you when the kit has it:`);
+            console.log(`  /* gap #${num}: ${f.title} */`);
+          }
+          if (f.screenshot && !/^https?:\/\//i.test(f.screenshot)) console.log(`Attach the screenshot by hand: open the issue and drop ${f.screenshot} into a comment.`);
+          console.log("Tell the person: the gap is reported to the kit team, the page uses a kitgap- stopgap until the kit ships it.");
+          return 0;
+        }
+        console.error(`gh issue create failed: ${(r.err || "").split("\n")[0]}. Writing the report to a file instead.`);
+      } finally { rmSync(tmp, { force: true }); }
+    } else {
+      console.error(auth.missing ? "gh (GitHub CLI) is not installed; writing the report to a file instead."
+        : "gh is not signed in (gh auth login); writing the report to a file instead.");
+    }
+  }
+
+  const dir = resolve(cwd, "kit-gaps");
+  mkdirSync(dir, { recursive: true });
+  const slug = slugify(f.title);
+  let file = join(dir, `${slug}.md`);
+  for (let k = 2; existsSync(file); k++) file = join(dir, `${slug}-${k}.md`);
+  const fileRel = rel(file, cwd);
+  const send = `gh issue create -R ${repo} --title ${JSON.stringify(fullTitle)} --label gap --label website-ui --body-file ${fileRel}`;
+  let url = `https://github.com/${repo}/issues/new?title=${encodeURIComponent(fullTitle)}&labels=${LABELS.join(",")}`;
+  if ((url + "&body=" + encodeURIComponent(body)).length < 6000) url += "&body=" + encodeURIComponent(body);
+  const header = [
+    `<!-- ${TITLE_PREFIX} ${f.title.replace(/--+>?/g, "-")}`,
+    "Not filed yet. Send it with:",
+    `  ${send}`,
+    `or open https://github.com/${repo}/issues/new, use the title above and paste this file. -->`,
+    "",
+  ].join("\n");
+  writeFileSync(file, header + body);
+  console.log(`${opts["dry-run"] ? "Dry run: nothing was sent." : "Not sent."} The report is in ${fileRel}`);
+  console.log("");
+  console.log("To send it, one of:");
+  console.log(`  1. ${send}`);
+  console.log(`  2. Open this link, check the text and press Submit:\n     ${url}`);
+  console.log(`  3. Give ${fileRel} to the kit team (repo ${repo}).`);
+  console.log("");
+  console.log("Tell the person a gap report is waiting to be sent, and which page uses the kitgap- stopgap.");
+  return 0;
+}

package/bin/lib/init.mjs

@@ -0,0 +1,99 @@
+// `gemboss-website init`: connect the kit's rules to the project's Claude Code (CLAUDE.md block + skill).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { PKG_DIR, PKG_NAME, UsageError, parseArgs, rel } from "./util.mjs";
+
+export const START = `<!-- ${PKG_NAME}:start -->`;
+export const END = `<!-- ${PKG_NAME}:end -->`;
+export const SKILL_MARKER = `<!-- managed by ${PKG_NAME} init -->`;
+export const SKILL_PATH = join(".claude", "skills", "gemboss-website-ui", "SKILL.md");
+
+const KIT = `node_modules/${PKG_NAME}`;
+
+/** The block between the markers (markers included), without line-ending decisions. */
+export function claudeBlock() {
+  return [
+    START,
+    `## Website UI kit: ${PKG_NAME}`,
+    "",
+    `This site's pages are built with the GemCommerce website kit \`${PKG_NAME}\`. Its rules win over habit and`,
+    "over generic design advice. Before you build or change any page, section, style or copy of this website:",
+    "",
+    `1. Read \`${KIT}/AGENTS.md\` completely, once per session.`,
+    `2. Start every new page from \`${KIT}/templates/page.html\` and compose it from \`${KIT}/templates/sections/\`.`,
+    `   Look in \`${KIT}/demo/index.html\` and \`${KIT}/docs/components.md\` before you write a new class.`,
+    "3. Use only the kit's tokens and scales. Never override a `.gw-*` class and never edit `node_modules`.",
+    "4. When the kit is missing something, follow the gap protocol (AGENTS.md section 9): a stopgap in",
+    "   `kit-gaps.css` with `kitgap-` classes, then `npx gemboss-website gap`, and tell the person you reported it.",
+    "5. Before you say a page is done, run `npx gemboss-website check`, fix every error, and look at the page at",
+    "   320px and 1366px.",
+    "6. To upgrade the kit, run `npx gemboss-website upgrade` first: what changed, which gaps the kit now covers",
+    "   (replace those stopgaps with the kit's classes) and the install command.",
+    "",
+    "The skill `gemboss-website-ui` (`.claude/skills/gemboss-website-ui/SKILL.md`) has the same procedure.",
+    "This block is written by `npx gemboss-website init`; edit outside the markers, not inside.",
+    END,
+  ].join("\n");
+}
+
+/**
+ * Put the block into `text`: replace what is between the markers, or append it. Returns { text, action } where
+ * action is "added" | "updated" | "unchanged". Throws when the markers are broken (never guesses).
+ */
+export function upsertBlock(text, block) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const b = block.split("\n").join(eol);
+  const starts = text.split(START).length - 1, ends = text.split(END).length - 1;
+  if (starts !== ends || starts > 1) {
+    throw new UsageError(`CLAUDE.md has ${starts} "${START}" and ${ends} "${END}" markers. Fix them by hand (one of each, start before end) and run init again; nothing was changed.`);
+  }
+  if (starts === 1) {
+    const s = text.indexOf(START), e = text.indexOf(END);
+    if (e < s) throw new UsageError(`CLAUDE.md: "${END}" comes before "${START}". Fix the markers by hand; nothing was changed.`);
+    const current = text.slice(s, e + END.length);
+    if (current === b) return { text, action: "unchanged" };
+    return { text: text.slice(0, s) + b + text.slice(e + END.length), action: "updated" };
+  }
+  if (!text.trim()) return { text: b + eol, action: "added" };
+  const sep = text.endsWith(eol + eol) ? "" : text.endsWith(eol) ? eol : eol + eol;
+  return { text: text + sep + b + eol, action: "added" };
+}
+
+export function cmdInit(argv) {
+  const opts = parseArgs(argv, { force: "bool" });
+  if (opts._.length) throw new UsageError(`init takes no arguments (got ${opts._.join(" ")}); run it in the project's root folder`);
+  const cwd = process.cwd();
+  const done = [];
+
+  const claudePath = resolve(cwd, "CLAUDE.md");
+  const had = existsSync(claudePath);
+  const before = had ? readFileSync(claudePath, "utf8") : "";
+  const { text, action } = upsertBlock(before, claudeBlock());
+  if (action !== "unchanged") writeFileSync(claudePath, text);
+  done.push([rel(claudePath), !had ? "created, kit block added" : action === "added" ? "kit block added at the end" : action === "updated" ? "kit block updated (text outside the markers untouched)" : "kit block already up to date"]);
+
+  const skillSrc = readFileSync(join(PKG_DIR, "skill", "SKILL.md"), "utf8");
+  const skillPath = resolve(cwd, SKILL_PATH);
+  if (!existsSync(skillPath)) {
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, skillSrc);
+    done.push([rel(skillPath), "created"]);
+  } else {
+    const cur = readFileSync(skillPath, "utf8");
+    if (cur === skillSrc) done.push([rel(skillPath), "already up to date"]);
+    else if (cur.includes(SKILL_MARKER) || opts.force) {
+      writeFileSync(skillPath, skillSrc);
+      done.push([rel(skillPath), cur.includes(SKILL_MARKER) ? "updated" : "overwritten (--force)"]);
+    } else {
+      done.push([rel(skillPath), "left alone: it was not written by init (no marker line). --force replaces it"]);
+    }
+  }
+
+  const w = Math.max(...done.map(([p]) => p.length));
+  console.log(`gemboss-website init (${PKG_NAME})`);
+  for (const [p, what] of done) console.log(`  ${p.padEnd(w)}  ${what}`);
+  console.log("");
+  console.log(`Claude Code now reads ${KIT}/AGENTS.md before website work in this project.`);
+  console.log("Next: start a page from the kit's templates/page.html, then run: npx gemboss-website check");
+  return 0;
+}

package/bin/lib/upgrade.mjs

@@ -0,0 +1,155 @@
+// `gemboss-website upgrade`: what changed since the installed kit, which reported gaps the kit now covers, which of
+// the project's stopgaps that frees, and the install command.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { PKG, PKG_DIR, PKG_NAME, UsageError, c, installedKit, isSemver, parseArgs, projectPackage, rel, semverCompare, walkFiles } from "./util.mjs";
+
+/** Changelog sections: [{ version, heading, lines }] in file order. "Unreleased" and other headings are skipped. */
+export function parseChangelog(text) {
+  const out = [];
+  let cur = null;
+  for (const line of text.split(/\r?\n/)) {
+    const h = /^##\s+\[?v?(\d+\.\d+\.\d+(?:-[\w.-]+)?)\]?/.exec(line);
+    if (h) { cur = { version: h[1], heading: line.replace(/^##\s+/, ""), lines: [] }; out.push(cur); continue; }
+    if (/^##\s/.test(line)) { cur = null; continue; }
+    if (cur) cur.lines.push(line);
+  }
+  for (const s of out) {
+    while (s.lines.length && !s.lines[s.lines.length - 1].trim()) s.lines.pop();
+    while (s.lines.length && !s.lines[0].trim()) s.lines.shift();
+  }
+  return out;
+}
+
+/** Gap numbers in a line: "Closes gap #12", "gap #12 and #14", "gaps #3, #4". */
+export function gapNumbers(line) {
+  const nums = [];
+  for (const m of line.matchAll(/\bgaps?\s*((?:#\d+(?:\s*(?:,|and|&)\s*)?)+)/gi)) {
+    for (const k of m[1].matchAll(/#(\d+)/g)) nums.push(Number(k[1]));
+  }
+  return nums;
+}
+
+/** Lines in the project that name a gap number, with the kitgap- classes near them. */
+function stopgapMentions(cwd) {
+  const files = walkFiles([cwd], /\.(?:css|html?|m?js|ts|jsx|tsx|vue|svelte|astro|scss)$/i);
+  const hits = [];
+  const stopgaps = new Map();
+  for (const f of files) {
+    let text;
+    try { text = readFileSync(f, "utf8"); } catch { continue; }
+    if (!/kitgap-|gap\s*#\d/i.test(text)) continue;
+    const lines = text.split("\n");
+    lines.forEach((l, i) => {
+      for (const m of l.matchAll(/\.?(kitgap-[\w-]+)/g)) {
+        const k = m[1].replace(/(__|--).*$/, "");
+        if (!stopgaps.has(k)) stopgaps.set(k, `${rel(f, cwd)}:${i + 1}`);
+      }
+      const nums = gapNumbers(l);
+      if (!nums.length) return;
+      // The stopgap a mention names: kitgap- classes from that line down to a blank line, the next comment or the
+      // next gap number.
+      const near = new Set();
+      for (let j = i; j < Math.min(lines.length, i + 40); j++) {
+        const nl = lines[j];
+        if (j > i && (!nl.trim() || /\/\*|<!--|^\s*\/\/|gap\s*#\d/i.test(nl))) break;
+        for (const m of nl.matchAll(/(kitgap-[\w-]+)/g)) near.add(m[1].replace(/(__|--).*$/, ""));
+      }
+      hits.push({ file: rel(f, cwd), line: i + 1, nums, text: l.trim().slice(0, 120), classes: [...near] });
+    });
+  }
+  return { hits, stopgaps };
+}
+
+function latestFromNpm() {
+  if (process.env.GEMBOSS_WEBSITE_LATEST) {
+    const v = process.env.GEMBOSS_WEBSITE_LATEST.trim();
+    return isSemver(v) ? { version: v } : { error: `GEMBOSS_WEBSITE_LATEST=${v}` };
+  }
+  if (process.env.GEMBOSS_WEBSITE_OFFLINE) return { error: "offline (GEMBOSS_WEBSITE_OFFLINE is set)" };
+  try {
+    const r = spawnSync("npm", ["view", PKG_NAME, "version"], { encoding: "utf8", timeout: 10000, shell: process.platform === "win32" });
+    if (r.error) return { error: r.error.code === "ETIMEDOUT" ? "npm did not answer within 10s" : String(r.error.message || r.error) };
+    const v = (r.stdout || "").trim().split(/\s+/).pop();
+    if (r.status !== 0 || !isSemver(v)) return { error: ((r.stderr || "").trim().split("\n")[0]) || `npm exited ${r.status}` };
+    return { version: v };
+  } catch (e) { return { error: String(e.message || e) }; }
+}
+
+function installCommand(cwd, version, dev) {
+  const spec = `${PKG_NAME}@${version}`;
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return `pnpm add ${dev ? "-D " : ""}${spec}`;
+  if (existsSync(join(cwd, "yarn.lock"))) return `yarn add ${dev ? "-D " : ""}${spec}`;
+  if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) return `bun add ${dev ? "-d " : ""}${spec}`;
+  return `npm install ${dev ? "-D " : ""}${spec}`;
+}
+
+export function cmdUpgrade(argv) {
+  const opts = parseArgs(argv, {});
+  if (opts._.length) throw new UsageError("upgrade takes no arguments");
+  const cwd = process.cwd();
+  const kit = installedKit(cwd);
+  const installed = kit ? kit.version : null;
+  const latest = latestFromNpm();
+  const changelogPath = process.env.GEMBOSS_WEBSITE_CHANGELOG ? resolve(process.env.GEMBOSS_WEBSITE_CHANGELOG) : join(PKG_DIR, "CHANGELOG.md");
+  const sections = existsSync(changelogPath) ? parseChangelog(readFileSync(changelogPath, "utf8")) : [];
+  const newestKnown = sections.reduce((v, s) => (!v || semverCompare(s.version, v) > 0 ? s.version : v), null);
+
+  const out = [c.bold("gemboss-website upgrade")];
+  out.push(`  installed: ${installed ? `${PKG_NAME} ${installed}` : `none (no node_modules/${PKG_NAME} from ${rel(cwd) || "."})`}`);
+  out.push(`  latest:    ${latest.version ? `${latest.version} (npm)` : `unknown: ${latest.error}. Using the changelog that ships with this CLI (${PKG.version}).`}`);
+
+  const from = installed || "0.0.0";
+  const newer = sections.filter((s) => semverCompare(s.version, from) > 0 && (!latest.version || semverCompare(s.version, latest.version) <= 0));
+  const closed = new Map();
+  if (installed && latest.version && semverCompare(installed, latest.version) >= 0) {
+    out.push("", c.green(`Up to date: ${installed} is the latest version.`));
+  } else if (!newer.length) {
+    out.push("", "No changelog entries newer than the installed version here.");
+  } else {
+    out.push("", `Changes since ${installed || "the start"} (${changelogPath === join(PKG_DIR, "CHANGELOG.md") ? `${PKG_NAME} CHANGELOG.md` : rel(changelogPath)}):`);
+    for (const s of newer) {
+      out.push("", c.bold(`## ${s.heading}`));
+      for (const l of s.lines) {
+        const nums = gapNumbers(l);
+        nums.forEach((n) => closed.set(n, { version: s.version, line: l.trim() }));
+        out.push(nums.length ? `${c.yellow(">> " + l)}` : `   ${l}`);
+      }
+    }
+  }
+
+  if (latest.version && (!newestKnown || semverCompare(latest.version, newestKnown) > 0) && !(installed && semverCompare(installed, latest.version) >= 0)) {
+    out.push("", `This CLI's changelog stops at ${newestKnown || "nothing"}. For everything up to ${latest.version}, run the latest CLI:`,
+      `  npx -y ${PKG_NAME}@${latest.version} upgrade`);
+  }
+
+  const { hits, stopgaps } = stopgapMentions(cwd);
+  if (closed.size) {
+    out.push("", c.bold(`Gaps the kit now covers: ${[...closed.keys()].map((n) => "#" + n).join(", ")}`));
+    for (const [n, info] of closed) out.push(`  #${n} in ${info.version}: ${info.line.replace(/^[-*]\s*/, "")}`);
+    const mine = hits.filter((h) => h.nums.some((n) => closed.has(n)));
+    if (mine.length) {
+      out.push("", "Stopgaps in this project for those gaps: after upgrading, use the kit's class and delete the kitgap- code.");
+      for (const h of mine) out.push(`  ${h.file}:${h.line}  ${h.text}${h.classes.length ? `  -> ${h.classes.map((k) => "." + k).join(", ")}` : ""}`);
+    } else out.push("  No stopgap in this project names those gap numbers.");
+  }
+  const named = new Set(hits.flatMap((h) => h.classes));
+  const unnamed = [...stopgaps].filter(([k]) => !named.has(k));
+  if (unnamed.length) {
+    out.push("", "Stopgaps without a gap number nearby (check by name whether the new kit has them):");
+    for (const [k, at] of unnamed) out.push(`  .${k}  ${at}`);
+  }
+  const reports = existsSync(join(cwd, "kit-gaps")) ? readdirSync(join(cwd, "kit-gaps")).filter((n) => n.endsWith(".md")) : [];
+  if (reports.length) out.push("", `Gap reports not sent yet (kit-gaps/): ${reports.join(", ")}. Send them: see the comment at the top of each.`);
+
+  const pj = projectPackage(cwd) || {};
+  const dev = !!(pj.devDependencies && pj.devDependencies[PKG_NAME]) && !(pj.dependencies && pj.dependencies[PKG_NAME]);
+  if (!(installed && latest.version && semverCompare(installed, latest.version) >= 0)) {
+    out.push("", c.bold("Upgrade:"), `  ${installCommand(cwd, latest.version || "latest", dev)}`,
+      "  npx gemboss-website init     # refresh the CLAUDE.md block and the skill",
+      "  npx gemboss-website check    # then look at the pages at 320px and 1366px");
+  }
+  console.log(out.join("\n"));
+  return 0;
+}

package/bin/lib/util.mjs

@@ -0,0 +1,147 @@
+// Shared helpers for the gemboss-website CLI. Node >= 18, no dependencies.
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The kit package this CLI belongs to (…/@gemboss/website-ui). */
+export const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const PKG = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
+export const PKG_NAME = PKG.name;
+export const SYSTEM = JSON.parse(readFileSync(join(PKG_DIR, "system.json"), "utf8"));
+
+export class UsageError extends Error {}
+
+/**
+ * Parse argv for one command. `spec` maps flag name -> "bool" | "string" | "list".
+ * Accepts --flag value, --flag=value and positionals; unknown flags are a usage error.
+ */
+export function parseArgs(argv, spec) {
+  const out = { _: [] };
+  for (const [k, t] of Object.entries(spec)) out[k] = t === "bool" ? false : t === "list" ? [] : undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") { out._.push(...argv.slice(i + 1)); break; }
+    if (!a.startsWith("--")) { out._.push(a); continue; }
+    const eq = a.indexOf("=");
+    const name = a.slice(2, eq === -1 ? undefined : eq);
+    const type = spec[name];
+    if (!type) throw new UsageError(`unknown option --${name}`);
+    if (type === "bool") {
+      if (eq !== -1) throw new UsageError(`--${name} takes no value`);
+      out[name] = true;
+      continue;
+    }
+    let val = eq === -1 ? argv[++i] : a.slice(eq + 1);
+    if (val === undefined || (eq === -1 && val.startsWith("--"))) throw new UsageError(`--${name} needs a value`);
+    if (type === "list") out[name].push(val); else out[name] = val;
+  }
+  return out;
+}
+
+/** Forward-slash path of `p` relative to `from` (or `p` itself when outside). */
+export function rel(p, from = process.cwd()) {
+  const r = relative(from, p);
+  return (r && !r.startsWith("..") ? r : p).split(sep).join("/");
+}
+
+/** True when `p` is inside the kit package itself (the kit's own css, templates, demo…). */
+export function isKitPath(p) {
+  let real;
+  try { real = realpathSync(p); } catch { real = resolve(p); }
+  let kit;
+  try { kit = realpathSync(PKG_DIR); } catch { kit = PKG_DIR; }
+  return real === kit || real.startsWith(kit + sep);
+}
+
+/**
+ * The @gemboss/website-ui installed in the project at `cwd`: walks up looking for
+ * node_modules/@gemboss/website-ui/package.json the way Node resolves packages.
+ */
+export function installedKit(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (;;) {
+    const pj = join(dir, "node_modules", ...PKG_NAME.split("/"), "package.json");
+    if (existsSync(pj)) {
+      try { return { version: JSON.parse(readFileSync(pj, "utf8")).version, dir: dirname(pj) }; } catch { /* broken */ }
+    }
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/** The project's package.json (in cwd), or null. */
+export function projectPackage(cwd = process.cwd()) {
+  try { return JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")); } catch { return null; }
+}
+
+/** Compare two semver strings (x.y.z with optional -pre). */
+export function semverCompare(a, b) {
+  const pa = parseSemver(a), pb = parseSemver(b);
+  for (let i = 0; i < 3; i++) if (pa.n[i] !== pb.n[i]) return pa.n[i] < pb.n[i] ? -1 : 1;
+  if (pa.pre === pb.pre) return 0;
+  if (!pa.pre) return 1;
+  if (!pb.pre) return -1;
+  return pa.pre < pb.pre ? -1 : 1;
+}
+function parseSemver(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([\w.-]+))?/.exec(String(v || "").trim());
+  return m ? { n: [+m[1], +m[2], +m[3]], pre: m[4] || "" } : { n: [0, 0, 0], pre: "" };
+}
+export const isSemver = (v) => /^v?\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(String(v || "").trim());
+
+/** Directory names never descended into while walking a project. */
+export const SKIP_DIRS = new Set(["node_modules", "dist", "build", "out", "coverage"]);
+
+/**
+ * Every file under `paths` whose name matches `re`, skipping SKIP_DIRS, dot-directories and the
+ * kit's own files. A path given explicitly is walked even when its own name is in SKIP_DIRS.
+ */
+export function walkFiles(paths, re, { ignore = [], includeKit = false } = {}) {
+  const ign = ignore.map((p) => resolve(p));
+  const ignored = (p) => ign.some((g) => p === g || p.startsWith(g + sep));
+  const out = [];
+  const seen = new Set();
+  const visit = (p, top) => {
+    if (ignored(p) || seen.has(p)) return;
+    seen.add(p);
+    if (!includeKit && isKitPath(p)) return;
+    let entries;
+    try { entries = readdirSync(p, { withFileTypes: true }); } catch {
+      if (re.test(p)) out.push(p);
+      return;
+    }
+    if (!top) {
+      const name = p.split(sep).pop();
+      if (SKIP_DIRS.has(name) || name.startsWith(".")) return;
+    }
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(p, e.name);
+      if (e.isDirectory()) visit(full, false);
+      else if (e.isFile() && re.test(e.name) && !ignored(full) && (includeKit || !isKitPath(full))) out.push(full);
+    }
+  };
+  for (const p of paths) visit(resolve(p), true);
+  return out;
+}
+
+/** Offsets of line starts, for offset -> line lookups. */
+export function lineIndex(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) starts.push(i + 1);
+  return (offset) => {
+    let lo = 0, hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid] <= offset) lo = mid; else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+}
+
+/** Replace every character except newlines with a space, so offsets and lines stay put. */
+export const blank = (s) => s.replace(/[^\n]/g, " ");
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+export const c = { bold: paint(1), dim: paint(2), red: paint(31), yellow: paint(33), green: paint(32), cyan: paint(36) };