@marcomigozzi/trailhead 0.17.0 → 0.18.0

package/plugins/trailhead/hooks/lib/audit-walk.test.js

@@ -798,5 +798,67 @@ function cli(args) {
   ok('attribute merge replacing a tracked line: merge is not a producer', !shas(c).includes(m));
 }
 
+// --- facets: freshness of the codebase issue's facets -------------------------
+{
+  const facetsRun = (dir, body) => {
+    const file = path.join(dir, '.git', 'facets-body.md');
+    fs.writeFileSync(file, body);
+    let text = '';
+    const code = walk.main(['facets', '--repo', dir, '--body-file', file], { stdout: { write: (t) => { text += t; } } });
+    return { code, out: JSON.parse(text) };
+  };
+  const facet = (name, sha, ...cited) => `## ${name}\n\n${sha ? `_as of ${sha}_\n\n` : ''}${cited.map((c) => `- \`${c}\` is here`).join('\n')}\n\n`;
+  const byName = (r, name) => r.out.facets.find((f) => f.name === name);
+
+  const dir = mkrepo();
+  const c1 = commit(dir, {
+    'src/a.js': 'a\n', 'src/b.js': 'b\n', 'lib/old.js': 'o\n', 'lib/mv.js': 'm\n',
+    'docs/x.md': 'x\n', 'star/[ab].txt': 's\n', 'star/a.txt': 'plain\n',
+  }, 'feat: base');
+  const s1 = c1.slice(0, 7);
+  const body = '# Codebase\n\n' + [
+    facet('Fresh', s1, 'docs/x.md'),
+    facet('Edited', s1, 'src/a.js:3-9', 'docs/x.md'),
+    facet('Gone', s1, 'lib/old.js'),
+    facet('Moved', s1, 'lib/mv.js'),
+    facet('Unstamped', null, 'src/b.js'),
+    facet('Rewritten', 'deadbeef', 'src/b.js'),
+    facet('Nothing', s1, 'no/such.js', '/etc/passwd', '../x', '-rf', ':x', 'a b', 'plain words'),
+    facet('Glob', s1, 'star/[ab].txt'),
+    facet('Dir', s1, 'src/'),
+  ].join('') + '## Fenced\n\n```\n## Not a facet\n```\n';
+  commit(dir, { 'src/a.js': 'a2\n', 'lib/old.js': null, 'star/[ab].txt': 's2\n' }, 'fix: edits');
+  git(dir, ['mv', 'lib/mv.js', 'lib/moved.js']);
+  const c2 = finishCommit(dir, ['commit', '-q'], 'refactor: rename', {});
+  const r = facetsRun(dir, body);
+  eq('facets: exit 0 and head', [r.code, r.out.head], [0, c2]);
+  eq('facets: fresh facet is current', [byName(r, 'Fresh').status, byName(r, 'Fresh').changed], ['current', []]);
+  eq('facets: edited cited file (with :line suffix) is stale', [byName(r, 'Edited').status, byName(r, 'Edited').changed, byName(r, 'Edited').paths], ['stale', ['src/a.js'], ['src/a.js', 'docs/x.md']]);
+  eq('facets: deleted cited file is stale', [byName(r, 'Gone').status, byName(r, 'Gone').changed], ['stale', ['lib/old.js']]);
+  eq('facets: renamed cited file is stale', byName(r, 'Moved').status, 'stale');
+  eq('facets: no stamp is unstamped', [byName(r, 'Unstamped').status, byName(r, 'Unstamped').sha], ['unstamped', null]);
+  eq('facets: unknown stamp is unresolved', byName(r, 'Rewritten').status, 'unresolved');
+  eq('facets: unsafe and missing tokens are ignored, nothing resolved is no-paths', [byName(r, 'Nothing').status, byName(r, 'Nothing').paths], ['no-paths', []]);
+  eq('facets: glob characters match literally and a real change reads stale', [byName(r, 'Glob').status, byName(r, 'Glob').changed], ['stale', ['star/[ab].txt']]);
+  eq('facets: trailing slash is stripped', [byName(r, 'Dir').status, byName(r, 'Dir').paths], ['stale', ['src']]);
+  ok('facets: a fenced ## is not a facet', !r.out.facets.some((f) => f.name === 'Not a facet'));
+  eq('facets: fenced section is listed as unstamped', byName(r, 'Fenced').status, 'unstamped');
+
+  // A stamp that is a real commit but not an ancestor of HEAD is unresolved.
+  git(dir, ['checkout', '-q', '-b', 'side', c1]);
+  const side = commit(dir, { 'side.txt': 's\n' }, 'feat: side');
+  git(dir, ['checkout', '-q', 'main']);
+  const o = facetsRun(dir, facet('Side', side.slice(0, 7), 'src/b.js'));
+  eq('facets: a stamp off HEAD history is unresolved', byName(o, 'Side').status, 'unresolved');
+
+  // Usage errors exit 2 with {"error":...}.
+  let text = '';
+  const bad = walk.main(['facets', '--repo', dir], { stdout: { write: (t) => { text += t; } } });
+  ok('facets: --body-file is required', bad === 2 && JSON.parse(text).error);
+  text = '';
+  const missing = walk.main(['facets', '--repo', dir, '--body-file', '/nonexistent/body.md'], { stdout: { write: (t) => { text += t; } } });
+  ok('facets: unreadable body file is a fatal error', missing === 2 && JSON.parse(text).error);
+}
+
 cleanup();
 console.log(`✓ audit-walk: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/git-env-mod.test.js

@@ -0,0 +1,55 @@
+// Mod side of #349: git spawns go through `env -u <repo-location vars> git ...`
+// (the mod's process.run cannot delete env), and the name list matches the template's.
+// The mod file is TypeScript: loaded through Node's type stripping (Node >= 22.18);
+// skipped on an older Node, where the source checks below still run.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { GIT_LOCATION_VARS } = require('../../templates/trailhead-git-env.js');
+
+const modDir = path.join(__dirname, '..', 'mod');
+let passed = 0;
+const t = (name, fn) => { fn(); passed++; console.log('ok -', name); };
+
+let mod = null;
+try { mod = require(path.join(modDir, 'git-env.ts')); } catch { /* no type stripping */ }
+
+if (mod) {
+  t('the mod name list equals the template list', () => {
+    assert.deepStrictEqual([...mod.GIT_LOCATION_VARS], [...GIT_LOCATION_VARS]);
+  });
+  t('gitArgv starts with the env -u wrapper and ends with git args', () => {
+    const argv = mod.gitArgv('-C', '/r', 'status');
+    const gitAt = argv.indexOf('git');
+    assert.strictEqual(argv[0], 'env');
+    assert.deepStrictEqual(argv.slice(gitAt), ['git', '-C', '/r', 'status']);
+    const pairs = argv.slice(1, gitAt);
+    assert.deepStrictEqual(pairs.filter((_, i) => i % 2 === 0), GIT_LOCATION_VARS.map(() => '-u'));
+    assert.deepStrictEqual(pairs.filter((_, i) => i % 2 === 1), [...GIT_LOCATION_VARS]);
+  });
+  t('scrubGitEnv wraps a gh argv the same way', () => {
+    const argv = mod.scrubGitEnv(['gh', 'api', 'graphql']);
+    assert.strictEqual(argv[0], 'env');
+    assert.deepStrictEqual(argv.slice(-3), ['gh', 'api', 'graphql']);
+  });
+  t('the wrapper really drops GIT_DIR (env -u, run for real)', () => {
+    const { spawnSync } = require('child_process');
+    const argv = mod.scrubGitEnv([process.execPath, '-p', "'GIT_DIR' in process.env"]);
+    const r = spawnSync(argv[0], argv.slice(1), { encoding: 'utf8', env: { ...process.env, GIT_DIR: '/x' } });
+    assert.strictEqual(r.stdout.trim(), 'false');
+  });
+}
+
+t('no mod file spawns git without the wrapper', () => {
+  for (const f of fs.readdirSync(modDir).filter((n) => /\.tsx?$/.test(n) && n !== 'git-env.ts')) {
+    const src = fs.readFileSync(path.join(modDir, f), 'utf8');
+    assert.ok(!/\[\s*'git'/.test(src), `${f} builds a raw git argv; use gitArgv()`);
+  }
+});
+
+t('map-pane gh calls are wrapped', () => {
+  const src = fs.readFileSync(path.join(modDir, 'map-pane.tsx'), 'utf8');
+  assert.ok(src.includes("scrubGitEnv(['gh', ...args])"));
+});
+
+console.log(`${passed} passed${mod ? '' : ' (type stripping unavailable: wrapper checks skipped)'}`);

package/plugins/trailhead/hooks/lib/git-env-spawn.test.js

@@ -0,0 +1,73 @@
+// Regression (#349): an inherited GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE must not
+// redirect the plugin's git spawns away from the checkout they are pointed at.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const T = path.resolve(__dirname, '..', '..', 'templates');
+let passed = 0;
+const eq = (name, a, b) => { assert.deepStrictEqual(a, b, name); passed++; console.log('ok -', name); };
+
+const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'git-env-spawn-')));
+const cleanEnv = () => { const e = { ...process.env }; for (const k of Object.keys(e)) if (/^GIT_(DIR|WORK_TREE|INDEX_FILE|COMMON_DIR)$/.test(k)) delete e[k]; return e; };
+const git = (cwd, ...args) => {
+  const r = spawnSync('git', ['-C', cwd, '-c', 'user.name=t', '-c', 'user.email=t@t', ...args], { encoding: 'utf8', env: cleanEnv() });
+  assert.strictEqual(r.status, 0, `git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout.trim();
+};
+function makeRepo(name) {
+  const dir = path.join(tmp, name);
+  fs.mkdirSync(dir);
+  git(dir, 'init', '-q', '-b', 'main');
+  git(dir, 'commit', '-q', '--allow-empty', '-m', 'init');
+  return dir;
+}
+const a = makeRepo('a');
+const b = makeRepo('b');
+git(b, 'checkout', '-q', '-b', 'trailhead/t5');
+git(b, 'commit', '-q', '--allow-empty', '-m', 'feat: work\n\nRefs: #5');
+git(b, 'checkout', '-q', 'main');
+const aHead = git(a, 'rev-parse', 'HEAD');
+const bMain = git(b, 'rev-parse', 'main');
+const bBranch = git(b, 'rev-parse', 'trailhead/t5');
+
+// The hostile parent env: points every git call at a.
+const hostile = { ...process.env, GIT_DIR: path.join(a, '.git'), GIT_WORK_TREE: a, GIT_INDEX_FILE: path.join(a, '.git', 'index') };
+const node = (script, args, env) => spawnSync(process.execPath, [path.join(T, script), ...args], { encoding: 'utf8', env });
+
+// checkout-in: a plain dir is no repo; with GIT_DIR set it must still be invalid.
+const plain = path.join(tmp, 'plain');
+fs.mkdirSync(plain);
+const ci = node('trailhead-checkout-in.js', ['--in', plain, '--cwd', plain], hostile);
+eq('checkout-in does not resolve a plain dir through GIT_DIR', JSON.parse(ci.stdout.trim()).status, 'invalid');
+
+// auto-merge: merges into b, leaves a alone.
+const am = node('trailhead-auto-merge.js', ['merge', '--repo', b, '--ticket', '5'], hostile);
+const out = JSON.parse(am.stdout.trim());
+eq('auto-merge merges into the target repo', [out.status, git(b, 'rev-parse', 'main')], ['merged', bBranch]);
+eq('auto-merge leaves the GIT_DIR repo alone', git(a, 'rev-parse', 'HEAD'), aHead);
+assert.notStrictEqual(bMain, bBranch);
+
+// issue-body: the gh spawn (which asks git for the repo) must not see GIT_DIR.
+const bin = path.join(tmp, 'bin');
+fs.mkdirSync(bin);
+fs.writeFileSync(path.join(bin, 'gh'), '#!/bin/sh\nprintf "dir=%s wt=%s idx=%s" "${GIT_DIR-unset}" "${GIT_WORK_TREE-unset}" "${GIT_INDEX_FILE-unset}"\n', { mode: 0o755 });
+const probe = `process.stdout.write(require(${JSON.stringify(path.join(T, 'trailhead-issue-body.js'))}).defaultGh(['x']).stdout)`;
+const ib = spawnSync(process.execPath, ['-e', probe], { encoding: 'utf8', env: { ...hostile, PATH: `${bin}${path.delimiter}${process.env.PATH}` } });
+eq('issue-body gh spawn gets no repo-location vars', ib.stdout, 'dir=unset wt=unset idx=unset');
+
+// The other gh-spawning templates share the same one-line scrub.
+for (const f of ['unblock', 'uat-backfill', 'merge-ticket', 'needs-you', 'uat-followup', 'auto-queue', 'capture']) {
+  const src = fs.readFileSync(path.join(T, `trailhead-${f}.js`), 'utf8');
+  eq(`${f} gh spawn is scrubbed`, /spawnSync\('gh', args, \{[^}]*env: gitEnv\(\)/.test(src), true);
+}
+
+// The statusline keeps its own copy of the names: it must equal the template list.
+const sl = fs.readFileSync(path.join(T, 'statusline-trailhead.sh'), 'utf8');
+const unsetLine = sl.match(/^unset ((?:GIT_\w+[ \\\n]+)+)/m)[1].split(/[\s\\]+/).filter(Boolean);
+eq('statusline unset list equals the template list', [...unsetLine].sort(), [...require(path.join(T, 'trailhead-git-env.js')).GIT_LOCATION_VARS].sort());
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`${passed} passed`);

package/plugins/trailhead/hooks/lib/git-env.test.js

@@ -0,0 +1,51 @@
+// Tests of templates/trailhead-git-env.js (and its hooks/lib copy).
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { GIT_LOCATION_VARS, gitEnv } = require('../../templates/trailhead-git-env.js');
+
+let n = 0;
+const t = (name, fn) => { fn(); n++; console.log('ok -', name); };
+
+t('removes every repo-location name', () => {
+  const base = { PATH: '/bin' };
+  for (const k of GIT_LOCATION_VARS) base[k] = 'x';
+  assert.deepStrictEqual(gitEnv(base), { PATH: '/bin' });
+});
+
+t('keeps GIT_CONFIG* and unrelated names', () => {
+  const base = { GIT_DIR: 'x', GIT_CONFIG: 'a', GIT_CONFIG_PARAMETERS: 'b', GIT_CONFIG_COUNT: '1', HOME: '/h' };
+  assert.deepStrictEqual(gitEnv(base), { GIT_CONFIG: 'a', GIT_CONFIG_PARAMETERS: 'b', GIT_CONFIG_COUNT: '1', HOME: '/h' });
+});
+
+t('extra is applied on top and may re-add a name', () => {
+  assert.deepStrictEqual(gitEnv({ GIT_DIR: 'x', A: '1' }, { A: '2', GIT_EDITOR: 'true' }), { A: '2', GIT_EDITOR: 'true' });
+});
+
+t('does not mutate its input or process.env', () => {
+  const base = Object.freeze({ GIT_DIR: 'x' });
+  gitEnv(base);
+  assert.strictEqual(base.GIT_DIR, 'x');
+  process.env.GIT_DIR = '/nonexistent-for-test';
+  try {
+    assert.ok(!('GIT_DIR' in gitEnv()));
+    assert.strictEqual(process.env.GIT_DIR, '/nonexistent-for-test');
+  } finally { delete process.env.GIT_DIR; }
+});
+
+t('the name list is git\'s local env vars minus GIT_CONFIG*', () => {
+  const r = spawnSync('git', ['rev-parse', '--local-env-vars'], { encoding: 'utf8' });
+  if (r.status !== 0) return;
+  const expected = r.stdout.split('\n').filter((s) => s && !s.startsWith('GIT_CONFIG')).sort();
+  const missing = expected.filter((k) => !GIT_LOCATION_VARS.includes(k));
+  assert.deepStrictEqual(missing, [], 'git knows local env vars the list lacks');
+});
+
+t('hooks/lib copy is byte-identical to the template', () => {
+  const a = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'trailhead-git-env.js'));
+  const b = fs.readFileSync(path.join(__dirname, 'trailhead-git-env.js'));
+  assert.ok(a.equals(b));
+});
+
+console.log(`${n} passed`);

package/plugins/trailhead/hooks/lib/global-config-dir.test.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// La config globale su Codex sta in <codexHome>, non in ~/.claude: ogni lettore, copiato dove l'installer
+// Codex lo mette, deve trovarla lì. Run: node global-config-dir.test.js
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const pluginDir = path.resolve(__dirname, '..', '..');
+const READERS = [
+  ['templates', 'trailhead-base-preflight.js'],
+  ['templates', 'trailhead-inbox-needs-info.js'],
+  ['templates', 'trailhead-isolation-copy.js'],
+  ['templates', 'trailhead-plan-review-rounds.js'],
+  ['templates', 'trailhead-test-run.js'],
+  ['templates', 'trailhead-uat-setup.js'],
+  ['hooks', 'trailhead-test-guard.js'],
+];
+
+const tmp = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'trailhead-global-config-'));
+const codexHome = path.join(tmp, 'codex');
+const skillDir = path.join(codexHome, 'skills', 'trailhead');
+const ENV = { HOME: path.join(tmp, 'home'), CLAUDE_CONFIG_DIR: path.join(tmp, 'claude') };
+
+// Il percorso del file di config che il lettore userebbe, con l'env dato.
+const configFileOf = (mod, env) =>
+  (mod.configDir ? path.join(mod.configDir(env), 'trailhead', 'config.json') : mod.globalConfigPath(env));
+
+let passed = 0;
+try {
+  for (const dir of ['templates', 'hooks']) {
+    fs.cpSync(path.join(pluginDir, dir), path.join(skillDir, dir), { recursive: true });
+  }
+  const expected = path.join(codexHome, 'trailhead', 'config.json');
+  for (const [dir, file] of READERS) {
+    const onCodex = require(path.join(skillDir, dir, file));
+    assert.strictEqual(configFileOf(onCodex, ENV), expected, `${file} on Codex`);
+    passed += 1;
+
+    const onClaude = require(path.join(pluginDir, dir, file));
+    assert.strictEqual(configFileOf(onClaude, ENV), path.join(ENV.CLAUDE_CONFIG_DIR, 'trailhead', 'config.json'), `${file} with CLAUDE_CONFIG_DIR`);
+    assert.strictEqual(configFileOf(onClaude, { HOME: ENV.HOME }), path.join(ENV.HOME, '.claude', 'trailhead', 'config.json'), `${file} default`);
+    passed += 2;
+  }
+} finally {
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+console.log(`global-config-dir.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/heredoc-mod.test.js

@@ -0,0 +1,85 @@
+// Mod side of #369: the mod strips heredoc bodies before it tests a Bash call for a tracker write,
+// with its own import-free leaf (a mod file imports nothing from hooks/lib). This keeps the leaf's
+// output equal to shell-scan's stripHeredocBodies over the commands that matter to the write check.
+// The mod file is TypeScript: loaded through Node's type stripping (Node >= 22.18);
+// skipped (with an explicit SKIP line) on a Node with no type stripping; any other load error fails.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { stripHeredocBodies } = require('./shell-scan.js');
+
+let passed = 0;
+const t = (name, fn) => { fn(); passed++; console.log('ok -', name); };
+
+const leaf = path.join(__dirname, '..', 'mod', 'heredoc.ts');
+assert.ok(fs.existsSync(leaf), 'mod/heredoc.ts is missing');
+let mod = null;
+try {
+  mod = require(leaf);
+} catch (err) {
+  // Only a Node with no type stripping may skip; a syntax error in the leaf must fail the test.
+  const noStripping = err.code === 'ERR_UNKNOWN_FILE_EXTENSION' || !process.features.typescript;
+  if (!noStripping) throw err;
+  console.log(`SKIP - mod/heredoc.ts not loadable without type stripping (${err.code || err.name})`);
+}
+
+const COMMANDS = [
+  'cat >f <<EOF\ngh issue close 5\nEOF',
+  "cat >f <<'EOF'\ngh issue close 5\nEOF",
+  'cat >f <<"EOF"\ngh issue close 5\nEOF',
+  'cat >f <<-EOF\n\tgh issue close 5\n\tEOF',
+  'cat <<A >a; cat <<B >b\ngh issue close 1\nA\ngh issue edit 2\nB',
+  'cat <<A >a; cat <<B >b\nx\nA\ny\nB\ngh issue close 3',
+  'gh issue create --body-file - <<EOF\nbody\nEOF',
+  'gh issue comment 5 -F - <<EOF\ngh issue close 9\nEOF',
+  "cat <<'EOF' >x\nb\nEOF\ngh issue close 5",
+  "cat <<'EOF' >x\nEOF2\ngh issue close 5\n EOF\nEOF",
+  "cat <<'EOF' >x\ngh issue close 5",
+  'cat <<-EOF >x\nb\n  EOF\ngh issue close 5\nEOF',
+  "cat <<< 'x'\ngh issue close 5",
+  'echo $((1<<2))\ngh issue close 5',
+  'echo $((1<<2)); gh issue view 5',
+  "cat <<'EOF' >x\nnode trailhead-issue-body.js append\nEOF",
+  'echo "a <<EOF"\ngh issue close 5',
+  'gh issue close 5',
+  // W1: a `<<` in a comment opens nothing
+  '# build body with <<EOF\ngh issue close 5',
+  'git commit -m "x" # see <<EOF\ngh issue close 5',
+  'echo a;# c <<EOF\ngh issue close 5',
+  'echo a&&(# c <<EOF\ngh issue close 5',
+  // a `#` inside a word is no comment
+  'cat a#b <<EOF\ngh issue close 5\nEOF',
+  'cat a#b <<EOF\ngh issue close 5',
+  // W2: an opener inside a multi-line quoted string opens nothing
+  'echo "a\ncat <<EOF\nb"\ngh issue close 5\nEOF',
+  "echo 'a\ncat <<EOF\nb'\ngh issue close 5",
+  'echo "a\n# x <<EOF\nb" <<EOF\ngh issue close 5\nEOF\ngh issue edit 2',
+  'echo "unbalanced\ncat <<EOF\ngh issue close 5\nEOF',
+  // a `<<` inside a parameter expansion opens nothing
+  'echo ${x:-<<EOF}\ngh issue close 5\nEOF',
+  'echo ${x:-<<EOF\ngh issue close 5',
+  // a body is not scanned for quotes: its apostrophe leaks nowhere
+  "cat <<EOF\nit's\nEOF\ncat <<B\ngh issue close 5\nB",
+  "cat <<EOF\nit's\nEOF\ngh issue close 5",
+];
+
+// Known difference (I1): shell-scan sees an opener inside `$(..)` that the leaf does not, so the
+// leaf keeps those lines (an extra read at worst). Asserted, not emulated.
+const KNOWN_DIFFS = [
+  'echo "$(cat <<EOF\nhello\nEOF\n)"',
+];
+
+if (mod) {
+  t('the mod leaf strips like shell-scan over the write-check commands', () => {
+    for (const cmd of COMMANDS) {
+      assert.strictEqual(mod.stripHeredocBodies(cmd), stripHeredocBodies(cmd), JSON.stringify(cmd));
+    }
+  });
+  t('the known $(..) difference keep the lines (safe direction)', () => {
+    for (const cmd of KNOWN_DIFFS) {
+      assert.strictEqual(mod.stripHeredocBodies(cmd), cmd, JSON.stringify(cmd));
+    }
+  });
+}
+
+console.log(`${passed} passed${mod ? '' : ' (type stripping unavailable: leaf checks skipped)'}`);

package/plugins/trailhead/hooks/lib/inbox-needs-info.test.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-inbox-needs-info.js. Run: node inbox-needs-info.test.js
+// No framework: plain asserts, same style as uat-backfill.test.js.
+//
+// Layers covered:
+//   1. main() against a fake tracker behind an injected `gh` runner: the
+//      classification, the reporter match, the days config, failed reads.
+//   2. End-to-end: the script itself with a fake `gh` on PATH (multi-page read,
+//      failing read).
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-inbox-needs-info.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'inbox-needs-info-'));
+const NOW = new Date('2026-06-30T12:00:00Z');
+const LABELED = '2026-06-10T12:00:00Z'; // 20 days before NOW
+
+// issues: [{number,title,author,labeledAt?,labelEvents?,comments?,failEvents?,failComments?}]
+function makeTracker(init = {}) {
+  const t = { issues: init.issues || [], failList: !!init.failList, calls: [] };
+  const res = (rows, status = 0) => ({ status, stdout: rows.map((r) => JSON.stringify(r)).join('\n'), stderr: status ? 'forced failure' : '' });
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    if (args[0] !== 'api') return res([], 1);
+    const url = args[2];
+    if (url.includes('/issues?labels=trailhead:needs-info&state=open&per_page=100')) {
+      if (t.failList) return res([], 1);
+      return res(t.issues.map((i) => ({ number: i.number, title: i.title || `T${i.number}`, author: i.author === undefined ? 'reporter' : i.author })));
+    }
+    const m = /\/issues\/(\d+)\/(events|comments)/.exec(url);
+    if (!m) return res([], 1);
+    const i = t.issues.find((x) => x.number === Number(m[1]));
+    if (m[2] === 'events') {
+      if (i.failEvents) return res([], 1);
+      return res(i.labelEvents || [{ at: i.labeledAt || LABELED }]);
+    }
+    if (i.failComments) return res([], 1);
+    return res(i.comments || []);
+  };
+  return t;
+}
+
+function run(t, { root, env, argv } = {}) {
+  let out = '';
+  const code = main(argv || ['--repo', 'o/r', '--config-root', root || tmp], {
+    gh: t.gh, now: () => NOW, env: env || { CLAUDE_CONFIG_DIR: path.join(tmp, 'noglobal') }, stdout: { write: (s) => { out += s; } }, stderr: { write: () => {} },
+  });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json };
+}
+
+const nums = (a) => a.map((x) => x.number);
+
+// --- classification ----------------------------------------------------------
+{
+  const t = makeTracker({ issues: [
+    { number: 1, comments: [{ author: 'reporter', at: '2026-06-05T00:00:00Z' }] }, // before the label
+    { number: 2, comments: [{ author: 'someone', at: '2026-06-11T00:00:00Z' }] }, // other user after
+    { number: 3, comments: [{ author: 'reporter', at: '2026-06-11T00:00:00Z' }] }, // reporter after
+    { number: 4, author: 'Reporter', comments: [{ author: 'reporter', at: '2026-06-12T00:00:00Z' }] }, // case-different login
+    { number: 5, comments: [{ author: 'reporter', at: LABELED }] }, // same-second tie
+    { number: 6, author: null, comments: [] }, // deleted reporter
+    { number: 7, author: 'ghost', comments: [{ author: 'ghost', at: '2026-06-12T00:00:00Z' }] },
+    { number: 8, labeledAt: '2026-06-25T12:00:00Z' }, // 5 days: still waiting
+    { number: 9, labeledAt: '2026-06-16T12:00:00Z' }, // exactly 14 days: timed out
+    { number: 10, labeledAt: '2026-06-16T12:00:01Z' }, // 13 whole days: waiting
+    { number: 11, labelEvents: [] }, // no label event
+    { number: 12, failEvents: true },
+    { number: 13, failComments: true },
+    { number: 14, labelEvents: [{ at: '2026-05-01T00:00:00Z' }, { at: '2026-06-25T12:00:00Z' }], comments: [{ author: 'reporter', at: '2026-06-01T00:00:00Z' }] }, // latest label wins
+  ] });
+  const r = run(t);
+  ok('exit 0, one JSON line', r.code === 0 && r.json.status === 'ok' && r.out.trim().split('\n').length === 1);
+  ok('answered: reporter after the label, case-insensitive', JSON.stringify(nums(r.json.answered)) === '[3,4]');
+  ok('answered carries answeredAt and author', r.json.answered[0].answeredAt === '2026-06-11T00:00:00Z' && r.json.answered[0].author === 'reporter');
+  ok('timedOut: before-label comment, other user, tie, 14 whole days', JSON.stringify(nums(r.json.timedOut)) === '[1,2,5,9]');
+  ok('timedOut carries ageDays', r.json.timedOut.find((x) => x.number === 9).ageDays === 14);
+  ok('waiting stays out of answered and timedOut', JSON.stringify(nums(r.json.waiting)) === '[8,10,14]');
+  ok('unknown: deleted reporter, ghost, no event, failed reads', JSON.stringify(nums(r.json.unknown)) === '[6,7,11,12,13]' && r.json.unknown.every((u) => u.reason));
+  ok('the default is 14 days', r.json.days === 14 && r.json.warnings.length === 0);
+  ok('read-only: only api reads, pull requests filtered by jq', t.calls.every((c) => c.startsWith('api ')) && t.calls[0].includes('select(.pull_request == null)'));
+  ok('comments are read since the label', t.calls.some((c) => c.includes('/issues/3/comments?since=2026-06-10T12:00:00Z&per_page=100')));
+}
+
+// --- days config -------------------------------------------------------------
+function configRoot(cfg) {
+  const root = fs.mkdtempSync(path.join(tmp, 'proj-'));
+  fs.mkdirSync(path.join(root, '.trailhead'));
+  if (cfg !== undefined) fs.writeFileSync(path.join(root, '.trailhead', 'config.json'), typeof cfg === 'string' ? cfg : JSON.stringify(cfg));
+  return root;
+}
+function globalEnv(cfg) {
+  const dir = fs.mkdtempSync(path.join(tmp, 'glob-'));
+  fs.mkdirSync(path.join(dir, 'trailhead'));
+  fs.writeFileSync(path.join(dir, 'trailhead', 'config.json'), typeof cfg === 'string' ? cfg : JSON.stringify(cfg));
+  return { CLAUDE_CONFIG_DIR: dir };
+}
+const one = () => makeTracker({ issues: [{ number: 1, labeledAt: '2026-06-25T12:00:00Z' }] }); // 5 days old
+{
+  const r = run(one(), { root: configRoot({ 'inbox.needs_info_days': 3 }) });
+  ok('project override: flat key', r.json.days === 3 && r.json.timedOut.length === 1);
+  const n = run(one(), { root: configRoot({ inbox: { needs_info_days: 7 } }) });
+  ok('project override: nested key', n.json.days === 7 && n.json.waiting.length === 1);
+  const b = run(one(), { root: configRoot({ 'inbox.needs_info_days': 3, inbox: { needs_info_days: 9 } }) });
+  ok('flat key wins over nested in one file', b.json.days === 3);
+  const g = run(one(), { root: configRoot({}), env: globalEnv({ 'inbox.needs_info_days': 4 }) });
+  ok('global config applies when the project sets nothing', g.json.days === 4);
+  const p = run(one(), { root: configRoot({ 'inbox.needs_info_days': 2 }), env: globalEnv({ 'inbox.needs_info_days': 4 }) });
+  ok('project wins over global', p.json.days === 2);
+}
+for (const bad of [0, -1, 1.5, '7', null]) {
+  const r = run(one(), { root: configRoot({ 'inbox.needs_info_days': bad }), env: globalEnv({ 'inbox.needs_info_days': 6 }) });
+  ok(`invalid value ${JSON.stringify(bad)} warns and falls to the global layer`, r.json.days === 6 && r.json.warnings.length === 1);
+}
+{
+  const r = run(one(), { root: configRoot('{nope') });
+  ok('invalid JSON warns and falls to the default', r.json.days === 14 && r.json.warnings.length === 1);
+  const d = run(one(), { root: path.join(tmp, 'missing-root') });
+  ok('a missing project config is silent', d.json.days === 14 && d.json.warnings.length === 0);
+}
+
+// --- failures and usage ------------------------------------------------------
+{
+  const r = run(makeTracker({ issues: [{ number: 1 }], failList: true }));
+  ok('a failed list read is status error, exit 1', r.code === 1 && r.json.status === 'error');
+}
+for (const argv of [['--bogus'], ['--repo'], ['--repo', 'nope', '--config-root', 'x'], ['--repo', 'o/r'], ['--config-root', 'x']]) {
+  const t = makeTracker();
+  const r = run(t, { argv });
+  ok(`usage error exit 2: ${argv.join(' ')}`, r.code === 2 && t.calls.length === 0);
+}
+
+// --- end-to-end with a fake gh on PATH ---------------------------------------
+function e2e(script) {
+  const binDir = fs.mkdtempSync(path.join(tmp, 'bin-'));
+  fs.writeFileSync(path.join(binDir, 'gh'), script, { mode: 0o755 });
+  return spawnSync('node', [scriptPath, '--repo', 'o/r', '--config-root', tmp], { encoding: 'utf8', env: { ...process.env, CLAUDE_CONFIG_DIR: path.join(tmp, 'noglobal'), PATH: binDir + path.delimiter + process.env.PATH } });
+}
+{
+  // Two pages for each read: one JSON document per line, as `--jq ... | tojson` prints.
+  const good = e2e(`#!/bin/sh
+case "$*" in
+  *"issues?labels="*) echo '{"number":5,"title":"A","author":"rep"}'; echo '{"number":6,"title":"B","author":"rep"}' ;;
+  *"/issues/5/events"*) echo '{"at":"2026-01-01T00:00:00Z"}'; echo '{"at":"2026-01-02T00:00:00Z"}' ;;
+  *"/issues/6/events"*) echo '{"at":"2026-01-01T00:00:00Z"}' ;;
+  *"/issues/5/comments"*) echo '{"author":"rep","at":"2026-01-03T00:00:00Z"}' ;;
+  *"/issues/6/comments"*) echo '{"author":"x","at":"2026-01-03T00:00:00Z"}' ;;
+  *) exit 1 ;;
+esac
+`);
+  const j = JSON.parse(good.stdout.trim());
+  ok('e2e: multi-page reads classify answered and timed out', good.status === 0 && JSON.stringify(nums(j.answered)) === '[5]' && JSON.stringify(nums(j.timedOut)) === '[6]');
+  const partial = e2e(`#!/bin/sh
+case "$*" in
+  *"issues?labels="*) echo '{"number":5,"title":"A","author":"rep"}' ;;
+  *"/issues/5/events"*) echo '{"at":"2026-01-01T00:00:00Z"}' ;;
+  *"/issues/5/comments"*) echo '{"author":"rep","at":"2026-01-03T00:00:00Z"}'; exit 1 ;;
+  *) exit 1 ;;
+esac
+`);
+  const p = JSON.parse(partial.stdout.trim());
+  ok('e2e: a read that fails after printing is unknown, never classified', partial.status === 0 && nums(p.unknown).join() === '5' && p.answered.length === 0 && p.timedOut.length === 0);
+  const down = e2e('#!/bin/sh\nexit 1\n');
+  ok('e2e: gh failing exits 1 with one JSON error line', down.status === 1 && JSON.parse(down.stdout.trim()).status === 'error');
+  const bad = spawnSync('node', [scriptPath, '--bogus'], { encoding: 'utf8' });
+  ok('e2e: usage error exits 2', bad.status === 2);
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`inbox-needs-info.test.js: ${passed} checks passed`);