@golden-frijoles/kit 0.15.0 → 0.17.0

package/dist/doc-format.mjs

@@ -110,8 +110,57 @@ export function siblingDocs(readmeRelPath) {
 
 // ── Individual checkers — each returns a list of { rule, detail } offenses for one file's content ──
 
+// An HTML comment that never closes hides EVERYTHING after it when the doc renders — the whole epic README, its
+// architecture lock included (think-skills and sketch-specs both shipped one, 2026-09-30, from an edit anchored on a
+// heading the old template's comment named). Code is skipped first: a `<!-- jev:` inside backticks or a fence is an
+// example, not a comment, and several sprint docs quote one.
+// A code span opens with a run of backticks and closes with the same run (``<!-- x`` included).
+const CODE_SPAN = /(`+)[\s\S]*?\1/g;
+
+// A later `-->` closes an open comment wherever it appears (a mermaid `A --> B` included) — that is what CommonMark
+// renders, so the rule agrees with the page; the text in between is still hidden, and only reading it shows that.
+export function unclosedComments(content) {
+  const lines = content.split('\n');
+  let fence = null;
+  let open = null; // the line an unclosed <!-- started on, while we are inside one
+  for (let i = 0; i < lines.length; i++) {
+    // The whole run of marks: a ```` fence is closed only by ```` or longer, never by the ``` it quotes.
+    const fenceMark = lines[i].match(/^ {0,3}(`{3,}|~{3,})/);
+    if (open === null && fenceMark) {
+      const mark = fenceMark[1];
+      if (fence === null) fence = mark;
+      else if (mark[0] === fence[0] && mark.length >= fence.length) fence = null;
+      continue;
+    }
+    if (fence !== null) continue;
+    let rest = open === null ? lines[i].replace(CODE_SPAN, '') : lines[i];
+    for (;;) {
+      if (open === null) {
+        const at = rest.indexOf('<!--');
+        if (at === -1) break;
+        open = i;
+        rest = rest.slice(at + 4);
+      } else {
+        const at = rest.indexOf('-->');
+        if (at === -1) break;
+        open = null;
+        rest = rest.slice(at + 3).replace(CODE_SPAN, '');
+      }
+    }
+  }
+  return open === null
+    ? []
+    : [
+        {
+          rule: 'unclosed-html-comment',
+          detail: `line ${open + 1} opens <!-- and nothing closes it — everything after it is hidden when the doc renders`,
+        },
+      ];
+}
+
 export function checkEpicReadme(content, { slug, exists = existsRelative } = {}) {
   const offenses = [];
+  offenses.push(...unclosedComments(content));
   // Many epics predate the seeds/ convention and genuinely have no seed file to link — that's an
   // accepted state (Sprint 2 sweep decision), not drift. Only require a **Scope seed:** field when a
   // real seed file exists for this epic's slug; a seed that exists but isn't linked IS still flagged.
@@ -230,6 +279,7 @@ export function bodyStartIndex(lines) {
 
 export function checkSprintDoc(content) {
   const offenses = [];
+  offenses.push(...unclosedComments(content));
   const all = content.split('\n');
   const statusLine = all
     .slice(bodyStartIndex(all))
@@ -331,6 +381,7 @@ export const RETRO_SECTION_STEMS = [
 // same date — that is fixing drift, not relaxing the check.
 export function checkRetrospective(content) {
   const offenses = [];
+  offenses.push(...unclosedComments(content));
   const closedLine = content.split('\n').find((l) => /closed/i.test(l) && l.trim() !== '');
   if (!closedLine) {
     offenses.push({ rule: 'retro-closed-missing', detail: 'no "Closed" date line found near the top' });

package/dist/lib/surface.mjs

@@ -0,0 +1,303 @@
+// surface.mjs — the `surface` block: one screen state written as an ordered list of blocks (sketch-specs D8–D10).
+//
+//   ```surface
+//   state: ship-features
+//   route: /app/flags/[projectSlug]
+//   - head "Features" action "+ New feature"
+//   - summary count 4
+//   - list columns "feature | state in production | type & risk | on / off"
+//   ```
+//
+// One description serves three readers: the product owner (sketch-render.mjs draws it grey), the review (it is text
+// in a seed) and a project's state contract (a project maps the generic kinds onto its own and compares the built
+// page). So the grammar records only what survives a change of data: the kind of each block in order, the words
+// that matter, and three facts — a primary action's words, a count, a list's column words. Never a value, a row
+// count or a pixel.
+//
+// A line grammar rather than YAML because the kit has zero dependencies and no YAML parser; a hand-rolled YAML
+// subset would accept things YAML readers reject and the other way round. Zero deps; no side effects at import.
+
+/**
+ * The generic vocabulary: twelve kinds, each with the facts it may carry (D10).
+ *
+ * A fact on a kind that cannot carry it is an error, not ignored: a `count` on an `answer` means the author
+ * believes something is counted, and a sketch that silently drops it approves a picture of a different screen.
+ */
+export const SURFACE_KINDS = Object.freeze({
+  head: ['action'],
+  answer: [],
+  summary: ['count'],
+  tiles: ['count'],
+  toolbar: [],
+  list: ['columns'],
+  empty: [],
+  card: [],
+  steps: ['count'],
+  field: [],
+  tabs: [],
+  note: [],
+});
+
+export const SURFACE_FACTS = Object.freeze(['action', 'count', 'columns']);
+
+const KIND_NAMES = Object.keys(SURFACE_KINDS);
+
+// OWN properties only. `kind in SURFACE_KINDS` also answers true for `toString`, `constructor` and `__proto__`, which
+// then parsed as kinds and crashed the renderer with a raw TypeError instead of a line-numbered error (#210 review).
+const isKind = (name) => Object.hasOwn(SURFACE_KINDS, name);
+const STATE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const HEADER = /^([A-Za-z][\w-]*):\s*(.*)$/;
+
+/** A parse error that knows where it happened. `message` is `<file>:<line>: <reason>`, ready to print. */
+export class SurfaceError extends Error {
+  constructor(file, line, reason) {
+    super(`${file}:${line}: ${reason}`);
+    this.name = 'SurfaceError';
+    this.file = file;
+    this.line = line;
+    this.reason = reason;
+  }
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    let diagonal = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const above = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diagonal = above;
+    }
+  }
+  return row[b.length];
+}
+
+function unknownKind(kind) {
+  const [nearest] = KIND_NAMES.map((name) => [name, distance(kind, name)]).sort((x, y) => x[1] - y[1]);
+  const hint = nearest[1] <= 2 ? ` — did you mean \`${nearest[0]}\`?` : '';
+  return `unknown kind \`${kind}\`${hint} Known kinds: ${KIND_NAMES.join(', ')}.`;
+}
+
+/**
+ * Split the rest of a block line into quoted strings and bare words.
+ * Throws a plain string (the reason) so the caller attaches the line number once.
+ */
+function tokenize(text) {
+  const tokens = [];
+  let i = 0;
+  while (i < text.length) {
+    if (/\s/.test(text[i])) {
+      i += 1;
+      continue;
+    }
+    if (text[i] === '"') {
+      let value = '';
+      i += 1;
+      for (;;) {
+        if (i >= text.length) throw 'unterminated string — a quoted string closes on the same line';
+        const char = text[i];
+        if (char === '\\') {
+          const next = text[i + 1];
+          if (next !== '"' && next !== '\\')
+            throw `unknown escape \`\\${next ?? ''}\` — only \\" and \\\\ are escapes`;
+          value += next;
+          i += 2;
+        } else if (char === '"') {
+          i += 1;
+          break;
+        } else {
+          value += char;
+          i += 1;
+        }
+      }
+      tokens.push({ quoted: true, value });
+      continue;
+    }
+    let word = '';
+    while (i < text.length && !/\s/.test(text[i])) {
+      if (text[i] === '"') throw `a quote inside \`${word}"\` — put a space before a quoted string`;
+      word += text[i];
+      i += 1;
+    }
+    tokens.push({ quoted: false, value: word });
+  }
+  return tokens;
+}
+
+/** Parse one block line (`<kind> ["words"] [fact value]…`, without its leading `- `). */
+function parseBlockLine(rest) {
+  // The shape the seed template shipped before this grammar existed (`- heading: "Orders"`). Named, because the
+  // generic "unknown kind `heading:`" would send the author looking for a kind rather than at the format.
+  if (/^[a-z][\w-]*:(\s|$)/.test(rest)) {
+    throw (
+      '`- <kind>: "…"` is the old list shape — write `- <kind> "words"` (for example `- head "Orders"`); ' +
+      'see groom/references/intent-and-visuals.md'
+    );
+  }
+  const tokens = tokenize(rest);
+  const first = tokens.shift();
+  if (first === undefined || first.quoted) throw 'a block line starts with its kind: `- <kind> …`';
+  const kind = first.value;
+  if (!isKind(kind)) throw unknownKind(kind);
+
+  const block = { kind, words: null };
+  if (tokens[0]?.quoted) block.words = tokens.shift().value;
+
+  while (tokens.length > 0) {
+    const name = tokens.shift();
+    if (name.quoted)
+      throw 'a second quoted string — a block has one words string; facts are `name value` pairs';
+    if (name.value === 'when:' || name.value === 'when') {
+      throw 'a surface is ONE state, so a block has no `when:` — write that state as its own surface block';
+    }
+    if (!SURFACE_FACTS.includes(name.value)) {
+      throw `unknown fact \`${name.value}\` — the facts are ${SURFACE_FACTS.join(', ')}`;
+    }
+    if (!SURFACE_KINDS[kind].includes(name.value)) {
+      const carries = SURFACE_KINDS[kind];
+      throw (
+        `\`${kind}\` carries no \`${name.value}\`` +
+        (carries.length > 0 ? ` (it carries: ${carries.join(', ')})` : ' (it carries no facts)')
+      );
+    }
+    if (Object.hasOwn(block, name.value)) throw `\`${name.value}\` given twice`;
+    const value = tokens.shift();
+    if (value === undefined) throw `\`${name.value}\` needs a value`;
+    if (name.value === 'count') {
+      // No leading zeros and no number past exact integers: `1e23` would be compared with a count read off a page.
+      if (value.quoted || !/^(0|[1-9]\d*)$/.test(value.value) || !Number.isSafeInteger(Number(value.value))) {
+        throw `\`count\` is a whole number, got \`${value.value}\``;
+      }
+      block.count = Number(value.value);
+    } else {
+      if (!value.quoted) throw `\`${name.value}\` takes a quoted string, got \`${value.value}\``;
+      if (name.value === 'action') block.action = value.value;
+      // A trailing bar is an unlabelled column — how a list's actions column reads today — so it is kept as "".
+      else block.columns = value.value.split('|').map((column) => column.trim());
+    }
+  }
+  return block;
+}
+
+/**
+ * Parse one bare surface block — the whole of a `.surface` file, or the body of a fence.
+ *
+ * @param {string} text the block's lines
+ * @param {string} file the name errors carry
+ * @param {number} firstLine the FILE line number of the text's first line, so an error inside a fenced block in a
+ *   long seed points at the seed's line rather than the block's
+ * @returns {{ state: string, route: string, line: number, blocks: Array<{ kind: string, words: string|null,
+ *   line: number, action?: string, count?: number, columns?: string[] }> }}
+ */
+export function parseSurface(text, file = '<surface>', firstLine = 1) {
+  const surface = { state: null, route: null, line: firstLine, blocks: [] };
+  const lines = text.split(/\r?\n/);
+  lines.forEach((raw, index) => {
+    const line = firstLine + index;
+    const content = raw.trim();
+    if (content === '' || content.startsWith('#')) return;
+    try {
+      if (content.startsWith('- ') || content === '-') {
+        surface.blocks.push({ ...parseBlockLine(content.slice(1).trim()), line });
+        return;
+      }
+      const header = HEADER.exec(content);
+      if (header === null)
+        throw `expected \`state:\`, \`route:\` or a block line \`- <kind> …\`, got \`${content}\``;
+      const [, key, value = ''] = header;
+      if (key === 'blocks') {
+        throw 'no `blocks:` list — each block is its own line, `- <kind> "words"`, straight after `state:` and `route:`';
+      }
+      if (key === 'when')
+        throw 'a surface is ONE state, so it has no `when:` — write each state as its own block';
+      if (key !== 'state' && key !== 'route')
+        throw `unknown header \`${key}:\` — a surface has \`state:\` and \`route:\``;
+      if (surface.blocks.length > 0) throw `\`${key}:\` comes before the first block line`;
+      if (surface[key] !== null) throw `\`${key}:\` given twice`;
+      const trimmed = value.trim();
+      if (key === 'state' && !STATE_ID.test(trimmed)) {
+        throw `state id \`${trimmed}\` must be lower-case words joined by hyphens (e.g. \`ship-features-empty\`)`;
+      }
+      if (key === 'route' && !trimmed.startsWith('/')) throw `route \`${trimmed}\` must start with /`;
+      surface[key] = trimmed;
+    } catch (reason) {
+      if (typeof reason !== 'string') throw reason;
+      throw new SurfaceError(file, line, reason);
+    }
+  });
+  if (surface.state === null)
+    throw new SurfaceError(file, firstLine, 'no `state:` line — every surface names its state id');
+  if (surface.route === null)
+    throw new SurfaceError(file, firstLine, 'no `route:` line — every surface names its route');
+  if (surface.blocks.length === 0) {
+    throw new SurfaceError(file, firstLine, 'no blocks — a surface lists at least one `- <kind> …` line');
+  }
+  return surface;
+}
+
+// CommonMark fences: up to three spaces of indent (four is an indented code block), three or more backticks or
+// tildes. EVERY fence is tracked, not only `surface` ones, because a seed shows examples inside a longer fence
+// (```` … ````) and a `surface` fence inside one is text, not a block.
+const FENCE = /^( {0,3})(`{3,}|~{3,})(.*)$/;
+
+/** Every fenced `surface` block in a markdown file, in order. */
+export function parseSurfaces(markdown, file = '<markdown>') {
+  const lines = markdown.split(/\r?\n/);
+  const surfaces = [];
+  let open = null;
+  lines.forEach((raw, index) => {
+    const fence = FENCE.exec(raw);
+    if (open === null) {
+      if (fence === null) return;
+      const [, , marks, info] = fence;
+      // A backtick fence's info string may not contain a backtick (CommonMark), so ```x``` is inline code.
+      if (marks[0] === '`' && info.includes('`')) return;
+      open = {
+        char: marks[0],
+        length: marks.length,
+        surface: info.trim() === 'surface',
+        line: index + 1,
+        body: [],
+      };
+      return;
+    }
+    const closes =
+      fence !== null && fence[2][0] === open.char && fence[2].length >= open.length && fence[3].trim() === '';
+    if (!closes) {
+      open.body.push(raw);
+      return;
+    }
+    if (open.surface) surfaces.push(parseSurface(open.body.join('\n'), file, open.line + 1));
+    open = null;
+  });
+  if (open?.surface) {
+    throw new SurfaceError(file, open.line, 'this `surface` fence is never closed');
+  }
+  return surfaces;
+}
+
+/**
+ * Check a project's `surface.map.json` (D11): `{ kinds: { <generic kind>: <project kind> } }`.
+ * Returns the problems, empty when the map is usable. Whether each VALUE is one of the project's own kinds only the
+ * project can say, so that half of the check lives with the project.
+ */
+export function validateMap(map) {
+  if (
+    map === null ||
+    typeof map !== 'object' ||
+    map.kinds === null ||
+    typeof map.kinds !== 'object' ||
+    Array.isArray(map.kinds)
+  ) {
+    return ['the map has no `kinds` object'];
+  }
+  const problems = [];
+  for (const [generic, target] of Object.entries(map.kinds)) {
+    if (!isKind(generic)) problems.push(unknownKind(generic));
+    if (typeof target !== 'string' || target.trim() === '') {
+      problems.push(`\`${generic}\` maps to ${JSON.stringify(target)}, not a kind name`);
+    }
+  }
+  return problems;
+}

package/dist/sketch-render.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// sketch-render.mjs — draw every `surface` block in a file as a plain grey wireframe (sketch-specs D16).
+//
+//   node scripts/sketch-render.mjs Roadmap/00-ideas/seeds/<seed>.md [--out <file.html>]
+//   node scripts/sketch-render.mjs apps/web/design-system/surfaces/<state>.surface
+//
+// The product owner approves a PICTURE, not a text list, so each state becomes one grey section: boxes in the
+// order the blocks are written, with the words that matter and the facts drawn (a count as that many boxes, a
+// list's column words over placeholder rows). Without --out the page goes to the OS temp folder, so a render never
+// litters `Roadmap/`; the path is printed either way.
+//
+// ⚠️ **Deliberately grey, and deliberately blind to any design system (D4).** A wireframe in brand colours gets
+// reviewed for its colours, and a renderer that imports the project's components becomes a second component
+// library that drifts from the first. So this file imports only `node:*` and the parser, every colour is a grey,
+// and a test fails on anything else. Zero deps.
+
+import { realpathSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSurface, parseSurfaces, SurfaceError } from './lib/surface.mjs';
+
+// Above this a count stops being a shape and becomes noise; the true number is printed beside the boxes.
+const MAX_BOXES = 12;
+
+const escape = (text) =>
+  String(text).replace(
+    /[&<>"']/g,
+    (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]
+  );
+
+// A kind whose words are missing still draws its shape: a grey bar where the words would be.
+const words = (block, tag = 'span', cls = 'w') =>
+  block.words === null
+    ? `<span class="bar"></span>`
+    : `<${tag} class="${cls}">${escape(block.words)}</${tag}>`;
+
+function boxes(count, cls, fill = () => '<span class="bar"></span>') {
+  const drawn = Math.min(count, MAX_BOXES);
+  const items = Array.from({ length: drawn }, (_, i) => `<div class="${cls}">${fill(i)}</div>`).join('');
+  return items + (count > MAX_BOXES ? `<span class="more">×${count}</span>` : '');
+}
+
+const DRAW = {
+  head: (b) =>
+    `<div class="row">${words(b, 'h2', 'title')}${
+      b.action === undefined ? '' : `<span class="button">${escape(b.action)}</span>`
+    }</div>`,
+  answer: (b) => words(b, 'p', 'answer'),
+  summary: (b) => `<div class="row wrap">${boxes(b.count ?? 0, 'stat')}</div>`,
+  tiles: (b) =>
+    `<div class="grid">${boxes(b.count ?? 0, 'tile', () => '<span class="bar"></span><span class="bar short"></span>')}</div>`,
+  steps: (b) =>
+    `<div class="row steps">${boxes(b.count ?? 3, 'step', (i) => `<span class="dot">${i + 1}</span>`)}</div>`,
+  toolbar: () =>
+    '<div class="row"><span class="search">Search</span><span class="pill"></span><span class="pill"></span></div>',
+  list: (b) => {
+    const columns = b.columns ?? null;
+    const cells = columns === null ? 1 : columns.length;
+    const head =
+      columns === null
+        ? ''
+        : `<div class="lrow lhead">${columns.map((c) => `<span>${escape(c)}</span>`).join('')}</div>`;
+    const row = `<div class="lrow">${'<span><span class="bar"></span></span>'.repeat(cells)}</div>`;
+    return `<div class="listbox">${head}${row.repeat(3)}</div>`;
+  },
+  empty: (b) => `<div class="empty">${words(b)}</div>`,
+  card: (b) => `<div class="card">${words(b)}</div>`,
+  field: (b) => `<label class="field">${words(b)}<span class="input"></span></label>`,
+  tabs: (b) => {
+    const labels = b.words === null ? ['', '', ''] : b.words.split('|').map((t) => t.trim());
+    return `<div class="row tabs">${labels
+      .map(
+        (t, i) =>
+          `<span class="tab${i === 0 ? ' on' : ''}">${t === '' ? '<span class="bar"></span>' : escape(t)}</span>`
+      )
+      .join('')}</div>`;
+  },
+  note: (b) => words(b, 'p', 'note'),
+};
+
+const STYLE = `
+*{box-sizing:border-box}body{margin:0;padding:24px 16px;background:#f4f4f4;color:#222;font:14px/1.45 system-ui,sans-serif}
+main{max-width:960px;margin:0 auto}h1{font-size:15px;color:#666;font-weight:600;margin:0 0 16px}
+section{background:#fff;border:1px solid #ccc;border-radius:8px;padding:20px;margin:0 0 28px}
+header{font:12px ui-monospace,monospace;color:#777;border-bottom:1px dashed #ccc;padding-bottom:8px;margin-bottom:16px}
+.block{margin:0 0 14px}.row{display:flex;gap:10px;align-items:center}.wrap{flex-wrap:wrap}
+.title{font-size:22px;margin:0;flex:1}.button{border:1px solid #555;border-radius:6px;padding:6px 12px;background:#e6e6e6;font-weight:600}
+.answer{font-size:16px;font-style:italic;margin:0;color:#333}.note{font-size:12px;color:#777;margin:0}
+.bar{display:inline-block;height:10px;width:120px;max-width:100%;background:#ddd;border-radius:3px}.bar.short{width:60px}
+.stat{border:1px solid #ccc;border-radius:6px;padding:10px;min-width:90px}
+.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(160px,1fr));gap:10px}
+.tile{border:1px solid #ccc;border-radius:6px;padding:16px;display:flex;flex-direction:column;gap:8px;min-height:80px}
+.more{font-size:12px;color:#777;align-self:center}
+.steps .step{display:flex;align-items:center;gap:10px}.steps .step+.step::before{content:"";width:28px;border-top:1px solid #aaa}
+.dot{display:inline-flex;width:26px;height:26px;border-radius:50%;border:1px solid #777;align-items:center;justify-content:center;font-size:12px}
+.search{flex:1;max-width:320px;border:1px solid #bbb;border-radius:6px;padding:6px 10px;color:#999}
+.pill{width:70px;height:26px;border:1px solid #bbb;border-radius:13px}
+.listbox{border:1px solid #ccc;border-radius:6px;overflow:hidden}.lrow{display:flex;border-top:1px solid #e4e4e4}
+.lrow:first-child{border-top:0}.lrow>span{flex:1;min-width:0;padding:10px;min-height:38px}
+.lhead{overflow-wrap:anywhere;background:#eee;font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:#555;font-weight:600}
+.empty{border:2px dashed #bbb;border-radius:8px;padding:32px;text-align:center;color:#666}
+.card{border:1px solid #bbb;border-radius:8px;padding:16px}
+.field{display:flex;flex-direction:column;gap:6px;max-width:420px}.input{height:34px;border:1px solid #aaa;border-radius:6px;background:#fafafa}
+.tabs{gap:0;border-bottom:1px solid #ccc}.tab{padding:8px 14px;color:#777}.tab.on{color:#222;border-bottom:2px solid #222;font-weight:600}
+`;
+
+/** One self-contained grey page, a section per surface. */
+export function renderSketch(surfaces, { title = 'Sketch' } = {}) {
+  const sections = surfaces
+    .map(
+      (surface) =>
+        `<section><header>${escape(surface.state)} · ${escape(surface.route)}</header>${surface.blocks
+          // `block.kind` is one of the parser's twelve (an own-property check there), so it is safe as an attribute
+          // and always has a drawing.
+          .map((block) => `<div class="block" data-kind="${block.kind}">${DRAW[block.kind](block)}</div>`)
+          .join('\n')}</section>`
+    )
+    .join('\n');
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escape(title)}</title><style>${STYLE}</style></head>
+<body><main><h1>${escape(title)} — grey wireframe, ${surfaces.length} state${surfaces.length === 1 ? '' : 's'}</h1>
+${sections}
+</main></body></html>
+`;
+}
+
+const USAGE = 'usage: node scripts/sketch-render.mjs <file.md|file.surface> [--out <file.html>]';
+
+export function main(argv) {
+  const args = [...argv];
+  let out = null;
+  let file = null;
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === '--out') {
+      out = args.shift() ?? null;
+      if (out === null) return { code: 2, stderr: USAGE };
+    } else if (arg.startsWith('-') || file !== null) {
+      return { code: 2, stderr: `unknown argument \`${arg}\`\n${USAGE}` };
+    } else {
+      file = arg;
+    }
+  }
+  if (file === null) return { code: 2, stderr: USAGE };
+
+  const text = readFileSync(file, 'utf8');
+  let surfaces;
+  try {
+    surfaces = extname(file) === '.surface' ? [parseSurface(text, file)] : parseSurfaces(text, file);
+  } catch (error) {
+    if (error instanceof SurfaceError) return { code: 1, stderr: error.message };
+    throw error;
+  }
+  if (surfaces.length === 0) return { code: 1, stderr: `${file}: no \`surface\` block to draw` };
+
+  const name = basename(file, extname(file));
+  const target = out ?? join(tmpdir(), `sketch-${name}.html`);
+  writeFileSync(target, renderSketch(surfaces, { title: `Sketch — ${name}` }));
+  return { code: 0, stdout: target };
+}
+
+// realpath on both sides: through a symlinked path a plain compare is false and the script exits 0 having done
+// nothing (#189 review).
+const isMain = (() => {
+  try {
+    return (
+      !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  const { code, stdout, stderr } = main(process.argv.slice(2));
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+  process.exitCode = code;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "The scripts the Golden Frijoles skills run, packaged so they work in any repo: planning, build-order, reporting and verification rails. Zero dependencies.",
   "type": "module",
   "bin": {