@marcomigozzi/trailhead 0.14.0 → 0.16.0

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

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-dashboard.js. Run: node dashboard.test.js
+// No framework: plain asserts, same style as issue-body.test.js.
+//
+// Layers covered:
+//   1. Pure renderDashboard() / mapFlags() on a fixed snapshot.
+//   2. main() against a fake tracker behind an injected `gh` runner: what is
+//      gathered (and what is not), last-audit carry-through, self-heal
+//      (create + pin, re-pin), the guarded write, dry-run.
+//   3. End-to-end: the script itself with a failing 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-dashboard.js');
+const { renderDashboard, mapFlags, classify, main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const AUDIT = '<!-- trailhead:last-audit 2026-10-01T10:00:00Z -->';
+
+// --- pure render -------------------------------------------------------------
+const SNAP = {
+  repo: 'o/r',
+  maps: [
+    { number: 14, title: '🗺 multi-host', openScoped: 0, total: 20, fog: false, closedEdges: null },
+    { number: 98, title: '🗺 website [v1]', openScoped: 5, total: 92, fog: null, closedEdges: true },
+    { number: 5, title: '🗺 plain', openScoped: 3, total: 10, fog: null, closedEdges: null },
+  ],
+  whiteboard: [
+    { number: 30, title: 'Frontier one', assignees: [], labels: ['trailhead:ticket', 'trailhead:whiteboard', 'trailhead:build'] },
+    { number: 31, title: 'Doing it', assignees: ['me'], labels: ['trailhead:ticket', 'trailhead:whiteboard'] },
+    { number: 32, title: 'Stuck', assignees: [], labels: ['trailhead:ticket', 'trailhead:whiteboard', 'trailhead:blocked'] },
+  ],
+  resolved: [{ number: 20, title: 'Done a' }, { number: 19, title: 'Done b' }],
+  inbox: 4,
+  anchors: { codebase: 2, conventions: 3 },
+  lastAudit: AUDIT,
+};
+
+{
+  const body = renderDashboard(SNAP);
+  ok('render: deterministic', body === renderDashboard(JSON.parse(JSON.stringify(SNAP))));
+  ok('render: ends with a single newline', body.endsWith('\n') && !body.endsWith('\n\n'));
+  const heads = body.split('\n').filter((l) => l.startsWith('## '));
+  ok('render: the three sections in order', JSON.stringify(heads) === JSON.stringify(['## 🗺 Maps', '## 🧷 Whiteboard (map-less tickets)', '## 📊 Counts']));
+  ok('render: map link with open count', body.includes('- [🗺 multi-host](https://github.com/o/r/issues/14): 0 open'));
+  ok('render: bracket in a title is escaped', body.includes('[🗺 website \\[v1\\]](https://github.com/o/r/issues/98)'));
+  ok('render: exhausted flag', /issues\/14\): 0 open · exhausted · closeable/.test(body));
+  ok('render: near cap + prunable flag', /issues\/98\): 5 open · near cap · 92\/100 · prunable/.test(body));
+  ok('render: an unflagged map has no flag', /issues\/5\): 3 open\n/.test(body));
+  ok('render: whiteboard lists', /Frontier \(1\):\n- \[Frontier one #30\]\(https:\/\/github.com\/o\/r\/issues\/30\)/.test(body)
+    && /In progress \(1\):\n- \[Doing it #31\]/.test(body) && /Blocked \(1\):\n- \[Stuck #32\]/.test(body));
+  ok('render: recently resolved titles', body.includes('_Recently resolved: [Done a #20](https://github.com/o/r/issues/20), [Done b #19](https://github.com/o/r/issues/19)_'));
+  ok('render: counts', /- Untriaged inbox: 4/.test(body) && /- Whiteboard frontier: 1/.test(body) && /- Open maps: 3/.test(body));
+  ok('render: anchors line', body.includes('[Codebase #2](https://github.com/o/r/issues/2)') && body.includes('[Conventions #3](https://github.com/o/r/issues/3)'));
+  ok('render: last-audit marker verbatim and last', body.trimEnd().endsWith(AUDIT));
+  ok('render: no em-dash', !body.includes('—'));
+}
+{
+  const body = renderDashboard({ ...SNAP, lastAudit: null, maps: [], whiteboard: [], resolved: [], anchors: { codebase: null, conventions: null } });
+  ok('render: empty tracker still has every section', /_No open maps\._/.test(body) && /_Nothing on the whiteboard\._/.test(body));
+  ok('render: no marker when none exists', !body.includes('last-audit'));
+  ok('render: no anchors line when none exist', !body.includes('Anchors'));
+}
+{
+  ok('mapFlags: exhausted needs zero scoped and no fog', JSON.stringify(mapFlags({ openScoped: 0, total: 3, fog: false })) === JSON.stringify(['exhausted · closeable']));
+  ok('mapFlags: fog keeps a zero-count map unflagged', mapFlags({ openScoped: 0, total: 3, fog: true }).length === 0);
+  ok('mapFlags: at cap', JSON.stringify(mapFlags({ openScoped: 4, total: 100, closedEdges: false })) === JSON.stringify(['at cap · 100/100']));
+  ok('mapFlags: at cap prunable', JSON.stringify(mapFlags({ openScoped: 4, total: 100, closedEdges: true })) === JSON.stringify(['at cap · 100/100 · prunable']));
+  ok('mapFlags: 89 is not near cap', mapFlags({ openScoped: 4, total: 89 }).length === 0);
+}
+
+// #263: classify() follows the panel's precedence (unverified > paused > blocked > in progress > frontier)
+{
+  const wbT = (number, assignees, ...extra) => ({ number, title: `T${number}`, assignees, labels: ['trailhead:ticket', 'trailhead:whiteboard', ...extra] });
+  const nums = (list) => list.map((t) => t.number);
+  const c = classify([
+    wbT(1, []),
+    wbT(2, ['me']),
+    wbT(3, [], 'trailhead:blocked'),
+    wbT(4, [], 'trailhead:paused'),
+    wbT(5, ['me'], 'trailhead:paused'),
+    wbT(6, [], 'trailhead:paused', 'trailhead:blocked'),
+    wbT(7, [], 'trailhead:paused', 'trailhead:unverified'),
+    wbT(8, ['me'], 'trailhead:blocked'),
+    wbT(9, [], 'trailhead:unverified'),
+  ]);
+  ok('classify: a paused ticket lands in paused, assigned or not, blocked or not', JSON.stringify(nums(c.paused)) === JSON.stringify([4, 5, 6]));
+  ok('classify: paused+unverified is quarantined as unverified', JSON.stringify(nums(c.unverified)) === JSON.stringify([7, 9]));
+  ok('classify: assigned+blocked is blocked', JSON.stringify(nums(c.blocked)) === JSON.stringify([3, 8]));
+  ok('classify: plain assigned is in progress, plain unassigned is frontier', JSON.stringify(nums(c.inProgress)) === JSON.stringify([2]) && JSON.stringify(nums(c.frontier)) === JSON.stringify([1]));
+  const body = renderDashboard({ ...SNAP, whiteboard: [wbT(30, []), wbT(31, ['me']), wbT(33, [], 'trailhead:paused'), wbT(34, ['me'], 'trailhead:paused'), wbT(32, [], 'trailhead:blocked')] });
+  ok('render: a Paused group sits between In progress and Blocked', /In progress \(1\):\n- \[T31 #31\][^\n]*\nPaused \(2\):\n- \[T33 #33\][^\n]*\n- \[T34 #34\][^\n]*\nBlocked \(1\):/.test(body));
+  ok('render: a paused ticket shows only under Paused', body.split('T33 #33').length === 2 && body.split('T34 #34').length === 2);
+  ok('render: Whiteboard frontier excludes paused tickets', /- Whiteboard frontier: 1\n/.test(body));
+}
+
+// --- fake tracker ------------------------------------------------------------
+function makeTracker(init = {}) {
+  const t = {
+    maps: init.maps || [
+      { number: 14, title: '🗺 multi-host', scoped: 0, total: 20, body: '## Destination\nx\n\n## Not yet specified\n_none yet_\n', edges: [] },
+      { number: 98, title: '🗺 website', scoped: 5, total: 92, body: 'body of 98 long enough', edges: [{ number: 1, state: 'closed' }, { number: 2, state: 'open' }] },
+      { number: 5, title: '🗺 plain', scoped: 3, total: 10, body: 'body of 5 long enough text', edges: [] },
+    ],
+    whiteboardOpen: init.whiteboardOpen || [
+      { number: 30, title: 'Frontier one', labels: [{ name: 'trailhead:ticket' }, { name: 'trailhead:whiteboard' }], assignees: [] },
+      { number: 31, title: 'Doing it', labels: [{ name: 'trailhead:ticket' }, { name: 'trailhead:whiteboard' }], assignees: [{ login: 'me' }] },
+    ],
+    closed: init.closed || [
+      { number: 20, title: 'Done a', closedAt: '2026-10-10T00:00:00Z', labels: [{ name: 'trailhead:whiteboard' }] },
+      { number: 19, title: 'Done old', closedAt: '2026-10-01T00:00:00Z', labels: [{ name: 'trailhead:whiteboard' }] },
+      { number: 18, title: 'Out of scope one', closedAt: '2026-10-12T00:00:00Z', labels: [{ name: 'trailhead:whiteboard' }, { name: 'trailhead:out-of-scope' }] },
+    ],
+    openIssues: init.openIssues || [
+      { number: 50, labels: [] }, { number: 51, labels: [{ name: 'bug' }] }, { number: 52, labels: [{ name: 'trailhead:ticket' }] },
+    ],
+    codebase: init.codebase === undefined ? 2 : init.codebase,
+    conventions: init.conventions === undefined ? 3 : init.conventions,
+    dash: init.dash === undefined ? { number: 33, body: 'Old hand written dashboard body.\n\n## Maps\nlots of prose here\n' + AUDIT + '\n', updatedAt: 'T1' } : init.dash,
+    pinned: init.pinned || [33],
+    edits: init.edits === undefined ? 1 : init.edits,
+    editStep: init.editStep === undefined ? 1 : init.editStep,
+    labels: [],
+    calls: [],
+    writes: [],
+    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) => {
+    const line = args.join(' ');
+    t.calls.push(line);
+    if (t.failOn && t.failOn.test(line)) return { status: 1, stdout: '', stderr: 'forced failure' };
+    if (args[0] === 'repo' && args[1] === 'view') return ok_('o/r\n');
+    if (args[0] === 'label' && args[1] === 'create') { t.labels.push(args[2]); return ok_(''); }
+    if (args[0] === 'issue' && args[1] === 'list') {
+      const li = args.indexOf('--label');
+      const label = li < 0 ? undefined : args[li + 1];
+      const state = args[args.indexOf('--state') + 1];
+      if (label === 'trailhead:map') return ok_(JSON.stringify(t.maps.map((m) => ({ number: m.number, title: m.title }))));
+      if (/^trailhead:map-\d+$/.test(label || '')) {
+        const m = t.maps.find((x) => 'trailhead:map-' + x.number === label);
+        return ok_(JSON.stringify(Array.from({ length: m.scoped }, (_, i) => ({ number: 1000 + i }))));
+      }
+      if (label === 'trailhead:whiteboard' && state === 'open') return ok_(JSON.stringify(t.whiteboardOpen));
+      if (label === 'trailhead:whiteboard' && state === 'closed') return ok_(JSON.stringify(t.closed));
+      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') {
+      const n = Number(args[2]);
+      if (t.dash && n === t.dash.number) return ok_(JSON.stringify({ body: t.dash.body, updatedAt: t.dash.updatedAt }));
+      const m = t.maps.find((x) => x.number === n);
+      if (m) return ok_(JSON.stringify({ body: m.body, updatedAt: 'M' }));
+    }
+    if (args[0] === 'issue' && args[1] === 'edit') {
+      const text = fs.readFileSync(args[args.indexOf('--body-file') + 1], 'utf8');
+      t.writes.push(text);
+      t.dash.body = text;
+      t.edits += t.editStep;
+      t.dash.updatedAt = 'T2';
+      return ok_('');
+    }
+    if (args[0] === 'issue' && args[1] === 'create') {
+      const text = fs.readFileSync(args[args.indexOf('--body-file') + 1], 'utf8');
+      t.created.push({ text, args });
+      t.dash = { number: 77, body: text, updatedAt: 'T1' };
+      return ok_('https://github.com/o/r/issues/77\n');
+    }
+    if (args[0] === 'api' && args[1] === 'graphql') {
+      const q = args.find((a) => a.startsWith('query=')) || '';
+      if (/userContentEdits/.test(q)) return ok_(JSON.stringify({ data: { repository: { issue: { userContentEdits: { totalCount: t.edits } } } } }));
+      if (/pinnedIssues/.test(q)) return ok_(JSON.stringify({ data: { repository: { pinnedIssues: { nodes: t.pinned.map((number) => ({ issue: { number } })) } } } }));
+      if (/pinIssue/.test(q)) { t.pins.push(args.join(' ')); return ok_('{}'); }
+    }
+    if (args[0] === 'api') {
+      const ep = args[1];
+      let m = /^repos\/o\/r\/issues\/(\d+)\/sub_issues/.exec(ep);
+      if (m) return ok_(JSON.stringify(t.maps.find((x) => x.number === Number(m[1])).edges));
+      m = /^repos\/o\/r\/issues\/(\d+)$/.exec(ep);
+      if (m) {
+        const n = Number(m[1]);
+        if (args.includes('.node_id')) return ok_('NODE_' + n + '\n');
+        const mp = t.maps.find((x) => x.number === n);
+        if (mp) return ok_(String(mp.total) + '\n');
+      }
+    }
+    return { status: 1, stdout: '', stderr: 'unexpected: ' + line };
+  };
+  return t;
+}
+
+const fakeGuard = { scan: (text) => (/ghp_[A-Za-z0-9]{20,}/.test(text) ? 'github token' : null) };
+
+function runMain(argv, t, extra = {}) {
+  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, { gh: t.gh, stdout: { write: (s) => chunks.push(s) }, guard: fakeGuard, ...extra });
+  } finally {
+    process.stderr.write = realErr;
+  }
+  return { code, out: chunks.join(''), err: errChunks.join('') };
+}
+
+// --- regenerate an existing dashboard ----------------------------------------
+{
+  const t = makeTracker();
+  const oldSize = Buffer.byteLength(t.dash.body);
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('regen: exit 0', r.code === 0);
+  ok('regen: exactly one output line', r.out.split('\n').filter(Boolean).length === 1);
+  ok('regen: summary line', /^dashboard #33: 3 maps, whiteboard 2, flags: map-14 exhausted, map-98 near cap 92\/100 prunable/.test(r.out));
+  ok('regen: reports old and new size', new RegExp(`body ${oldSize} -> ${Buffer.byteLength(t.writes[0])} bytes`).test(r.out));
+  ok('regen: one write', t.writes.length === 1);
+  ok('regen: the old prose is gone, the shape is generated', !t.writes[0].includes('lots of prose here') && t.writes[0].includes('## 🗺 Maps'));
+  ok('regen: last-audit kept verbatim', t.writes[0].trimEnd().endsWith(AUDIT));
+  ok('regen: closed out-of-scope tickets are not "resolved", newest first', /Recently resolved: \[Done a #20\].*\[Done old #19\]/.test(t.writes[0]) && !t.writes[0].includes('Out of scope one'));
+  ok('regen: inbox counts only issues without a trailhead label', /- Untriaged inbox: 2/.test(t.writes[0]));
+  ok('regen: label ensured first', t.labels.includes('trailhead:dashboard'));
+  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();
+  runMain(['--repo', 'o/r'], t);
+  const views = t.calls.filter((c) => c.startsWith('issue view'));
+  ok('fog: body read only for the zero-count map', views.some((c) => c.startsWith('issue view 14 ')) && !views.some((c) => c.startsWith('issue view 98 ') || c.startsWith('issue view 5 ')));
+  const edges = t.calls.filter((c) => /\/sub_issues/.test(c));
+  ok('closed-edge check only for near/at-cap maps', edges.length === 1 && /issues\/98\/sub_issues/.test(edges[0]));
+}
+{
+  // a zero-count map with fog left is not exhausted
+  const t = makeTracker({ maps: [{ number: 14, title: '🗺 m', scoped: 0, total: 2, body: '## Not yet specified\n- still foggy\n', edges: [] }] });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('fog left: not flagged exhausted', /flags: none/.test(r.out) && !t.writes[0].includes('exhausted'));
+}
+
+// --- W2: a missing fog section is unconfirmed, not empty ----------------------
+{
+  const t = makeTracker({ maps: [{ number: 14, title: '🗺 m', scoped: 0, total: 2, body: '## Destination\nSomewhere good, long enough.\n', edges: [] }] });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('W2: no "Not yet specified" section: not flagged exhausted', r.code === 0 && /flags: none/.test(r.out) && !t.writes[0].includes('exhausted'));
+  ok('W2: mapFlags keeps fog=null unflagged', mapFlags({ openScoped: 0, total: 2, fog: null }).length === 0);
+}
+
+// --- W3: newest closures are inside the window; a hit limit is said out loud --
+{
+  const t = makeTracker();
+  runMain(['--repo', 'o/r'], t);
+  const q = t.calls.find((c) => c.startsWith('issue list --label trailhead:whiteboard --state closed'));
+  ok('W3: the resolved query is sorted by recent updates', /--search sort:updated-desc/.test(q));
+  ok('W3: a normal run reports no truncation', !/truncated/.test(t.writes[0]) && !/truncated/.test(runMain(['--repo', 'o/r', '--dry-run'], makeTracker()).out));
+}
+{
+  const many = (n, extra) => Array.from({ length: n }, (_, i) => ({ number: 5000 + i, title: 't' + i, labels: [], assignees: [], ...extra }));
+  const t = makeTracker({ openIssues: many(1000) });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('W3: inbox at its limit is said in the output line', r.code === 0 && /truncated: inbox/.test(r.out));
+  ok('W3: the inbox count is rendered as a lower bound', /- Untriaged inbox: 1000\+/.test(t.writes[0]));
+  const w = makeTracker({ whiteboardOpen: many(200, { labels: [{ name: 'trailhead:whiteboard' }] }) });
+  ok('W3: whiteboard at its limit is said', /truncated: whiteboard/.test(runMain(['--repo', 'o/r'], w).out));
+  const dropped = many(100, { closedAt: '2026-10-01T00:00:00Z', labels: [{ name: 'trailhead:whiteboard' }, { name: 'trailhead:out-of-scope' }] });
+  const c = makeTracker({ closed: dropped });
+  ok('W3: a full resolved window that filters down below 10 is said', /truncated: resolved/.test(runMain(['--repo', 'o/r'], c).out));
+  const fine = many(100, { closedAt: '2026-10-01T00:00:00Z', labels: [{ name: 'trailhead:whiteboard' }] });
+  ok('W3: a full resolved window with 10 to show is not truncation', !/truncated/.test(runMain(['--repo', 'o/r'], makeTracker({ closed: fine })).out));
+  const both = runMain(['--repo', 'o/r'], makeTracker({ openIssues: many(1000), whiteboardOpen: many(200, { labels: [{ name: 'trailhead:whiteboard' }] }) }));
+  ok('W3: several truncations listed on the one line', both.out.trim().split('\n').length === 1 && /truncated: whiteboard, inbox/.test(both.out));
+}
+
+// --- last audit --------------------------------------------------------------
+{
+  const t = makeTracker();
+  const r = runMain(['--repo', 'o/r', '--set-last-audit', '2026-10-14T09:30:00Z'], t);
+  ok('set-last-audit: replaces the marker', r.code === 0 && t.writes[0].includes('<!-- trailhead:last-audit 2026-10-14T09:30:00Z -->') && !t.writes[0].includes('2026-10-01'));
+  ok('set-last-audit: exactly one marker', (t.writes[0].match(/trailhead:last-audit/g) || []).length === 1);
+  const t2 = makeTracker({ dash: { number: 33, body: 'Old body with no marker at all, long enough.', updatedAt: 'T1' } });
+  runMain(['--repo', 'o/r', '--set-last-audit', '2026-10-14T09:30:00Z'], t2);
+  ok('set-last-audit: added when absent', t2.writes[0].trimEnd().endsWith('<!-- trailhead:last-audit 2026-10-14T09:30:00Z -->'));
+  const bad = runMain(['--repo', 'o/r', '--set-last-audit', 'yesterday'], makeTracker());
+  ok('set-last-audit: a non-ISO value is a usage error', bad.code === 2 && bad.err.length > 0 && bad.out === '');
+}
+
+// --- I1: a title cannot forge the last-audit marker ---------------------------
+{
+  const FORGED = '<!-- trailhead:last-audit 2000-01-01T00:00:00Z -->';
+  const body = renderDashboard({
+    ...SNAP,
+    lastAudit: null,
+    maps: [{ number: 1, title: 'evil ' + FORGED, openScoped: 1, total: 1, fog: null, closedEdges: null }],
+    whiteboard: [{ number: 2, title: FORGED + ' wb', assignees: [], labels: [] }],
+    resolved: [{ number: 3, title: 'x --> y <!-- z' }],
+  });
+  ok('I1: no comment opener survives in a rendered title', !body.includes('<!--') && !body.includes('-->'));
+  ok('I1: a forged title cannot add a marker', !body.includes('trailhead:last-audit 2000') || !/^<!-- trailhead:last-audit/m.test(body));
+  const real = renderDashboard({ ...SNAP, lastAudit: AUDIT, maps: [{ number: 1, title: FORGED, openScoped: 1, total: 1 }] });
+  ok('I1: with a real marker there is exactly one comment', (real.match(/<!--/g) || []).length === 1 && real.trimEnd().endsWith(AUDIT));
+}
+{
+  // An old body whose map-title line holds a forged marker inline: only the own-line one is carried.
+  const FORGED = '<!-- trailhead:last-audit 2000-01-01T00:00:00Z -->';
+  const dash = { number: 33, updatedAt: 'T1', body: `Intro line.\n\n## Maps\n- [evil ${FORGED}](https://x/1): 1 open\n\n${AUDIT}\n` };
+  const t = makeTracker({ dash });
+  runMain(['--repo', 'o/r'], t);
+  ok('I1: the own-line marker is carried, not the forged inline one', t.writes[0].includes(AUDIT) && !t.writes[0].includes('2000-01-01'));
+  const t2 = makeTracker({ dash: { number: 33, updatedAt: 'T1', body: `Intro line.\n\n## Maps\n- [evil ${FORGED}](https://x/1): 1 open\n` } });
+  runMain(['--repo', 'o/r'], t2);
+  ok('I1: a forged inline marker alone is not carried', !t2.writes[0].includes('trailhead:last-audit'));
+}
+
+// --- self-heal ---------------------------------------------------------------
+{
+  const t = makeTracker({ dash: null, pinned: [] });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('create: issue created once with the final body, never empty', r.code === 0 && t.created.length === 1 && t.created[0].text.includes('## 🗺 Maps') && t.created[0].text.trim() !== '');
+  ok('create: labelled trailhead:dashboard, no placeholder write after', t.created[0].args.includes('trailhead:dashboard') && t.writes.length === 0);
+  ok('create: pinned', t.pins.length === 1 && /NODE_77|id=NODE_77/.test(t.pins[0]));
+  ok('create: summary names the new issue', /^dashboard #77: 3 maps/.test(r.out) && /created/.test(r.out));
+}
+{
+  const t = makeTracker({ pinned: [2, 3] });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('re-pin: an unpinned dashboard is pinned again', r.code === 0 && t.pins.length === 1 && /NODE_33/.test(t.pins[0]));
+}
+{
+  const t = makeTracker({ dash: null, pinned: [] });
+  const r = runMain(['--repo', 'o/r', '--set-last-audit', '2026-10-14T09:30:00Z'], t);
+  ok('create with --set-last-audit: marker in the first body', t.created[0].text.includes('trailhead:last-audit 2026-10-14T09:30:00Z'));
+  const ghost = makeTracker({ dash: null, pinned: [] });
+  const guardHit = runMain(['--repo', 'o/r'], ghost, { guard: { scan: () => 'github token' } });
+  ok('create: a secret in the generated body aborts the create', guardHit.code === 1 && ghost.created.length === 0);
+}
+
+// --- I2: a pin-check failure after the write is not an abort ------------------
+{
+  const t = makeTracker({ failOn: /pinnedIssues/ });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('I2: the body was written', t.writes.length === 1);
+  ok('I2: exit 0, one line saying written and the pin check failed', r.code === 0 && r.out.trim().split('\n').length === 1
+    && /written, pin check failed: .*forced failure/.test(r.out) && !/^aborted/.test(r.out));
+  ok('I2: the line still carries the summary and sizes', /^dashboard #33: 3 maps/.test(r.out) && /body \d+ -> \d+ bytes/.test(r.out));
+}
+
+// --- guards ------------------------------------------------------------------
+{
+  const t = makeTracker();
+  t.maps[0].title = '🗺 leak ghp_' + 'a'.repeat(36);
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('secret in the whole generated body: abort, nothing written', r.code === 1 && /secret/.test(r.out) && t.writes.length === 0);
+  const t2 = makeTracker();
+  const r2 = runMain(['--repo', 'o/r'], t2, { guard: null });
+  ok('no guard module: fail closed', r2.code === 1 && /secret-scan unavailable/.test(r2.out) && t2.writes.length === 0);
+  const t3 = makeTracker({ dash: { number: 33, body: '', updatedAt: 'T1' } });
+  const r3 = runMain(['--repo', 'o/r'], t3);
+  ok('empty existing body: refused, nothing written', r3.code === 1 && /empty/.test(r3.out) && t3.writes.length === 0);
+  const t4 = makeTracker({ failOn: /issue list --label trailhead:whiteboard --state open/ });
+  const r4 = runMain(['--repo', 'o/r'], t4);
+  ok('a failed gather aborts, nothing written', r4.code === 1 && /^aborted: /.test(r4.out) && t4.writes.length === 0);
+}
+
+// --- dry run -----------------------------------------------------------------
+{
+  const t = makeTracker();
+  const r = runMain(['--repo', 'o/r', '--dry-run'], t);
+  ok('dry-run: exit 0, one line, sizes', r.code === 0 && r.out.split('\n').filter(Boolean).length === 1 && /dry-run/.test(r.out) && /body \d+ -> \d+ bytes/.test(r.out));
+  ok('dry-run: writes nothing', t.writes.length === 0 && t.created.length === 0 && t.pins.length === 0 && !t.calls.some((c) => c.startsWith('label create')));
+  const m = makeTracker({ dash: null, pinned: [] });
+  const r2 = runMain(['--repo', 'o/r', '--dry-run'], m);
+  ok('dry-run: a missing dashboard is reported, not created', r2.code === 0 && /would create/.test(r2.out) && m.created.length === 0 && m.pins.length === 0);
+}
+
+// --- usage errors ------------------------------------------------------------
+for (const argv of [['--bogus'], ['--repo'], ['--repo', 'nope'], ['--set-last-audit'], ['extra']]) {
+  const t = makeTracker();
+  const r = runMain(argv, t);
+  ok(`usage error exit 2: ${argv.join(' ')}`, r.code === 2 && r.err.length > 0 && r.out === '' && t.calls.length === 0);
+}
+
+// --- end-to-end with a failing fake gh on PATH --------------------------------
+{
+  const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dashboard-bin-'));
+  fs.writeFileSync(path.join(binDir, 'gh'), '#!/bin/sh\nexit 1\n', { mode: 0o755 });
+  const res = spawnSync('node', [scriptPath, '--repo', 'o/r'], { encoding: 'utf8', env: { ...process.env, PATH: binDir + path.delimiter + process.env.PATH } });
+  ok('e2e: gh failing aborts with exit 1 and one line', res.status === 1 && /^aborted: /.test(res.stdout) && res.stdout.trim().split('\n').length === 1);
+  const bad = spawnSync('node', [scriptPath, '--bogus'], { encoding: 'utf8' });
+  ok('e2e: usage error exits 2', bad.status === 2);
+}
+
+{
+  // GitHub stops recording body edits at 100: the write is clean on an exact read-back.
+  const t = makeTracker({ edits: 100, editStep: 0 });
+  const r = runMain(['--repo', 'o/r'], t);
+  ok('full edit history: the dashboard write is not a conflict', r.code === 0 && !/conflict|aborted/.test(r.out) && t.writes.length === 1);
+  ok('full edit history: the output says the check was read-back only', /edit history full/.test(r.out));
+}
+console.log(`dashboard.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/fixtures/commit-msg-legacy-js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead commit-msg hook (git). Host-independent guardrail: installed into
+// .git/hooks/commit-msg at repo first-use so trailhead's commit discipline is
+// enforced on EVERY `git commit`, whatever agent host drives it (Codex has no
+// hook bus; this git hook is how the commit-guard survives there). Decision #16.
+//
+// Self-contained by design: detached from the trailhead install, it inlines the
+// same rules as plugins/trailhead/hooks/lib/commit-message-check.js. That
+// lib's test drives this hook end-to-end so the copies cannot drift.
+//
+// git passes the commit-message file path as argv[2]. On a violation: print the
+// reason to stderr and exit 1 (git aborts the commit). Otherwise exit 0.
+// Crash-safe: any unexpected error exits 0 (never wedge a commit).
+//
+// Note: a merge/revert/fixup message already fails the conventional-subject
+// rule below, so it needs no special case; `git commit --amend` keeps whatever
+// trailer the original message carried; `git commit --no-verify` bypasses this
+// hook entirely, as before.
+
+const fs = require('fs');
+const path = require('path');
+
+const TYPES = 'feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert';
+const CONVENTIONAL = new RegExp(`^(${TYPES})(\\([^)]+\\))?!?:\\s.+`);
+const CO_AUTHORED = /co-authored-by\s*:/i;
+const SCISSORS = '# ------------------------ >8';
+const REFS_LINE = /^\s*refs\s*:(.*)$/i;
+
+function messageRegion(raw) {
+  const text = String(raw == null ? '' : raw);
+  const i = text.indexOf(SCISSORS);
+  return i === -1 ? text : text.slice(0, i);
+}
+function subjectOf(raw) {
+  for (const line of messageRegion(raw).split('\n')) {
+    if (line.trim() === '' || line.startsWith('#')) continue;
+    return line.trim();
+  }
+  return '';
+}
+
+// Mirrors parseSessionTicket() in commit-message-check.js: parses the first
+// line of a .trailhead/session-ticket marker (`#<n> <title>`).
+function parseSessionTicket(text) {
+  const raw = String(text == null ? '' : text).replace(/^/, '');
+  const firstLine = raw.split('\n')[0].replace(/\r$/, '');
+  const m = firstLine.match(/^#([1-9]\d*)(?:\s|$)/);
+  return m ? Number(m[1]) : null;
+}
+
+// Mirrors hasRefsFor() in commit-message-check.js.
+function hasRefsFor(message, n) {
+  const target = new RegExp('#' + n + '(?![\\w])');
+  for (const line of messageRegion(message).split('\n')) {
+    if (line.trim().startsWith('#')) continue;
+    const m = line.match(REFS_LINE);
+    if (m && target.test(m[1])) return true;
+  }
+  return false;
+}
+
+// Reads the session-ticket marker at the worktree top-level. git runs
+// commit-msg from the worktree top-level (linked worktrees included), so
+// process.cwd() is the right root here. Its own try/catch: a read error
+// (marker absent, unreadable, etc.) must never skip the other rules below,
+// it just leaves the Refs rule off.
+function readTicket() {
+  try {
+    const markerPath = path.join(process.cwd(), '.trailhead', 'session-ticket');
+    return parseSessionTicket(fs.readFileSync(markerPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const file = process.argv[2];
+  const raw = file ? fs.readFileSync(file, 'utf8') : '';
+  const region = messageRegion(raw);
+
+  if (CO_AUTHORED.test(region)) {
+    process.stderr.write('trailhead: do not add a Co-Authored-By trailer to commits. Remove it and commit again.\n');
+    process.exit(1);
+  }
+  const subject = subjectOf(raw);
+  if (subject && !CONVENTIONAL.test(subject)) {
+    process.stderr.write(`trailhead: commit subject must be Conventional Commits: <type>(<scope>)?: <subject>. Valid types: ${TYPES.replace(/\|/g, ', ')}.\n`);
+    process.exit(1);
+  }
+  if (subject.length > 72) {
+    process.stderr.write('trailhead: commit subject must be 72 characters or less.\n');
+    process.exit(1);
+  }
+
+  const ticket = readTicket();
+  if (Number.isInteger(ticket) && ticket > 0 && !hasRefsFor(raw, ticket)) {
+    process.stderr.write(`trailhead: this commit is on ticket #${ticket} (per .trailhead/session-ticket) but has no "Refs: #${ticket}" trailer. Add "Refs: #${ticket}" as the last line of the message and commit again. If this commit is not part of ticket #${ticket}, remove the stale .trailhead/session-ticket marker first.\n`);
+    process.exit(1);
+  }
+} catch {
+  process.exit(0); // never wedge a commit on an unexpected error
+}
+process.exit(0);