@marcomigozzi/trailhead 0.14.0 → 0.16.0

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

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-uat-setup.js. Run: node uat-setup.test.js
+// No framework: plain asserts, same style as base-preflight.test.js. Real temp dirs.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-uat-setup.js');
+const { main, parseArgs } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, actual, expected) => {
+  assert.deepStrictEqual(actual, expected, `${name}: got ${JSON.stringify(actual)}, want ${JSON.stringify(expected)}`);
+  passed++;
+};
+
+const tmpDirs = [];
+const mktmp = () => {
+  const d = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-uat-setup-test-')));
+  tmpDirs.push(d);
+  return d;
+};
+const writeConfig = (root, obj) => {
+  fs.mkdirSync(path.join(root, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.trailhead', 'config.json'), typeof obj === 'string' ? obj : JSON.stringify(obj));
+};
+
+function run(argv, { env = {}, cwd = '/' } = {}) {
+  const chunks = [];
+  const errChunks = [];
+  const realErr = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (s) => { errChunks.push(String(s)); return true; };
+  let code;
+  try {
+    code = main(argv, { cwd, env: { HOME: '/nonexistent-home', ...env }, stdout: { write: (s) => chunks.push(s) } });
+  } finally {
+    process.stderr.write = realErr;
+  }
+  const lines = chunks.join('').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  return { code, out: lines[0], lines, err: errChunks.join('') };
+}
+
+const emptyHome = mktmp();
+const envNoGlobal = { CLAUDE_CONFIG_DIR: emptyHome };
+const plan = (dir, extra = [], env = {}) => run(['plan', '--repo', dir, ...extra], { env: { ...envNoGlobal, ...env } });
+const go = (dir, extra = [], env = {}) => run(['run', '--repo', dir, ...extra], { env: { ...envNoGlobal, ...env } });
+const proj = (cfg) => { const d = mktmp(); if (cfg !== undefined) writeConfig(d, cfg); return d; };
+
+// --- usage ----------------------------------------------------------------------
+{
+  ok('parseArgs: missing command', parseArgs([]).error);
+  ok('parseArgs: unknown command', parseArgs(['nope', '--repo', '/x']).error);
+  ok('parseArgs: missing --repo', parseArgs(['plan']).error);
+  ok('parseArgs: unknown flag', parseArgs(['plan', '--repo', '/x', '--bogus']).error);
+  ok('parseArgs: valueless flag', parseArgs(['plan', '--repo']).error);
+  ok('parseArgs: --only and --from are exclusive', parseArgs(['run', '--repo', '/x', '--only', '0', '--from', '1']).error);
+  ok('parseArgs: bad timeout', parseArgs(['run', '--repo', '/x', '--ready-timeout', 'abc']).error);
+  for (const v of ['Infinity', '1e999', '-1', '0', 'NaN']) {
+    ok(`parseArgs: --step-timeout ${v} rejected`, parseArgs(['run', '--repo', '/x', '--step-timeout', v]).error);
+    ok(`parseArgs: --ready-timeout ${v} rejected`, parseArgs(['run', '--repo', '/x', '--ready-timeout', v]).error);
+  }
+  ok('parseArgs: fractional timeout accepted', !parseArgs(['run', '--repo', '/x', '--step-timeout', '0.5']).error);
+  const inf = run(['run', '--repo', '/x', '--step-timeout', 'Infinity']);
+  eq('infinite timeout exits 2 with no stdout', [inf.code, inf.lines.length], [2, 0]);
+  const r = run([]);
+  eq('usage error exits 2', r.code, 2);
+  ok('usage error writes stderr, no stdout', r.err.includes('usage') && r.lines.length === 0);
+}
+
+// --- config reading -------------------------------------------------------------
+{
+  eq('unset: unconfigured', plan(proj()).out.status, 'unconfigured');
+  eq('no uat key: unconfigured', plan(proj({ testing: { webapp: true } })).out.status, 'unconfigured');
+  const none = plan(proj({ uat: { setup: [] } }));
+  eq('[]: none', [none.out.status, none.code], ['none', 0]);
+  eq('[]: run is none too', go(proj({ uat: { setup: [] } })).out.status, 'none');
+  eq('unconfigured run runs nothing', go(proj()).out.status, 'unconfigured');
+  const nested = plan(proj({ uat: { setup: [{ name: 'a', run: 'true' }] } }));
+  eq('nested: ready to plan', [nested.out.status, nested.out.steps.length], ['ready', 1]);
+  const flat = plan(proj({ 'uat.setup': [{ name: 'a', run: 'true' }, { name: 'b', run: 'true' }] }));
+  eq('flat: read', flat.out.steps.length, 2);
+  const both = plan(proj({ uat: { setup: [{ name: 'n', run: 'true' }] }, 'uat.setup': [{ name: 'f', run: 'true' }] }));
+  eq('both: nested wins', both.out.steps[0].name, 'n');
+  ok('both: a warning', both.out.warnings.some((w) => /nested/.test(w)));
+  const bad = plan(proj('{not json'));
+  eq('unparseable file: invalid', bad.out.status, 'invalid');
+}
+
+// --- project replaces global, key by key ----------------------------------------
+{
+  const home = mktmp();
+  fs.mkdirSync(path.join(home, 'trailhead'));
+  fs.writeFileSync(path.join(home, 'trailhead', 'config.json'), JSON.stringify({
+    uat: { setup: [{ name: 'global', run: 'true' }], accounts: { qa: { user: 'g@x.io', secret: '$G_PW' } } },
+  }));
+  const env = { CLAUDE_CONFIG_DIR: home };
+  const onlyGlobal = run(['plan', '--repo', proj()], { env });
+  eq('global only: setup from global', onlyGlobal.out.steps[0].name, 'global');
+  const p = proj({ uat: { setup: [{ name: 'project', run: 'true' }] } });
+  const mixed = run(['plan', '--repo', p], { env });
+  eq('project setup replaces global setup', mixed.out.steps.map((s) => s.name), ['project']);
+  eq('accounts still resolved from global', mixed.out.accounts.map((a) => a.role), ['qa']);
+  const empty = run(['plan', '--repo', proj({ uat: { setup: [] } })], { env });
+  eq('project [] replaces a global list', empty.out.status, 'none');
+  const wt = mktmp();
+  const viaRoot = run(['plan', '--repo', wt, '--config-root', p], { env });
+  eq('--config-root supplies the project file', viaRoot.out.steps[0].name, 'project');
+}
+
+// --- validation -----------------------------------------------------------------
+{
+  const invalid = (name, cfg) => {
+    const r = go(proj(cfg));
+    eq(`invalid: ${name}`, [r.out.status, r.code], ['invalid', 0]);
+    ok(`invalid: ${name} has a message`, typeof r.out.message === 'string' && r.out.message.length > 0);
+  };
+  invalid('setup not an array', { uat: { setup: 'make up' } });
+  invalid('step not an object', { uat: { setup: ['make up'] } });
+  invalid('step without run', { uat: { setup: [{ name: 'a' }] } });
+  invalid('step without name', { uat: { setup: [{ run: 'true' }] } });
+  invalid('empty name', { uat: { setup: [{ name: ' ', run: 'true' }] } });
+  invalid('non-string check', { uat: { setup: [{ name: 'a', run: 'true', check: 1 }] } });
+  invalid('unknown key', { uat: { setup: [{ name: 'a', run: 'true', extra: 1 }] } });
+  invalid('accounts not an object', { uat: { accounts: [] } });
+  invalid('uat is a string', { uat: 'x' });
+  invalid('uat is an array', { uat: [] });
+  invalid('uat is null', { uat: null });
+  invalid('account without secret', { uat: { setup: [], accounts: { qa: { user: 'u' } } } });
+  invalid('account without user', { uat: { setup: [], accounts: { qa: { secret: '$X' } } } });
+  invalid('literal secret rejected', { uat: { setup: [], accounts: { qa: { user: 'u', secret: 'hunter2' } } } });
+  invalid('secret embedded in text rejected', { uat: { setup: [], accounts: { qa: { user: 'u', secret: 'pw-$X' } } } });
+  invalid('unknown account key', { uat: { setup: [], accounts: { qa: { user: 'u', secret: '$X', extra: 1 } } } });
+  const okAcc = plan(proj({ uat: { setup: [], accounts: { qa: { user: 'u@x.io', secret: '${QA_PW}' }, dev: { user: '$DEV_USER', secret: '$DEV_PW' } } } }), [], { QA_PW: 'sekret-1' });
+  eq('literal user and bare refs accepted', okAcc.out.status, 'none');
+  // invalid accounts must not run an otherwise good setup
+  const marker = path.join(mktmp(), 'ran');
+  const r = go(proj({ uat: { setup: [{ name: 'a', run: `touch ${marker}` }], accounts: { qa: { user: 'u', secret: 'literal' } } } }));
+  eq('invalid accounts: nothing runs', [r.out.status, fs.existsSync(marker)], ['invalid', false]);
+}
+
+// --- plan -----------------------------------------------------------------------
+{
+  const d = proj({ uat: {
+    setup: [
+      { name: 'db', run: 'docker compose up -d db', check: 'true', note: 'ask before using the Pixel' },
+      { name: 'app', run: 'DEVICE=$ADB_DEVICE npm start --token ${API_TOKEN}' },
+    ],
+    accounts: { qa: { user: 'qa@x.io', secret: '$QA_PW' }, dev: { user: '$DEV_USER', secret: '${DEV_PW}' } },
+  } });
+  const r = plan(d, [], { ADB_DEVICE: 'emulator-5554', QA_PW: 'topsecret' });
+  eq('plan: steps', r.out.steps.map((s) => [s.index, s.name, s.note || null, s.check]), [[0, 'db', 'ask before using the Pixel', true], [1, 'app', null, false]]);
+  eq('plan: step env presence', r.out.steps[1].env, [{ name: 'ADB_DEVICE', set: true }, { name: 'API_TOKEN', set: false }]);
+  eq('plan: accounts', r.out.accounts, [
+    { role: 'qa', user: 'qa@x.io', userEnv: null, secretEnv: { name: 'QA_PW', set: true } },
+    { role: 'dev', user: null, userEnv: { name: 'DEV_USER', set: false }, secretEnv: { name: 'DEV_PW', set: false } },
+  ]);
+  ok('plan: never prints a value', !JSON.stringify(r.out).includes('emulator-5554') && !JSON.stringify(r.out).includes('topsecret'));
+  const marker = path.join(mktmp(), 'ran');
+  plan(proj({ uat: { setup: [{ name: 'a', run: `touch ${marker}` }] } }));
+  ok('plan never runs anything', !fs.existsSync(marker));
+}
+
+// --- run ------------------------------------------------------------------------
+{
+  const dir = mktmp();
+  const f = (n) => path.join(dir, n);
+  const d = proj({ uat: { setup: [
+    { name: 'up', run: `touch ${f('up')}`, check: `test -f ${f('up')}` },
+    { name: 'always', run: `echo x >> ${f('log')}` },
+  ] } });
+  const first = go(d);
+  eq('run: failing check runs the step, then ready', [first.out.status, first.out.steps.map((s) => s.result)], ['ready', ['ran', 'ran']]);
+  const second = go(d);
+  eq('run: passing check skips, no check always runs', second.out.steps.map((s) => s.result), ['skipped', 'ran']);
+  eq('run: always step ran twice', fs.readFileSync(f('log'), 'utf8').split('\n').filter(Boolean).length, 2);
+  ok('run: ok steps carry no output', second.out.steps.every((s) => s.output === undefined));
+}
+{
+  const dir = mktmp();
+  const f = (n) => path.join(dir, n);
+  const d = proj({ uat: { setup: [
+    { name: 's0', run: `touch ${f('s0')}` },
+    { name: 's1', run: 'echo boom-visible; exit 3' },
+    { name: 's2', run: `touch ${f('s2')}` },
+  ] } });
+  const r = go(d);
+  eq('failed: status and failedStep', [r.out.status, r.out.failedStep], ['failed', 1]);
+  eq('failed: step result carries code and output', [r.out.steps[1].result, r.out.steps[1].code, r.out.steps[1].output.trim()], ['failed', 3, 'boom-visible']);
+  eq('failed: stops at the first failure', [fs.existsSync(f('s0')), fs.existsSync(f('s2')), r.out.steps.length], [true, false, 2]);
+  fs.unlinkSync(f('s0'));
+  const from = go(d, ['--from', '1']);
+  eq('--from skips the earlier steps', [from.out.steps[0].index, fs.existsSync(f('s0'))], [1, false]);
+  const only = go(proj({ uat: { setup: [{ name: 'a', run: `touch ${f('oa')}` }, { name: 'b', run: `touch ${f('ob')}` }] } }), ['--only', '1']);
+  eq('--only runs exactly one', [only.out.status, only.out.steps.map((s) => s.index), fs.existsSync(f('oa')), fs.existsSync(f('ob'))], ['ready', [1], false, true]);
+  eq('--only out of range: invalid', go(d, ['--only', '9']).out.status, 'invalid');
+  const cwdProbe = go(proj({ uat: { setup: [{ name: 'cwd', run: 'pwd > cwd.txt' }] } }), []);
+  ok('run cwd is --repo', cwdProbe.out.status === 'ready');
+}
+{
+  const dir = mktmp();
+  const marker = path.join(dir, 'ran');
+  const d = proj({ uat: { setup: [
+    { name: 'needs', run: `touch ${marker}; echo $MISSING_ONE ${'${MISSING_TWO}'}`, check: 'false' },
+  ] } });
+  const r = go(d, [], { MISSING_ONE: '' });
+  eq('missing-env: failed and names the variables', [r.out.status, r.out.steps[0].result, r.out.steps[0].missing], ['failed', 'missing-env', ['MISSING_ONE', 'MISSING_TWO']]);
+  ok('missing-env runs nothing', !fs.existsSync(marker));
+}
+{
+  // shell-local $names are not env references: single quotes and \$ escape
+  const marker = path.join(mktmp(), 'ran');
+  const pl = plan(proj({ uat: { setup: [{ name: 'local', run: "for f in a b; do echo \\$f; done; awk '{print $NF}' </dev/null; echo '$QUOTED'; echo \\$ESC; echo \"\\$ESC2\"; echo $REAL", check: "echo '${Q2}' >/dev/null" }] } }), [], { REAL: 'v' });
+  eq('plan: only unquoted, unescaped refs listed', pl.out.steps[0].env.map((e) => e.name), ['REAL']);
+  const loc = go(proj({ uat: { setup: [{ name: 'local', run: `awk '{print $NF}' </dev/null; echo '$NOPE_UNSET' >/dev/null; echo \\$NOPE_UNSET2 >/dev/null; touch ${marker}` }] } }));
+  eq('run: single-quoted and escaped refs need no env', [loc.out.status, loc.out.steps[0].result, fs.existsSync(marker)], ['ready', 'ran', true]);
+  const dq = go(proj({ uat: { setup: [{ name: 'dq', run: 'echo "$DQ_MISSING"' }] } }));
+  eq('double-quoted ref still required', [dq.out.steps[0].result, dq.out.steps[0].missing], ['missing-env', ['DQ_MISSING']]);
+  const sq = go(proj({ uat: { setup: [{ name: 'sq', run: "echo 'it''s' $SQ_MISSING" }] } }));
+  eq('ref after adjacent quotes still required', sq.out.steps[0].missing, ['SQ_MISSING']);
+}
+{
+  // un commento di shell non apre span tra apici e i suoi riferimenti sono ignorati
+  const marker = path.join(mktmp(), 'ran');
+  const cm = go(proj({ uat: { setup: [{ name: 'cm', run: "# don't forget\necho dev=$DEVICE_ID" }] } }));
+  eq('apostrophe in a comment: later ref still required', [cm.out.steps[0].result, cm.out.steps[0].missing], ['missing-env', ['DEVICE_ID']]);
+  const cref = go(proj({ uat: { setup: [{ name: 'cref', run: `echo hi # uses $COMMENT_ONLY\ntouch ${marker}` }] } }));
+  eq('ref inside a comment is not required', [cref.out.steps[0].result, fs.existsSync(marker)], ['ran', true]);
+  const mid = go(proj({ uat: { setup: [{ name: 'mid', run: 'echo a#b $HASH_MISSING' }] } }));
+  eq('# not at a word start is no comment', mid.out.steps[0].missing, ['HASH_MISSING']);
+  const dqh = go(proj({ uat: { setup: [{ name: 'dqh', run: 'echo "# $DQH_MISSING"' }] } }));
+  eq('# inside double quotes is no comment', dqh.out.steps[0].missing, ['DQH_MISSING']);
+  // quote aperta a fine testo: fail closed, ogni riferimento conta
+  const open = go(proj({ uat: { setup: [{ name: 'open', run: "echo it's $OPEN_MISSING '$OPEN_QUOTED'" }] } }));
+  eq('unbalanced single quote: every ref required', open.out.steps[0].missing, ['OPEN_MISSING', 'OPEN_QUOTED']);
+  const openD = go(proj({ uat: { setup: [{ name: 'openD', run: "echo \"x $OPEND_MISSING '$OPEND_Q'" }] } }));
+  eq('unbalanced double quote: every ref required', openD.out.steps[0].missing, ['OPEND_MISSING', 'OPEND_Q']);
+}
+{
+  const big = parseArgs(['run', '--repo', '/x', '--step-timeout', '86401']);
+  ok('parseArgs: --step-timeout above 86400 rejected', big.error);
+  ok('parseArgs: --ready-timeout above 86400 rejected', parseArgs(['run', '--repo', '/x', '--ready-timeout', '86401']).error);
+  ok('parseArgs: 86400 accepted', !parseArgs(['run', '--repo', '/x', '--step-timeout', '86400', '--ready-timeout', '86400']).error);
+  eq('oversized timeout exits 2', run(['run', '--repo', '/x', '--ready-timeout', '999999']).code, 2);
+}
+{
+  // a tiny fractional timeout still becomes a valid >= 1 ms spawn timeout
+  const r = go(proj({ uat: { setup: [{ name: 'hang', run: 'sleep 30' }] } }), ['--step-timeout', '0.0001']);
+  eq('sub-millisecond timeout: timeout result', r.out.steps[0].result, 'timeout');
+}
+{
+  // a mid-run exception keeps the steps already collected
+  const gone = mktmp();
+  const prev = process.env.TMPDIR;
+  process.env.TMPDIR = gone;
+  try {
+    const r = go(proj({ uat: { setup: [
+      { name: 'a', run: 'true', check: `rm -rf ${gone}` },
+      { name: 'b', run: 'true' },
+    ] } }));
+    eq('mid-run exception: invalid with message', [r.out.status, typeof r.out.message], ['invalid', 'string']);
+    eq('mid-run exception: collected steps kept', r.out.steps.map((s) => [s.index, s.result]), [[0, 'skipped']]);
+  } finally {
+    if (prev === undefined) delete process.env.TMPDIR; else process.env.TMPDIR = prev;
+  }
+}
+{
+  // the poll after run caps each check at the remaining ready time
+  const dir = mktmp();
+  const t0 = Date.now();
+  const r = go(proj({ uat: { setup: [{ name: 'slow', run: `touch ${dir}/ran`, check: `test -f ${dir}/ran && sleep 30` }] } }), ['--ready-timeout', '1']);
+  eq('slow check while polling: not-ready', r.out.steps[0].result, 'not-ready');
+  ok('poll check capped at the remaining ready time', Date.now() - t0 < 8000);
+}
+{
+  // not-ready: the run succeeds but the check never passes
+  const d = proj({ uat: { setup: [{ name: 'srv', run: 'true', check: 'false' }] } });
+  const t0 = Date.now();
+  const r = go(d, ['--ready-timeout', '1']);
+  eq('not-ready', [r.out.status, r.out.steps[0].result], ['failed', 'not-ready']);
+  ok('not-ready waited for the timeout', Date.now() - t0 >= 900);
+  // ready after a delayed check
+  const dir = mktmp();
+  const d2 = proj({ uat: { setup: [{ name: 'srv', run: `(sleep 1; touch ${dir}/up) >/dev/null 2>&1 &`, check: `test -f ${dir}/up` }] } });
+  const r2 = go(d2, ['--ready-timeout', '10']);
+  eq('a backgrounded process is detected through check', [r2.out.status, r2.out.steps[0].result], ['ready', 'ran']);
+}
+{
+  // timeouts
+  const t0 = Date.now();
+  const r = go(proj({ uat: { setup: [{ name: 'hang', run: 'sleep 30' }] } }), ['--step-timeout', '1']);
+  eq('hung run: timeout', [r.out.status, r.out.steps[0].result], ['failed', 'timeout']);
+  ok('hung run killed promptly', Date.now() - t0 < 10000);
+  // a hung check counts as failing before run: the step runs
+  const dir = mktmp();
+  const r2 = go(proj({ uat: { setup: [{ name: 'c', run: `touch ${dir}/ran`, check: 'sleep 30' }] } }), ['--step-timeout', '1', '--ready-timeout', '1']);
+  eq('hung check before run: step runs', fs.existsSync(path.join(dir, 'ran')), true);
+  eq('hung check while polling: not-ready', r2.out.steps[0].result, 'not-ready');
+  // a backgrounded child holding stdout must not hang the helper
+  const t1 = Date.now();
+  const r3 = go(proj({ uat: { setup: [{ name: 'bg', run: 'sleep 4 &' }] } }));
+  eq('background child does not block', r3.out.status, 'ready');
+  ok('returns before the background child ends', Date.now() - t1 < 3500);
+}
+{
+  // output: bounded tail and redaction
+  const big = go(proj({ uat: { setup: [{ name: 'big', run: 'yes aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | head -c 20000000; exit 1' }] } }));
+  ok('large output stays bounded', big.out.steps[0].output.length <= 2100);
+  const red = go(proj({ uat: {
+    setup: [{ name: 'leak', run: 'echo "token=$API_TOKEN pw=$QA_PW"; exit 1' }],
+    accounts: { qa: { user: 'u', secret: '$QA_PW' } },
+  } }), [], { API_TOKEN: 'abc123', QA_PW: 'zzz-secret' });
+  const o = red.out.steps[0].output;
+  ok('output redacts referenced values to $NAME', o.includes('token=$API_TOKEN') && o.includes('pw=$QA_PW') && !o.includes('abc123') && !o.includes('zzz-secret'));
+  const overlap = go(proj({ uat: { setup: [{ name: 'o', run: 'echo $SHORT $LONG; exit 1' }] } }), [], { SHORT: 'abc', LONG: 'abcdef' });
+  const oo = overlap.out.steps[0].output;
+  ok('overlapping values redact whole (longest first)', oo.includes('$SHORT $LONG') && !oo.includes('def'));
+}
+
+// --- end to end -----------------------------------------------------------------
+{
+  const d = proj({ uat: { setup: [{ name: 'a', run: 'true' }] } });
+  const out = execFileSync('node', [scriptPath, 'run', '--repo', d], {
+    env: { ...process.env, CLAUDE_CONFIG_DIR: emptyHome, HOME: '/nonexistent-home' },
+  }).toString();
+  const parsed = JSON.parse(out.trim());
+  eq('e2e: ready', parsed.status, 'ready');
+  eq('e2e: one JSON line', out.trim().split('\n').length, 1);
+  let code = 0;
+  try { execFileSync('node', [scriptPath], { stdio: 'ignore' }); } catch (err) { code = err.status; }
+  eq('e2e: usage error exits 2', code, 2);
+  ok('e2e: helper is executable', (fs.statSync(scriptPath).mode & 0o111) !== 0);
+}
+
+// --- cleanup --------------------------------------------------------------------
+for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true });
+
+console.log(`uat-setup.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/work-state.test.js

@@ -213,6 +213,51 @@ for (const argv of [
   ok('clear absent: absent, exit 0', r2.code === 0 && r2.lines[0].status === 'absent');
 }
 
+// --- clear also removes the session-ticket marker (#253) ---------------------
+{
+  const ticketPath = (dir) => path.join(dir, '.trailhead', 'session-ticket');
+  const seed = (dir, { state, marker }) => {
+    fs.mkdirSync(path.join(dir, '.trailhead'), { recursive: true });
+    if (state) fs.writeFileSync(statePath(dir), '{}');
+    if (marker) fs.writeFileSync(ticketPath(dir), '253\n');
+  };
+  const combos = [
+    [true, true, 'cleared', 'removed'],
+    [true, false, 'cleared', 'absent'],
+    [false, true, 'absent', 'removed'],
+    [false, false, 'absent', 'absent'],
+  ];
+  for (const [state, marker, wantStatus, wantMarker] of combos) {
+    const dir = mktmp();
+    seed(dir, { state, marker });
+    const r = run(['clear', '--repo', dir], { cwd: '/' });
+    ok(`clear state=${state} marker=${marker}: exit 0, one line`, r.code === 0 && r.lines.length === 1);
+    ok(`clear state=${state} marker=${marker}: status ${wantStatus}`, r.lines[0].status === wantStatus);
+    ok(`clear state=${state} marker=${marker}: sessionTicket ${wantMarker}`, r.lines[0].sessionTicket === wantMarker);
+    ok(`clear state=${state} marker=${marker}: both files gone`, !fs.existsSync(statePath(dir)) && !fs.existsSync(ticketPath(dir)));
+  }
+  // partial failure: the first removal throws, the second still runs
+  {
+    const dir = mktmp();
+    seed(dir, { state: true, marker: true });
+    const broken = { ...fs, unlinkSync: (p) => { if (p === statePath(dir)) throw new Error('boom state'); return fs.unlinkSync(p); } };
+    const r = run(['clear', '--repo', dir], { cwd: '/', fsMod: broken });
+    ok('clear partial failure: exit 0', r.code === 0);
+    ok('clear partial failure: state skipped with message', r.lines[0].status === 'skipped' && /boom state/.test(r.lines[0].message));
+    ok('clear partial failure: marker still removed', r.lines[0].sessionTicket === 'removed' && !fs.existsSync(ticketPath(dir)));
+    ok('clear partial failure: state file kept', fs.existsSync(statePath(dir)));
+  }
+  // the marker failing never skips the work-state removal
+  {
+    const dir = mktmp();
+    seed(dir, { state: true, marker: true });
+    const broken = { ...fs, unlinkSync: (p) => { if (p === ticketPath(dir)) throw new Error('boom marker'); return fs.unlinkSync(p); } };
+    const r = run(['clear', '--repo', dir], { cwd: '/', fsMod: broken });
+    ok('clear marker failure: state cleared, marker skipped', r.code === 0 && r.lines[0].status === 'cleared' && r.lines[0].sessionTicket === 'skipped');
+    ok('clear marker failure: state file gone', !fs.existsSync(statePath(dir)));
+  }
+}
+
 // --- pure functions ----------------------------------------------------------
 {
   ok('sanitizeState: non-object -> {}', JSON.stringify(sanitizeState(null)) === '{}' && JSON.stringify(sanitizeState('x')) === '{}');