@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/hooks/lib/statusline-context.test.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// Tests for templates/statusline-trailhead.sh (barra contesto, --context-only).
+// Run: node statusline-context.test.js
+// No framework: plain asserts, same style as work-state.test.js.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const script = path.resolve(__dirname, '..', '..', 'templates', 'statusline-trailhead.sh');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-statusline-ctx-'));
+const home = path.join(root, 'home');
+const cfg = path.join(root, 'cfg');
+const proj = path.join(root, 'proj');
+for (const d of [home, cfg, path.join(proj, '.claude')]) fs.mkdirSync(d, { recursive: true });
+
+const SETTINGS = {
+  user: path.join(cfg, 'settings.json'),
+  project: path.join(proj, '.claude', 'settings.json'),
+  local: path.join(proj, '.claude', 'settings.local.json'),
+};
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, got, want) => { assert.strictEqual(got, want, `${name}: got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`); passed++; };
+
+function setSettings(files) {
+  for (const f of Object.values(SETTINGS)) fs.rmSync(f, { force: true });
+  for (const [k, v] of Object.entries(files || {})) {
+    fs.writeFileSync(SETTINGS[k], typeof v === 'string' ? v : JSON.stringify(v));
+  }
+}
+
+// Esegue lo script e ritorna { pct, shown, out }
+function ctx(tok, { env = {}, settings = {}, modelId = 'claude-opus-5-5[1m]', size = 1000000 } = {}) {
+  setSettings(settings);
+  const base = { ...process.env };
+  for (const k of ['CLAUDE_CODE_AUTO_COMPACT_WINDOW', 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE',
+    'DISABLE_AUTO_COMPACT', 'DISABLE_COMPACT', 'CONTEXT_LIMIT', 'CONTEXT_USABLE_RATIO']) delete base[k];
+  const input = {
+    model: { id: modelId, display_name: 'Test' },
+    workspace: { project_dir: proj, current_dir: proj },
+    context_window: { context_window_size: size, current_usage: { input_tokens: tok } },
+  };
+  const r = spawnSync('bash', [script, '--context-only'], {
+    input: JSON.stringify(input),
+    env: { ...base, NO_COLOR: '1', TRAILHEAD_STATUSLINE_USAGE: '0', HOME: home, CLAUDE_CONFIG_DIR: cfg, ...env },
+    encoding: 'utf8',
+  });
+  const out = r.stdout.trim();
+  const m = out.match(/^\[.{10}\] (\d+)k\/(\d+)k \((\d+)%\)$/);
+  assert.ok(m, `unexpected output: ${JSON.stringify(out)} ${r.stderr}`);
+  return { pct: Number(m[3]), shown: `${m[1]}k/${m[2]}k`, out };
+}
+const pct = (tok, o) => ctx(tok, o).pct;
+
+// --- default 1M: soglia = 1M - 33k = 967k ---
+eq('default 966k', pct(966000), 100);
+eq('default 967k', pct(967000), 100);
+eq('default 900k', pct(900000), 93);
+ok('default 800k not 100', pct(800000) < 100);
+eq('display full window', ctx(900000).shown, '900k/1000k');
+
+// --- autoCompactWindow ---
+const win650 = { autoCompactWindow: 650000 };
+eq('top-level 617k', pct(617000, { settings: { user: win650 } }), 100);
+ok('top-level 600k', pct(600000, { settings: { user: win650 } }) < 100);
+const perModel = { modelSettings: { 'claude-opus-5-5': { autoCompactWindow: 650000 } } };
+eq('per-model 617k', pct(617000, { settings: { user: perModel } }), 100);
+ok('per-model 600k', pct(600000, { settings: { user: perModel } }) < 100);
+eq('per-model beats top-level', pct(617000, {
+  settings: { user: { autoCompactWindow: 900000, ...perModel } } }), 100);
+eq('per-model beats top-level (larger top)', pct(300000, {
+  settings: { user: { autoCompactWindow: 400000, modelSettings: { 'claude-opus-5-5': { autoCompactWindow: 1000000 } } } } }), 31);
+eq('local beats user', pct(617000, { settings: { user: { autoCompactWindow: 1000000 }, local: win650 } }), 100);
+eq('local beats project', pct(617000, { settings: { project: { autoCompactWindow: 1000000 }, local: win650 } }), 100);
+eq('project beats user', pct(617000, { settings: { user: { autoCompactWindow: 1000000 }, project: win650 } }), 100);
+eq('invalid json skipped', pct(617000, { settings: { user: win650, local: '{nope' } }), 100);
+eq('non-positive setting ignored', pct(900000, { settings: { user: { autoCompactWindow: -5 } } }), 93);
+eq('non-numeric setting ignored', pct(900000, { settings: { user: { autoCompactWindow: 'big' } } }), 93);
+eq('invalid higher file value falls to lower', pct(617000, {
+  settings: { user: win650, local: { autoCompactWindow: 'x' } } }), 100);
+
+// --- env CLAUDE_CODE_AUTO_COMPACT_WINDOW ---
+eq('env beats setting', pct(617000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '650000' },
+  settings: { user: { autoCompactWindow: 1000000 } } }), 100);
+for (const bad of ['abc', '0', '-100']) {
+  eq(`env ${bad} ignored`, pct(900000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: bad } }), 93);
+}
+eq('env bad falls back to setting', pct(617000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: 'abc' },
+  settings: { user: win650 } }), 100);
+eq('window above model capped', pct(966000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '5000000' } }), 100);
+eq('window above model capped 900k', pct(900000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '5000000' } }), 93);
+
+// --- CLAUDE_AUTOCOMPACT_PCT_OVERRIDE ---
+eq('pct 50 at threshold', pct(500000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '50' } }), 100);
+eq('pct 50 at 450k', pct(450000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '50' } }), 90);
+for (const v of ['100', '101', '0', '-3', 'abc']) {
+  eq(`pct ${v} no change`, pct(900000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: v } }), 93);
+}
+eq('pct 1 -> threshold 10k', pct(10000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '1' } }), 100);
+eq('pct 1 at 5k', pct(5000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '1' } }), 50);
+
+// --- disabilitato ---
+eq('DISABLE_AUTO_COMPACT', pct(400000, { env: { DISABLE_AUTO_COMPACT: '1' } }), 40);
+eq('DISABLE_COMPACT true', pct(400000, { env: { DISABLE_COMPACT: 'TRUE' } }), 40);
+eq('disabled ignores settings and pct', pct(400000, { env: { DISABLE_AUTO_COMPACT: 'yes', CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '10' },
+  settings: { user: win650 } }), 40);
+eq('falsy DISABLE ignored', pct(900000, { env: { DISABLE_AUTO_COMPACT: '0' } }), 93);
+eq('DISABLE_COMPACT on', pct(400000, { env: { DISABLE_COMPACT: 'on' } }), 40);
+eq('DISABLE false ignored', pct(900000, { env: { DISABLE_COMPACT: 'false' } }), 93);
+
+// --- per-modello in un file meno specifico batte top-level in uno piu' specifico ---
+eq('per-model user beats top-level local', pct(617000, {
+  settings: { user: perModel, local: { autoCompactWindow: 1000000 } } }), 100);
+
+// --- fallback tabella modello (niente context_window_size): 200k, soglia 167k ---
+eq('model table fallback', pct(100000, { size: 0 }), 60);
+eq('model table fallback display', ctx(100000, { size: 0 }).shown, '100k/200k');
+
+// --- tetto modello ---
+eq('CONTEXT_LIMIT caps display', ctx(100000, { env: { CONTEXT_LIMIT: '200000' } }).shown, '100k/200k');
+eq('CONTEXT_LIMIT pct (threshold 167k)', pct(100000, { env: { CONTEXT_LIMIT: '200000' } }), 60);
+
+// --- override manuale CONTEXT_USABLE_RATIO ---
+eq('ratio 0.8 old behaviour', pct(800000, { env: { CONTEXT_USABLE_RATIO: '0.8' } }), 100);
+eq('ratio 0.8 at 400k', pct(400000, { env: { CONTEXT_USABLE_RATIO: '0.8' } }), 50);
+eq('ratio bypasses window setting', pct(400000, { env: { CONTEXT_USABLE_RATIO: '0.8' }, settings: { user: win650 } }), 50);
+eq('ratio invalid ignored', pct(900000, { env: { CONTEXT_USABLE_RATIO: '2' } }), 93);
+
+// --- bordo soglia: finestra 34k -> soglia 1000 ---
+const edge = { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '34000' } };
+eq('edge threshold-1', pct(994, edge), 99);
+eq('edge threshold', pct(1000, edge), 100);
+// finestra minuscola: soglia mai sotto 1
+eq('tiny window guard', pct(5, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '10' } }), 100);
+
+// --- credenziali: il blocco usage legge .credentials.json da CLAUDE_CONFIG_DIR (#320) ---
+// Segnale osservabile: la dir cache viene creata solo se il guard sulle credenziali passa.
+function usageReached({ withCreds }) {
+  const credCfg = path.join(root, withCreds ? 'cfg-creds' : 'cfg-nocreds');
+  const cache = path.join(root, withCreds ? 'cache-creds' : 'cache-nocreds');
+  fs.mkdirSync(credCfg, { recursive: true });
+  fs.mkdirSync(cache, { recursive: true });
+  if (withCreds) {
+    fs.writeFileSync(path.join(credCfg, '.credentials.json'), JSON.stringify({ claudeAiOauth: { accessToken: 'dummy' } }));
+  }
+  const env = { ...process.env, NO_COLOR: '1', HOME: home, CLAUDE_CONFIG_DIR: credCfg, XDG_CACHE_HOME: cache,
+    USAGE_API_TIMEOUT: '1', HTTPS_PROXY: 'http://127.0.0.1:9', https_proxy: 'http://127.0.0.1:9' };
+  delete env.TRAILHEAD_STATUSLINE_USAGE;
+  const input = { model: { id: 'claude-opus-5-5', display_name: 'Test' }, workspace: { project_dir: proj, current_dir: proj } };
+  spawnSync('bash', [script, '--context-only'], { input: JSON.stringify(input), env, encoding: 'utf8' });
+  return fs.existsSync(path.join(cache, 'trailhead-statusline'));
+}
+ok('usage block reached with creds under CLAUDE_CONFIG_DIR', usageReached({ withCreds: true }));
+ok('usage block skipped without creds', !usageReached({ withCreds: false }));
+
+// retry: il python in background puo' ancora scrivere nella cache mentre si pulisce
+fs.rmSync(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+console.log(`statusline-context.test.js: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/uat-followup.test.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-uat-followup.js (#281). Run: node uat-followup.test.js
+// No framework: plain asserts. A fake tracker sits behind an injected `gh` runner;
+// one end-to-end run uses a fake `gh` on PATH.
+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-uat-followup.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Fake tracker behind `gh api graphql`: answers GraphQL-shaped pages, 'pageSize' issues each,
+// following the `after` cursor (a page index as a string).
+function makeTracker(init = {}) {
+  const t = { issues: init.issues || [], fail: !!init.fail, raw: init.raw, pageSize: init.pageSize || 100, respond: init.respond, calls: [], argLists: [] };
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    t.argLists.push(args);
+    if (t.fail) return { status: 1, stdout: '', stderr: 'forced failure' };
+    if (t.raw !== undefined) return { status: 0, stdout: t.raw, stderr: '' };
+    const afterIdx = args.findIndex((x) => typeof x === 'string' && x.startsWith('after='));
+    const page = afterIdx < 0 ? 0 : Number(args[afterIdx].slice('after='.length));
+    if (t.respond) return { status: 0, stdout: JSON.stringify(t.respond(page)), stderr: '' };
+    const slice = t.issues.slice(page * t.pageSize, (page + 1) * t.pageSize);
+    const more = (page + 1) * t.pageSize < t.issues.length;
+    const pageInfo = { hasNextPage: more, endCursor: more ? String(page + 1) : null };
+    return { status: 0, stdout: JSON.stringify({ data: { repository: { issues: { nodes: slice, pageInfo } } } }), stderr: '' };
+  };
+  return t;
+}
+
+function run(t, argv) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { gh: t.gh, stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } } });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, errOut, json };
+}
+
+const URL_ = (n, repo = 'o/r') => `https://github.com/${repo}/issues/${n}`;
+const fu = (number, state, body, title = `UAT ${number}`) => ({ number, title, state, body });
+const base = ['find', '--parent', '281', '--repo', 'o/r'];
+
+// --- matching ----------------------------------------------------------------
+{
+  // A URL whose number runs into letters is not a pointer to that issue.
+  const t = makeTracker({ issues: [fu(310, 'OPEN', 'UAT of: [P](https://github.com/o/r/issues/281abc)')] });
+  const r = run(t, base);
+  ok('URL with trailing letters after the number does not match', r.code === 0 && r.json.open.length === 0 && r.json.reuse === null);
+}
+{
+  const t = makeTracker({ issues: [
+    fu(300, 'OPEN', `Intro\n\nUAT of: [Parent](${URL_(281)})\n\n- [ ] step`),
+    fu(301, 'OPEN', 'UAT of: #281\n- [ ] step'),
+    fu(302, 'OPEN', 'See the UAT of: [P](' + URL_(281) + ') mid-line'),
+    fu(303, 'OPEN', `UAT of: [P](${URL_(28)})`),
+    fu(304, 'OPEN', `UAT of: [P](${URL_(2810)})`),
+    fu(305, 'OPEN', 'UAT of: #28'),
+    fu(306, 'OPEN', 'UAT of: #2810'),
+    fu(307, 'OPEN', `UAT of: [P](${URL_(281, 'other/r')})`),
+    fu(308, 'OPEN', 'no pointer at all'),
+    fu(309, 'OPEN', `UAT of: [P](${URL_(281, 'O/R')})`),
+    fu(310, 'OPEN', `UAT of: [P](${URL_(281)})\r\n- [ ] step`),
+  ] });
+  const r = run(t, base);
+  const nums = r.json.open.map((x) => x.number);
+  ok('matches by URL, by #n, case-insensitive repo, CRLF', JSON.stringify(nums) === '[300,301,309,310]');
+  ok('ignores mid-line, prefix numbers, other repo, no pointer', !nums.some((n) => [302, 303, 304, 305, 306, 307, 308].includes(n)));
+  ok('prints one JSON line with title', r.code === 0 && r.json.status === 'ok' && r.json.parent === 281 && r.json.open[0].title === 'UAT 300' && r.out.trim().split('\n').length === 1);
+  ok('reuse is the lowest open', r.json.reuse === 300);
+  const a0 = t.calls[0];
+  ok('one graphql call with the label and both states, never issue list or search', t.calls.length === 1 && a0.includes('api graphql') && a0.includes('labels:["trailhead:uat"]') && a0.includes('states:[OPEN,CLOSED]') && !a0.includes('issue list') && !a0.includes('--search'));
+  ok('owner and name go as string fields, no cursor on the first page', a0.includes('-f owner=o') && a0.includes('-f name=r') && !a0.includes('after='));
+}
+
+// --- open vs closed ------------------------------------------------------------
+{
+  const t = makeTracker({ issues: [
+    fu(12, 'CLOSED', 'UAT of: #281'),
+    fu(11, 'CLOSED', 'UAT of: #281'),
+    fu(20, 'OPEN', 'UAT of: #281'),
+    fu(15, 'OPEN', 'UAT of: #281'),
+  ] });
+  const r = run(t, base);
+  ok('splits open and closed ascending', JSON.stringify(r.json.open.map((x) => x.number)) === '[15,20]' && JSON.stringify(r.json.closed.map((x) => x.number)) === '[11,12]');
+  ok('reuse picks the lowest open of several', r.json.reuse === 15);
+}
+{
+  const t = makeTracker({ issues: [fu(11, 'CLOSED', 'UAT of: #281')] });
+  const r = run(t, base);
+  ok('only closed: reported, reuse null', r.code === 0 && r.json.closed.length === 1 && r.json.open.length === 0 && r.json.reuse === null);
+}
+{
+  const r = run(makeTracker({ issues: [] }), base);
+  ok('none found: empty lists, reuse null', r.code === 0 && r.json.reuse === null && r.json.open.length === 0 && r.json.closed.length === 0);
+}
+
+// --- errors --------------------------------------------------------------------
+{
+  const r = run(makeTracker({ fail: true }), base);
+  ok('gh failure is a fail-closed error', r.code === 1 && r.json.status === 'error' && typeof r.json.reason === 'string');
+  const b = run(makeTracker({ raw: 'not json' }), base);
+  ok('bad JSON is an error', b.code === 1 && b.json.status === 'error');
+  const o = run(makeTracker({ raw: '{"a":1}' }), base);
+  ok('JSON without data.repository is an error', o.code === 1 && o.json.status === 'error');
+  const er = run(makeTracker({ raw: JSON.stringify({ errors: [{ message: 'boom' }], data: null }) }), base);
+  ok('errors array is an error', er.code === 1 && er.json.status === 'error' && /boom/.test(er.json.reason));
+  const nr = run(makeTracker({ raw: JSON.stringify({ data: { repository: null } }) }), base);
+  ok('null repository is an error', nr.code === 1 && nr.json.status === 'error');
+  const nn = run(makeTracker({ raw: JSON.stringify({ data: { repository: { issues: { pageInfo: { hasNextPage: false, endCursor: null } } } } }) }), base);
+  ok('missing nodes is an error', nn.code === 1 && nn.json.status === 'error');
+  const np = run(makeTracker({ raw: JSON.stringify({ data: { repository: { issues: { nodes: [] } } } }) }), base);
+  ok('missing pageInfo is an error', np.code === 1 && np.json.status === 'error');
+  const nc = run(makeTracker({ raw: JSON.stringify({ data: { repository: { issues: { nodes: [], pageInfo: { hasNextPage: true, endCursor: null } } } } }) }), base);
+  ok('hasNextPage without a cursor is an error', nc.code === 1 && nc.json.status === 'error');
+  const endless = makeTracker({ respond: (p) => ({ data: { repository: { issues: { nodes: [], pageInfo: { hasNextPage: true, endCursor: String(p + 1) } } } } }) });
+  const cap = run(endless, base);
+  ok('page cap exceeded is an error, never a partial answer', cap.code === 1 && cap.json.status === 'error' && /page/.test(cap.json.reason) && endless.calls.length === 100);
+}
+
+// --- pagination ----------------------------------------------------------------
+{
+  const t = makeTracker({ pageSize: 2, issues: [
+    fu(1, 'OPEN', 'x'), fu(2, 'CLOSED', 'x'), fu(3, 'OPEN', 'x'),
+    fu(4, 'OPEN', 'UAT of: #281'), fu(5, 'CLOSED', 'UAT of: #281'),
+  ] });
+  const r = run(t, base);
+  ok('follow-up on a later page is found', r.code === 0 && r.json.reuse === 4 && r.json.closed[0].number === 5);
+  ok('three pages, cursor passed on later ones only', t.calls.length === 3 && !t.calls[0].includes('after=') && t.calls[1].includes('-f after=1') && t.calls[2].includes('-f after=2'));
+  ok('no page uses issue list or search', t.calls.every((c) => c.includes('api graphql') && !c.includes('issue list') && !c.includes('--search')));
+}
+
+// --- usage ---------------------------------------------------------------------
+for (const argv of [
+  [], ['bogus'], ['find'], ['find', '--parent', '281'], ['find', '--repo', 'o/r'],
+  ['find', '--parent', '0', '--repo', 'o/r'], ['find', '--parent', 'abc', '--repo', 'o/r'], ['find', '--parent', '-3', '--repo', 'o/r'],
+  ['find', '--parent', '281', '--repo', 'nope'], ['find', '--parent'], ['find', '--parent', '281', '--repo'],
+  ['find', '--parent', '281', '--repo', 'o/r', '--bogus', 'x'],
+]) {
+  const t = makeTracker();
+  const r = run(t, argv);
+  ok(`usage error exit 2: ${argv.join(' ') || '(none)'}`, r.code === 2 && t.calls.length === 0 && r.errOut.length > 0 && r.out === '');
+}
+
+// --- end-to-end with a fake gh on PATH ------------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'uat-followup-'));
+  const binDir = path.join(tmp, 'bin');
+  fs.mkdirSync(binDir);
+  const payload = JSON.stringify({ data: { repository: { issues: { nodes: [fu(7, 'OPEN', 'UAT of: #281', 'Follow-up')], pageInfo: { hasNextPage: false, endCursor: null } } } } });
+  fs.writeFileSync(path.join(binDir, 'gh'), `#!/bin/sh\ncat <<'EOF_JSON'\n${payload}\nEOF_JSON\n`, { mode: 0o755 });
+  const env = { ...process.env, PATH: binDir + path.delimiter + process.env.PATH };
+  const res = spawnSync('node', [scriptPath, ...base], { encoding: 'utf8', env });
+  ok('e2e: finds the follow-up through gh on PATH', res.status === 0 && JSON.parse(res.stdout.trim()).reuse === 7);
+  fs.writeFileSync(path.join(binDir, 'gh'), '#!/bin/sh\nexit 1\n', { mode: 0o755 });
+  const bad = spawnSync('node', [scriptPath, ...base], { encoding: 'utf8', env });
+  ok('e2e: failing gh exits 1 with a JSON error line', bad.status === 1 && JSON.parse(bad.stdout.trim()).status === 'error');
+  const use = spawnSync('node', [scriptPath, '--bogus'], { encoding: 'utf8' });
+  ok('e2e: usage error exits 2', use.status === 2);
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`uat-followup.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/unblock.test.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-unblock.js. Run: node unblock.test.js
+// No framework: plain asserts, same style as needs-you.test.js.
+//
+// Layers covered:
+//   1. main() against a fake tracker behind an injected `gh` (multi-page reads included).
+//   2. Usage errors (exit 2).
+//   3. End-to-end: the script itself with a fake `gh` on PATH.
+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-unblock.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- fake tracker ------------------------------------------------------------
+// dependents: [{number, state, labels}] of the closed issue (paginated output is the
+// concatenation of one JSON object per line, whatever the page size).
+// blockers: { [dependent]: [{number, state}] }. failOn: blocking | blocked_by | edit.
+function makeTracker(init = {}) {
+  const t = { dependents: init.dependents || [], blockers: init.blockers || {}, failOn: init.failOn || null, badJson: !!init.badJson, calls: [], edits: [] };
+  const res = (stdout, status = 0) => ({ status, stdout, stderr: status ? 'forced failure' : '' });
+  const lines = (list) => list.map((o) => JSON.stringify(o)).join('\n') + (list.length ? '\n' : '');
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    if (args[0] === 'api') {
+      const url = args.find((a) => a.startsWith('repos/'));
+      const m = /issues\/(\d+)\/dependencies\/(blocking|blocked_by)$/.exec(url || '');
+      if (!m) return res('', 1);
+      if (t.failOn === m[2]) return res('', 1);
+      if (t.badJson) return res('not json\n');
+      if (m[2] === 'blocking') return res(lines(t.dependents));
+      return res(lines(t.blockers[m[1]] || []));
+    }
+    if (args[0] === 'issue' && args[1] === 'edit') {
+      if (t.failOn === 'edit') return res('', 1);
+      t.edits.push(args.join(' '));
+      const n = Number(args[2]);
+      const d = t.dependents.find((x) => x.number === n);
+      if (d) d.labels = d.labels.filter((l) => l !== args[args.indexOf('--remove-label') + 1]);
+      return res('');
+    }
+    return res('', 1);
+  };
+  return t;
+}
+
+function run(t, argv, extra = {}) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { gh: t.gh, stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } }, ...extra });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json, errOut };
+}
+
+const args = ['--issue', '5', '--repo', 'o/r'];
+const B = 'trailhead:blocked';
+
+// --- last blocker closed -> label removed ------------------------------------
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B, 'x'] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }, { number: 6, state: 'closed' }] },
+  });
+  const r = run(t, args);
+  ok('unblock: exits 0 with status ok', r.code === 0 && r.json.status === 'ok');
+  ok('unblock: the dependent is listed', JSON.stringify(r.json.unblocked) === '[8]' && r.json.stillBlocked.length === 0);
+  ok('unblock: the blocked label is removed', t.edits.length === 1 && t.edits[0].includes('--remove-label trailhead:blocked') && t.edits[0].includes('-R o/r'));
+  ok('unblock: the reads are paginated', t.calls.filter((c) => c.startsWith('api')).every((c) => c.includes('--paginate')));
+  const again = run(t, args);
+  ok('unblock: a retry is idempotent (label already gone)', again.code === 0 && again.json.unblocked.length === 0 && t.edits.length === 1);
+}
+
+// --- another blocker still open ----------------------------------------------
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }, { number: 6, state: 'open' }, { number: 7, state: 'open' }] },
+  });
+  const r = run(t, args);
+  ok('unblock: an open blocker keeps the label', r.code === 0 && r.json.unblocked.length === 0 && t.edits.length === 0);
+  ok('unblock: stillBlocked names the open blockers', r.json.stillBlocked.length === 1 && r.json.stillBlocked[0].issue === 8 && JSON.stringify(r.json.stillBlocked[0].openBlockers) === '[6,7]');
+}
+
+// --- skipped dependents -------------------------------------------------------
+{
+  const t = makeTracker({
+    dependents: [
+      { number: 8, state: 'open', labels: [] },
+      { number: 9, state: 'closed', labels: [B] },
+      { number: 10, state: 'open', labels: [B] },
+    ],
+    blockers: { 10: [{ number: 5, state: 'closed' }] },
+  });
+  const r = run(t, args);
+  ok('unblock: a dependent without the label is skipped', !t.calls.some((c) => c.includes('issues/8/')));
+  ok('unblock: a closed dependent is skipped', !t.calls.some((c) => c.includes('issues/9/')));
+  ok('unblock: only the open labelled dependent is unblocked', JSON.stringify(r.json.unblocked) === '[10]');
+}
+
+// --- no dependents ------------------------------------------------------------
+{
+  const r = run(makeTracker(), args);
+  ok('unblock: no dependents is ok and empty', r.code === 0 && r.json.status === 'ok' && r.json.unblocked.length === 0 && r.json.stillBlocked.length === 0);
+}
+
+// --- gh failures --------------------------------------------------------------
+{
+  const t = makeTracker({ failOn: 'blocking' });
+  const r = run(t, args);
+  ok('unblock: a failed dependents read is an error', r.code === 1 && r.json.status === 'error' && /dependents|blocking/.test(r.json.reason));
+  ok('unblock: nothing edited after a failed read', t.edits.length === 0);
+}
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B] }, { number: 9, state: 'open', labels: [B] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }], 9: [{ number: 5, state: 'closed' }] },
+    failOn: 'blocked_by',
+  });
+  const r = run(t, args);
+  ok('unblock: a failed blockers read is an error naming the step', r.code === 1 && r.json.status === 'error' && /blocked_by|blockers/.test(r.json.reason));
+  ok('unblock: nothing further edited after the failure', t.edits.length === 0 && t.calls.filter((c) => c.includes('issues/9/')).length === 0);
+}
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B] }, { number: 9, state: 'open', labels: [B] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }], 9: [{ number: 5, state: 'closed' }] },
+    failOn: 'edit',
+  });
+  const r = run(t, args);
+  ok('unblock: a failed label removal is an error', r.code === 1 && r.json.status === 'error' && /remove/.test(r.json.reason));
+  ok('unblock: the next dependent is not touched after a failed edit', t.calls.filter((c) => c.startsWith('issue edit')).length === 1);
+}
+{
+  const r = run(makeTracker({ badJson: true }), args);
+  ok('unblock: unparseable gh output is an error', r.code === 1 && r.json.status === 'error' && /unparseable/.test(r.json.reason));
+}
+
+// --- multi-page reads ---------------------------------------------------------
+// gh api --paginate with --jq prints one object per line across every page, so a
+// second page is just more lines; the fake returns them concatenated, and the helper
+// must read all of them (two pages of dependents, an open blocker only on page two).
+{
+  const t = makeTracker({
+    dependents: [
+      ...Array.from({ length: 30 }, (_, i) => ({ number: 100 + i, state: 'closed', labels: [] })),
+      { number: 8, state: 'open', labels: [B] },
+    ],
+    blockers: {
+      8: [...Array.from({ length: 30 }, (_, i) => ({ number: 200 + i, state: 'closed' })), { number: 99, state: 'open' }],
+    },
+  });
+  const r = run(t, args);
+  ok('unblock: a dependent on the second page is found', r.code === 0 && r.json.stillBlocked.length === 1 && r.json.stillBlocked[0].issue === 8);
+  ok('unblock: an open blocker only on the second page keeps the label', JSON.stringify(r.json.stillBlocked[0].openBlockers) === '[99]' && t.edits.length === 0);
+}
+
+// --- usage errors -------------------------------------------------------------
+{
+  const t = makeTracker();
+  for (const [name, argv] of [
+    ['no arguments', []],
+    ['missing --repo', ['--issue', '5']],
+    ['missing --issue', ['--repo', 'o/r']],
+    ['bad --issue', ['--issue', 'x', '--repo', 'o/r']],
+    ['bad --repo', ['--issue', '5', '--repo', 'nope']],
+    ['unknown flag', ['--issue', '5', '--repo', 'o/r', '--force']],
+    ['flag without value', ['--issue']],
+  ]) {
+    const r = run(t, argv);
+    ok(`usage: ${name} exits 2 with stderr`, r.code === 2 && r.errOut.startsWith('usage:') && r.out === '');
+  }
+  ok('usage: no gh call on a usage error', t.calls.length === 0);
+}
+
+// --- end-to-end: the script with a fake gh on PATH -----------------------------
+{
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'unblock-e2e-')));
+  const bin = path.join(dir, 'gh');
+  fs.writeFileSync(bin, [
+    '#!/bin/sh',
+    'case "$*" in',
+    '  *dependencies/blocking*) echo \'{"number":8,"state":"open","labels":["trailhead:blocked"]}\' ;;',
+    '  *dependencies/blocked_by*) echo \'{"number":5,"state":"closed"}\' ;;',
+    '  *"issue edit"*) echo "$*" >> "' + path.join(dir, 'edits.log') + '" ;;',
+    '  *) exit 1 ;;',
+    'esac',
+    '',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+  const r = spawnSync('node', [scriptPath, '--issue', '5', '--repo', 'o/r'], { encoding: 'utf8', env: { ...process.env, PATH: `${dir}:${process.env.PATH}` } });
+  let j = null;
+  try { j = JSON.parse(r.stdout.trim()); } catch { /* not json */ }
+  ok('e2e: exits 0 with one JSON line', r.status === 0 && j && j.status === 'ok' && JSON.stringify(j.unblocked) === '[8]');
+  ok('e2e: the label edit reached gh', fs.readFileSync(path.join(dir, 'edits.log'), 'utf8').includes('--remove-label trailhead:blocked'));
+  const bad = spawnSync('node', [scriptPath], { encoding: 'utf8' });
+  ok('e2e: a usage error exits 2', bad.status === 2);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`unblock.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/unmodelled.js

@@ -62,6 +62,11 @@ const WRAPPER_VALUE_FLAGS = {
   nohup: [],
 };
 
+// Is `word` (as written, quotes allowed) a command wrapper from the list above? #316
+function isWrapperWord(word) {
+  return Object.prototype.hasOwnProperty.call(WRAPPER_VALUE_FLAGS, dequote(word));
+}
+
 // Index just past a wrapper's own flags (and assignments), from the wrapper at toks[k].
 function skipWrapper(toks, k) {
   const w = dequote(toks[k]);
@@ -342,4 +347,4 @@ function unmodelledReason(guard, what, hit, redact) {
     `interpret with certainty, so it cannot verify ${what}. Rewrite it in a simple form: ${hit.hint}.`;
 }
 
-module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason };
+module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason, isWrapperWord };