@marcomigozzi/trailhead 0.13.0 → 0.14.0

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

@@ -7,8 +7,9 @@ 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');
+// TRAILHEAD_GUARD_HOOK re-runs this suite through the merged trailhead-bash-guards.js.
+const HOOK = process.env.TRAILHEAD_GUARD_HOOK || path.join(__dirname, 'trailhead-body-guard.js');
+const { ghBodyWrite, isEmptyBody, evaluate } = require('./trailhead-body-guard.js');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
@@ -87,6 +88,10 @@ ok("isEmptyBody('x') is false", isEmptyBody('x') === false);
 ok("isEmptyBody(' a ') is false", isEmptyBody(' a ') === false);
 
 // --- end-to-end: block ---
+// #219: a quoted command word or subcommand is the same word for bash.
+const bQuoted = runHook('gh "issue" edit 5 --body ""');
+ok('blocks an empty --body behind a quoted subcommand (#219)', bQuoted.code === 2 && /EMPTY_ISSUE_BODY_WRITE/.test(bQuoted.out));
+
 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));
 
@@ -206,9 +211,144 @@ 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
+// The merged runner also runs the secret-guard, which resolves `$(cat <path>)`: point it at a real clean file.
+const a4File = path.join(os.tmpdir(), `bg-subst-${process.pid}.md`);
+fs.writeFileSync(a4File, 'not empty\n');
+const a4 = runHook(`gh issue edit 5 --body "$(cat ${a4File})"`); // unknowable, can't prove empty
+fs.unlinkSync(a4File);
 ok('allows an unknowable (shell-expansion) body (exit 0)', a4.code === 0 && a4.out.trim() === '');
 
+// --- regression (#211): an empty-body write chained after another command ---
+const isBlock = (r) => r.code === 2 && /"decision":"block"/.test(r.out) && /EMPTY_ISSUE_BODY_WRITE/.test(r.out);
+const isAllow = (r) => r.code === 0 && r.out.trim() === '';
+ok('blocks an empty --body chained after cd (exit 2)', isBlock(runHook('cd /tmp && gh issue edit 5 --body ""')));
+ok('blocks an empty --body after a variable assignment (exit 2)', isBlock(runHook('D=x && gh issue edit 5 --body ""')));
+ok('blocks an empty --body inside a subshell (exit 2)', isBlock(runHook('( gh issue edit 5 --body "" )')));
+ok('blocks an empty --body inside if/then (exit 2)', isBlock(runHook('if true; then gh issue edit 5 --body ""; fi')));
+ok('blocks an empty write that is a LATER statement after a non-empty one (exit 2)',
+  isBlock(runHook('gh issue edit 5 --body "x"; gh issue edit 6 --body ""')));
+ok('blocks a chained gh api -f body="" after cd (exit 2)',
+  isBlock(runHook('cd /tmp && gh api --method PATCH repos/o/r/issues/5 -f body=""')));
+ok('allows a chained non-empty body (exit 0)', isAllow(runHook('cd /tmp && gh issue edit 5 --body "x"')));
+ok('allows a chained empty gh issue comment (out of scope, exit 0)',
+  isAllow(runHook('cd /tmp && gh issue comment 5 --body ""')));
+ok('allows a chained empty gh issue create (out of scope, exit 0)',
+  isAllow(runHook('cd /tmp && gh issue create --title t --body ""')));
+{
+  // After a cd the working directory is unknown: a relative path cannot be proven empty.
+  const relName = `bg-rel-${process.pid}.md`;
+  fs.writeFileSync(path.join(process.cwd(), relName), '');
+  // evaluate() directly: the merged runner's secret-guard has its own (separate) block for this shape.
+  ok('allows a RELATIVE --body-file after cd (unknowable)',
+    evaluate(`cd /tmp && gh issue edit 5 --body-file ${relName}`).kind === 'allow');
+  ok('allows a RELATIVE api body=@path after cd (unknowable)',
+    evaluate(`cd /tmp && gh api --method PATCH repos/o/r/issues/5 -F body=@${relName}`).kind === 'allow');
+  ok('blocks the same RELATIVE --body-file when no cd precedes it',
+    evaluate(`gh issue edit 5 --body-file ${relName}`).kind === 'block');
+  fs.unlinkSync(path.join(process.cwd(), relName));
+  const absEmpty = path.join(os.tmpdir(), `bg-abs-empty-${process.pid}.md`);
+  fs.writeFileSync(absEmpty, '');
+  ok('blocks an ABSOLUTE empty --body-file after cd (exit 2)',
+    isBlock(runHook(`cd /tmp && gh issue edit 5 --body-file ${absEmpty}`)));
+  fs.unlinkSync(absEmpty);
+}
+
+{
+  // Partial install (no secret-guard next to the hook): the leading write still blocks.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bg-partial-'));
+  fs.mkdirSync(path.join(dir, 'lib'));
+  fs.copyFileSync(path.join(__dirname, 'trailhead-body-guard.js'), path.join(dir, 'trailhead-body-guard.js'));
+  fs.copyFileSync(path.join(__dirname, 'lib', 'gh-subcommand.js'), path.join(dir, 'lib', 'gh-subcommand.js'));
+  fs.copyFileSync(path.join(__dirname, 'lib', 'body-sources.js'), path.join(dir, 'lib', 'body-sources.js'));
+  const partial = require(path.join(dir, 'trailhead-body-guard.js'));
+  ok('without secret-guard, a leading empty --body still blocks',
+    partial.evaluate('gh issue edit 5 --body ""').kind === 'block');
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --- regression (#213): repeated / mixed body flags resolve like gh (pflag keeps the LAST) ---
+{
+  const blk = (c) => evaluate(c).kind === 'block';
+  const alw = (c) => evaluate(c).kind === 'allow';
+  for (const sub of ['issue', 'pr']) {
+    const g = `gh ${sub} edit 5`;
+    ok(`#213 ${sub}: blocks --body "x" --body ""`, blk(`${g} --body "x" --body ""`));
+    ok(`#213 ${sub}: blocks --body=x --body=`, blk(`${g} --body=x --body=`));
+    ok(`#213 ${sub}: blocks -b "x" --body ""`, blk(`${g} -b "x" --body ""`));
+    ok(`#213 ${sub}: blocks -b "x" -b ""`, blk(`${g} -b "x" -b ""`));
+    ok(`#213 ${sub}: allows --body "" --body "x"`, alw(`${g} --body "" --body "x"`));
+    ok(`#213 ${sub}: allows --body= --body=x`, alw(`${g} --body= --body=x`));
+    ok(`#213 ${sub}: allows --body "" -b "x"`, alw(`${g} --body "" -b "x"`));
+    ok(`#213 ${sub}: allows --body '' --body 'x'`, alw(`${g} --body '' --body 'x'`));
+  }
+  const g = 'gh issue edit 5';
+  ok('#213 blocks --body "x" --body "   "', blk(`${g} --body "x" --body "   "`));
+  ok('#213 blocks an attached -b""', blk(`${g} -b""`));
+  ok('#213 allows --body "" --body "$(cat f)" (unknowable last)', alw(`${g} --body "" --body "$(cat f)"`));
+  ok('#213 allows --body "" --body $B (unknowable last)', alw(`${g} --body "" --body $B`));
+  ok('#213 allows --body "" --body-file /dev/null (gh mutual-exclusion error)', alw(`${g} --body "" --body-file /dev/null`));
+  ok('#213 allows --body "x" --body-file /dev/null (gh mutual-exclusion error)', alw(`${g} --body "x" --body-file /dev/null`));
+  ok('#213 allows --body "x" --body-file "" (empty file flag = absent)', alw(`${g} --body "x" --body-file ""`));
+  ok('#213 blocks --body "" --body-file "" (empty file flag = absent)', blk(`${g} --body "" --body-file ""`));
+  const full = path.join(os.tmpdir(), `bg-213-full-${process.pid}.md`);
+  fs.writeFileSync(full, 'real content\n');
+  ok('#213 blocks --body-file <full> --body-file /dev/null (last wins)', blk(`${g} --body-file ${full} --body-file /dev/null`));
+  ok('#213 allows --body-file /dev/null --body-file <full> (last wins)', alw(`${g} --body-file /dev/null --body-file ${full}`));
+  fs.unlinkSync(full);
+  ok('#213 per statement: blocks a later repeated-flag empty write',
+    blk('gh issue edit 5 --body "x" --body ""; gh issue edit 6 --body "x"'));
+  ok('#213 per statement: allows when the last --body of each statement is non-empty',
+    alw('gh issue edit 5 --body "" --body "x"; gh issue edit 6 --body "ok"'));
+}
+
+// --- regression (#213 review): backslash-newline continuations, stdin-like body files ---
+{
+  const blk = (c) => evaluate(c).kind === 'block';
+  const alw = (c) => evaluate(c).kind === 'allow';
+  const { words } = require('./lib/body-sources.js');
+  ok('words: unindented continuation joins (a\\<nl>b -> ab)', JSON.stringify(words('a\\\nb')) === '["ab"]');
+  ok('words: spaced continuation keeps two words', JSON.stringify(words('a \\\nb')) === '["a","b"]');
+  ok('words: continuation inside double quotes is removed', JSON.stringify(words('"a\\\nb"')) === JSON.stringify(['"ab"']));
+  ok('words: continuation inside single quotes is literal', JSON.stringify(words("'a\\\nb'")) === JSON.stringify(["'a\\\nb'"]));
+  ok('#213 blocks --title t \\<nl>--body ""', blk('gh issue edit 5 --title t \\\n--body ""'));
+  ok('#213 blocks edit 5 \\<nl>--body ""', blk('gh issue edit 5 \\\n--body ""'));
+  ok('#213 blocks --body "x" \\<nl>--body ""', blk('gh issue edit 5 --body "x" \\\n--body ""'));
+  ok('#213 allows --body "" \\<nl>--body "x"', alw('gh issue edit 5 --body "" \\\n--body "x"'));
+  for (const f of ['/dev/stdin', '/dev/fd/0', '/proc/self/fd/0', '-']) {
+    const r = ghBodyWrite(`gh issue edit 5 --body-file ${f}`);
+    ok(`#213 --body-file ${f} is unknowable`, r && r.body === null);
+  }
+  // Run only this guard as a real hook process behind a shell pipe (stdin is a consumed pipe, like in production).
+  const bodyGuardOnly = (c) => {
+    try {
+      execFileSync('sh', ['-c', 'printf %s "$TH_IN" | "$TH_NODE" "$TH_HOOK"'], {
+        env: { ...process.env, TH_IN: JSON.stringify({ tool_input: { command: c } }), TH_NODE: process.execPath, TH_HOOK: path.join(__dirname, 'trailhead-body-guard.js') },
+      });
+      return true;
+    } catch { return false; }
+  };
+  ok('#213 negative control: the bodyGuardOnly harness sees a block', !bodyGuardOnly('gh issue edit 5 --body ""'));
+  {
+    // `..` after a symlink resolves in the kernel, not lexically: lnk/s -> real/sub, so lnk/s/../empty.md is real/empty.md.
+    const d = fs.mkdtempSync(path.join(os.tmpdir(), 'bg-213-lnk-'));
+    fs.mkdirSync(path.join(d, 'real', 'sub'), { recursive: true });
+    fs.mkdirSync(path.join(d, 'lnk'));
+    fs.writeFileSync(path.join(d, 'real', 'empty.md'), '');
+    fs.writeFileSync(path.join(d, 'lnk', 'empty.md'), 'not empty\n');
+    fs.symlinkSync(path.join(d, 'real', 'sub'), path.join(d, 'lnk', 's'));
+    ok('#213 blocks a --body-file whose .. follows a symlink (read the raw path)',
+      blk(`gh issue edit 5 --body-file ${d}/lnk/s/../empty.md`));
+    fs.rmSync(d, { recursive: true, force: true });
+  }
+  for (const f of ['/dev//stdin', '/dev/fd//0', '/dev/./stdin']) {
+    ok(`#213 allows --body-file ${f} (non-canonical stdin spelling)`, bodyGuardOnly(`gh issue edit 5 --body-file ${f}`)); // the secret-guard judges these spellings on its own
+  }
+  ok('#213 pins: an escaped backslash before the newline is not a continuation (allows)',
+    alw('gh issue edit 5 --title t \\\\\n--body ""'));
+  ok('#213 pins: backslash CR LF is not a continuation (allows)',
+    alw('gh issue edit 5 --title t \\\r\n--body ""'));
+}
+
 // --- crash-safety ---
 try {
   execFileSync('node', [HOOK], { input: 'not json at all {{{' });
@@ -219,4 +359,85 @@ try {
 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() === '');
 
+// #225: a flag between the subcommand and the verb must not hide the write.
+const bFlagVerb = runHook('gh issue -R o/r edit 5 --body ""');
+ok('blocks an empty --body with a flag before the verb (exit 2)', bFlagVerb.code === 2 && /EMPTY_ISSUE_BODY_WRITE/.test(bFlagVerb.out));
+
+// #227: constructs the guard cannot interpret are blocked, not emulated.
+{
+  const CODE = 'BODY_GUARD_UNMODELLED_CONSTRUCT';
+  const clean = path.join(os.tmpdir(), `bg-um-clean-${process.pid}.md`);
+  fs.writeFileSync(clean, 'A real body.\n');
+  const code = (c) => { const r = runHook(c); return r.code === 2 ? (JSON.parse(r.out).code || '?') : null; };
+
+  // Gaps that used to pass.
+  for (const c of [
+    `gh api -X PATCH repos/o/r/issues/1 -f 'body'=""`,
+    'gh api -X PATCH repos/o/r/issues/1 -f bo""dy=""',
+    'printf -v B %s x; gh issue edit 1 --body "$B"',
+    'source ./x.sh; gh issue edit 1 --body "$B"',
+    'source ./x.sh; gh issue edit 1 --body-file rel.md',
+    '. ./x.sh && gh pr edit 1 --body "$B"',
+    `eval 'gh issue edit 1 --body real'`,
+    'echo ${ gh issue edit 1 --body ""; }',
+    'alias g=gh; g issue edit 1 --body ""',
+    'f() { gh issue edit 1 --body real; }; f',
+    `gh issue ed\\\nit 1 --body real`,
+  // Through the merged runner the secret-guard speaks first on some of these (its own gate); still a block.
+  ]) ok(`blocks an unmodelled construct: ${c.slice(0, 50)}`, code(c) === CODE || (!!process.env.TRAILHEAD_GUARD_HOOK && code(c) !== null));
+
+  // An unknowable body behind a quoted key blocks too (through the merged runner the secret-guard may speak first).
+  ok('a quoted api key with an unknowable body blocks', code('gh api -X PATCH repos/o/r/issues/1 -f b\\ody="$B"') !== null);
+  ok('a quoted api key with an unreadable file blocks', code("gh api -X PATCH repos/o/r/issues/1 -f 'body'=@/nonexistent/bg-um.md") !== null);
+  for (const c of [
+    `printf -v B %s ''; gh issue edit 1 --body "it's $B and 'x'"`,
+    `source x.sh; gh issue edit 1 --body "it's $B and 'x'"`,
+    `printf -v B %s ''; printf %s "$B" | gh issue edit 1 --body-file -`,
+    `printf -v B %s ''; gh issue edit 1 --body-file - <<EOF\n$B\nEOF`,
+  ]) ok(`W2: a state-dependent write after the construct still blocks: ${c.slice(0, 40).replace(/\n/g, ' ')}`, code(c) !== null);
+  for (const c of ["source x; gh issue edit 1 --body 'lit'", 'source x; gh issue edit 1 --body lit', `source x; gh issue edit 1 --body "it's fine"`]) {
+    ok(`W2: a literal write after source passes: ${c}`, runHook(c).code === 0);
+  }
+  ok('the existing empty-body verdict keeps priority', code('source ./x.sh; gh issue edit 1 --body ""') === 'EMPTY_ISSUE_BODY_WRITE' ||
+    (!!process.env.TRAILHEAD_GUARD_HOOK && code('source ./x.sh; gh issue edit 1 --body ""') !== null));
+  ok('an empty body before the construct keeps its verdict', code('gh issue edit 1 --body ""; alias g=gh') === 'EMPTY_ISSUE_BODY_WRITE');
+
+  // Plain controls pass.
+  for (const c of [
+    "alias ll='ls -l'",
+    'alias g=gh',
+    'source ~/.venv/bin/activate && pytest',
+    'eval "$(ssh-agent)"',
+    'eval "$(ssh-agent)"; gh issue edit 1 --body-file ' + clean,
+    'printf -v x %s y; echo $x',
+    `gh issue edit 1 --body-file ${clean}; source ./x.sh`,
+    `. venv/bin/activate && gh issue edit 1 --body 'hello'`,
+    `source venv/bin/activate && gh issue edit 1 --body-file ${clean}`,
+    'f() { gh issue edit 1 --body x; }',
+    `gh issue edit 1 --body 'use eval, source and alias here'`,
+    `gh issue edit 1 --body-file ${clean} # eval x`,
+    `gh issue edit 1 \\\n  --body-file ${clean}`,
+    'gh api -X PATCH repos/o/r/issues/1 -f body=x',
+    `gh api -X PATCH repos/o/r/issues/1 -f 'body'=real`, // a known, non-empty body is read like the plain form
+    `gh api -X PATCH repos/o/r/issues/1 -f 'body'=@${clean}`,
+    'gh api -X PATCH repos/o/r/issues/1 -f "body=x"',
+    `gh api -X PATCH repos/o/r/issues/1 -F title=x`,
+  ]) ok(`passes a plain form: ${c.slice(0, 50)}`, runHook(c).code === 0);
+
+  // Not a body-guard concern (a comment adds text, it overwrites nothing); the merged runner's
+  // secret-guard may block these for its own reasons, so only the standalone guard is checked.
+  if (!process.env.TRAILHEAD_GUARD_HOOK) {
+    for (const c of [
+      'alias g=gh; g issue comment 1 --body x',
+      'printf -v B %s x; gh issue comment 1 --body "$B"',
+      `source ./x.sh; gh issue comment 1 --body-file ${clean}`,
+    ]) ok(`passes a non-overwriting write: ${c.slice(0, 50)}`, runHook(c).code === 0);
+  }
+
+  const r = runHook(`gh api -X PATCH repos/o/r/issues/1 -f 'body'=""`);
+  const reason = JSON.parse(r.out).reason;
+  ok('the message names the guard and asks for the simple form', /^trailhead body-guard: /.test(reason) && /Rewrite it in a simple form/.test(reason));
+  fs.rmSync(clean);
+}
+
 console.log(`✓ body-guard: ${passed} assertions passed`);

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

@@ -5,15 +5,17 @@
 //   2. Conventional Commits subject: <type>(<scope>)?: <subject>, <=72 chars.
 // Blocks with exit 2 + {"decision":"block","reason":...}; allows everything else.
 // Crash-safe: any error → exit 0 (never wedge the user's workflow).
-// Self-contained, no dependencies.
+// Self-contained, no dependencies. Exports a pure evaluate(cmd) so the merged
+// trailhead-bash-guards.js can run it in-process; run directly it is unchanged.
 
 const { checkCommitMessage } = require('./lib/commit-message-check.js');
 
 const CO_AUTHORED = /co-authored-by\s*:/i;
 
-function block(code, reason) {
-  process.stdout.write(JSON.stringify({ decision: 'block', code, reason }));
-  process.exit(2);
+const ALLOW = { kind: 'allow' };
+
+function blockVerdict(code, reason) {
+  return { kind: 'block', payload: { decision: 'block', code, reason } };
 }
 
 // Token-walk: is this shell string a `git commit …`? Handles env-var prefixes
@@ -50,18 +52,15 @@ function extractMessage(cmd) {
   return null;
 }
 
-let data = '';
-const timer = setTimeout(() => process.exit(0), 5000);
-process.stdin.on('data', (c) => (data += c));
-process.stdin.on('end', () => {
-  clearTimeout(timer);
+// Pure verdict for one command: {kind:'allow'} or {kind:'block', payload}. Never
+// exits or writes; any internal error falls through to allow (crash-safe).
+function evaluate(cmd) {
   try {
-    const cmd = (JSON.parse(data).tool_input || {}).command || '';
-    if (!isGitCommit(cmd)) process.exit(0);
+    if (!isGitCommit(cmd)) return ALLOW;
 
     // Co-Authored-By anywhere in the command (covers -m, -F, heredocs).
     if (CO_AUTHORED.test(cmd)) {
-      block('CO_AUTHORED_BY_FORBIDDEN',
+      return blockVerdict('CO_AUTHORED_BY_FORBIDDEN',
         'trailhead: do not add a Co-Authored-By trailer to commits. Remove it and commit again.');
     }
 
@@ -71,10 +70,38 @@ process.stdin.on('end', () => {
       // `#` lines as message text (cleanup=whitespace), so a `#…` first line is
       // a real subject to validate, not a comment to skip.
       const verdict = checkCommitMessage(msg, { stripComments: false });
-      if (!verdict.ok) block(verdict.code, verdict.reason);
+      if (!verdict.ok) return blockVerdict(verdict.code, verdict.reason);
     }
   } catch {
     // fall through to allow
   }
+  return ALLOW;
+}
+
+// Standalone CLI: write the payload and exit exactly as the guard always did.
+function run(data) {
+  let cmd = '';
+  try {
+    cmd = (JSON.parse(data).tool_input || {}).command || '';
+  } catch {
+    process.exit(0);
+  }
+  const v = evaluate(cmd);
+  if (v.kind === 'block') {
+    process.stdout.write(JSON.stringify(v.payload));
+    process.exit(2);
+  }
   process.exit(0);
-});
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000);
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { evaluate };

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

@@ -5,7 +5,8 @@ const assert = require('assert');
 const { execFileSync } = require('child_process');
 const path = require('path');
 
-const HOOK = path.join(__dirname, 'trailhead-commit-guard.js');
+// TRAILHEAD_GUARD_HOOK re-runs this suite through the merged trailhead-bash-guards.js.
+const HOOK = process.env.TRAILHEAD_GUARD_HOOK || path.join(__dirname, 'trailhead-commit-guard.js');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };

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

@@ -13,8 +13,8 @@
 // and local paths / URLs / VCS refs carry no typed name and pass through.
 // Blocks with exit 2 + {"decision":"block",...}; allows everything else.
 // Crash-safe: any error → exit 0 (never wedge the user's workflow).
-// Self-contained, no dependencies. Pure functions exported for tests; runs as a
-// hook when executed directly.
+// Self-contained, no dependencies. Pure functions (incl. evaluate) exported for tests
+// and the merged trailhead-bash-guards.js; runs as a hook when executed directly.
 
 const SENTINEL = /(?:^|\s)TRAILHEAD_VERIFIED_INSTALL=1(?:\s|$)/;
 
@@ -133,7 +133,7 @@ function isVerified(cmd) {
   return SENTINEL.test(String(cmd));
 }
 
-function block(hit) {
+function blockVerdict(hit) {
   const list = hit.packages.join(', ');
   const reason =
     `trailhead: this ${hit.ecosystem} install names package(s) not yet vetted (${list}). ` +
@@ -142,8 +142,20 @@ function block(hit) {
     'and repository metadata (present and matching). ' +
     'STOP and ask the human on anything suspicious (block-and-ask): do not install on your own judgement. ' +
     'Once vetted, re-run the exact command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1` to proceed.';
-  process.stdout.write(JSON.stringify({ decision: 'block', code: 'UNVETTED_PACKAGE_INSTALL', reason }));
-  process.exit(2);
+  return { kind: 'block', payload: { decision: 'block', code: 'UNVETTED_PACKAGE_INSTALL', reason } };
+}
+
+// Pure verdict for one command: {kind:'allow'} or {kind:'block', payload}. Never
+// exits or writes; any internal error falls through to allow.
+function evaluate(cmd) {
+  try {
+    if (isVerified(cmd)) return { kind: 'allow' }; // agent has vetted these
+    const hit = detectInstall(cmd);
+    if (hit) return blockVerdict(hit);
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  return { kind: 'allow' };
 }
 
 function run(data) {
@@ -153,12 +165,10 @@ function run(data) {
   } catch {
     process.exit(0); // unparseable input: nothing to gate
   }
-  try {
-    if (isVerified(cmd)) process.exit(0); // agent has vetted these
-    const hit = detectInstall(cmd);
-    if (hit) block(hit);
-  } catch {
-    // fall through to allow: a guard must never wedge the workflow
+  const v = evaluate(cmd);
+  if (v.kind === 'block') {
+    process.stdout.write(JSON.stringify(v.payload));
+    process.exit(2);
   }
   process.exit(0);
 }
@@ -173,4 +183,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { detectInstall, isVerified };
+module.exports = { detectInstall, isVerified, evaluate };

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

@@ -5,7 +5,8 @@ const assert = require('assert');
 const { execFileSync } = require('child_process');
 const path = require('path');
 
-const HOOK = path.join(__dirname, 'trailhead-install-guard.js');
+// TRAILHEAD_GUARD_HOOK re-runs this suite through the merged trailhead-bash-guards.js.
+const HOOK = process.env.TRAILHEAD_GUARD_HOOK || path.join(__dirname, 'trailhead-install-guard.js');
 const { detectInstall, isVerified } = require('./trailhead-install-guard.js');
 
 let passed = 0;

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.js

@@ -7,7 +7,14 @@
 // practice (an approval asked with only the project's name, no URL), so this
 // hook blocks an AskUserQuestion that is a mockup-approval ask when the
 // assistant prose immediately before it (no tool call in between) holds no
-// URL or file path.
+// URL or file path. A link carried by the approval question itself (question,
+// header, option label or description) is accepted too.
+// Transcript timing: Claude Code writes the CURRENT assistant message (its
+// text and tool_use blocks) to the transcript only after the tool call
+// completes, so at PreToolUse the prose carrying the link is usually not
+// there yet. The prose check therefore runs only when the pending ask is
+// found in the transcript (by tool_use_id, or as the identical tail ask);
+// otherwise the guard cannot judge and allows.
 // Blocks with exit 2 + {"decision":"block",...}; allows everything else.
 // Fail-OPEN on any error (exit 0): a missing/unreadable transcript or an
 // unexpected shape must never wedge the workflow.
@@ -16,7 +23,7 @@
 // Pure functions are exported for tests; runs as a hook when executed directly.
 
 const fs = require('fs');
-const { hasLink, isMockupApprovalAsk, BLOCK_REASON } = require('./lib/mockup-link.js');
+const { hasLink, isMockupApprovalAsk, askHasLink, BLOCK_REASON } = require('./lib/mockup-link.js');
 
 // Only the transcript tail matters: the prose sits right before the ask.
 const TAIL_BYTES = 512 * 1024;
@@ -25,14 +32,41 @@ const blocksOf = (e) => (Array.isArray(e.message && e.message.content) ? e.messa
 const isPendingAsk = (e) => e.type === 'assistant'
   && blocksOf(e).some((b) => b.type === 'tool_use' && b.name === 'AskUserQuestion');
 
+const mainChain = (entries) => entries.filter((e) => e && (e.type === 'assistant' || e.type === 'user') && !e.isSidechain);
+
+// Index (in the main chain) of the entry holding the pending ask being
+// judged, or -1 when it is not in the transcript yet. With a tool_use id:
+// the assistant entry carrying that id. Without: the last entry, only if it
+// is a pending AskUserQuestion whose input equals toolInput.
+function pendingAskIndex(entries, toolUseId, toolInput) {
+  const main = mainChain(entries);
+  if (toolUseId) {
+    return main.findIndex((e) => e.type === 'assistant'
+      && blocksOf(e).some((b) => b.type === 'tool_use' && b.id === toolUseId));
+  }
+  const i = main.length - 1;
+  if (i < 0 || !isPendingAsk(main[i])) return -1;
+  const same = blocksOf(main[i]).some((b) => b.type === 'tool_use' && b.name === 'AskUserQuestion'
+    && JSON.stringify(b.input) === JSON.stringify(toolInput));
+  return same ? i : -1;
+}
+
 // The assistant prose right before the ask: walk the main-chain entries back
-// from the end, skip the pending AskUserQuestion entries, and collect text
-// blocks until anything else (a user turn, a tool result, another tool call).
-function proseBeforeAsk(entries) {
-  const main = entries.filter((e) => e && (e.type === 'assistant' || e.type === 'user') && !e.isSidechain);
-  let i = main.length - 1;
-  while (i >= 0 && isPendingAsk(main[i])) i--;
+// from the anchor entry (default: the end), skip the pending AskUserQuestion
+// entries (keeping the text that precedes the tool_use inside the anchor
+// entry itself), and collect text blocks until anything else (a user turn, a tool
+// result, another tool call).
+function proseBeforeAsk(entries, anchor) {
+  const main = mainChain(entries);
+  let i = anchor === undefined ? main.length - 1 : anchor;
   const texts = [];
+  // Text blocks in the same entry, before its tool_use, are prose too.
+  if (i >= 0 && main[i] && isPendingAsk(main[i])) {
+    const blocks = blocksOf(main[i]);
+    const firstTool = blocks.findIndex((b) => b.type === 'tool_use');
+    blocks.slice(0, firstTool).filter((b) => b.type === 'text').forEach((b) => texts.push(b.text || ''));
+  }
+  while (i >= 0 && isPendingAsk(main[i])) i--;
   for (; i >= 0; i--) {
     const e = main[i];
     if (e.type !== 'assistant') break;
@@ -73,9 +107,12 @@ function run(data) {
     const payload = JSON.parse(data);
     if (payload.tool_name && payload.tool_name !== 'AskUserQuestion') process.exit(0);
     if (!isMockupApprovalAsk(payload.tool_input)) process.exit(0);
+    if (askHasLink(payload.tool_input)) process.exit(0);
     if (!payload.transcript_path) process.exit(0);
-    const prose = proseBeforeAsk(parseEntries(readTail(payload.transcript_path)));
-    if (!hasLink(prose)) block();
+    const entries = parseEntries(readTail(payload.transcript_path));
+    const idx = pendingAskIndex(entries, payload.tool_use_id, payload.tool_input);
+    if (idx < 0) process.exit(0); // current message not flushed yet: cannot judge
+    if (!hasLink(proseBeforeAsk(entries, idx))) block();
   } catch {
     // fall through to allow: a guard must never wedge the workflow
   }
@@ -92,4 +129,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { isMockupApprovalAsk, hasLink, proseBeforeAsk };
+module.exports = { isMockupApprovalAsk, hasLink, askHasLink, proseBeforeAsk, pendingAskIndex };

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.test.js

@@ -10,6 +10,8 @@ const {
   isMockupApprovalAsk,
   hasLink,
   proseBeforeAsk,
+  pendingAskIndex,
+  askHasLink,
 } = require('./trailhead-mockup-link-guard.js');
 
 const HOOK = path.join(__dirname, 'trailhead-mockup-link-guard.js');
@@ -20,7 +22,7 @@ const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 // Costruttori di righe transcript (stesso shape JSONL di Claude Code)
 const text = (t) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'text', text: t }] } });
 const thinking = () => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'thinking', thinking: '' }] } });
-const toolUse = (name, input = {}) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'tool_use', id: 'x', name, input }] } });
+const toolUse = (name, input = {}, id = 'x') => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'tool_use', id, name, input }] } });
 const toolResult = (c) => ({ type: 'user', isSidechain: false, message: { content: [{ type: 'tool_result', tool_use_id: 'x', content: c }] } });
 const userPrompt = (c) => ({ type: 'user', isSidechain: false, message: { content: c } });
 
@@ -103,8 +105,45 @@ const sidechain = [
 ];
 ok('sidechain text is ignored', !hasLink(proseBeforeAsk(sidechain)));
 
-const noAskYet = [userPrompt('x'), text('Ecco https://a.b/c')];
-ok('works when the pending tool_use is not yet in the transcript', hasLink(proseBeforeAsk(noAskYet)));
+// Senza ancora: comportamento storico, si parte dalla coda del transcript
+const noAnchor = [userPrompt('x'), text('Ecco https://a.b/c')];
+ok('without an anchor the prose is read from the transcript tail', hasLink(proseBeforeAsk(noAnchor)));
+
+// Con ancora: si parte dall'ask trovato, non dalla coda
+const anchored = [
+  userPrompt('x'),
+  text('Mockup: https://a.b/c'),
+  toolUse('AskUserQuestion', approvalInput, 'ask1'),
+  toolResult('Approvo'),
+  text('Altro testo senza link'),
+];
+ok('with an anchor the prose is read back from the anchored ask', hasLink(proseBeforeAsk(anchored, 2)));
+
+// --- askHasLink ---
+const askWith = (over) => ({ questions: [{ ...approvalInput.questions[0], ...over }] });
+ok('link in the approval question counts', askHasLink(askWith({ question: 'Approvi il mockup https://claude.ai/artifact/AbC123?' })));
+ok('link in the approval header counts', askHasLink(askWith({ header: 'https://claude.ai/artifact/AbC123' })));
+ok('link in an approval option label counts', askHasLink(askWith({ options: [{ label: 'Apri https://a.b/c' }, { label: 'No' }] })));
+ok('link in an approval option description counts', askHasLink(askWith({ options: [{ label: 'Approvo', description: 'vedi mockups/faq.html' }] })));
+ok('approval ask without any link has none', !askHasLink(approvalInput));
+ok('link only in a different non-approval question does not count', !askHasLink({
+  questions: [
+    { question: 'Dove sta il piano?', options: [{ label: 'https://a.b/piano' }] },
+    approvalInput.questions[0],
+  ],
+}));
+ok('malformed input has no ask link', !askHasLink({}) && !askHasLink(null));
+
+// --- pendingAskIndex ---
+const withIds = [userPrompt('x'), toolUse('Bash', {}, 'b1'), toolResult('ok'), text('Prosa'), toolUse('AskUserQuestion', approvalInput, 'ask1')];
+ok('pendingAskIndex finds the entry by tool_use id', pendingAskIndex(withIds, 'ask1', approvalInput) === 4);
+ok('pendingAskIndex by id ignores a missing id', pendingAskIndex(withIds, 'nope', approvalInput) === -1);
+ok('pendingAskIndex without id falls back to input equality on the tail', pendingAskIndex(withIds, undefined, approvalInput) === 4);
+ok('pendingAskIndex without id is -1 when the tail ask has a different input',
+  pendingAskIndex(withIds, undefined, askWith({ question: 'Approvi il mockup B?' })) === -1);
+ok('pendingAskIndex is -1 when the tail is the previous tool_result',
+  pendingAskIndex([userPrompt('x'), toolUse('Bash', {}, 'b1'), toolResult('ok')], undefined, approvalInput) === -1);
+ok('pendingAskIndex ignores sidechain entries', pendingAskIndex([{ ...toolUse('AskUserQuestion', approvalInput, 'ask1'), isSidechain: true }], 'ask1', approvalInput) === -1);
 
 // --- end-to-end ---
 function writeTranscript(entries) {
@@ -138,6 +177,39 @@ ok('other tools are ignored', r4.code === 0);
 const r5 = runHook({ tool_name: 'AskUserQuestion', tool_input: { questions: [{ question: 'Approvi il piano?', options: [] }] }, transcript_path: writeTranscript(failing) });
 ok('non-mockup ask is allowed', r5.code === 0);
 
+// Shape reale di Claude Code 2.1.295: il messaggio corrente non e' ancora nel transcript
+const unflushed = [userPrompt('lavora #12'), toolUse('Bash', {}, 'b1'), toolResult('ok')];
+const ra = runHook({ tool_name: 'AskUserQuestion', tool_use_id: 'ask1', tool_input: approvalInput, transcript_path: writeTranscript(unflushed) });
+ok('(a) transcript ending at a previous tool_result fails open', ra.code === 0 && ra.out.trim() === '');
+
+const flushedNoLink = [...failing.slice(0, 5), toolUse('AskUserQuestion', approvalInput, 'ask1')];
+const rb = runHook({ tool_name: 'AskUserQuestion', tool_use_id: 'ask1', tool_input: approvalInput, transcript_path: writeTranscript(flushedNoLink) });
+ok('(b) tool_use_id with the ask entry present and no link in the prose is blocked', rb.code === 2 && /MOCKUP_LINK_MISSING/.test(rb.out));
+
+const linkedAsk = askWith({ question: 'Approvi il mockup https://claude.ai/artifact/AbC123?' });
+const rc = runHook({ tool_name: 'AskUserQuestion', tool_use_id: 'ask1', tool_input: linkedAsk, transcript_path: writeTranscript(failing) });
+ok('(c) link carried by the ask question is allowed', rc.code === 0 && rc.out.trim() === '');
+
+const otherPending = [userPrompt('x'), text('Niente link'), toolUse('AskUserQuestion', { questions: [{ question: 'Altro?', options: [] }] }, 'other')];
+const rd = runHook({ tool_name: 'AskUserQuestion', tool_use_id: 'ask1', tool_input: approvalInput, transcript_path: writeTranscript(otherPending) });
+ok('(d) transcript ending in a different pending ask fails open', rd.code === 0 && rd.out.trim() === '');
+
+// Testo e tool_use nella STESSA riga di transcript
+const sameEntry = (t) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'text', text: t }, { type: 'tool_use', id: 'ask1', name: 'AskUserQuestion', input: approvalInput }] } });
+ok('text before the tool_use in the same entry counts as prose', hasLink(proseBeforeAsk([userPrompt('x'), sameEntry('Vedi https://a.b/c')], 1)));
+ok('same-entry text is also read from the tail', hasLink(proseBeforeAsk([userPrompt('x'), sameEntry('Vedi https://a.b/c')])));
+const rs1 = runHook({ tool_name: 'AskUserQuestion', tool_use_id: 'ask1', tool_input: approvalInput, transcript_path: writeTranscript([userPrompt('x'), sameEntry('Vedi https://a.b/c')]) });
+ok('same-entry text with a link is allowed', rs1.code === 0 && rs1.out.trim() === '');
+const rs2 = runHook({ tool_name: 'AskUserQuestion', tool_use_id: 'ask1', tool_input: approvalInput, transcript_path: writeTranscript([userPrompt('x'), sameEntry('Mockup pronto su MyApp')]) });
+ok('same-entry text without a link is blocked', rs2.code === 2 && /MOCKUP_LINK_MISSING/.test(rs2.out));
+
+// Senza tool_use_id: ask in coda identico a tool_input (fallback per uguaglianza)
+const ri1 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: writeTranscript(flushedNoLink) });
+ok('no id, identical tail ask, no link in the prose is blocked', ri1.code === 2 && /MOCKUP_LINK_MISSING/.test(ri1.out));
+const flushedLink = [...failing.slice(0, 4), text('Mockup: https://claude.ai/artifact/AbC123xyz'), toolUse('AskUserQuestion', approvalInput, 'ask1')];
+const ri2 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: writeTranscript(flushedLink) });
+ok('no id, identical tail ask, link in the prose is allowed', ri2.code === 0 && ri2.out.trim() === '');
+
 let r6;
 try { execFileSync('node', [HOOK], { input: 'not json' }); r6 = 0; } catch (e) { r6 = e.status; }
 ok('unparseable input fails open', r6 === 0);