@marcomigozzi/trailhead 0.6.0 → 0.8.0

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

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// trailhead-search-guard.js: PreToolUse(Bash) hook.
+// Structural fix for the recurring #132 -> #133 -> #134 defect: the prose
+// search-command-hygiene ban (never `cd` then read/search a RELATIVE path) is
+// present in every engine agent and in `_shared/techniques.md`, but a subagent
+// under load still emits the banned shape, and the resulting relative read is
+// non-static, so a `Read()` deny rule under bypass permissions falls back to a
+// manual approval prompt (defeating headless operation). Prose hardening keeps
+// regressing, so this hook makes the shape structurally impossible instead of
+// merely discouraged.
+//
+// Blocks a SINGLE Bash command string that both:
+//   (a) changes the working directory - a `cd <dir>`, `pushd <dir>`, or
+//       `env -C <dir>` statement - joined to other statements via `&&`, `;`,
+//       `|`, or a newline (i.e. NOT the sole statement); AND
+//   (b) a later statement in that same command reads/searches a RELATIVE path
+//       via a read/search verb (grep, rg, ag, cat, head, tail, wc, nl, sed,
+//       awk, less, more, or `git grep`/`git log`/`git show`/`git diff`
+//       without a `-C`).
+//
+// KNOWN LIMITATION (do not try to catch this here): a *standalone* `cd <abs>`
+// in one Bash call followed by a relative read in a LATER, separate call
+// relies on the shell's persisted cwd, which this stateless per-call hook
+// cannot see. Blocking a lone `cd` would be far too aggressive (a legitimate,
+// common shape) so it is deliberately left to the prose directive.
+//
+// Blocks with exit 2 + {"decision":"block","code":...,"reason":...}; allows
+// everything else. Crash-safe: any error -> exit 0 (never wedge the user's
+// workflow). Self-contained (its own dependency is the sibling lib/ module,
+// no external packages). Pure functions exported for tests; runs as a hook
+// when executed directly.
+
+// --- tokenizing -------------------------------------------------------------
+// The quote-aware tokenizer/statement-splitter (splitStatements, tokenize,
+// stripQuotes, basename) and the search-verb pattern-positional-skipping
+// machinery (SEARCH_VERB_CONFIG, scanArgsSkippingPattern) are shared with
+// trailhead-secret-read-guard.js via lib/shell-scan.js (#135 follow-up), so
+// the two guards can never drift into two divergent tokenizers.
+const {
+  basename,
+  stripQuotes,
+  splitStatements,
+  tokenize,
+  skipEnvPrefix,
+  SEARCH_VERB_CONFIG,
+  scanArgsSkippingPattern,
+} = require('./lib/shell-scan.js');
+
+// A leading grouping/keyword token that can precede the "real" first word of a
+// statement without itself being that word: `(cd app && ...)`, `{ cd app; ... }`,
+// `do cd "$d" && ...` (loop body), `then cd x`, `else cd x`. Stripping these
+// (and a `(`/`{` glued directly onto the next token, e.g. `(cd`) lets the
+// `cd`/`pushd`/read-verb checks below see the actual command even when it's
+// wrapped in a subshell, brace group, or loop/conditional body.
+const LEADING_GROUP_TOKENS = new Set(['(', '{', 'do', 'then', 'else']);
+// A trailing grouping/keyword token (or glued punctuation) that can follow the
+// real last word of a statement: `grep ... foo.txt)`, `grep ... foo.txt;`,
+// `grep ... foo.txt }`, `... ; fi`, `... ; done`.
+const TRAILING_GROUP_TOKENS = new Set([')', '}', ';', 'fi', 'done']);
+
+// Strip a single leading grouping/keyword token and a single trailing
+// grouping/keyword token (or glued punctuation) from an already-tokenized
+// statement, so subshells, brace groups, and loop/conditional bodies don't
+// hide a `cd`/read-verb from the checks that follow. Best-effort: handles the
+// common shapes, not a full shell parser.
+function normalizeStatementTokens(tokens) {
+  let t = tokens;
+  if (t.length && LEADING_GROUP_TOKENS.has(t[0])) {
+    t = t.slice(1);
+  } else if (t.length && (t[0][0] === '(' || t[0][0] === '{') && t[0].length > 1) {
+    t = [t[0].slice(1), ...t.slice(1)];
+  }
+  if (t.length) {
+    const last = t[t.length - 1];
+    if (TRAILING_GROUP_TOKENS.has(last)) {
+      t = t.slice(0, -1);
+    } else {
+      const stripped = last.replace(/[)};]+$/, '');
+      if (stripped !== last) {
+        t = stripped ? [...t.slice(0, -1), stripped] : t.slice(0, -1);
+      }
+    }
+  }
+  return t;
+}
+
+// A relative-path FILE argument: not absolute, not stdin (`-`), not a dynamic
+// value we cannot resolve statically (fail open on those, same posture as the
+// commit-guard's UNEXPANDABLE handling).
+function isRelativeFileArg(t) {
+  const bare = stripQuotes(t);
+  if (!bare || bare === '-') return false;
+  if (bare.startsWith('/')) return false;
+  if (bare.startsWith('$') || bare.includes('$(') || bare.includes('`')) return false;
+  return true;
+}
+
+// --- per-verb argument scanning ---------------------------------------------
+
+// grep/rg/ag/sed/awk (the pattern-first search verbs) come from the shared
+// lib (see lib/shell-scan.js); cat/head/tail/wc/nl/less/more take only FILE
+// positionals and are specific to this guard's read-hygiene check.
+const VERB_CONFIG = {
+  ...SEARCH_VERB_CONFIG,
+  cat: { patternFirst: false, valueFlags: new Set() },
+  head: { patternFirst: false, valueFlags: new Set(['-n', '-c']) },
+  tail: { patternFirst: false, valueFlags: new Set(['-n', '-c']) },
+  wc: { patternFirst: false, valueFlags: new Set() },
+  nl: { patternFirst: false, valueFlags: new Set() },
+  less: { patternFirst: false, valueFlags: new Set() },
+  more: { patternFirst: false, valueFlags: new Set() },
+};
+
+// Walk a verb's argument tokens (verb itself already stripped) for the first
+// relative FILE argument found, via the shared pattern/flag-skipping walker.
+function scanArgsForRelativeFile(args, config) {
+  return scanArgsSkippingPattern(args, config, isRelativeFileArg);
+}
+
+// `git grep`/`git log`/`git show`/`git diff` WITHOUT a `-C` (or --work-tree):
+// git grep has a pattern positional like plain grep; log/show/diff don't, so
+// only their pathspec after an explicit `--` is checked (the common idiom),
+// keeping this conservative rather than guessing at ref vs. path tokens.
+function detectGitRelativeRead(tokens) {
+  let i = 1; // tokens[0] === 'git'
+  let hasC = false;
+  while (i < tokens.length && tokens[i].startsWith('-')) {
+    if ((tokens[i] === '-C' || tokens[i] === '--work-tree') && !tokens[i].includes('=')) {
+      hasC = true;
+      i += 2;
+      continue;
+    }
+    if (tokens[i].startsWith('--work-tree=') || tokens[i].startsWith('--git-dir=')) {
+      if (tokens[i].startsWith('--work-tree=')) hasC = true;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  if (hasC) return null; // already path-explicit
+  const sub = tokens[i];
+  if (!['grep', 'log', 'show', 'diff'].includes(sub)) return null;
+  i++;
+  if (sub === 'grep') {
+    return scanArgsForRelativeFile(tokens.slice(i), VERB_CONFIG.grep);
+  }
+  const dashIdx = tokens.indexOf('--', i);
+  if (dashIdx === -1) return null;
+  return scanArgsForRelativeFile(tokens.slice(dashIdx + 1), { patternFirst: false, valueFlags: new Set() });
+}
+
+// Is this statement itself a read/search verb call with a relative file arg?
+function readViolationInStatement(stmt) {
+  const tokens = normalizeStatementTokens(tokenize(stmt));
+  const i = skipEnvPrefix(tokens);
+  const rest = tokens.slice(i);
+  if (rest.length === 0) return null;
+  const bin = basename(rest[0]);
+  if (bin === 'git') {
+    const file = detectGitRelativeRead(rest);
+    return file ? { verb: `git ${rest[1] || ''}`.trim(), file } : null;
+  }
+  const config = VERB_CONFIG[bin];
+  if (!config) return null;
+  const file = scanArgsForRelativeFile(rest.slice(1), config);
+  return file ? { verb: bin, file } : null;
+}
+
+// Does this statement change the shell's persistent cwd (`cd`/`pushd`)? `env
+// -C` is deliberately excluded here: it changes the directory only for the ONE
+// command it wraps, not the rest of the script, so it's handled separately
+// as a same-statement check, not this cross-statement sticky flag.
+function isCdOrPushdStatement(stmt) {
+  const tokens = normalizeStatementTokens(tokenize(stmt));
+  const i = skipEnvPrefix(tokens);
+  const bin = tokens[i];
+  return bin === 'cd' || bin === 'pushd';
+}
+
+// `env -C <dir> <cmd> …`: the directory change and the read live in the SAME
+// statement (env execs its argument as a single command with that cwd), so
+// this is checked independently of the cross-statement `cwdChanged` flag.
+function envDashCRelativeRead(stmt) {
+  const tokens = tokenize(stmt);
+  let i = skipEnvPrefix(tokens);
+  if (basename(tokens[i]) !== 'env') return null;
+  i++;
+  let foundC = false;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (t === '-C') { foundC = true; i += 2; break; }
+    if (t.startsWith('--chdir=')) { foundC = true; i += 1; break; }
+    if (t.startsWith('-')) { i++; continue; } // some other env flag, best-effort skip
+    break; // reached the wrapped command
+  }
+  if (!foundC) return null;
+  const rest = tokens.slice(i);
+  if (rest.length === 0) return null;
+  const bin = basename(rest[0]);
+  if (bin === 'git') {
+    const file = detectGitRelativeRead(rest);
+    return file ? { verb: 'git', file } : null;
+  }
+  const config = VERB_CONFIG[bin];
+  if (!config) return null;
+  const file = scanArgsForRelativeFile(rest.slice(1), config);
+  return file ? { verb: bin, file } : null;
+}
+
+// --- top-level detection -----------------------------------------------------
+
+// Detect the banned shape across the whole command. Returns
+// { verb, file } on a hit, or null. Pure, exported for tests.
+// KNOWN NARROWER GAP (deliberately not implemented): `cd app && grep -rn TODO`
+// with no path argument at all implicitly searches the (now-relative) cwd,
+// but adding that case risks false-positiving on legitimate stdin-reading
+// commands, so it is left to the prose directive.
+function detectSearchHygieneViolation(cmd) {
+  const statements = splitStatements(cmd);
+  let cwdChanged = false;
+  for (let idx = 0; idx < statements.length; idx++) {
+    const stmt = statements[idx];
+
+    const envHit = envDashCRelativeRead(stmt);
+    if (envHit) return envHit;
+
+    if (cwdChanged) {
+      const hit = readViolationInStatement(stmt);
+      if (hit) return hit;
+    }
+
+    // A `cd`/`pushd` only counts when it is joined to a LATER statement (not
+    // the sole statement) - a lone standalone `cd` is the known limitation
+    // above and must never be blocked here.
+    if (isCdOrPushdStatement(stmt) && idx < statements.length - 1) {
+      cwdChanged = true;
+    }
+  }
+  return null;
+}
+
+function block(hit) {
+  const reason =
+    "trailhead search-hygiene: a 'cd <dir>' (or pushd/env -C) followed by a relative " +
+    `${hit.verb} read (\`${hit.file}\`) makes the read target non-static, which trips the ` +
+    'Read() deny rule under bypass permissions (prompting for manual approval instead of ' +
+    'running headless). Pass explicit paths instead and never cd first: ' +
+    'grep -niE "<patterns>" <abs>/<file>, git -C <abs> ..., or use the Grep/Read tools.';
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'SEARCH_HYGIENE_VIOLATION', reason }));
+  process.exit(2);
+}
+
+function run(data) {
+  let cmd = '';
+  try {
+    cmd = (JSON.parse(data).tool_input || {}).command || '';
+  } catch {
+    process.exit(0); // unparseable input: nothing to gate
+  }
+  try {
+    const hit = detectSearchHygieneViolation(cmd);
+    if (hit) block(hit);
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends -> give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { detectSearchHygieneViolation };

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Tests for trailhead-search-guard.js. Run: node trailhead-search-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 HOOK = path.join(__dirname, 'trailhead-search-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) {
+  const input = JSON.stringify({ tool_input: { command } });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- ticket #134: the exact regression command must be BLOCKED ---
+const ticketCmd = String.raw`cd app && grep -n "go_router" pubspec.yaml pubspec.lock | head; echo "=== router file ==="; grep -rln "GoRouter(" lib/ ; echo "=== /who route def ==="; grep -rn "'/who'\|\"/who\"\|/profile/manage\|path: '/home'" lib/ | head -30`;
+const rTicket = runHook(ticketCmd);
+ok('ticket #134 exact command is blocked (exit 2)', rTicket.code === 2 && /SEARCH_HYGIENE_VIOLATION|search-hygiene/.test(rTicket.out));
+
+// --- BLOCK cases ---
+const r1 = runHook('cd app && grep -n "go_router" pubspec.yaml');
+ok('cd <relative> && grep <relative> is blocked (exit 2)', r1.code === 2 && /search-hygiene/.test(r1.out));
+
+const r2 = runHook('cd /abs/app; grep -rln "GoRouter(" lib/');
+ok('cd <abs>; grep <relative> is blocked (exit 2)', r2.code === 2 && /search-hygiene/.test(r2.out));
+
+const r3 = runHook('pushd app && cat file.txt');
+ok('pushd <dir> && cat <relative> is blocked (exit 2)', r3.code === 2 && /search-hygiene/.test(r3.out));
+
+const r4 = runHook('cd app && wc -l foo.txt');
+ok('cd <dir> && wc -l <relative> is blocked (exit 2)', r4.code === 2 && /search-hygiene/.test(r4.out));
+
+const r5 = runHook('cd app &&\ngrep -n "x" foo.txt\n');
+ok('cd <dir> && then relative grep on a later line (newline-joined) is blocked (exit 2)', r5.code === 2 && /search-hygiene/.test(r5.out));
+
+const r6 = runHook('cd app; echo hi; grep -n "x" foo.txt');
+ok('cd <dir>; ...; relative grep several statements later is blocked (exit 2)', r6.code === 2 && /search-hygiene/.test(r6.out));
+
+const r7 = runHook('env -C app grep -n "x" foo.txt');
+ok('env -C <dir> grep <relative> (single statement) is blocked (exit 2)', r7.code === 2 && /search-hygiene/.test(r7.out));
+
+const r8 = runHook('cd app && git log -- foo.txt');
+ok('cd <dir> && git log without -C on a relative path is blocked (exit 2)', r8.code === 2 && /search-hygiene/.test(r8.out));
+
+const r9 = runHook('cd app && rg "TODO" foo.txt');
+ok('cd <dir> && rg <relative> is blocked (exit 2)', r9.code === 2 && /search-hygiene/.test(r9.out));
+
+// --- ALLOW cases (no false positives) ---
+const a1 = runHook('grep -n "x" /abs/app/pubspec.yaml');
+ok('path-explicit grep with no cd is allowed (exit 0)', a1.code === 0 && a1.out.trim() === '');
+
+const a2 = runHook('git -C /abs/app grep "x"');
+ok('git -C <abs> grep is allowed (exit 0)', a2.code === 0 && a2.out.trim() === '');
+
+const a3 = runHook('cd /abs && npm test');
+ok('cd <abs> && npm test (no read/search verb) is allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
+
+const a4 = runHook('cd /abs && ls -la');
+ok('cd <abs> && ls (not a Read()-denied verb) is allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
+
+const a5 = runHook('cd /abs/app');
+ok('a bare standalone cd <abs> alone is allowed (exit 0) - known limitation, never block a lone cd', a5.code === 0 && a5.out.trim() === '');
+
+const a6 = runHook('grep "cd foo" /abs/file');
+ok('grep whose pattern happens to contain "cd" but path is absolute is allowed (exit 0)', a6.code === 0 && a6.out.trim() === '');
+
+const a7 = runHook('grep -n "x" file --with-something');
+ok('command with no cd at all is allowed regardless of relative path (exit 0)', a7.code === 0 && a7.out.trim() === '');
+
+const a8 = runHook('cd /abs/app && grep -n "x" /abs/app/foo.txt');
+ok('cd <abs> && grep with an absolute-path argument is allowed (exit 0)', a8.code === 0 && a8.out.trim() === '');
+
+const a9 = runHook('cd /abs/app && grep -n "x" -r --include=*.js');
+ok('cd <abs> && grep with only flags/patterns (no file arg) is allowed (exit 0)', a9.code === 0 && a9.out.trim() === '');
+
+// --- #134 follow-up: Finding 1 - heredoc bodies are DATA, not statements ---
+const h1 = runHook(`cat > setup.sh <<'EOF'\ncd /some/dir\ngrep -n pattern file.txt\nEOF\n`);
+ok('heredoc body (cd + grep as literal data) is allowed, not parsed as statements (exit 0)', h1.code === 0 && h1.out.trim() === '');
+
+const h2 = runHook(`bash -c 'cat' <<EOF\ncd app\ngrep -n x foo.txt\nEOF\n`);
+ok('heredoc fed to a command is allowed, its body is data not executed statements (exit 0)', h2.code === 0 && h2.out.trim() === '');
+
+const h3 = runHook(`cat > setup.sh <<'EOF'\nsome literal data\nEOF\ncd app && grep -n x foo.txt`);
+ok('a REAL cd + grep violation outside a heredoc on the same command still blocks (exit 2)', h3.code === 2 && /search-hygiene/.test(h3.out));
+
+// --- #134 follow-up: Finding 2 - grouping containers must not hide the violation ---
+const g1 = runHook('(cd app && grep -n x foo.txt)');
+ok('subshell-wrapped cd + grep is blocked (exit 2)', g1.code === 2 && /search-hygiene/.test(g1.out));
+
+const g2 = runHook('{ cd app; grep -n x foo.txt; }');
+ok('brace-group-wrapped cd + grep is blocked (exit 2)', g2.code === 2 && /search-hygiene/.test(g2.out));
+
+const g3 = runHook('for d in */; do cd "$d" && grep -n x foo.txt; cd ..; done');
+ok('loop-body cd + grep is blocked (exit 2)', g3.code === 2 && /search-hygiene/.test(g3.out));
+
+const g4 = runHook('(cd /abs && npm test)');
+ok('subshell-wrapped cd <abs> && npm test (no read verb) is still allowed (exit 0)', g4.code === 0 && g4.out.trim() === '');
+
+// --- #134 follow-up: Finding 3 - `--` end-of-options marker must not swallow the file ---
+const d1 = runHook('cd app && grep -- -x foo.txt');
+ok('cd + grep -- -x <relative file> is blocked (exit 2), `--` must not eat the file arg', d1.code === 2 && /search-hygiene/.test(d1.out) && /foo\.txt/.test(d1.out));
+
+// --- #134 follow-up: Finding 4 - rg-specific value flags must not misattribute the file ---
+const f1 = runHook('cd app && rg -g "*.js" TODO src/foo.js');
+ok('cd + rg -g <glob> <pattern> <relative file> reports the real file, not the pattern (exit 2)', f1.code === 2 && /search-hygiene/.test(f1.out) && /src\/foo\.js/.test(f1.out) && !/`TODO`/.test(f1.out));
+
+console.log(`✓ search-guard: ${passed} assertions passed`);