@marcomigozzi/trailhead 0.15.0 → 0.16.0

package/plugins/trailhead/hooks/lib/auto-slot.test.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-auto-slot.js. Run: node auto-slot.test.js
+// No framework: plain asserts, same style as auto-queue.test.js.
+//
+// Layers covered:
+//   1. main() open / list against REAL temporary git repos (the default git runner).
+//   2. Usage errors (exit 2).
+//   3. End-to-end: the script itself through spawnSync.
+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-auto-slot.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const git = (cwd, ...args) => {
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr}`);
+  return r.stdout.trim();
+};
+
+// A parent dir holding <parent>/repo with two commits. Returns { parent, repo, first, second }.
+function makeRepo() {
+  const parent = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'auto-slot-')));
+  const repo = path.join(parent, 'repo');
+  fs.mkdirSync(repo);
+  git(repo, 'init', '-q', '-b', 'main');
+  git(repo, 'config', 'user.name', 'T');
+  git(repo, 'config', 'user.email', 't@example.com');
+  git(repo, 'config', 'commit.gpgsign', 'false');
+  fs.writeFileSync(path.join(repo, 'a.txt'), 'one\n');
+  git(repo, 'add', 'a.txt');
+  git(repo, 'commit', '-q', '-m', 'first');
+  const first = git(repo, 'rev-parse', 'HEAD');
+  fs.writeFileSync(path.join(repo, 'a.txt'), 'two\n');
+  git(repo, 'commit', '-q', '-am', 'second');
+  const second = git(repo, 'rev-parse', 'HEAD');
+  return { parent, repo, first, second };
+}
+
+function run(argv, deps = {}) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } }, ...deps });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json, errOut };
+}
+
+const open = (repo, n, base, deps) => run(['open', '--repo', repo, '--ticket', String(n), '--base', base], deps);
+const list = (repo, deps) => run(['list', '--repo', repo], deps);
+
+// --- open: created -----------------------------------------------------------
+{
+  const { parent, repo, first, second } = makeRepo();
+  const r = open(repo, 7, first);
+  const wt = path.join(parent, 'repo-t7');
+  ok('open: created exits 0', r.code === 0);
+  ok('open: created status, ticket, branch, path', r.json.status === 'created' && r.json.ticket === 7 && r.json.branch === 'trailhead/t7' && r.json.path === wt);
+  ok('open: the worktree directory exists', fs.existsSync(path.join(wt, 'a.txt')));
+  ok('open: branch points exactly at --base', git(repo, 'rev-parse', 'refs/heads/trailhead/t7') === first);
+  ok('open: branch is not the repo HEAD', git(repo, 'rev-parse', 'refs/heads/trailhead/t7') !== second && git(repo, 'rev-parse', 'HEAD') === second);
+  ok('open: worktree checked out on the branch', git(wt, 'rev-parse', '--abbrev-ref', 'HEAD') === 'trailhead/t7');
+
+  // reentered: same call again, nothing new created
+  const again = open(repo, 7, second);
+  ok('open: reentered when the branch is already checked out there', again.code === 0 && again.json.status === 'reentered' && again.json.path === wt);
+  ok('open: reentered does not move the branch', git(repo, 'rev-parse', 'refs/heads/trailhead/t7') === first);
+
+  // reattached: worktree removed, branch kept
+  git(repo, 'worktree', 'remove', '--force', wt);
+  const re = open(repo, 7, second);
+  ok('open: reattached when the branch exists without a worktree', re.code === 0 && re.json.status === 'reattached' && re.json.path === wt);
+  ok('open: reattached keeps the branch commit', git(repo, 'rev-parse', 'refs/heads/trailhead/t7') === first && git(wt, 'rev-parse', 'HEAD') === first);
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- open: branch checked out at another path -> reentered with that path ---
+{
+  const { parent, repo, first } = makeRepo();
+  const other = path.join(parent, 'elsewhere');
+  git(repo, 'worktree', 'add', '-q', '-b', 'trailhead/t9', other, first);
+  const r = open(repo, 9, first);
+  ok('open: a hand-made worktree elsewhere is reentered with its path', r.code === 0 && r.json.status === 'reentered' && r.json.path === other);
+  ok('open: nothing created at the sibling path', !fs.existsSync(path.join(parent, 'repo-t9')));
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- open: path collision ----------------------------------------------------
+{
+  const { parent, repo, first } = makeRepo();
+  const target = path.join(parent, 'repo-t3');
+  fs.mkdirSync(target);
+  fs.writeFileSync(path.join(target, 'keep.txt'), 'mine\n');
+  const r = open(repo, 3, first);
+  ok('open: existing path is an error', r.code === 1 && r.json.status === 'error' && /exist/.test(r.json.reason));
+  ok('open: existing path is never overwritten', fs.readFileSync(path.join(target, 'keep.txt'), 'utf8') === 'mine\n');
+  ok('open: no branch created on a path collision', spawnSync('git', ['-C', repo, 'rev-parse', '--verify', '--quiet', 'refs/heads/trailhead/t3']).status !== 0);
+
+  // reattach into an occupied path is an error too
+  git(repo, 'branch', 'trailhead/t4', first);
+  fs.mkdirSync(path.join(parent, 'repo-t4'));
+  const r4 = open(repo, 4, first);
+  ok('open: reattach onto an existing path is an error', r4.code === 1 && r4.json.status === 'error');
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- open: invalid base ------------------------------------------------------
+{
+  const { parent, repo } = makeRepo();
+  const r = open(repo, 5, 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef');
+  ok('open: unresolvable base is an error', r.code === 1 && r.json.status === 'error' && /base/.test(r.json.reason));
+  ok('open: nothing created for an invalid base', !fs.existsSync(path.join(parent, 'repo-t5')));
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- open: clone-required on a superrepo -------------------------------------
+{
+  const { parent, repo, first } = makeRepo();
+  fs.writeFileSync(path.join(repo, '.gitmodules'), '[submodule "lib"]\n\tpath = lib\n\turl = https://example.com/lib.git\n');
+  const r = open(repo, 8, first);
+  ok('open: a declared submodule needs a clone', r.code === 0 && r.json.status === 'clone-required' && r.json.path === path.join(parent, 'repo-t8') && r.json.branch === 'trailhead/t8');
+  ok('open: clone-required creates no worktree', !fs.existsSync(path.join(parent, 'repo-t8')));
+  fs.writeFileSync(path.join(repo, '.gitmodules'), '# nothing declared\n');
+  const none = open(repo, 8, first);
+  ok('open: a .gitmodules without a submodule section does not force a clone', none.json.status === 'created');
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- list --------------------------------------------------------------------
+{
+  const { parent, repo, first, second } = makeRepo();
+  ok('list: a repo with no slot is empty', list(repo).json.slots.length === 0);
+
+  open(repo, 12, first);
+  open(repo, 4, second);
+  // worktree on a non-slot branch is not a slot
+  git(repo, 'worktree', 'add', '-q', '-b', 'feature/x', path.join(parent, 'feature-x'), first);
+
+  // a sibling clone on trailhead/t21
+  const clone = path.join(parent, 'repo-t21');
+  git(parent, 'clone', '-q', repo, clone);
+  git(clone, 'config', 'user.name', 'T');
+  git(clone, 'config', 'user.email', 't@example.com');
+  git(clone, 'checkout', '-q', '-b', 'trailhead/t21', first);
+  // a sibling clone on the wrong branch is ignored
+  const wrong = path.join(parent, 'repo-t22');
+  git(parent, 'clone', '-q', repo, wrong);
+  git(wrong, 'checkout', '-q', '-b', 'trailhead/t99');
+  // a sibling dir that is not a git checkout is ignored
+  fs.mkdirSync(path.join(parent, 'repo-t30'));
+  // a sibling dir inside another checkout (no own git dir) is ignored
+  fs.mkdirSync(path.join(repo, 'repo-t31'));
+
+  const wt12 = path.join(parent, 'repo-t12');
+  const wt4 = path.join(parent, 'repo-t4');
+  // work state: present on t12, unparseable on t4, absent on the clone
+  fs.mkdirSync(path.join(wt12, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(wt12, '.trailhead', 'work-state.json'), JSON.stringify({ ticket: 12, auto: true }));
+  fs.mkdirSync(path.join(wt4, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(wt4, '.trailhead', 'work-state.json'), '{not json');
+  // dirty: t12 has an untracked file (.trailhead is untracked too, so both worktrees are dirty); clone is clean
+  fs.writeFileSync(path.join(wt12, 'new.txt'), 'x\n');
+
+  const r = list(repo);
+  ok('list: exits 0 with status ok', r.code === 0 && r.json.status === 'ok');
+  ok('list: slots sorted by ticket', JSON.stringify(r.json.slots.map((s) => s.ticket)) === JSON.stringify([4, 12, 21]));
+  const by = Object.fromEntries(r.json.slots.map((s) => [s.ticket, s]));
+  ok('list: worktree kind, branch and path', by[12].kind === 'worktree' && by[12].branch === 'trailhead/t12' && by[12].path === wt12);
+  ok('list: sibling clone is listed as clone', by[21].kind === 'clone' && by[21].branch === 'trailhead/t21' && by[21].path === clone);
+  ok('list: non-slot worktree, wrong-branch clone, non-git dir and nested dir are ignored', !r.json.slots.some((s) => [99, 30, 31].includes(s.ticket)) && r.json.slots.length === 3);
+  ok('list: work state present is parsed', by[12].workState && by[12].workState.ticket === 12 && by[12].workState.auto === true);
+  ok('list: work state absent is null without a warning', by[21].workState === null && !r.json.warnings.some((w) => w.includes('repo-t21')));
+  ok('list: unparseable work state is null plus a warning', by[4].workState === null && r.json.warnings.length === 1 && r.json.warnings[0].includes('repo-t4'));
+  ok('list: dirty detected', by[12].dirty === true);
+  ok('list: a clean checkout is not dirty', by[21].dirty === false);
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- W1: stale worktree (directory deleted by hand) --------------------------
+{
+  const { parent, repo, first } = makeRepo();
+  open(repo, 6, first);
+  open(repo, 7, first);
+  const wt = path.join(parent, 'repo-t6');
+  fs.rmSync(wt, { recursive: true, force: true });
+  const r = open(repo, 6, first);
+  ok('open: a stale worktree is an error naming it and git worktree prune', r.code === 1 && r.json.status === 'error' && r.json.reason.includes(wt) && /stale/.test(r.json.reason) && r.json.reason.includes('git worktree prune'));
+  ok('open: a stale worktree is not pruned automatically', git(repo, 'worktree', 'list', '--porcelain').includes(wt));
+  const l = list(repo);
+  ok('list: a stale worktree is kept out of slots', l.code === 0 && JSON.stringify(l.json.slots.map((x) => x.ticket)) === JSON.stringify([7]));
+  ok('list: a stale worktree is a warning naming it and suggesting prune', l.json.warnings.length === 1 && l.json.warnings[0].includes(wt) && /stale/.test(l.json.warnings[0]) && l.json.warnings[0].includes('git worktree prune'));
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- W2: superrepo with an existing slot path --------------------------------
+{
+  const { parent, repo, first } = makeRepo();
+  fs.writeFileSync(path.join(repo, '.gitmodules'), '[submodule "lib"]\n\tpath = lib\n\turl = https://example.com/lib.git\n');
+  const target = path.join(parent, 'repo-t8');
+  const missing = open(repo, 8, first);
+  ok('open: missing path on a superrepo is clone-required with kind clone', missing.json.status === 'clone-required' && missing.json.kind === 'clone');
+
+  fs.mkdirSync(target);
+  fs.writeFileSync(path.join(target, 'keep.txt'), 'mine\n');
+  const plain = open(repo, 8, first);
+  ok('open: a plain existing dir on a superrepo is an error, never clone-required', plain.code === 1 && plain.json.status === 'error');
+  ok('open: the existing dir is untouched', fs.readFileSync(path.join(target, 'keep.txt'), 'utf8') === 'mine\n');
+  fs.rmSync(target, { recursive: true, force: true });
+
+  git(parent, 'clone', '-q', repo, target);
+  git(target, 'checkout', '-q', '-b', 'trailhead/t8', first);
+  const clone = open(repo, 8, first);
+  ok('open: an existing clone on the slot branch is reentered with kind clone', clone.code === 0 && clone.json.status === 'reentered' && clone.json.kind === 'clone' && clone.json.path === target && clone.json.branch === 'trailhead/t8');
+
+  git(target, 'checkout', '-q', '-b', 'other');
+  const wrong = open(repo, 8, first);
+  ok('open: an existing clone on another branch is an error', wrong.code === 1 && wrong.json.status === 'error');
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+{
+  const { parent, repo, first } = makeRepo();
+  ok('open: worktree statuses carry kind worktree', open(repo, 1, first).json.kind === 'worktree' && open(repo, 1, first).json.kind === 'worktree');
+  git(repo, 'worktree', 'remove', '--force', path.join(parent, 'repo-t1'));
+  const rea = open(repo, 1, first);
+  ok('open: reattached carries kind worktree', rea.json.status === 'reattached' && rea.json.kind === 'worktree');
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+// --- list: a git failure on the main repo ------------------------------------
+{
+  const notRepo = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'auto-slot-nr-')));
+  const r = list(notRepo);
+  ok('list: git failing on the main repo is an error', r.code === 1 && r.json.status === 'error');
+  fs.rmSync(notRepo, { recursive: true, force: true });
+}
+
+// --- injectable git runner ---------------------------------------------------
+{
+  const calls = [];
+  const fake = (args) => { calls.push(args.join(' ')); return { status: 1, stdout: '', stderr: 'boom' }; };
+  const r = list('/nowhere/repo', { git: fake });
+  ok('seam: injected git runner is used and its failure is an error', r.code === 1 && r.json.status === 'error' && calls.length >= 1 && calls[0].startsWith('-C /nowhere/repo'));
+}
+
+// --- usage errors ------------------------------------------------------------
+{
+  const u = (argv) => run(argv);
+  ok('usage: no command exits 2', u([]).code === 2);
+  ok('usage: unknown command exits 2', u(['remove', '--repo', '/x']).code === 2);
+  ok('usage: open without --ticket exits 2', u(['open', '--repo', '/x', '--base', 'abc']).code === 2);
+  ok('usage: open without --base exits 2', u(['open', '--repo', '/x', '--ticket', '3']).code === 2);
+  ok('usage: open without --repo exits 2', u(['open', '--ticket', '3', '--base', 'abc']).code === 2);
+  ok('usage: bad --ticket exits 2', u(['open', '--repo', '/x', '--ticket', 'x', '--base', 'abc']).code === 2);
+  ok('usage: list without --repo exits 2', u(['list']).code === 2);
+  ok('usage: unknown flag exits 2', u(['list', '--repo', '/x', '--bogus', '1']).code === 2);
+  ok('usage: errors go to stderr, stdout stays empty', u(['open']).errOut.startsWith('usage:') && u(['open']).out === '');
+}
+
+// --- end-to-end --------------------------------------------------------------
+{
+  const { parent, repo, first } = makeRepo();
+  const res = spawnSync('node', [scriptPath, 'open', '--repo', repo, '--ticket', '15', '--base', first], { encoding: 'utf8' });
+  const j = JSON.parse(res.stdout.trim());
+  ok('e2e: open prints one JSON line and exits 0', res.status === 0 && j.status === 'created' && j.path === path.join(parent, 'repo-t15'));
+  const ls = spawnSync('node', [scriptPath, 'list', '--repo', repo], { encoding: 'utf8' });
+  const lj = JSON.parse(ls.stdout.trim());
+  ok('e2e: list finds the new slot', ls.status === 0 && lj.slots.length === 1 && lj.slots[0].ticket === 15);
+  ok('e2e: usage error exits 2', spawnSync('node', [scriptPath, '--bogus'], { encoding: 'utf8' }).status === 2);
+  fs.rmSync(parent, { recursive: true, force: true });
+}
+
+console.log(`auto-slot.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/checkout-in.test.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-checkout-in.js. Run: node checkout-in.test.js
+// No framework: plain asserts, same style as uat-backfill.test.js.
+//
+// Layers covered:
+//   1. The pure token helpers: encode / decode round-trip.
+//   2. The CLI against real temp git repos: invalid, here, move, the `cd` field.
+//   3. The protocol contract: the work skill moves before it loads or preflights.
+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-checkout-in.js');
+const skillPath = path.resolve(__dirname, '..', '..', 'skills', 'trailhead-work', 'SKILL.md');
+const { encodeIn, decodeIn } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, a, b) => { assert.deepStrictEqual(a, b, name); passed++; };
+
+const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'checkout-in-')));
+const sh = (cwd, ...args) => {
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  assert.strictEqual(r.status, 0, `git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout;
+};
+function makeRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  sh(dir, 'init', '-q', '-b', 'main');
+  sh(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init');
+  return fs.realpathSync(dir);
+}
+const run = (inArg, cwd) => {
+  const r = spawnSync(process.execPath, [scriptPath, '--in', inArg, '--cwd', cwd], { encoding: 'utf8' });
+  return { code: r.status, out: r.stdout.trim() ? JSON.parse(r.stdout.trim()) : null, err: r.stderr };
+};
+const tokenOf = (p) => encodeIn(p).slice('--in='.length);
+
+// --- 1. pure helpers ---------------------------------------------------------------
+const odd = [
+  '/tmp/with space/repo',
+  "/tmp/it's/repo",
+  '/tmp/"dq"/repo',
+  '/tmp/-leading/repo',
+  '-dash-first',
+  '/tmp/uniè中文/repo',
+  "/tmp/a'b'c d/$HOME/`x`",
+];
+for (const p of odd) {
+  const enc = encodeIn(p);
+  ok(`token shape ${p}`, /^--in=[A-Za-z0-9_-]+$/.test(enc));
+  eq(`round-trip ${p}`, decodeIn(enc.slice(5)), p);
+}
+eq('decode of garbage', decodeIn('!!!'), null);
+eq('decode of empty', decodeIn(''), null);
+
+// --- 2. CLI ------------------------------------------------------------------------
+const main = makeRepo(path.join(tmp, 'main repo'));
+const other = makeRepo(path.join(tmp, 'other'));
+const plain = path.join(tmp, 'plain');
+fs.mkdirSync(plain);
+
+{
+  const r = run(tokenOf(main), main);
+  eq('here in the root', [r.code, r.out.status, r.out.path], [0, 'here', main]);
+}
+{
+  fs.mkdirSync(path.join(main, 'sub'));
+  const r = run(tokenOf(main), path.join(main, 'sub'));
+  eq('here from a subdir of the same checkout', r.out.status, 'here');
+}
+{
+  const r = run(tokenOf(main), other);
+  eq('move from another repo', [r.code, r.out.status, r.out.path], [0, 'move', main]);
+  ok('move carries a cd', r.out.cd === `cd -- '${main}'`);
+}
+{
+  const r = run(tokenOf(main), plain);
+  eq('move from outside any repo', r.out.status, 'move');
+}
+{
+  const r = run(tokenOf(main), path.join(tmp, 'missing-cwd'));
+  eq('move from a cwd that does not exist', r.out.status, 'move');
+}
+
+// A worktree root is its own checkout: here only for itself.
+{
+  const wt = path.join(tmp, 'wt');
+  sh(main, 'worktree', 'add', '-q', '-b', 'wt-branch', wt);
+  const wtReal = fs.realpathSync(wt);
+  eq('worktree root is here for itself', run(tokenOf(wtReal), wtReal).out.status, 'here');
+  eq('worktree root is move from the main checkout', run(tokenOf(wtReal), main).out.status, 'move');
+  eq('main checkout is move from the worktree', run(tokenOf(main), wtReal).out.status, 'move');
+}
+
+// A symlinked path compares canonical.
+{
+  const link = path.join(tmp, 'link-to-main');
+  fs.symlinkSync(main, link);
+  const r = run(tokenOf(link), main);
+  eq('symlinked path is here by canonical compare', r.out.status, 'here');
+  eq('symlinked cwd is here too', run(tokenOf(main), link).out.status, 'here');
+}
+
+// invalid: never searches for another checkout.
+{
+  eq('relative path is invalid', run(tokenOf('relative/dir'), main).out.status, 'invalid');
+  eq('missing path is invalid', run(tokenOf(path.join(tmp, 'nope')), main).out.status, 'invalid');
+  eq('non-repo dir is invalid', run(tokenOf(plain), main).out.status, 'invalid');
+  eq('subdir of a repo is invalid (not a root)', run(tokenOf(path.join(main, 'sub')), other).out.status, 'invalid');
+  const bad = run('!!!', main);
+  eq('undecodable token is invalid', [bad.code, bad.out.status], [0, 'invalid']);
+  ok('invalid has a reason', typeof bad.out.reason === 'string' && bad.out.reason.length > 0);
+  ok('invalid has no cd', !('cd' in run(tokenOf(plain), main).out));
+}
+
+// usage errors
+{
+  const r = spawnSync(process.execPath, [scriptPath, '--cwd', main], { encoding: 'utf8' });
+  eq('missing --in is a usage error', r.status, 2);
+  const r2 = spawnSync(process.execPath, [scriptPath, '--in', tokenOf(main)], { encoding: 'utf8' });
+  eq('missing --cwd is a usage error', r2.status, 2);
+}
+
+// The cd field, run by a shell, lands in the path for every pathological case.
+{
+  let n = 0;
+  for (const p of odd) {
+    if (!path.isAbsolute(p)) continue;
+    const dir = path.join(tmp, `odd${n++}`, p.replace(/^\/tmp\//, '').replace(/\//g, '_'));
+    const real = makeRepo(dir);
+    const r = run(tokenOf(real), plain);
+    eq(`move for ${dir}`, r.out.status, 'move');
+    const cd = spawnSync('sh', ['-c', `${r.out.cd} && pwd -P`], { encoding: 'utf8', cwd: plain });
+    eq(`cd lands in ${dir}`, cd.stdout.trim(), real);
+  }
+  // A quote and a leading dash in the actual directory names.
+  for (const name of ["it's here", '-dash', 'sp ace "dq" $x `y`']) {
+    const real = makeRepo(path.join(tmp, 'pathological', name));
+    const r = run(tokenOf(real), plain);
+    const cd = spawnSync('sh', ['-c', `${r.out.cd} && pwd -P`], { encoding: 'utf8', cwd: plain });
+    eq(`cd lands in ${name}`, cd.stdout.trim(), real);
+  }
+}
+
+// --- 3. protocol contract: the move comes before anything else -----------------------
+{
+  const skill = fs.readFileSync(skillPath, 'utf8');
+  const move = skill.indexOf('## Move into the handed checkout');
+  ok('move section exists', move >= 0);
+  const load = skill.indexOf('## Load first');
+  const pre = skill.indexOf('## Preflight');
+  ok('move section sits before Load first', load > move);
+  ok('move section sits before the Preflight', pre > move);
+  const section = skill.slice(move, load);
+  ok('names the helper', section.includes('trailhead-checkout-in.js'));
+  ok('names the --in= word', section.includes('--in='));
+  ok('names work and resume', /`work`/.test(section) && /`resume`/.test(section));
+  ok('runs the cd field verbatim', /`cd` field[^.]*verbatim/.test(section));
+  ok('cd is its own Bash call', /own Bash call/.test(section));
+  ok('post-move re-check requires here', /re-run the helper/.test(section) && /`here`/.test(section));
+  ok('stops on invalid', /`invalid`[^.]*stop/.test(section));
+  ok('stops on a failed cd', /failed `cd`[^.]*stop|`cd` fails[^.]*stop|stop[^.]*`cd` fail/i.test(section));
+  ok('stops when the post-check is not here', /could not move/.test(section));
+  ok('stops when the helper is missing', /missing[^.]*stop|stop[^.]*missing/i.test(section));
+  ok('never moves by hand', /by hand/.test(section));
+  ok('Routing points at the move section', /Routing[\s\S]*Move into the handed checkout/.test(skill.slice(skill.indexOf('## Routing'))));
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`checkout-in: ${passed} assertions passed`);

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

@@ -131,6 +131,8 @@ function makeTracker(init = {}) {
     created: [],
     pins: [],
     failOn: init.failOn || null,
+    // extra open issues per singleton label (duplicates): { label: [{ number, title }] }
+    dups: init.dups || {},
   };
   const ok_ = (stdout) => ({ status: 0, stdout, stderr: '' });
   t.gh = (args) => {
@@ -150,9 +152,11 @@ function makeTracker(init = {}) {
       }
       if (label === 'trailhead:whiteboard' && state === 'open') return ok_(JSON.stringify(t.whiteboardOpen));
       if (label === 'trailhead:whiteboard' && state === 'closed') return ok_(JSON.stringify(t.closed));
-      if (label === 'trailhead:codebase') return ok_(JSON.stringify(t.codebase ? [{ number: t.codebase }] : []));
-      if (label === 'trailhead:conventions') return ok_(JSON.stringify(t.conventions ? [{ number: t.conventions }] : []));
-      if (label === 'trailhead:dashboard') return ok_(JSON.stringify(t.dash ? [{ number: t.dash.number }] : []));
+      const lim = Number(args[args.indexOf('--limit') + 1]);
+      const extra = (t.dups[label] || []);
+      if (label === 'trailhead:codebase') return ok_(JSON.stringify((t.codebase ? [{ number: t.codebase, title: 'Codebase' }] : []).concat(extra).slice(0, lim)));
+      if (label === 'trailhead:conventions') return ok_(JSON.stringify((t.conventions ? [{ number: t.conventions, title: 'Conventions' }] : []).concat(extra).slice(0, lim)));
+      if (label === 'trailhead:dashboard') return ok_(JSON.stringify((t.dash ? [{ number: t.dash.number, title: '📊 trailhead dashboard' }] : []).concat(extra).slice(0, lim)));
       if (label === undefined) return ok_(JSON.stringify(t.openIssues));
     }
     if (args[0] === 'issue' && args[1] === 'view') {
@@ -232,6 +236,65 @@ function runMain(argv, t, extra = {}) {
   ok('regen: already pinned, no pin call', t.pins.length === 0);
 }
 
+// --- singleton lookups fail closed on duplicates (#274) -----------------------
+{
+  const noWrites = (t) => t.writes.length === 0 && t.created.length === 0 && t.pins.length === 0 && !t.calls.some((c) => c.startsWith('issue edit') || c.startsWith('issue create') || c.startsWith('label create'));
+  // many dashboards
+  for (const flags of [[], ['--dry-run']]) {
+    const t = makeTracker({ dups: { 'trailhead:dashboard': [{ number: 41, title: 'Dashboard twin\nsecond line' }] } });
+    const r = runMain(['--repo', 'o/r', ...flags], t);
+    ok(`dups dashboard${flags[0] || ''}: exit 1 and aborted`, r.code === 1 && /^aborted: /.test(r.out));
+    ok(`dups dashboard${flags[0] || ''}: names both numbers and titles`, /trailhead:dashboard: .*\(#33\).*\(#41\)/.test(r.out) && r.out.includes('Dashboard twin second line'));
+    ok(`dups dashboard${flags[0] || ''}: one line, nothing written`, r.out.split('\n').filter(Boolean).length === 1 && noWrites(t));
+  }
+  // many codebase / conventions, named together in one abort
+  {
+    const t = makeTracker({ dups: { 'trailhead:codebase': [{ number: 8, title: 'Codebase 2' }], 'trailhead:conventions': [{ number: 9, title: 'Conv 2' }] } });
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('dups anchors: exit 1', r.code === 1 && /^aborted: /.test(r.out));
+    ok('dups anchors: codebase and conventions both named', /trailhead:codebase: Codebase \(#2\), Codebase 2 \(#8\)/.test(r.out) && /trailhead:conventions: Conv/.test(r.out) && r.out.includes('(#3)') && r.out.includes('(#9)'));
+    ok('dups anchors: nothing written', noWrites(t));
+  }
+  {
+    const t = makeTracker({ dups: { 'trailhead:codebase': [{ number: 8, title: 'Codebase 2' }] } });
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('dups codebase only: aborts, conventions not named', r.code === 1 && /\(#8\)/.test(r.out) && !/trailhead:conventions/.test(r.out) && noWrites(t));
+  }
+  // many dashboards and no existing dashboard path is untouched: zero dashboard + dup anchors still aborts before create
+  {
+    const t = makeTracker({ dash: null, dups: { 'trailhead:conventions': [{ number: 9, title: 'Conv 2' }] } });
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('dups with no dashboard: aborts before create', r.code === 1 && noWrites(t));
+  }
+  // a window hit by the fetch limit says more may exist (I1)
+  {
+    const many = Array.from({ length: 11 }, (_, i) => ({ number: 100 + i, title: 'Twin ' + i }));
+    const t = makeTracker({ dups: { 'trailhead:dashboard': many } });
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('dups at the limit: aborts and says possibly more', r.code === 1 && /\(#108\), and possibly more/.test(r.out) && !r.out.includes("(#109)") && noWrites(t));
+    const t2 = makeTracker({ dups: { 'trailhead:dashboard': [{ number: 41, title: 'Twin' }] } });
+    ok('dups under the limit: no "possibly more"', !/possibly more/.test(runMain(['--repo', 'o/r'], t2).out));
+  }
+  // control characters in a title never reach the abort line (I2)
+  {
+    const t = makeTracker({ dups: { 'trailhead:dashboard': [{ number: 41, title: 'Evil\x1b[31m twin\x07\x7f' }] } });
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('dups: control characters stripped from titles', r.code === 1 && /Evil\\\[31m twin/.test(r.out) && !/[\x00-\x08\x0b-\x1f\x7f]/.test(r.out));
+  }
+  // zero and one: unchanged
+  {
+    const t = makeTracker();
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('one each: writes as before', r.code === 0 && t.writes.length === 1 && /^dashboard #33:/.test(r.out));
+    ok('lookups fetch more than one result', t.calls.filter((c) => /--label trailhead:(dashboard|codebase|conventions) /.test(c)).every((c) => !/--limit 1$/.test(c)));
+  }
+  {
+    const t = makeTracker({ dash: null, codebase: 0, conventions: 0 });
+    const r = runMain(['--repo', 'o/r'], t);
+    ok('zero each: create and pin path unchanged, anchors absent', r.code === 0 && t.created.length === 1 && t.pins.length === 1 && !/Anchors:/.test(t.created[0].text));
+  }
+}
+
 // --- what is (not) gathered --------------------------------------------------
 {
   const t = makeTracker();