@hncode/hncode 0.4.1 → 0.5.0

package/src/output-styles.js

@@ -0,0 +1,183 @@
+// Output styles, loaded from FILES — the way Claude Code's `.claude/output-styles/`
+// works (a file's NAME is the style, its BODY is the instructions).
+//
+// Why files rather than another picker entry: an output style is a paragraph of
+// prompting that a user iterates on. Editing a TOML string inside config.toml for
+// that is unpleasant, and it makes the style unreviewable in a diff. A directory of
+// Markdown files means the style is editable with $EDITOR, diffable, and shareable
+// by copying one file.
+//
+// File format (all parts optional except the body):
+//
+//     ---
+//     name: Terse reviewer
+//     description: Reviews code, states findings, no praise
+//     ---
+//     You answer only in short declarative sentences. Never open with praise…
+//
+// A file with no frontmatter is valid: the name then comes from the filename
+// (`terse-reviewer.md` -> `Terse Reviewer`), which is what makes ad-hoc styles
+// cheap to add.
+//
+// The style is INJECTED as a system-ish reminder on each request rather than baked
+// into the system prompt, so switching styles does not invalidate the prompt cache
+// and reverting is a matter of clearing a flag.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Where styles are read from, most specific first.
+ *
+ * `home` is the `.hncode` DIRECTORY, matching how config.js resolves every other
+ * per-user path (`path.join(homeDir(), '.hncode', …)`). Deriving it independently
+ * here — `process.env.HNCODE_HOME || ~/.hncode` — got it wrong under HNCODE_HOME,
+ * which points at the PARENT of `.hncode`: styles then lived in
+ * `<HNCODE_HOME>/output-styles` while the rest of the app looked in
+ * `<HNCODE_HOME>/.hncode/…`, so a user with HNCODE_HOME set could never see a style.
+ * The caller passes `config.hncodeDir()`, so both agree by construction.
+ */
+export function styleDirs(cwd, home) {
+  const base = home || defaultHncodeDir();
+  const dirs = [path.join(base, 'output-styles')];
+  // Project-level styles override the personal ones of the same name, so a repo can
+  // pin its own style for everyone working in it.
+  if (cwd) dirs.push(path.join(cwd, '.hncode', 'output-styles'));
+  return dirs;
+}
+
+// The per-user .hncode directory, resolved exactly as config.js does it:
+//   path.join(HNCODE_HOME || os.homedir(), '.hncode')
+// HNCODE_HOME stands in for the HOME directory — it is how a test or a user keeping
+// config on another drive relocates the whole thing — so `.hncode` is appended to
+// it. Appending it to a value that ALREADY contained `.hncode` put the styles one
+// directory too deep and made them invisible.
+function defaultHncodeDir() {
+  return path.join(process.env.HNCODE_HOME || os.homedir(), '.hncode');
+}
+
+/** `terse-reviewer` -> `Terse Reviewer`. The fallback name when a file has none. */
+export function nameFromFile(file) {
+  const base = path.basename(String(file || ''), '.md');
+  return base.split(/[-_]+/).filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * Split a style file into { meta, body }.
+ *
+ * Only a leading `---` fence is treated as frontmatter — the same rule as Jekyll's,
+ * chosen because a style BODY will often contain `---` (a horizontal rule in
+ * Markdown), and treating a later one as a fence would swallow the instructions.
+ */
+export function parseStyle(raw, file = '') {
+  const text = String(raw == null ? '' : raw).replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  const meta = {};
+  let body = text;
+  if (lines[0] !== undefined && lines[0].trim() === '---') {
+    // Find the CLOSING fence; everything between is metadata.
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i].trim() === '---') { end = i; break; }
+    }
+    if (end > 0) {
+      for (let i = 1; i < end; i++) {
+        const m = /^\s*([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
+        if (!m) continue;
+        // Strip one layer of quotes if present; a description with a colon is
+        // otherwise fine because only the FIRST colon separates the key.
+        meta[m[1].toLowerCase()] = m[2].trim().replace(/^(['"])(.*)\1$/, '$2');
+      }
+      body = lines.slice(end + 1).join('\n');
+    }
+  }
+  const name = meta.name || nameFromFile(file);
+  return { name, description: meta.description || '', body: body.trim(), meta };
+}
+
+/** Every style readable right now, sorted by name. Missing directories are not an error. */
+export function listStyles(cwd, home) {
+  const found = new Map();   // name (lowercased) -> style
+  for (const dir of styleDirs(cwd, home)) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    for (const f of entries.sort()) {
+      if (!f.endsWith('.md')) continue;
+      let raw = '';
+      try { raw = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+      const style = parseStyle(raw, f);
+      if (!style.body) continue;                 // a style with no body does nothing
+      // The LATER directory wins (project over personal): this loop runs home first.
+      found.set(style.name.toLowerCase(), { ...style, file: path.join(dir, f), dir });
+    }
+  }
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** One style by name (case-insensitive), or null. */
+export function findStyle(name, cwd, home) {
+  // A trailing `.md` is dropped, since `ls` shows the extension and typing it is the
+  // obvious thing to do after looking at the directory.
+  const want = String(name == null ? '' : name).trim().toLowerCase().replace(/\.md$/, '');
+  if (!want) return null;
+  const all = listStyles(cwd, home);
+  // Every spelling a user might type, most exact first:
+  //   1. the display name (`Terse Reviewer`)
+  //   2. the FILE name without .md (`terse-reviewer`) — this is what `ls` shows and
+  //      what a user types after seeing the directory, and without it the lookup
+  //      failed for the very style they just created.
+  //   3. a prefix of either, so `/output-style terse` is enough to disambiguate.
+  const fileOf = (s) => String(s.file || '').replace(/^.*[\\/]/, '').replace(/\.md$/, '').toLowerCase();
+  return all.find((s) => s.name.toLowerCase() === want)
+    || all.find((s) => fileOf(s) === want)
+    || all.find((s) => s.name.toLowerCase().startsWith(want))
+    || all.find((s) => fileOf(s).startsWith(want))
+    || null;
+}
+
+/**
+ * The reminder text that carries a style into a request.
+ *
+ * Deliberately wrapped in the same `<system-reminder>` envelope the harness uses
+ * elsewhere, and placed so the model reads it as an instruction about FORM rather
+ * than as content to answer. It says the style overrides earlier formatting
+ * requests, because a system prompt already contains output rules and the later
+ * instruction is the one a model follows.
+ */
+export function styleReminder(style) {
+  if (!style || !style.body) return '';
+  return [
+    '<system-reminder>',
+    `The user has selected the "${style.name}" output style. It governs the FORM of`,
+    'your replies and takes precedence over any earlier formatting instruction.',
+    '',
+    style.body,
+    '</system-reminder>',
+  ].join('\n');
+}
+
+/** Create a starter file so /output-style new gives the user something to edit. */
+export function writeStyleTemplate(dir, name) {
+  fs.mkdirSync(dir, { recursive: true });
+  const slug = String(name || 'my-style').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'my-style';
+  const file = path.join(dir, `${slug}.md`);
+  if (fs.existsSync(file)) return { file, created: false };
+  const body = [
+    '---',
+    `name: ${nameFromFile(file)}`,
+    'description: what this style is for',
+    '---',
+    '',
+    'Write your style instructions here. They describe the FORM of every reply:',
+    'length, tone, structure, what to leave out. They are added to each request as',
+    'a system reminder, so they take precedence over the default formatting rules.',
+    '',
+  ].join('\n');
+  fs.writeFileSync(file, body, 'utf8');
+  return { file, created: true };
+}
+
+export default { styleDirs, listStyles, findStyle, parseStyle, styleReminder, nameFromFile, writeStyleTemplate };

package/src/patch.js

@@ -0,0 +1,248 @@
+// Symbol-level patching — let a plugin wrap ANY exported function or class method
+// in hncode's own source, without editing that source.
+//
+// WHY THIS EXISTS
+// --------------
+// The original `api.patch(seam, fn)` only exposed nine hand-picked "seams"
+// (systemPrompt, llmRequest, …). Everything else — Agent.send, LLM.chat, any of
+// the ~340 exported functions — was unreachable from a plugin. This module makes
+// every symbol patchable by rewriting the target module's SOURCE at load time.
+//
+// HOW IT WORKS (and why it is safe)
+// ---------------------------------
+// ESM exports are read-only bindings, so a plugin cannot monkey-patch them at
+// runtime (verified: `Cannot assign to read only property`). But a module CAN
+// reassign its OWN bindings, and Node's `module.registerHooks({ load })` lets us
+// rewrite a module's source as it is loaded. So for each requested target we:
+//
+//   1. leave the original declaration untouched (no body parsing at all), and
+//   2. append a small footer that reassigns the symbol through our wrapper:
+//        foo = __hncodePatch("file.js#foo", foo);
+//        Klass.prototype.m = __hncodePatch("file.js#Klass.m", Klass.prototype.m);
+//
+// For an `export const` target we also rewrite that one declaration line
+// (`const` → `let`) so it can be reassigned — still a single-line change, still
+// no function-body analysis. This was chosen over an AST rewriter (acorn) to keep
+// hncode's zero-runtime-dependency promise; it relies only on the fact that the
+// target's declaration line is well-formed, which holds for every export in src/.
+//
+// ORDERING (important)
+// --------------------
+// The load hook only sees modules that are imported AFTER it is registered;
+// already-cached modules are left alone (verified). hncode's entry therefore
+// registers this loader and loads plugins BEFORE importing the business modules
+// (see src/bootstrap.js). A module that has already been imported cannot be
+// patched — patching it is reported as a skipped target, not a silent no-op.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import module from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+// Registry: { "file.js#symbol": [handler, …] }. The loader reads it per module.
+const registry = new Map();
+
+// The nine legacy abstract seams, kept so `api.patch('systemPrompt', fn)` from an
+// existing plugin keeps working. These are handled by plugin.js's chain runner,
+// NOT by this module; listed here so api.patch can tell the two target kinds apart.
+export const LEGACY_SEAMS = new Set([
+  'systemPrompt', 'llmRequest', 'llmHeaders', 'llmBody', 'llmResponse',
+  'toolDispatch', 'toolResult', 'beforeRender', 'afterRender',
+]);
+
+let loaderInstalled = false;
+let loaderActive = false;
+const patchedFiles = new Set();
+
+// A target is "file.js#symbol" (a plain export) or "file.js#Class.method".
+const TARGET_RE = /^([^#]+)#([A-Za-z_$][\w$]*)(?:\.([A-Za-z_$][\w$]*))?$/;
+
+/** Normalise a user-supplied target into { file, base, method|null } or null. */
+export function parseTarget(target) {
+  const m = TARGET_RE.exec(String(target || '').trim());
+  if (!m) return null;
+  return { file: m[1], base: m[2], method: m[3] || null, id: `${m[1]}#${m[2]}${m[3] ? '.' + m[3] : ''}` };
+}
+
+/** Register one handler for a symbol target. Returns an unregister function. */
+export function addPatch(target, handler) {
+  const info = parseTarget(target);
+  if (!info) throw new Error(`patch: bad target "${target}" (want "file.js#symbol" or "file.js#Class.method")`);
+  if (!handler || typeof handler !== 'object') throw new Error('patch: handler must be an object like { before, after, around }');
+  if (!info.method && patchedFiles.has(info.file) && !registry.get(info.id)) {
+    // Allow it anyway; the loader may not have run yet for this file.
+  }
+  const list = registry.get(info.id) || [];
+  list.push(handler);
+  registry.set(info.id, list);
+  return () => {
+    const arr = registry.get(info.id);
+    if (!arr) return;
+    const i = arr.indexOf(handler);
+    if (i >= 0) arr.splice(i, 1);
+    if (!arr.length) registry.delete(info.id);
+  };
+}
+
+/** All registered target ids (for /plugins-style introspection). */
+export function listPatchTargets() { return [...registry.keys()]; }
+
+/** Remove every handler (used by _resetPlugins and tests). */
+export function clearPatches() { registry.clear(); }
+
+// ---------------------------------------------------------------------------
+// The runtime wrapper applied in the module footer.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap `fn` so every handler registered for `id` runs around it.
+ * - before(...args): if it returns an array, that replaces the argument list.
+ * - after(result, args): if it returns non-undefined, that replaces the result.
+ * - around(original, args, thisArg): full control; its return value is the result.
+ * Handler `this` is the call's `this` (so a class method can read its instance).
+ */
+export function applyPatches(id, fn) {
+  const handlers = registry.get(id);
+  if (!handlers || !handlers.length) return fn;
+
+  function wrapped(...args) {
+    let finalArgs = args;
+    for (const h of handlers) {
+      if (typeof h.before === 'function') {
+        const r = h.before.apply(this, finalArgs);
+        if (Array.isArray(r)) finalArgs = r;
+      }
+    }
+
+    // `around` takes over the call entirely; otherwise call the original.
+    const aroundHandler = handlers.filter((h) => typeof h.around === 'function').pop();
+    const aroundFn = aroundHandler && aroundHandler.around;
+    const invoke = () => (aroundFn ? aroundFn.call(this, fn, finalArgs, this) : fn.apply(this, finalArgs));
+
+    const finish = (result) => {
+      let out = result;
+      for (const h of handlers) {
+        if (typeof h.after === 'function') {
+          const r = h.after.call(this, out, finalArgs);
+          if (r !== undefined) out = r;
+        }
+      }
+      return out;
+    };
+
+    const r = invoke();
+    // Preserve asyncness: only then-ables get the after-chain deferred.
+    if (r && typeof r.then === 'function') return r.then(finish);
+    return finish(r);
+  }
+  return wrapped;
+}
+
+// Expose to rewritten modules (they run in their own scope and cannot import us
+// without a cycle). One global, set once.
+function installGlobal() {
+  if (!globalThis.__hncodePatch) {
+    globalThis.__hncodePatch = (id, fn) => applyPatches(id, fn);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The load hook: rewrite a module's source to append the patch footers.
+// ---------------------------------------------------------------------------
+
+/** Build the footer source for the targets whose file matches `base`. */
+function footerFor(base, ids) {
+  const lines = ['', '/* hncode:patch-footer (auto-generated) */', ';(() => {', '  const P = globalThis.__hncodePatch;', '  if (!P) return;'];
+  for (const id of ids) {
+    const info = parseTarget(id);
+    if (!info) continue;
+    const ref = info.method ? `${info.base}.prototype.${info.method}` : info.base;
+    lines.push(`  try { ${ref} = P(${JSON.stringify(id)}, ${ref}); } catch (e) { console.error('[hncode-patch] ${id}:', e.message); }`);
+  }
+  lines.push('})();', '');
+  return lines.join('\n');
+}
+
+/**
+ * In `src`, make target `file#symbol` reassignable:
+ *  - `export const NAME = …` → `export let NAME = …`   (only for a plain target)
+ * The declaration line is matched literally; function bodies are never touched.
+ */
+function makeReassignable(src, info) {
+  if (info.method) return src; // class methods are patched via the prototype
+  const re = new RegExp(`^(\\s*)export const (${info.base})\\b`, 'm');
+  return src.replace(re, '$1export let $2');
+}
+
+/** Rewrite one module's source, or return it unchanged when it has no targets. */
+export function rewriteSource(filename, src) {
+  const base = filename.split(/[\\/]/).pop();
+  const ids = [...registry.keys()].filter((id) => parseTarget(id)?.file === base);
+  if (!ids.length) return null;
+
+  let out = src;
+  for (const id of ids) {
+    const info = parseTarget(id);
+    // A plain target declares a top-level function/const; make it mutable if const.
+    out = makeReassignable(out, info);
+  }
+  return out + footerFor(base, ids);
+}
+
+/**
+ * Register the Node load hook. Idempotent and NON-FATAL: if the runtime has no
+ * `module.registerHooks` (added in Node 22.15; hncode still declares engines
+ * >=20) or registration throws, symbol patching is simply disabled. It must
+ * never throw — a throw here would propagate through bootstrap and stop hncode
+ * from starting at all, which is far worse than a missing optional feature.
+ * Returns true when the loader is active.
+ */
+export function installPatchLoader() {
+  installGlobal();
+  if (loaderInstalled) return loaderActive;
+  loaderInstalled = true;
+
+  if (typeof module.registerHooks !== 'function') {
+    // Older Node: patching is unavailable. Everything else keeps working.
+    console.error('[hncode-patch] module.registerHooks is unavailable on this Node — symbol patching disabled.');
+    return (loaderActive = false);
+  }
+
+  let srcDir;
+  try { srcDir = path.dirname(fileURLToPath(import.meta.url)); } catch { return (loaderActive = false); }
+
+  try {
+    module.registerHooks({
+      load(url, context, nextLoad) {
+        const r = nextLoad(url, context);
+        // Only hncode's own src/*.js files, and only when something targets them.
+        if (!url.startsWith('file:') || !url.includes('/src/') || typeof r.source === 'undefined') return r;
+        let file;
+        try { file = fileURLToPath(url); } catch { return r; }
+        if (path.dirname(file) !== srcDir) return r;
+        try {
+          const s = typeof r.source === 'string' ? r.source : Buffer.from(r.source).toString('utf8');
+          const rewritten = rewriteSource(file, s);
+          if (rewritten == null) return r;
+          patchedFiles.add(path.basename(file));
+          return { ...r, source: rewritten, format: r.format || 'module' };
+        } catch (e) {
+          // A rewrite failure must not break the module load — return it as-is
+          // and report, rather than taking hncode down.
+          console.error(`[hncode-patch] failed to rewrite ${url}:`, e && e.message);
+          return r;
+        }
+      },
+    });
+    loaderActive = true;
+  } catch (e) {
+    console.error('[hncode-patch] could not install the load hook — symbol patching disabled:', e && e.message);
+    loaderActive = false;
+  }
+  return loaderActive;
+}
+
+/** Whether the load hook is actually active (installed AND usable). index.js uses
+ *  this to decide whether plugins still need loading — if patching is disabled,
+ *  bootstrap already loaded them, so it must NOT be treated as "installed". */
+export function isLoaderInstalled() { return loaderActive; }

package/src/permissions.js

@@ -30,9 +30,19 @@ const PATH_ARGS = {
   Grep: ['path', 'pattern'],
 };
 
+/** Strip a trailing `# …` comment. ` #` (whitespace before the hash) is the
+ *  delimiter, so a `#` inside an argument — `Bash(echo a#b)` — is left alone. */
+export function stripRuleComment(text) {
+  const m = /(^|\s)#/.exec(String(text == null ? '' : text));
+  return m ? String(text).slice(0, m.index + m[1].length).trim() : String(text == null ? '' : text).trim();
+}
+
 // `Bash(npm run test)` / `Read(./src/**)` -> { tool, arg }
 export function parseRule(rule) {
-  const text = String(rule == null ? '' : rule).trim();
+  // The comment is stripped FIRST. Without this a rule carrying `# match: …`
+  // examples parsed as null (the text no longer ends with `)`) and the rule
+  // silently stopped matching anything — so annotating a rule broke it.
+  const text = stripRuleComment(rule);
   if (!text) return null;
   const open = text.indexOf('(');
   if (open === -1) return { tool: text, arg: null };
@@ -118,3 +128,122 @@ export function describeRules(rules) {
   }
   return lines.join('\n');
 }
+
+// ---------------------------------------------------------------------------
+// Rule self-tests
+// ---------------------------------------------------------------------------
+// A rule that silently matches NOTHING is worse than no rule at all: the user
+// believes `npm test` is allowed, the prompt appears anyway, and nothing says why.
+// A typo in a glob (`./src/*` vs `./src/**`) is invisible until the prompt shows up
+// at the wrong moment.
+//
+// So a rule may carry its own examples, checked when the rules are read:
+//
+//   Bash(npm run test *)   # match: npm run test foo   | not_match: npm run tests
+//
+// This mirrors codex's `prefix_rule(match=[...], not_match=[...])`, which validates
+// its examples at load time. The examples live on the SAME line as the rule, as a
+// trailing comment, so a rule and its test cannot drift into two places and the
+// line-based config format does not have to change.
+//
+// Several examples are separated by `|`. An example is the ARGUMENT the rule
+// describes — the command for Bash, the path for a file tool — so no quoting is
+// needed for the common case.
+
+/** Split one rule line into `{ rule, match, not_match }`. */
+export function parseRuleLine(line) {
+  const text = String(line == null ? '' : line);
+  // A ` #` delimiter, so a `#` inside an argument stays part of the rule.
+  const delim = /(^|\s)#/.exec(text);
+  const ruleText = delim ? text.slice(0, delim.index + delim[1].length).trim() : text.trim();
+  const comment = delim ? text.slice(delim.index + delim[0].length).trim() : '';
+  const out = { rule: ruleText, match: [], not_match: [] };
+  if (!comment) return out;
+  // Scan for the markers rather than splitting on them: `split` with a LOOKAHEAD
+  // of `\bnot[_-]?match` splits `not-match` into `not-` and `match:` (the boundary
+  // before `match` matched first), which produced two unusable halves. An explicit
+  // scan takes the longest marker at each position and cannot do that.
+  const marker = /(not[_-]?match|match)\s*:/gi;
+  const found = [];
+  let m;
+  while ((m = marker.exec(comment)) !== null) {
+    found.push({ key: /^not/i.test(m[1]) ? 'not_match' : 'match', from: m.index, bodyStart: m.index + m[0].length });
+  }
+  for (let i = 0; i < found.length; i++) {
+    const end = i + 1 < found.length ? found[i + 1].from : comment.length;
+    const body = comment.slice(found[i].bodyStart, end);
+    for (const ex of body.split('|')) {
+      const t = ex.trim();
+      if (t) out[found[i].key].push(t);
+    }
+  }
+  return out;
+}
+
+/** An example string -> the argument object `ruleMatches` expects. */
+export function exampleArgs(toolName, example) {
+  const ex = String(example == null ? '' : example).trim();
+  if (toolName === 'Bash') return { command: ex };
+  return { path: ex, file_path: ex, pattern: ex };
+}
+
+/**
+ * Check every rule's examples. Returns `{ checks, failed }`; a failed check is
+ * `{ rule, kind: 'match'|'not_match', example, list }`.
+ *
+ * A rule with NO examples yields no checks: the test is opt-in, so adding this to an
+ * existing config cannot start reporting errors for rules nobody annotated.
+ */
+export function selfTestRules(rules) {
+  const list = rules || {};
+  const checks = [];
+  const failed = [];
+  // `deny` is included on purpose: an over-broad deny is the MOST damaging typo of
+  // the three, because it can lock the agent out of the work it was asked to do.
+  for (const key of ['allow', 'ask', 'deny']) {
+    const arr = Array.isArray(list[key]) ? list[key] : [];
+    for (const raw of arr) {
+      const { rule, match, not_match } = parseRuleLine(raw);
+      if (!rule) continue;
+      const parsed = parseRule(rule);
+      if (!parsed) {
+        failed.push({ rule, kind: 'parse', example: '', list: key });
+        continue;
+      }
+      for (const ex of match) {
+        const pass = ruleMatches(parsed, parsed.tool, exampleArgs(parsed.tool, ex));
+        checks.push({ rule, kind: 'match', example: ex, pass, list: key });
+        if (!pass) failed.push({ rule, kind: 'match', example: ex, list: key });
+      }
+      for (const ex of not_match) {
+        const pass = !ruleMatches(parsed, parsed.tool, exampleArgs(parsed.tool, ex));
+        checks.push({ rule, kind: 'not_match', example: ex, pass, list: key });
+        if (!pass) failed.push({ rule, kind: 'not_match', example: ex, list: key });
+      }
+    }
+  }
+  return { checks, failed };
+}
+
+/** The self-test block for the /permissions panel. */
+export function describeSelfTest(result) {
+  if (!result || !result.checks.length) {
+    return result && result.failed.length
+      ? `${result.failed.length} rule(s) could not be parsed:\n`
+        + result.failed.map((f) => `  FAIL ${f.list}: ${f.rule}`).join('\n')
+      : 'No rule has examples yet. Add them on the rule line:\n'
+        + '  Bash(git push *)   # match: git push | not_match: git pull';
+  }
+  const out = [`${result.checks.length} example(s) checked, ${result.failed.length} failed:`];
+  for (const c of result.checks) {
+    const want = c.kind === 'match' ? 'should match    ' : 'should NOT match';
+    out.push(`  ${c.pass ? 'ok  ' : 'FAIL'} ${want} ${c.list}: ${c.rule}  <- ${c.example}`);
+  }
+  return out.join('\n');
+}
+
+export default {
+  parseRule, ruleMatches, decideFromRules, describeRules,
+  parseRuleLine, selfTestRules, describeSelfTest, exampleArgs,
+};
+

package/src/plan.js

@@ -1,7 +1,8 @@
-// Plan review helpers — turning a model's <plan> block into something the user
+// Plan review helpers — turning a model's plan block into something the user
 // can actually review before any file is touched.
 //
-// Plan mode already asks the model for a <plan>…</plan> block and prompts to
+// Plan mode already asks the model for a <|plan|>…</|plan|> block and prompts to
+// approve it. What this module adds is the review material and the persistence:
 // approve it. What this module adds is the review material and the persistence:
 //
 //   * filesReferenced(plan)  — which paths the plan says it will touch, so the