@marcomigozzi/trailhead 0.8.1 → 0.9.0

package/plugins/trailhead/hooks/lib/gh-subcommand.js

@@ -0,0 +1,102 @@
+'use strict';
+// gh-subcommand.js: shared gh-subcommand detector, extracted from
+// trailhead-body-guard.js's ghBodyWrite and trailhead-secret-guard.js's
+// ghIssueWrite (#153 follow-up), so both guards share ONE token walk instead
+// of drifting copies.
+//
+// Bug fixed here (#153): the original inline walk only treated `-R`/`--repo`
+// as a two-token (value-taking) global gh flag. Any OTHER two-token global
+// flag (e.g. `gh --hostname h issue edit 5 --body ""`) desynced the walk:
+// after skipping `--hostname`, the index landed on its value `h`, which is
+// not a `-`-prefixed flag so the loop stopped there, and `h` was mistaken for
+// the subcommand. The write became invisible to both guards (a missed
+// empty-body block in body-guard, an unscanned secret in secret-guard).
+//
+// Follow-up fix (#153): a first pass tolerated a stray value token after any
+// unknown flag UNLESS that token was itself a flag or a subcommand keyword
+// (issue/pr/api). That guard reintroduced the exact same desync whenever the
+// flag's VALUE literally equalled a subcommand keyword, e.g.
+// `gh --hostname api issue edit 5` mis-resolved `sub` to `api` (the flag
+// value), hiding the real `issue edit` write again.
+//
+// Fix: drop the keyword-based guard entirely and model flag arity instead.
+// gh's only value-taking global flag before a subcommand is -R/--repo; a
+// small, explicit set of global flags are boolean (take no value). Every
+// OTHER flag token is treated as value-taking, so its value can never be
+// mistaken for the subcommand - including when that value happens to equal
+// a subcommand keyword like `issue`/`pr`/`api`.
+//
+// Second follow-up fix (#153): treating every unknown flag as value-taking
+// reopened the MIRROR case - an unknown BOOLEAN flag directly before the
+// subcommand (e.g. `gh --foo issue edit 5`) now gets treated as value-taking
+// and swallows the subcommand itself as if it were the flag's value, landing
+// `sub` on the verb (`edit`) instead of `issue`. The two failure directions
+// (a flag's VALUE colliding with a subcommand keyword, vs. an unknown
+// BOOLEAN flag consuming the subcommand) cannot both be resolved by a
+// positional walk alone: `gh --X <tok> issue edit` and `gh --X issue edit`
+// are structurally ambiguous without knowing --X's arity in advance, and gh
+// itself rejects unknown flags so neither shape occurs with the real `gh`
+// binary. But the guard defends against any `gh`-named binary, so it must
+// not depend on that.
+//
+// Design principle: keep the value-taking primary walk (it is correct for
+// every KNOWN two-token flag, e.g. -R/--repo, and for the common case of an
+// unknown two-token flag), then ADD a fail-safe fallback that scans forward
+// for a recognized write-subcommand keyword whenever the walk did not land
+// on one. Erring toward DETECTION (scanning/considering a write) is the safe
+// direction for a security guard; under-detection (missing a real write) is
+// the dangerous one. The downstream verb gate in each guard still prevents a
+// stray keyword token in a genuinely non-write command from being
+// misclassified as a write.
+//
+// Self-contained. No requires.
+
+// gh's boolean global flags (take NO value). gh's only value-taking global
+// flag before a subcommand is -R/--repo; every other flag token here is
+// treated as value-taking, so an unknown two-token global flag's value can
+// never be mistaken for the subcommand (#153) - including when that value
+// happens to equal a subcommand keyword like `issue`/`pr`/`api`.
+const BOOLEAN_GLOBAL_FLAGS = new Set(['-h', '--help', '--version']);
+
+// The subcommands the guards care about; used by the fail-safe fallback
+// below to recover from an unknown boolean flag swallowing the subcommand.
+const WRITE_SUBCOMMANDS = new Set(['issue', 'pr', 'api']);
+
+// Parse a raw shell command string and locate the gh subcommand/verb.
+// Returns { sub, verb } (verb may be undefined) or null when this is not a
+// gh invocation at all.
+function parseGhSubcommand(cmd) {
+  const toks = String(cmd).trim().split(/\s+/);
+  let i = 0;
+  while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++; // env prefix
+  if (i >= toks.length || !/(^|\/)gh$/.test(toks[i])) return null;         // the gh binary
+  const start = i + 1; // first token after `gh`
+  i = start;
+  // Primary positional walk. -R/--repo (and any non-boolean, non-glued flag)
+  // is treated as value-taking: consume one following non-flag token so an
+  // unknown two-token global flag's value cannot shift the subcommand (#153).
+  while (i < toks.length && toks[i].startsWith('-')) {
+    const flag = toks[i];
+    i++; // the flag token itself
+    if (flag.includes('=') || BOOLEAN_GLOBAL_FLAGS.has(flag)) continue; // no separate value
+    if (i < toks.length && !toks[i].startsWith('-')) i++;               // consume its value
+  }
+  let sub = toks[i];
+  let verb = toks[i + 1];
+  // Fail-safe fallback: if the walk did NOT land on a recognized write
+  // subcommand, an unknown *boolean* flag before the subcommand may have
+  // consumed the subcommand itself as if it were the flag's value (the mirror
+  // of the value-collision case). Scan forward for the first recognized
+  // subcommand keyword and use it. Over-detection is the safe direction for a
+  // guard; under-detection (missing a real write) is the dangerous one (#153).
+  // The downstream guards still gate on the verb, so a stray keyword token in a
+  // non-write command does not become a spurious write.
+  if (!WRITE_SUBCOMMANDS.has(sub)) {
+    for (let j = start; j < toks.length; j++) {
+      if (WRITE_SUBCOMMANDS.has(toks[j])) { sub = toks[j]; verb = toks[j + 1]; break; }
+    }
+  }
+  return { sub, verb };
+}
+
+module.exports = { parseGhSubcommand, BOOLEAN_GLOBAL_FLAGS, WRITE_SUBCOMMANDS };

package/plugins/trailhead/hooks/lib/gh-subcommand.test.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Tests for gh-subcommand.js. Run: node gh-subcommand.test.js
+const assert = require('assert');
+const { parseGhSubcommand } = require('./gh-subcommand.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- env prefix + gh binary detection ---
+ok('env prefix before gh is skipped',
+  (() => { const r = parseGhSubcommand('FOO=1 gh issue edit'); return r && r.sub === 'issue' && r.verb === 'edit'; })());
+ok('an absolute gh path is recognised',
+  (() => { const r = parseGhSubcommand('/usr/bin/gh api repos/o/r/issues/5'); return r && r.sub === 'api'; })());
+ok('a non-gh command returns null', parseGhSubcommand('echo issue edit') === null);
+ok('a bare gh with no subcommand does not throw', (() => {
+  const r = parseGhSubcommand('gh');
+  return r && r.sub === undefined && r.verb === undefined;
+})());
+
+// --- plain subcommand/verb ---
+ok('plain gh issue edit', (() => { const r = parseGhSubcommand('gh issue edit 5'); return r.sub === 'issue' && r.verb === 'edit'; })());
+ok('plain gh pr edit', (() => { const r = parseGhSubcommand('gh pr edit'); return r.sub === 'pr' && r.verb === 'edit'; })());
+ok('plain gh api', (() => { const r = parseGhSubcommand('gh api repos/o/r/issues/5'); return r.sub === 'api'; })());
+
+// --- -R / --repo two-token form still resolves ---
+ok('gh -R owner/repo issue edit 5 resolves issue/edit',
+  (() => { const r = parseGhSubcommand('gh -R owner/repo issue edit 5'); return r.sub === 'issue' && r.verb === 'edit'; })());
+ok('gh --repo owner/repo pr edit resolves pr/edit',
+  (() => { const r = parseGhSubcommand('gh --repo owner/repo pr edit'); return r.sub === 'pr' && r.verb === 'edit'; })());
+
+// --- --repo=owner/repo single-token form ---
+ok('gh --repo=owner/repo issue edit resolves issue/edit',
+  (() => { const r = parseGhSubcommand('gh --repo=owner/repo issue edit'); return r.sub === 'issue' && r.verb === 'edit'; })());
+
+// --- REGRESSION (#153): an unknown two-token global flag no longer desyncs ---
+ok('gh --hostname h issue edit 5 --body "" resolves issue/edit',
+  (() => { const r = parseGhSubcommand('gh --hostname h issue edit 5 --body ""'); return r.sub === 'issue' && r.verb === 'edit'; })());
+ok('gh --hostname h pr edit 5 resolves pr/edit',
+  (() => { const r = parseGhSubcommand('gh --hostname h pr edit 5'); return r.sub === 'pr' && r.verb === 'edit'; })());
+ok('gh --hostname h api --method PATCH ... resolves api',
+  (() => {
+    const r = parseGhSubcommand('gh --hostname h api --method PATCH repos/o/r/issues/5 -f body=x');
+    return r.sub === 'api';
+  })());
+
+// --- multiple unknown two-token flags ---
+ok('gh --hostname h --foo bar issue edit 5 resolves issue/edit',
+  (() => { const r = parseGhSubcommand('gh --hostname h --foo bar issue edit 5'); return r.sub === 'issue' && r.verb === 'edit'; })());
+
+// --- REGRESSION (#153 follow-up): a two-token global flag whose VALUE
+// literally equals a subcommand keyword must still resolve the real
+// subcommand, not the flag's value ---
+ok('gh --hostname api issue edit 5 resolves issue/edit (flag value equals a keyword)',
+  (() => { const r = parseGhSubcommand('gh --hostname api issue edit 5'); return r.sub === 'issue' && r.verb === 'edit'; })());
+ok('gh --hostname issue issue comment 5 resolves issue/comment (flag value equals a keyword)',
+  (() => { const r = parseGhSubcommand('gh --hostname issue issue comment 5'); return r.sub === 'issue' && r.verb === 'comment'; })());
+ok('gh --hostname pr pr edit 5 resolves pr/edit (flag value equals a keyword)',
+  (() => { const r = parseGhSubcommand('gh --hostname pr pr edit 5'); return r.sub === 'pr' && r.verb === 'edit'; })());
+
+// --- a real boolean global flag directly before the subcommand is not over-consumed ---
+// (Trade-off of the new model: an UNKNOWN flag like --foo is now treated as
+// value-taking, so it consumes the next token. Only flags in
+// BOOLEAN_GLOBAL_FLAGS are known to take no value.)
+ok('gh --help issue edit resolves issue/edit (real boolean flag not swallowing the subcommand)',
+  (() => { const r = parseGhSubcommand('gh --help issue edit'); return r.sub === 'issue' && r.verb === 'edit'; })());
+
+// --- single-token --hostname=h form ---
+ok('gh --hostname=h issue edit resolves issue/edit',
+  (() => { const r = parseGhSubcommand('gh --hostname=h issue edit'); return r.sub === 'issue' && r.verb === 'edit'; })());
+
+// --- gh api with explicit flags before the write flag (baseline) ---
+ok('gh api --method PATCH ... resolves api',
+  (() => {
+    const r = parseGhSubcommand('gh api --method PATCH repos/o/r/issues/5 -f body=x');
+    return r.sub === 'api';
+  })());
+
+// --- REGRESSION (#153 second follow-up): an unknown BOOLEAN flag directly
+// before the subcommand must not swallow the subcommand as its own value
+// (the mirror of the keyword-value collision case above) ---
+ok('gh --foo issue edit 5 resolves issue/edit (unknown boolean flag)',
+  (() => { const r = parseGhSubcommand('gh --foo issue edit 5'); return r.sub === 'issue' && r.verb === 'edit'; })());
+ok('gh -x pr edit 5 resolves pr/edit (unknown short boolean flag)',
+  (() => { const r = parseGhSubcommand('gh -x pr edit 5'); return r.sub === 'pr' && r.verb === 'edit'; })());
+ok('gh --foo api repos/o/r/issues/5 -f body=x resolves api (unknown boolean flag)',
+  (() => {
+    const r = parseGhSubcommand('gh --foo api repos/o/r/issues/5 -f body=x');
+    return r.sub === 'api';
+  })());
+ok('gh --foo --bar issue edit 5 resolves issue/edit (two unknown boolean flags)',
+  (() => { const r = parseGhSubcommand('gh --foo --bar issue edit 5'); return r.sub === 'issue' && r.verb === 'edit'; })());
+
+// --- a genuine non-write subcommand must NOT be forced to look like a write ---
+// (the fallback only fires when the walk missed a WRITE_SUBCOMMANDS keyword;
+// `repo` is not one, so it must be reported as-is, not fabricated into a keyword)
+ok('gh repo view owner/repo resolves sub "repo" (not forced into a write keyword)',
+  (() => { const r = parseGhSubcommand('gh repo view owner/repo'); return r.sub === 'repo'; })());
+
+console.log(`✓ gh-subcommand: ${passed} assertions passed`);

package/plugins/trailhead/hooks/trailhead-body-guard.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// trailhead-body-guard.js: PreToolUse(Bash) hook.
+// trailhead rewrites issue/PR bodies with a read-modify-write: `gh issue view
+// <n> --json body` -> transform in memory -> `gh issue edit <n> --body...`.
+// If the pre-write read hits a transient failure (e.g. a GitHub HTTP 5xx) and
+// comes back with an empty body without `gh` exiting non-zero, that empty
+// string flows straight into the write and clobbers the existing body. A
+// trailhead body is never legitimately empty, so this is the write-site
+// backstop: it hard-blocks a `gh issue edit` / `gh pr edit` / `gh api` write
+// that would set a body to empty or whitespace-only, protecting the existing
+// body from a degraded read.
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Fail-OPEN on any error (exit 0): this is a cheap backstop, not a hard
+// dependency, and a crash here must never block a legitimate write.
+// Self-contained. Pure functions are exported for tests; runs as a hook when
+// executed directly.
+
+const fs = require('fs');
+const os = require('os');
+const { parseGhSubcommand } = require('./lib/gh-subcommand.js');
+
+// Is the resolved body text clearly empty or whitespace-only?
+function isEmptyBody(text) {
+  return text === '' || /^\s*$/.test(text);
+}
+
+// A value that is a shell expansion (command substitution, backticks, or a
+// bare env-var reference) can't be resolved statically: treat it as unknown
+// rather than guessing, so the guard never blocks on a body it can't prove
+// empty.
+function isShellExpansion(text) {
+  return /\$\(/.test(text) || /`/.test(text) || /^\$/.test(text);
+}
+
+// `fs.readFileSync` does not expand `~`; do it ourselves so a `~/`-prefixed
+// (or bare `~`) --body-file / api @-path is actually read, rather than
+// throwing ENOENT and silently falling through to "unknowable".
+function expandHome(p) {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return os.homedir() + p.slice(1);
+  return p;
+}
+
+// Read a --body-file (or api `@file`) target, mirroring secret-guard's
+// bodyFileText: sliced to ~1MB. Throws (ENOENT etc.) are the caller's
+// problem to catch.
+function readBodyFile(filePath) {
+  return fs.readFileSync(expandHome(filePath), 'utf8').slice(0, 1_000_000);
+}
+
+// Strip one matching pair of surrounding quotes (an artifact of parsing a
+// bare `body=` value that itself contains a literal `""`/`''`, e.g. `-f
+// body=""`, where the RAW command text carries the quote characters rather
+// than the shell having already stripped them). A no-op when the value
+// isn't quote-wrapped.
+function stripQuotedPair(val) {
+  if (val.length >= 2) {
+    const first = val[0];
+    const last = val[val.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return val.slice(1, -1);
+    }
+  }
+  return val;
+}
+
+// Resolve the body for a `gh issue edit` / `gh pr edit` command. Returns:
+//   undefined -> no body param present at all (not a body-carrying write)
+//   { body: string } -> known body text
+//   { body: null }   -> a body param IS present but its text is unknowable
+//                        (shell expansion, stdin/process-substitution path,
+//                        or an unreadable --body-file): never block on this.
+function resolveEditBody(cmd) {
+  // --body-file <path> / its short alias -F (quoted or bare; bare stops at
+  // whitespace/shell metacharacters, same tokenizer approach as
+  // secret-guard's bodyFileText). The `(?<![-\w])` guard on -F mirrors
+  // secret-guard's bodyFileText: it stops -F matching when embedded inside
+  // a longer token, and keeps --body-file from being double-matched.
+  const fileMatch = cmd.match(
+    /(?:--body-file|(?<![-\w])-F)(?:=|\s+)(?:"([^"]+)"|'([^']+)'|([^\s"';|&()<>`]+))/
+  );
+  if (fileMatch) {
+    const p = fileMatch[1] || fileMatch[2] || fileMatch[3];
+    if (p === '-' || p.startsWith('<')) return { body: null }; // stdin / process substitution
+    try {
+      return { body: readBodyFile(p) };
+    } catch {
+      return { body: null }; // unreadable: unknowable, not provably empty
+    }
+  }
+
+  // Inline --body <val> / --body=<val> / its short alias -b, quoted or
+  // bare. The `(?<![-\w])` guard on -b keeps it from matching the "-b"
+  // that appears inside "--body" itself.
+  const inlineMatch = cmd.match(
+    /(?:--body|(?<![-\w])-b)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S*))/
+  );
+  if (inlineMatch) {
+    const val =
+      inlineMatch[1] !== undefined
+        ? inlineMatch[1]
+        : inlineMatch[2] !== undefined
+        ? inlineMatch[2]
+        : inlineMatch[3];
+    if (val === undefined) return { body: null };
+    if (isShellExpansion(val)) return { body: null };
+    return { body: val };
+  }
+
+  return undefined; // no body param at all
+}
+
+// Resolve the body for a `gh api ... -f/-F/--field/--raw-field body=<val>`
+// write. Called only once the caller has already confirmed a `body=` field
+// is present, so a null return here always means "unknowable", never
+// "absent". Handles gh's `@<path>` file-reference form (`@-` is stdin, so
+// unknowable) and a bare value carrying literal surrounding quotes (e.g.
+// `-f body=""`, where the shell hasn't run yet so the quote characters are
+// still in the raw command text).
+function resolveApiBody(cmd) {
+  let raw;
+  let m = cmd.match(/(?:-f|-F|--field|--raw-field)\s+"body=([^"]*)"/);
+  if (m) raw = m[1];
+  if (raw === undefined) {
+    m = cmd.match(/(?:-f|-F|--field|--raw-field)\s+'body=([^']*)'/);
+    if (m) raw = m[1];
+  }
+  if (raw === undefined) {
+    m = cmd.match(/(?:-f|-F|--field|--raw-field)\s+body=(\S*)/);
+    if (m) raw = m[1];
+  }
+  if (raw === undefined) return null;
+
+  const val = stripQuotedPair(raw);
+
+  if (val.startsWith('@')) {
+    const ref = val.slice(1);
+    if (ref === '-') return null; // @- : stdin, unknowable
+    try {
+      return readBodyFile(ref);
+    } catch {
+      return null; // unreadable: unknowable, not provably empty
+    }
+  }
+
+  if (isShellExpansion(val)) return null;
+  return val;
+}
+
+// Is this a `gh` write that would CLOBBER an issue/PR body (the
+// read-modify-write overwrite shape), and if so what would it write?
+// Returns { kind, body } or null. `kind` is 'issue' | 'pr' | 'api'; `body` is
+// the resolved text (string), or null when present-but-unknowable. Only
+// `gh issue edit` / `gh pr edit` / `gh api ... body=` are recognised: `create`
+// and `comment` add new content rather than overwrite an existing body, so
+// they are out of scope for this guard.
+function ghBodyWrite(cmd) {
+  const parsed = parseGhSubcommand(cmd);
+  if (!parsed) return null;
+  const { sub, verb } = parsed;
+
+  if ((sub === 'issue' || sub === 'pr') && verb === 'edit') {
+    const resolved = resolveEditBody(cmd);
+    if (resolved === undefined) return null; // no body param: not this guard's concern
+    return { kind: sub, body: resolved.body };
+  }
+  if (sub === 'api' && /(?:^|\s)(?:-f|-F|--field|--raw-field)\s+['"]?body=/.test(cmd)) {
+    return { kind: 'api', body: resolveApiBody(cmd) };
+  }
+  return null;
+}
+
+function block(kind) {
+  const label = kind === 'api' ? 'GitHub API write' : `gh ${kind} edit`;
+  process.stdout.write(
+    JSON.stringify({
+      decision: 'block',
+      code: 'EMPTY_ISSUE_BODY_WRITE',
+      reason:
+        `trailhead: this ${label} would set an EMPTY issue body, overwriting the existing one. ` +
+        'A trailhead body is never legitimately empty, so this usually means a read-modify-write whose ' +
+        'pre-write read returned an empty or degraded body (e.g. a transient HTTP 5xx on `gh issue view --json body`). ' +
+        'Aborting to protect the existing body: re-read the current body (treat a non-200 or empty read as a hard ' +
+        'error, retry once with backoff), rebuild it, then write again.',
+    })
+  );
+  process.exit(2);
+}
+
+function run(data) {
+  try {
+    let cmd = '';
+    try {
+      cmd = (JSON.parse(data).tool_input || {}).command || '';
+    } catch {
+      process.exit(0); // unparseable input: nothing meaningful to say
+    }
+    const hit = ghBodyWrite(cmd);
+    if (!hit || hit.body === null || hit.body === undefined) {
+      process.exit(0); // not a body write, or a body we cannot prove empty
+    }
+    if (isEmptyBody(hit.body)) {
+      block(hit.kind);
+    }
+    process.exit(0);
+  } catch {
+    process.exit(0); // never let a crash here block a legitimate write
+  }
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends → give up (no write identified)
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { ghBodyWrite, isEmptyBody, resolveEditBody, resolveApiBody };

package/plugins/trailhead/hooks/trailhead-body-guard.test.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// Tests for trailhead-body-guard.js. Run: node trailhead-body-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const HOOK = path.join(__dirname, 'trailhead-body-guard.js');
+const { ghBodyWrite, isEmptyBody } = require('./trailhead-body-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe tool_input JSON on stdin, capture {code, out}.
+function runHook(command, env = {}) {
+  const input = JSON.stringify({ tool_input: { command } });
+  try {
+    const out = execFileSync('node', [HOOK], { input, env: { ...process.env, ...env } });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- unit: ghBodyWrite() recognition ---
+{
+  const tmp = path.join(os.tmpdir(), `bg-file-${process.pid}.md`);
+  fs.writeFileSync(tmp, 'hello there\n');
+  const r1 = ghBodyWrite(`gh issue edit 5 --body-file ${tmp}`);
+  ok('recognizes gh issue edit --body-file', r1 && r1.kind === 'issue' && r1.body === 'hello there\n');
+  fs.unlinkSync(tmp);
+}
+ok('recognizes gh issue edit --body (inline)',
+  (() => { const r = ghBodyWrite('gh issue edit 5 --body "hi"'); return r && r.kind === 'issue' && r.body === 'hi'; })());
+ok('recognizes gh pr edit --body "" (empty inline)',
+  (() => { const r = ghBodyWrite('gh pr edit 5 --body ""'); return r && r.kind === 'pr' && r.body === ''; })());
+ok('recognizes gh api ... -f body=foo',
+  (() => { const r = ghBodyWrite('gh api --method PATCH repos/o/r/issues/5 -f body=foo'); return r && r.kind === 'api' && r.body === 'foo'; })());
+ok('recognizes the -R o/r global-flag form',
+  (() => { const r = ghBodyWrite('gh -R owner/repo issue edit 5 --body "hi"'); return r && r.kind === 'issue' && r.body === 'hi'; })());
+// Regression (#153): an unknown two-token global flag (e.g. --hostname h)
+// before the subcommand must not desync the walk and hide the write.
+ok('recognizes gh issue edit behind an unknown two-token global flag (--hostname h)',
+  (() => { const r = ghBodyWrite('gh --hostname h issue edit 5 --body ""'); return r && r.kind === 'issue' && r.body === ''; })());
+ok('recognizes gh pr edit behind an unknown two-token global flag (--hostname h)',
+  (() => { const r = ghBodyWrite('gh --hostname h pr edit 5 --body ""'); return r && r.kind === 'pr' && r.body === ''; })());
+// Regression (#153 follow-up): a two-token global flag whose VALUE literally
+// equals a subcommand keyword (`api`) must still resolve the real `issue
+// edit` write.
+ok('recognizes gh issue edit behind a keyword-valued two-token global flag (--hostname api)',
+  (() => { const r = ghBodyWrite('gh --hostname api issue edit 5 --body ""'); return r && r.kind === 'issue' && r.body === ''; })());
+// Regression (#153 second follow-up): an unknown BOOLEAN flag directly
+// before the subcommand must not swallow the subcommand as its own value.
+ok('recognizes gh issue edit behind an unknown boolean flag (--foo)',
+  (() => { const r = ghBodyWrite('gh --foo issue edit 5 --body ""'); return r && r.kind === 'issue' && r.body === ''; })());
+
+// --- unit: ghBodyWrite() non-matches ---
+ok('ignores gh issue edit with no body param',
+  ghBodyWrite('gh issue edit 5 --add-label x') === null);
+ok('ignores gh issue comment (excluded verb)',
+  ghBodyWrite('gh issue comment 5 --body "hi"') === null);
+ok('ignores gh issue create (excluded verb)',
+  ghBodyWrite('gh issue create --title t --body-file /tmp/x') === null);
+ok('ignores non-gh commands',
+  ghBodyWrite('echo --body ""') === null);
+
+// --- unit: unknowable bodies are not blockable ---
+{
+  const r = ghBodyWrite('gh issue edit 5 --body "$(cat f)"');
+  ok('a shell-expansion inline body is unknowable (not blockable)', r && r.kind === 'issue' && r.body === null);
+}
+{
+  const r = ghBodyWrite('gh issue edit 5 --body-file -');
+  ok('a --body-file - (stdin) body is unknowable (not blockable)', r && r.kind === 'issue' && r.body === null);
+}
+{
+  const r = ghBodyWrite('gh issue edit 5 --body-file /no/such/file/does-not-exist.md');
+  ok('a --body-file whose read throws is unknowable (not blockable)', r && r.kind === 'issue' && r.body === null);
+}
+
+// --- unit: isEmptyBody() ---
+ok("isEmptyBody('') is true", isEmptyBody('') === true);
+ok("isEmptyBody('   \\n\\t ') is true", isEmptyBody('   \n\t ') === true);
+ok("isEmptyBody('x') is false", isEmptyBody('x') === false);
+ok("isEmptyBody(' a ') is false", isEmptyBody(' a ') === false);
+
+// --- end-to-end: block ---
+const b1 = runHook('gh issue edit 5 --body ""');
+ok('blocks an empty inline --body (exit 2)', b1.code === 2 && /"decision":"block"/.test(b1.out) && /EMPTY_ISSUE_BODY_WRITE/.test(b1.out));
+
+// Regression (#153): the same block must fire when an unknown two-token
+// global flag (e.g. --hostname h) sits before the subcommand.
+const bHost1 = runHook('gh --hostname h issue edit 5 --body ""');
+ok('blocks an empty --body behind an unknown two-token global flag (issue edit, exit 2)',
+  bHost1.code === 2 && /"decision":"block"/.test(bHost1.out) && /EMPTY_ISSUE_BODY_WRITE/.test(bHost1.out));
+const bHost2 = runHook('gh --hostname h pr edit 5 --body ""');
+ok('blocks an empty --body behind an unknown two-token global flag (pr edit, exit 2)',
+  bHost2.code === 2 && /"decision":"block"/.test(bHost2.out) && /EMPTY_ISSUE_BODY_WRITE/.test(bHost2.out));
+
+// Regression (#153 follow-up): a two-token global flag whose VALUE literally
+// equals a subcommand keyword (`api`) must still block the real `issue edit`
+// empty-body write end to end.
+const bHost3 = runHook('gh --hostname api issue edit 5 --body ""');
+ok('blocks an empty --body behind a keyword-valued two-token global flag (--hostname api, exit 2)',
+  bHost3.code === 2 && /"decision":"block"/.test(bHost3.out) && /EMPTY_ISSUE_BODY_WRITE/.test(bHost3.out));
+
+// Regression (#153 second follow-up): an unknown BOOLEAN flag before the
+// subcommand must not hide the write by swallowing the subcommand itself.
+const bFoo = runHook('gh --foo issue edit 5 --body ""');
+ok('blocks an empty --body behind an unknown boolean flag (--foo, exit 2)',
+  bFoo.code === 2 && /"decision":"block"/.test(bFoo.out) && /EMPTY_ISSUE_BODY_WRITE/.test(bFoo.out));
+
+{
+  const empty = path.join(os.tmpdir(), `bg-empty-${process.pid}.md`);
+  fs.writeFileSync(empty, '');
+  const b2 = runHook(`gh issue edit 5 --body-file ${empty}`);
+  ok('blocks an empty --body-file (exit 2)', b2.code === 2 && /"decision":"block"/.test(b2.out));
+  fs.unlinkSync(empty);
+}
+
+{
+  const whitespace = path.join(os.tmpdir(), `bg-ws-${process.pid}.md`);
+  fs.writeFileSync(whitespace, '   \n\t \n');
+  const b3 = runHook(`gh pr edit 5 --body-file ${whitespace}`);
+  ok('blocks a whitespace-only --body-file (exit 2)', b3.code === 2 && /"decision":"block"/.test(b3.out));
+  fs.unlinkSync(whitespace);
+}
+
+const b4 = runHook('gh api --method PATCH repos/o/r/issues/5 -f body=');
+ok('blocks an empty gh api body= (exit 2)', b4.code === 2 && /"decision":"block"/.test(b4.out));
+
+// --- end-to-end: block via short flags (-b / -F, gh's documented aliases) ---
+const b5 = runHook('gh issue edit 5 -b ""');
+ok('blocks an empty short -b (issue edit, exit 2)', b5.code === 2 && /"decision":"block"/.test(b5.out));
+
+const b6 = runHook('gh pr edit 5 -b ""');
+ok('blocks an empty short -b (pr edit, exit 2)', b6.code === 2 && /"decision":"block"/.test(b6.out));
+
+{
+  const shortEmpty = path.join(os.tmpdir(), `bg-short-empty-${process.pid}.md`);
+  fs.writeFileSync(shortEmpty, '');
+  const b7 = runHook(`gh issue edit 5 -F ${shortEmpty}`);
+  ok('blocks an empty short -F body-file (exit 2)', b7.code === 2 && /"decision":"block"/.test(b7.out));
+  fs.unlinkSync(shortEmpty);
+}
+
+const a5 = runHook('gh issue edit 5 -b "real content"');
+ok('allows a non-empty short -b (exit 0)', a5.code === 0 && a5.out.trim() === '');
+
+// --- unit: ghBodyWrite() recognizes short flags directly ---
+ok('ghBodyWrite recognizes -b (issue edit)',
+  (() => { const r = ghBodyWrite('gh issue edit 5 -b "hi"'); return r && r.kind === 'issue' && r.body === 'hi'; })());
+{
+  const tmp = path.join(os.tmpdir(), `bg-shortfile-${process.pid}.md`);
+  fs.writeFileSync(tmp, 'content\n');
+  const r = ghBodyWrite(`gh pr edit 5 -F ${tmp}`);
+  ok('ghBodyWrite recognizes -F (pr edit)', r && r.kind === 'pr' && r.body === 'content\n');
+  fs.unlinkSync(tmp);
+}
+// -b must not accidentally match the "-b" inside "--body" itself.
+ok('ghBodyWrite still resolves --body correctly alongside the -b alias',
+  (() => { const r = ghBodyWrite('gh issue edit 5 --body "hi"'); return r && r.kind === 'issue' && r.body === 'hi'; })());
+
+// --- end-to-end: block via gh api empty-body forms ---
+const b8 = runHook('gh api --method PATCH repos/o/r/issues/5 -f body=""');
+ok('blocks gh api -f body="" (literal empty double-quotes, exit 2)', b8.code === 2 && /"decision":"block"/.test(b8.out));
+
+const b9 = runHook("gh api --method PATCH repos/o/r/issues/5 -f body=''");
+ok("blocks gh api -f body='' (literal empty single-quotes, exit 2)", b9.code === 2 && /"decision":"block"/.test(b9.out));
+
+{
+  const apiEmpty = path.join(os.tmpdir(), `bg-api-empty-${process.pid}.md`);
+  fs.writeFileSync(apiEmpty, '');
+  const b10 = runHook(`gh api --method PATCH repos/o/r/issues/5 -F body=@${apiEmpty}`);
+  ok('blocks gh api -F body=@<empty file> (exit 2)', b10.code === 2 && /"decision":"block"/.test(b10.out));
+  fs.unlinkSync(apiEmpty);
+}
+
+const a6 = runHook('gh api --method PATCH repos/o/r/issues/5 -F body=@-');
+ok('allows gh api -F body=@- (stdin, unknowable, exit 0)', a6.code === 0 && a6.out.trim() === '');
+
+{
+  const apiFull = path.join(os.tmpdir(), `bg-api-full-${process.pid}.md`);
+  fs.writeFileSync(apiFull, 'real content\n');
+  const a7 = runHook(`gh api --method PATCH repos/o/r/issues/5 -f body=@${apiFull}`);
+  ok('allows a non-empty gh api -f body=@<file> (exit 0)', a7.code === 0 && a7.out.trim() === '');
+  fs.unlinkSync(apiFull);
+}
+
+// --- end-to-end: block via ~-expanded --body-file (fs.readFileSync does not expand ~) ---
+{
+  const homeRel = `.bg-tilde-test-${process.pid}.md`;
+  const homeAbs = path.join(os.homedir(), homeRel);
+  fs.writeFileSync(homeAbs, '');
+  const b11 = runHook(`gh issue edit 5 --body-file ~/${homeRel}`);
+  ok('blocks an empty ~/-prefixed --body-file (exit 2)', b11.code === 2 && /"decision":"block"/.test(b11.out));
+  fs.unlinkSync(homeAbs);
+}
+
+// --- end-to-end: allow ---
+const a1 = runHook('gh issue edit 5 --body "not empty"');
+ok('allows a non-empty body write (exit 0, no output)', a1.code === 0 && a1.out.trim() === '');
+const a2 = runHook('gh issue view 5 --json body'); // read, not a write
+ok('allows a read (exit 0)', a2.code === 0 && a2.out.trim() === '');
+const a3 = runHook('gh issue comment 5 --body ""'); // excluded verb, even though empty
+ok('allows an empty gh issue comment (excluded verb, exit 0)', a3.code === 0 && a3.out.trim() === '');
+const a4 = runHook('gh issue edit 5 --body "$(cat f)"'); // unknowable, can't prove empty
+ok('allows an unknowable (shell-expansion) body (exit 0)', a4.code === 0 && a4.out.trim() === '');
+
+// --- crash-safety ---
+try {
+  execFileSync('node', [HOOK], { input: 'not json at all {{{' });
+  ok('unparseable stdin does not throw (exit 0)', true);
+} catch (e) {
+  ok('unparseable stdin exits 0', e.status === 0);
+}
+const c2 = runHook('gh issue edit 5 --add-label x'); // non-body gh command
+ok('a non-body gh command exits 0', c2.code === 0 && c2.out.trim() === '');
+
+console.log(`✓ body-guard: ${passed} assertions passed`);