@marcomigozzi/trailhead 0.15.0 → 0.16.0

package/plugins/trailhead/templates/trailhead-auto-slot.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto-slot helper (self-contained, ships in templates/ so it reaches every
+// install channel). Opens and lists the slot workspaces of an autonomous run with
+// parallel slots: one workspace per ticket in flight, a worktree (or, on a superrepo,
+// an independent clone) at a sibling path on its own branch. #283.
+//
+// CLI:
+//   node trailhead-auto-slot.js open --repo <main-checkout> --ticket <n> --base <sha>
+//   node trailhead-auto-slot.js list --repo <main-checkout>
+//
+// Layout: the workspace of ticket <n> is <parent of the main checkout>/<basename>-t<n>
+// on the branch trailhead/t<n>.
+//
+// open (never overwrites anything, never removes anything):
+//   - the branch is already checked out in a worktree (at the slot path or any other
+//     path, e.g. one made by hand earlier): status "reentered" with that path;
+//   - the branch exists but has no worktree: "reattached" (git worktree add <path> <branch>);
+//   - neither: "created" (git worktree add -b <branch> <path> <base>), the branch pointing
+//     exactly at --base (the trunk SHA captured at claim, so a moved main checkout never
+//     changes it);
+//   - the branch's worktree is registered in git but its directory is gone (deleted by
+//     hand): "error" naming it and telling to run `git worktree prune` (never pruned here);
+//   - the slot path already exists: an independent git checkout on the branch (a clone
+//     slot) is "reentered" with kind "clone"; anything else is "error", never overwritten.
+//     This check comes before the submodule rule, so an existing path is never cloned over;
+//   - only a missing path, with the main checkout declaring a submodule (.gitmodules):
+//     "clone-required", nothing created. The caller sets the clone up at the same path, then checks out the branch
+//     at the same base, so a clone slot carries the same path, branch and base.
+// list: every slot workspace, sorted by ticket: each worktree on a trailhead/t<n> branch,
+//   plus each sibling <basename>-t<n> that is an independent git checkout on the branch
+//   trailhead/t<n> and not already a worktree. Each entry:
+//   {ticket, kind: "worktree"|"clone", branch, path, dirty, workState}
+//   A worktree git lists but whose directory is gone (stale) is kept out of slots and
+//   reported in warnings, with a `git worktree prune` suggestion.
+//   dirty is true when `git status --porcelain` is non-empty; workState is the parsed
+//   <path>/.trailhead/work-state.json, or null (missing, or unreadable plus a warning).
+//
+// Prints exactly one JSON line on stdout:
+//   open:  {"status":"created|reentered|reattached|clone-required","ticket":n,"branch":"...","path":"...","kind":"worktree|clone"}
+//   list:  {"status":"ok","slots":[...],"warnings":[...]}
+//   error: {"status":"error","reason":"..."}
+// Exit 0 on ok, 1 on an error, 2 on a usage error (stderr).
+
+const { spawnSync } = require('child_process');
+const nodeFs = require('fs');
+const path = require('path');
+
+function defaultGit(args) {
+  const r = spawnSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+const branchOf = (n) => `trailhead/t${n}`;
+const BRANCH_RE = /^refs\/heads\/trailhead\/t(\d+)$/;
+
+// --- args ---------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (cmd !== 'open' && cmd !== 'list') return { error: `usage: expected open or list, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const allowed = cmd === 'open' ? ['--repo', '--ticket', '--base'] : ['--repo'];
+  const o = { cmd, repo: null, ticket: null, base: null };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const v = argv[i];
+    if (flag === '--ticket') {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: --ticket must be a positive integer, got: ${v}` };
+      o.ticket = Number(v);
+    } else if (!v.trim()) {
+      return { error: `usage: ${flag} requires a non-empty value` };
+    } else if (flag === '--repo') {
+      o.repo = v;
+    } else {
+      o.base = v;
+    }
+  }
+  if (!o.repo) return { error: `usage: ${cmd} requires --repo` };
+  if (cmd === 'open' && !o.ticket) return { error: 'usage: open requires --ticket' };
+  if (cmd === 'open' && !o.base) return { error: 'usage: open requires --base' };
+  return o;
+}
+
+// --- git helpers --------------------------------------------------------------
+
+// [{ path, branch|null }] from `git worktree list --porcelain`, main checkout first.
+function parseWorktrees(text) {
+  const out = [];
+  for (const block of String(text).split(/\n\s*\n/)) {
+    let wt = null;
+    let branch = null;
+    for (const line of block.split('\n')) {
+      if (line.startsWith('worktree ')) wt = line.slice('worktree '.length);
+      else if (line.startsWith('branch ')) branch = line.slice('branch '.length);
+    }
+    if (wt) out.push({ path: wt, branch });
+  }
+  return out;
+}
+
+const realOr = (fs, p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+function hasSubmodule(fs, main) {
+  try {
+    return /^\s*\[submodule\s/m.test(fs.readFileSync(path.join(main, '.gitmodules'), 'utf8'));
+  } catch { return false; }
+}
+
+// --- open ---------------------------------------------------------------------
+
+function openSlot(ctx, o) {
+  const { git, fs, main, fail, emit } = ctx;
+  const branch = branchOf(o.ticket);
+  const target = path.join(path.dirname(main), `${path.basename(main)}-t${o.ticket}`);
+  const result = (status, p, kind) => { emit({ status, ticket: o.ticket, branch, path: p, kind }); return 0; };
+
+  const wl = git(['-C', o.repo, 'worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return fail(`git worktree list failed: ${firstLine(wl.stderr) || 'exit ' + wl.status}`);
+  const held = parseWorktrees(wl.stdout).find((w) => w.branch === `refs/heads/${branch}`);
+  if (held) {
+    if (!fs.existsSync(held.path)) return fail(`stale worktree of ${branch}: ${held.path} is gone from disk but git still lists it; run git worktree prune and retry`);
+    return result('reentered', held.path, 'worktree');
+  }
+
+  // The slot path is checked before the submodule rule, so an existing path is never cloned over.
+  if (fs.existsSync(target)) {
+    if (cloneOnBranch(git, fs, target, branch)) return result('reentered', target, 'clone');
+    return fail(`slot path already exists and is not a checkout of ${branch}: ${target}`);
+  }
+
+  if (hasSubmodule(fs, main)) return result('clone-required', target, 'clone');
+
+  const exists = git(['-C', o.repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+  if (exists.status === 0) {
+    const add = git(['-C', o.repo, 'worktree', 'add', target, branch]);
+    if (add.status !== 0) return fail(`git worktree add failed: ${firstLine(add.stderr) || 'exit ' + add.status}`);
+    return result('reattached', target, 'worktree');
+  }
+
+  const base = git(['-C', o.repo, 'rev-parse', '--verify', '--quiet', `${o.base}^{commit}`]);
+  if (base.status !== 0) return fail(`base does not resolve to a commit: ${o.base}`);
+  const add = git(['-C', o.repo, 'worktree', 'add', '-b', branch, target, base.stdout.trim()]);
+  if (add.status !== 0) return fail(`git worktree add failed: ${firstLine(add.stderr) || 'exit ' + add.status}`);
+  return result('created', target, 'worktree');
+}
+
+// --- list ---------------------------------------------------------------------
+
+// { workState, warning } for the checkout at dir.
+function readWorkState(fs, dir) {
+  const file = path.join(dir, '.trailhead', 'work-state.json');
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (e) {
+    if (e && e.code === 'ENOENT') return { workState: null, warning: null };
+    return { workState: null, warning: `unreadable work state at ${file}` };
+  }
+  try { return { workState: JSON.parse(raw), warning: null }; } catch {
+    return { workState: null, warning: `unparseable work state at ${file}` };
+  }
+}
+
+function isDirty(git, dir) {
+  const r = git(['-C', dir, 'status', '--porcelain']);
+  return r.status === 0 ? { dirty: r.stdout.trim() !== '', warning: null } : { dirty: null, warning: `git status failed at ${dir}` };
+}
+
+// True when dir is an independent checkout (its git dir lives inside it) on `branch`.
+function cloneOnBranch(git, fs, dir, branch) {
+  const g = git(['-C', dir, 'rev-parse', '--absolute-git-dir']);
+  if (g.status !== 0) return false;
+  const gitDir = realOr(fs, g.stdout.trim());
+  const root = realOr(fs, dir);
+  if (gitDir !== root && !gitDir.startsWith(root + path.sep)) return false;
+  const b = git(['-C', dir, 'symbolic-ref', '--quiet', 'HEAD']);
+  return b.status === 0 && b.stdout.trim() === `refs/heads/${branch}`;
+}
+
+function listSlots(ctx, o) {
+  const { git, fs, main, fail, emit } = ctx;
+  const wl = git(['-C', o.repo, 'worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return fail(`git worktree list failed: ${firstLine(wl.stderr) || 'exit ' + wl.status}`);
+  const entries = [];
+  const warnings = [];
+  const seen = new Set();
+  for (const w of parseWorktrees(wl.stdout)) {
+    const m = w.branch && BRANCH_RE.exec(w.branch);
+    if (!m || realOr(fs, w.path) === main) continue;
+    seen.add(realOr(fs, w.path));
+    if (!fs.existsSync(w.path)) {
+      warnings.push(`stale worktree of ${branchOf(m[1])}: ${w.path} is gone from disk but git still lists it; run git worktree prune`);
+      continue;
+    }
+    entries.push({ ticket: Number(m[1]), kind: 'worktree', branch: branchOf(m[1]), path: w.path });
+  }
+
+  const parent = path.dirname(main);
+  const re = new RegExp(`^${path.basename(main).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-t(\\d+)$`);
+  let names = [];
+  try { names = fs.readdirSync(parent); } catch { /* unreadable parent: no clones */ }
+  for (const name of names) {
+    const m = re.exec(name);
+    if (!m) continue;
+    const dir = path.join(parent, name);
+    if (seen.has(realOr(fs, dir))) continue;
+    if (!cloneOnBranch(git, fs, dir, branchOf(m[1]))) continue;
+    entries.push({ ticket: Number(m[1]), kind: 'clone', branch: branchOf(m[1]), path: dir });
+  }
+
+  const slots = entries.sort((a, b) => a.ticket - b.ticket).map((e) => {
+    const d = isDirty(git, e.path);
+    const s = readWorkState(fs, e.path);
+    for (const w of [d.warning, s.warning]) if (w) warnings.push(w);
+    return { ...e, dirty: d.dirty, workState: s.workState };
+  });
+  emit({ status: 'ok', slots, warnings });
+  return 0;
+}
+
+function main(argv, { git, stdout, stderr, fs } = {}) {
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const o = parseArgs(argv || []);
+  if (o.error) { err.write(o.error + '\n'); return 2; }
+  const fsx = fs || nodeFs;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason) => { emit({ status: 'error', reason }); return 1; };
+  const ctx = { git: git || defaultGit, fs: fsx, main: realOr(fsx, o.repo), fail, emit };
+  return o.cmd === 'open' ? openSlot(ctx, o) : listSlots(ctx, o);
+}
+
+module.exports = { main, parseArgs, parseWorktrees, hasSubmodule };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}

package/plugins/trailhead/templates/trailhead-checkout-in.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead checkout-in (self-contained, ships in templates/ so it reaches every
+// install channel). The panel cannot move the session's directory, so it hands the
+// pinned checkout to `work` / `resume` as a trailing `--in=<token>` word and the
+// verb moves there first. This helper decodes the token, validates it and says
+// whether the session is already there. It fails closed: it never searches for
+// another checkout. #312.
+//
+// The token is base64url(path) (alphabet [A-Za-z0-9_-], no padding), so a path
+// with spaces, quotes or a leading `-` travels as one shell-safe word.
+//
+// CLI:
+//   node trailhead-checkout-in.js --in <b64url> --cwd <dir>
+//
+// Prints exactly one JSON line on stdout:
+//   {"status":"here"|"move"|"invalid","path":"...","reason":"...","cd":"..."}
+// `cd` is present on `move` only: a ready-to-run, single-quote-escaped command.
+// Exit 0 for the three statuses, 2 on a usage error (stderr).
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PREFIX = '--in=';
+
+function encodeIn(p) {
+  return PREFIX + Buffer.from(String(p), 'utf8').toString('base64url');
+}
+
+function decodeIn(token) {
+  if (typeof token !== 'string' || !/^[A-Za-z0-9_-]+$/.test(token)) return null;
+  const p = Buffer.from(token, 'base64url').toString('utf8');
+  // Round-trip guard: a token that does not re-encode to itself is not ours.
+  return p !== '' && Buffer.from(p, 'utf8').toString('base64url') === token ? p : null;
+}
+
+function real(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function toplevelOf(dir) {
+  const r = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  if (r.status !== 0) return null;
+  const top = r.stdout.replace(/\n$/, '');
+  return top === '' ? null : real(top);
+}
+
+// POSIX single-quote escaping: ' becomes '\''.
+function cdCommand(p) {
+  return `cd -- '${p.replace(/'/g, `'\\''`)}'`;
+}
+
+function check(token, cwd) {
+  const p = decodeIn(token);
+  if (p === null) return { status: 'invalid', path: '', reason: 'the token does not decode to a path' };
+  if (!path.isAbsolute(p)) return { status: 'invalid', path: p, reason: 'the path is not absolute' };
+  const canon = real(p);
+  if (canon === null) return { status: 'invalid', path: p, reason: 'the path does not exist' };
+  // The path must be a checkout root itself, never a folder inside one.
+  if (toplevelOf(p) !== canon) return { status: 'invalid', path: p, reason: 'the path is not the root of a git checkout' };
+  const here = real(cwd) !== null ? toplevelOf(cwd) : null;
+  if (here === canon) return { status: 'here', path: p };
+  return { status: 'move', path: p, cd: cdCommand(p) };
+}
+
+function main(argv) {
+  const get = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+  };
+  const token = get('--in');
+  const cwd = get('--cwd');
+  if (token === null || cwd === null) {
+    process.stderr.write('usage: trailhead-checkout-in.js --in <b64url> --cwd <dir>\n');
+    return 2;
+  }
+  process.stdout.write(JSON.stringify(check(token, cwd)) + '\n');
+  return 0;
+}
+
+module.exports = { encodeIn, decodeIn, check, cdCommand };
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));

package/plugins/trailhead/templates/trailhead-dashboard.js

@@ -13,6 +13,9 @@
 // existing body. --dry-run gathers and reads through gh, computes and scans, but
 // writes, creates, pins and labels nothing; it prints the old and new byte sizes.
 //
+// Singleton labels (dashboard, codebase, conventions): more than one open issue
+// aborts before any write, naming every duplicate by title and number.
+//
 // Self-heal: ensures the `trailhead:dashboard` label; creates the issue directly
 // with the final scanned body when it is missing (never an empty or placeholder
 // body) and pins it; re-pins it when unpinned. Never closes or prunes a map: the
@@ -165,12 +168,33 @@ function gatherMap(gh, repo, m, truncated) {
   return out;
 }
 
-function firstNumber(gh, repo, label) {
-  const list = issueList(gh, repo, ['--label', label, '--state', 'open', '--json', 'number', '--limit', '1']);
-  return list.length ? list[0].number : null;
+// Singleton labels: exactly one open issue each. More than one is ambiguous and
+// never resolved by picking one (#274).
+const SINGLETON_LIMIT = 10;
+const SINGLETON_LABELS = [LABEL, 'trailhead:codebase', 'trailhead:conventions'];
+
+// Looks up every singleton label first and aborts (GatherError) naming all the
+// duplicated ones at once, before anything is written. Returns the single
+// number per label, or null when there is none.
+function lookupSingletons(gh, repo) {
+  const found = SINGLETON_LABELS.map((label) => ({
+    label,
+    list: issueList(gh, repo, ['--label', label, '--state', 'open', '--json', 'number,title', '--limit', String(SINGLETON_LIMIT)]),
+  }));
+  const dupes = found.filter((f) => f.list.length > 1);
+  if (dupes.length) {
+    // Control characters are stripped so the one-line stdout stays safe; a list
+    // that filled the fetch limit may be cut, so say more may exist.
+    const safe = (title) => linkText(title).replace(/[\x00-\x1f\x7f]/g, '');
+    const named = dupes.map((f) => `${f.label}: ${f.list.map((i) => `${safe(i.title)} (#${i.number})`).join(', ')}${f.list.length >= SINGLETON_LIMIT ? ', and possibly more' : ''}`).join('; ');
+    throw new GatherError(`ambiguous singleton issues, close the duplicates and keep one: ${named}`);
+  }
+  const num = (label) => { const f = found.find((x) => x.label === label); return f.list.length ? f.list[0].number : null; };
+  return { dashboard: num(LABEL), codebase: num('trailhead:codebase'), conventions: num('trailhead:conventions') };
 }
 
-function gatherSnapshot(gh, repo) {
+function gatherSnapshot(gh, repo, singles) {
+  const one = singles || lookupSingletons(gh, repo);
   const truncated = [];
   const capped = (list, limit, name) => { if (list.length >= limit) truncated.push(name); return list; };
   const maps = capped(issueList(gh, repo, ['--label', 'trailhead:map', '--state', 'open', '--json', 'number,title', '--limit', String(LIMITS.maps)]), LIMITS.maps, 'maps')
@@ -190,7 +214,7 @@ function gatherSnapshot(gh, repo) {
   if (closed.length >= LIMITS.resolved && resolved.length < RESOLVED_SHOWN) truncated.push('resolved');
   const openIssues = capped(issueList(gh, repo, ['--state', 'open', '--json', 'number,labels', '--limit', String(LIMITS.inbox)]), LIMITS.inbox, 'inbox');
   const inbox = openIssues.filter((i) => !names(i.labels).some((n) => n.startsWith('trailhead:'))).length;
-  const anchors = { codebase: firstNumber(gh, repo, 'trailhead:codebase'), conventions: firstNumber(gh, repo, 'trailhead:conventions') };
+  const anchors = { codebase: one.codebase, conventions: one.conventions };
   return { repo, maps, whiteboard, resolved, inbox, anchors, lastAudit: null, truncated };
 }
 
@@ -209,11 +233,6 @@ function summaryLine(number, snap) {
   return `dashboard${number === null ? '' : ' #' + number}: ${snap.maps.length} maps, whiteboard ${snap.whiteboard.length}, flags: ${flagSummary(snap.maps)}${cut}`;
 }
 
-function findDashboard(gh, repo) {
-  const list = issueList(gh, repo, ['--label', LABEL, '--state', 'open', '--json', 'number', '--limit', '1']);
-  return list.length ? list[0].number : null;
-}
-
 function isPinned(gh, repo, number) {
   const [owner, name] = repo.split('/');
   const q = 'query($o:String!,$n:String!){repository(owner:$o,name:$n){pinnedIssues(first:3){nodes{issue{number}}}}}';
@@ -284,10 +303,11 @@ function main(argv, { gh, stdout, stderr, guard, tmpdir, firstEditDelta2 } = {})
   try {
     const repo = o.repo || defaultRepo(run);
     if (!repo) return abort('cannot resolve the repository (pass --repo owner/name)');
+    const singles = lookupSingletons(run, repo); // fail closed on duplicates, before any write
     if (!o.dryRun) run(['label', 'create', LABEL, '--color', '5319E7', '--description', 'Pinned index of the trailhead surface', '-R', repo]); // idempotent, failure = already there
-    const snap = gatherSnapshot(run, repo);
+    const snap = gatherSnapshot(run, repo, singles);
     const marker = o.setLastAudit ? `<!-- trailhead:last-audit ${o.setLastAudit} -->` : null;
-    const number = findDashboard(run, repo);
+    const number = singles.dashboard;
 
     if (number === null) {
       const body = renderDashboard({ ...snap, lastAudit: marker });