@marcomigozzi/trailhead 0.16.1 → 0.18.0

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

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead capture helper (self-contained, ships in templates/ so it reaches every
+// install channel). Scriptable capture for automations (CI, cron, bots): opens a bug,
+// todo, seed or idea with the full label wiring, without a chat session. #332.
+//
+// CLI:
+//   node trailhead-capture.js --type bug|todo|idea|seed --title <t> \
+//        (--body <b> | --body-file <path|->) --repo <owner/name> \
+//        [--map <n> | --of <n>] [--trigger <text>] [--unverified] \
+//        [--dedupe-key <key>] [--no-dashboard]
+//   --trigger is required for seed and rejected otherwise. --unverified is rejected for idea.
+//   --of is only for bug and is exclusive with --map (the ticket inherits the origin's map or the whiteboard).
+//   --dedupe-key matches ^[A-Za-z0-9._:-]{1,100}$ and makes the run idempotent.
+//
+// Flow (nothing is created on any pre-check failure): trust check, destination, dedupe,
+// secret-scan of the exact payload, create (labels ride in the one create call), label
+// read-back, post-create trust verification when the identity was unreadable, native
+// sub-issue edge (map tickets), dashboard refresh (whiteboard tickets).
+//
+// Prints exactly one JSON line on stdout:
+//   created:  {"status":"created","issue","url","type","destination","labels","trust","edge"?,"dashboard","warnings"}   exit 0
+//   existing: {"status":"existing","issue","url","dedupeKey"}                                          exit 0
+//   partial:  {"status":"partial","issue","url",...,"edge":"failed","warnings"}                        exit 3
+//   error:    {"status":"error","reason",...} ("trust":"insufficient" on a trust failure)             exit 1
+//   usage:    {"status":"usage","reason"} (also on stderr)                                              exit 2
+// A caller checking only the exit status therefore never mistakes a partial for success.
+
+const { spawnSync } = require('child_process');
+const { gitEnv } = require('./trailhead-git-env.js');
+const fs = require('fs');
+const path = require('path');
+
+const TYPES = ['bug', 'todo', 'idea', 'seed'];
+const TYPE_LABEL = { bug: 'trailhead:bug', todo: 'trailhead:build', seed: 'trailhead:build' };
+const ALLOWLIST_VAR = 'TRAILHEAD_LABEL_ALLOWLIST';
+const ACTIONS_BOT = 'github-actions[bot]';
+const SEARCH_CAP = 1000;
+const KEY_RE = /^[A-Za-z0-9._:-]{1,100}$/;
+
+function defaultGh(args, input) {
+  const r = spawnSync('gh', args, { input, encoding: 'utf8', env: gitEnv(), maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+function defaultSleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+const failText = (r) => firstLine(r.stderr) || 'exit ' + r.status;
+const markerFor = (key) => `<!-- trailhead-dedupe: ${key} -->`;
+
+// --- secret guard (same approach as trailhead-needs-you.js) -------------------
+
+function guardCandidates() {
+  return [
+    path.join(__dirname, '..', 'hooks', 'trailhead-secret-guard.js'),
+    path.join(__dirname, '..', '..', 'hooks', 'trailhead-secret-guard.js'),
+  ];
+}
+
+// The shipped secret-guard module ({ scan }), or null when none is found.
+function loadGuard(candidates = guardCandidates()) {
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      const m = require(file);
+      if (m && typeof m.scan === 'function') return m;
+    } catch { /* try the next layout */ }
+  }
+  return null;
+}
+
+// null when the text is clean, else the abort reason (fail closed).
+function secretProblem(text, guard) {
+  if (!guard || typeof guard.scan !== 'function') return 'secret-scan unavailable, nothing created';
+  try {
+    const hit = guard.scan(text, {});
+    return hit ? `secret detected (${hit}) in the payload, nothing created` : null;
+  } catch {
+    return 'secret-scan unavailable, nothing created';
+  }
+}
+
+// --- args ---------------------------------------------------------------------
+
+const VALUE_FLAGS = ['--type', '--title', '--body', '--body-file', '--repo', '--map', '--of', '--trigger', '--dedupe-key'];
+const BOOL_FLAGS = ['--unverified', '--no-dashboard'];
+
+function parseArgs(argv) {
+  const o = { type: null, title: null, body: null, bodyFile: null, repo: null, map: null, of: null, trigger: null, unverified: false, dedupeKey: null, noDashboard: false };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (BOOL_FLAGS.includes(flag)) {
+      if (flag === '--unverified') o.unverified = true; else o.noDashboard = true;
+      continue;
+    }
+    if (!VALUE_FLAGS.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 === '--type') {
+      if (!TYPES.includes(v)) return { error: `usage: --type must be one of ${TYPES.join('|')}, got: ${v}` };
+      o.type = v;
+    } else if (flag === '--repo') {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(v)) return { error: `usage: --repo must be owner/name, got: ${v}` };
+      o.repo = v;
+    } else if (flag === '--map' || flag === '--of') {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: ${flag} must be a positive integer, got: ${v}` };
+      o[flag === '--map' ? 'map' : 'of'] = Number(v);
+    } else if (flag === '--dedupe-key') {
+      if (!KEY_RE.test(v)) return { error: `usage: --dedupe-key must match ${KEY_RE}, got: ${v}` };
+      o.dedupeKey = v;
+    } else if (flag === '--title') o.title = v;
+    else if (flag === '--body') o.body = v;
+    else if (flag === '--body-file') o.bodyFile = v;
+    else o.trigger = v;
+  }
+  if (!o.type) return { error: 'usage: --type is required' };
+  if (o.title === null || !o.title.trim()) return { error: 'usage: a non-empty --title is required' };
+  if (!o.repo) return { error: 'usage: --repo is required' };
+  if (o.body !== null && o.bodyFile !== null) return { error: 'usage: --body and --body-file are mutually exclusive' };
+  if (o.body === null && o.bodyFile === null) return { error: 'usage: one of --body or --body-file is required' };
+  if (o.type === 'seed' && (o.trigger === null || !o.trigger.trim())) return { error: 'usage: seed requires a non-empty --trigger' };
+  if (o.type !== 'seed' && o.trigger !== null) return { error: 'usage: --trigger is only for --type seed' };
+  if (o.of !== null && o.type !== 'bug') return { error: 'usage: --of is only for --type bug' };
+  if (o.unverified && o.type === 'idea') return { error: 'usage: --unverified is only for ticket types (fog is already off the frontier)' };
+  if (o.of !== null && o.map !== null) return { error: 'usage: --of and --map are mutually exclusive' };
+  return o;
+}
+
+// --- pure payload ---------------------------------------------------------------
+
+// { title, body, labels, destination } from the resolved inputs. map: { number, title, url } | null,
+// of: { title, url } | null. Pure.
+function buildIssue({ type, title, body, map, of, trigger, unverified, dedupeKey }) {
+  const isIdea = type === 'idea';
+  const labels = isIdea ? ['trailhead:fog'] : ['trailhead:ticket', TYPE_LABEL[type]];
+  if (type === 'seed') labels.push('trailhead:seed', 'trailhead:blocked');
+  if (!isIdea) labels.push(map ? `trailhead:map-${map.number}` : 'trailhead:whiteboard');
+  if (!isIdea && unverified) labels.push('trailhead:unverified');
+
+  const parts = [];
+  if (map) parts.push(`Parent: [${map.title}](${map.url})`);
+  if (of) parts.push(`Regression of: [${of.title}](${of.url})`);
+  if (type === 'seed') parts.push(`Trigger: ${trigger.trim()}`);
+  parts.push(String(body).replace(/\s+$/, ''));
+  if (type === 'seed') parts.push(`## Blocked by\n\n- Trigger: ${trigger.trim()}`);
+  if (dedupeKey) parts.push(markerFor(dedupeKey));
+  const destination = map ? `map-${map.number}` : isIdea ? 'none' : 'whiteboard';
+  return { title: title.trim(), body: parts.join('\n\n') + '\n', labels, destination };
+}
+
+// The same parsing expression as templates/trailhead-label-guard.yml (parity is tested).
+function parseAllowlist(s) {
+  return (s || '').split(',').map((x) => x.trim().toLowerCase()).filter(Boolean);
+}
+
+// --- gh steps ---------------------------------------------------------------------
+
+function parseJson(r) {
+  if (r.status !== 0) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+// True when the login has write, maintain or admin on the repo. A failed read counts as none.
+function hasWrite(run, repo, login) {
+  const j = parseJson(run(['api', `repos/${repo}/collaborators/${login}/permission`]));
+  if (!j) return false;
+  return ['admin', 'write'].includes(j.permission) || j.role_name === 'maintain';
+}
+
+// The repository's own allowlist (the source the guard Action reads), never the local env.
+function readAllowlist(run, repo) {
+  const r = run(['api', `repos/${repo}/actions/variables/${ALLOWLIST_VAR}`, '--jq', '.value']);
+  return r.status === 0 ? parseAllowlist(r.stdout.trim()) : [];
+}
+
+// { trust: 'ok'|'allowlisted'|'pending'|'insufficient', login? }. The env argument is accepted
+// and deliberately ignored: a caller-controlled allowlist would defeat the check.
+function checkTrust(run, repo) {
+  const who = run(['api', 'user', '--jq', '.login']);
+  const login = who.status === 0 ? who.stdout.trim() : '';
+  if (!login) return { trust: 'pending' };
+  if (hasWrite(run, repo, login)) return { trust: 'ok', login };
+  if (readAllowlist(run, repo).includes(login.toLowerCase())) return { trust: 'allowlisted', login };
+  return { trust: 'insufficient', login };
+}
+
+// An open `trailhead:map` -> { number, title, url }, else { error }.
+function readMap(run, repo, n) {
+  const j = parseJson(run(['issue', 'view', String(n), '--json', 'state,title,url,labels', '-R', repo]));
+  if (!j) return { error: `cannot read map #${n}` };
+  const names = (j.labels || []).map((l) => (typeof l === 'string' ? l : l && l.name));
+  if (String(j.state).toUpperCase() !== 'OPEN') return { error: `map #${n} is not open` };
+  if (!names.includes('trailhead:map')) return { error: `#${n} is not a trailhead:map` };
+  return { number: n, title: String(j.title), url: String(j.url) };
+}
+
+// { map, of? } with map null for the whiteboard, or { error }.
+function resolveDestination(run, repo, { map, of }) {
+  if (map) {
+    const m = readMap(run, repo, map);
+    return m.error ? { error: m.error } : { map: m };
+  }
+  if (of) {
+    const unresolved = { error: 'origin destination unresolved' };
+    const j = parseJson(run(['issue', 'view', String(of), '--json', 'title,url,labels', '-R', repo]));
+    if (!j) return unresolved;
+    const names = (j.labels || []).map((l) => (typeof l === 'string' ? l : l && l.name));
+    const maps = names.filter((n) => /^trailhead:map-[1-9]\d*$/.test(n));
+    const origin = { title: String(j.title), url: String(j.url) };
+    if (maps.length === 1 && !names.includes('trailhead:whiteboard')) {
+      const m = readMap(run, repo, Number(maps[0].slice('trailhead:map-'.length)));
+      return m.error ? unresolved : { map: m, of: origin };
+    }
+    if (maps.length === 0 && names.includes('trailhead:whiteboard')) return { map: null, of: origin };
+    return unresolved;
+  }
+  return { map: null };
+}
+
+// Lines of `gh api --paginate ... --jq '... | tojson'`: one JSON document per line.
+function jsonLines(r) {
+  if (r.status !== 0) return null;
+  const out = [];
+  for (const line of r.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { return null; }
+  }
+  return out;
+}
+
+// { issue, url } for an open issue carrying the exact marker, null for none, { error } on failure.
+function findDuplicate(run, repo, key) {
+  const marker = markerFor(key);
+  const s = run(['issue', 'list', '-R', repo, '--state', 'open', '--search', `"trailhead-dedupe: ${key}" in:body`, '--json', 'number,url,body', '--limit', String(SEARCH_CAP)]);
+  const list = parseJson(s);
+  if (!Array.isArray(list)) return { error: `dedupe search failed: ${failText(s)}` };
+  const hit = list.find((i) => String(i.body || '').includes(marker));
+  if (hit) return { issue: hit.number, url: hit.url };
+  if (list.length < SEARCH_CAP) return null;
+  // A search at its cap cannot be trusted to be complete: scan every open issue.
+  const scan = run(['api', '--paginate', `repos/${repo}/issues?state=open&per_page=100`, '--jq', '.[] | {number, html_url, body, pr: (.pull_request != null)} | tojson']);
+  const rows = jsonLines(scan);
+  if (!rows) return { error: `dedupe scan failed: ${failText(scan)}` };
+  const found = rows.find((i) => !i.pr && String(i.body || '').includes(marker));
+  return found ? { issue: found.number, url: found.html_url } : null;
+}
+
+// Waits between reads of the issue events right after create: the endpoint can briefly return a
+// successful but empty (or partial) list before the labeled events are visible.
+const EVENTS_BACKOFF_MS = [1000, 2000, 4000];
+
+// { label, actor } of each trailhead:* labeled event on the issue, or null when unreadable.
+function labelEvents(run, repo, n) {
+  const r = run(['api', '--paginate', `repos/${repo}/issues/${n}/events`, '--jq', '.[] | select(.event == "labeled") | {label: .label.name, actor: .actor.login} | tojson']);
+  const rows = jsonLines(r);
+  if (!rows) return null;
+  return rows.filter((e) => String(e.label).startsWith('trailhead:')).map((e) => ({ label: String(e.label), actor: String(e.actor) }));
+}
+
+// Decides one actor's trust: 'actions-token' | 'allowlisted' | 'ok' | null.
+function actorTrust(run, repo, actor, allow) {
+  if (actor === ACTIONS_BOT) return 'actions-token';
+  if (allow.includes(actor.toLowerCase())) return 'allowlisted';
+  return hasWrite(run, repo, actor) ? 'ok' : null;
+}
+
+// Post-create trust for an unreadable identity: re-reads the events (bounded backoff) until every
+// expected trailhead:* label shows a labeled event, then every actor who applied one must be one the
+// guard Action never strips. 'actions-token' | 'allowlisted' | 'ok', { bad: actor }, or { error }.
+function verifyActors(run, repo, n, expected, nap) {
+  // Nothing to wait for would pass with no actor checked: fail closed.
+  if (!expected.length) return { error: 'no trailhead:* label to verify, so who applied the labels is unverified' };
+  let allow = null;
+  const rank = { 'actions-token': 0, allowlisted: 1, ok: 2 };
+  const trusts = new Map();
+  let events = null;
+  for (let attempt = 0; attempt <= EVENTS_BACKOFF_MS.length; attempt++) {
+    if (attempt) nap(EVENTS_BACKOFF_MS[attempt - 1]);
+    events = labelEvents(run, repo, n);
+    if (!events) continue;
+    // A bad actor seen on any read fails at once.
+    for (const actor of new Set(events.map((e) => e.actor))) {
+      if (trusts.has(actor)) continue;
+      if (!allow) allow = readAllowlist(run, repo);
+      const t = actorTrust(run, repo, actor, allow);
+      if (!t) return { bad: actor };
+      trusts.set(actor, t);
+    }
+    if (expected.every((l) => events.some((e) => e.label === l))) {
+      let result = 'actions-token';
+      for (const t of trusts.values()) if (rank[t] > rank[result]) result = t;
+      return { trust: result };
+    }
+  }
+  if (!events) return { error: 'the issue events could not be read, so who applied the labels is unverified' };
+  const unseen = expected.filter((l) => !events.some((e) => e.label === l));
+  return { error: `no visible labeled event for ${unseen.join(', ')}, so who applied the labels is unverified` };
+}
+
+function readBody(o, stdin) {
+  if (o.body !== null) return o.body;
+  try {
+    if (o.bodyFile === '-') return stdin !== undefined ? stdin : fs.readFileSync(0, 'utf8');
+    return fs.readFileSync(o.bodyFile, 'utf8');
+  } catch (e) {
+    return { error: `cannot read the body: ${e.message}` };
+  }
+}
+
+function main(argv, { gh, guard, stdout, stderr, sleep, dashboard, stdin } = {}) {
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const o = parseArgs(argv || []);
+  if (o.error) { emit({ status: 'usage', reason: o.error }); err.write(o.error + '\n'); return 2; }
+  const run = gh || defaultGh;
+  const nap = sleep || defaultSleep;
+  const fail = (reason, extra = {}) => { emit({ status: 'error', reason, ...extra }); return 1; };
+  const repo = o.repo;
+
+  const body = readBody(o, stdin);
+  if (body && typeof body === 'object') return fail(body.error);
+
+  // 2. trust (pre-create)
+  const tr = checkTrust(run, repo);
+  if (tr.trust === 'insufficient') {
+    return fail(`${tr.login} lacks write access and is not in the repository allowlist (${ALLOWLIST_VAR}): the label guard would strip the labels`, { trust: 'insufficient' });
+  }
+  let trust = tr.trust;
+
+  // 3. destination
+  const dest = resolveDestination(run, repo, o);
+  if (dest.error) return fail(dest.error);
+
+  // 4. dedupe
+  if (o.dedupeKey) {
+    const dup = findDuplicate(run, repo, o.dedupeKey);
+    if (dup && dup.error) return fail(dup.error);
+    if (dup) { emit({ status: 'existing', issue: dup.issue, url: dup.url, dedupeKey: o.dedupeKey }); return 0; }
+  }
+
+  // 5. build and secret-scan exactly the payload that will be sent
+  const built = buildIssue({ type: o.type, title: o.title, body, map: dest.map, of: dest.of, trigger: o.trigger, unverified: o.unverified, dedupeKey: o.dedupeKey });
+  const problem = secretProblem(`${built.title}\n\n${built.body}`, guard === undefined ? loadGuard() : guard);
+  if (problem) return fail(problem);
+
+  // 6. create
+  const isTicket = o.type !== 'idea';
+  if (isTicket && !dest.map) run(['label', 'create', 'trailhead:whiteboard', '--color', 'C5DEF5', '--description', 'Loose ticket, no map', '-R', repo]);
+  const c = run(['issue', 'create', '-R', repo, '--title', built.title, '--label', built.labels.join(','), '--body-file', '-'], built.body);
+  if (c.status !== 0) return fail(`gh issue create failed: ${failText(c)}`);
+  const m = /\/issues\/(\d+)\s*$/.exec(c.stdout.trim());
+  if (!m) return fail('gh issue create printed no issue URL');
+  const issue = Number(m[1]);
+  const url = c.stdout.trim().split('\n').pop().trim();
+  const made = { issue, url };
+
+  // 7. read-back
+  const rb = parseJson(run(['issue', 'view', String(issue), '--json', 'labels', '-R', repo]));
+  if (!rb) return fail('cannot read back the created issue labels', made);
+  const have = (rb.labels || []).map((l) => (typeof l === 'string' ? l : l && l.name));
+  const missing = built.labels.filter((l) => !have.includes(l));
+  if (missing.length) return fail(`labels missing: ${missing.join(', ')}`, made);
+
+  // 7b. unreadable identity: verify who applied the labels
+  if (trust === 'pending') {
+    const expected = built.labels.filter((l) => l.startsWith('trailhead:'));
+    const v = verifyActors(run, repo, issue, expected, nap);
+    if (v.error) return fail(v.error, { trust: 'insufficient', ...made });
+    if (!v.trust) return fail(`labels applied by ${v.bad} will be stripped by the label guard`, { trust: 'insufficient', ...made });
+    trust = v.trust;
+  }
+
+  // 8. native edge for a map ticket
+  const warnings = [];
+  const result = { status: 'created', ...made, type: o.type, destination: built.destination, labels: built.labels, trust };
+  if (isTicket && dest.map) {
+    let edge = false;
+    for (let attempt = 0; attempt < 2 && !edge; attempt++) {
+      if (attempt) nap(1000);
+      const id = run(['api', `repos/${repo}/issues/${issue}`, '--jq', '.id']);
+      if (id.status !== 0 || !id.stdout.trim()) continue;
+      const e = run(['api', '--method', 'POST', `repos/${repo}/issues/${dest.map.number}/sub_issues`, '-F', `sub_issue_id=${id.stdout.trim()}`]);
+      edge = e.status === 0;
+    }
+    if (!edge) {
+      warnings.push(`native sub-issue edge to map #${dest.map.number} failed (e.g. the 100 sub-issue cap); the ticket keeps its trailhead:map-${dest.map.number} label so it stays on the frontier; repair it with the trailhead prune command`);
+      result.status = 'partial';
+      result.edge = 'failed';
+    } else {
+      result.edge = 'ok';
+    }
+  }
+
+  // 10. dashboard: only for a whiteboard ticket
+  if (!isTicket || dest.map) result.dashboard = 'not-applicable';
+  else if (o.noDashboard) result.dashboard = 'skipped';
+  else {
+    const sink = { write: () => true };
+    const dash = dashboard || require('./trailhead-dashboard.js');
+    let code = 1;
+    try { code = dash.main(['--repo', repo, '--update-only'], { gh: run, stdout: sink, stderr: sink }); } catch { code = 1; }
+    if (code === 0) result.dashboard = 'refreshed';
+    else { result.dashboard = 'failed'; warnings.push('the dashboard refresh failed; refresh it with the trailhead dashboard command'); }
+  }
+  result.warnings = warnings;
+  emit(result);
+  return result.status === 'partial' ? 3 : 0;
+}
+
+module.exports = { main, parseArgs, buildIssue, parseAllowlist, checkTrust, verifyActors, resolveDestination, findDuplicate, loadGuard, secretProblem };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}

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

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead checkout-find (self-contained, ships in templates/ so it reaches every
+// install channel). When a checkout path a session was handed no longer exists (the
+// repo moved), this finds the repo's checkout by its `origin` remote instead of a
+// hand-run search of the disk. #329.
+//
+// Search order is an explicit precedence, not a uniqueness claim: the focused roots
+// first (the parent of --cwd and of its git toplevel, and the usual code folders under
+// $HOME), then $HOME itself only if they found nothing. `found` is the single match of
+// the first tier that has any; a later tier is never weighed against it.
+//
+// Walk: breadth-first, depth-limited, one realpath-visited set (overlapping roots and
+// symlink cycles never count a checkout twice), dot-dirs and node_modules skipped, a
+// found checkout never descended into. A directory holding `.git` (directory or file)
+// is a checkout; its origin is read with `git remote get-url origin`. A visited-dir
+// cap per tier bounds the walk; hitting it sets `truncated`, and a lone match under
+// truncation is reported `ambiguous`, never `found`, so the caller asks.
+//
+// Main checkouts (`.git` dir) and linked worktrees/submodules (`.git` file) are equal
+// candidates: the remote cannot tell a moved worktree from its main checkout.
+//
+// CLI:
+//   node trailhead-checkout-find.js --repo <[host/]owner/name> [--cwd <dir>]
+//        [--roots <dir>:<dir>...] [--depth <n>]
+// `--roots` replaces the default tiers with one explicit tier (tests, odd layouts).
+//
+// Prints exactly one JSON line on stdout (plus "truncated":true when the cap hit):
+//   {"status":"found","path":"..."}
+//   {"status":"ambiguous","candidates":[{"path":"...","kind":"main"|"linked"}]}
+//   {"status":"none","searched":["..."]}
+// Exit 0 for the three statuses, 2 on a usage error (stderr).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { gitEnv } = require('./trailhead-git-env.js');
+
+const DEFAULT_DEPTH = 3;
+const DEFAULT_CAP = 20000;
+const CODE_DIRS = ['Git', 'git', 'src', 'code', 'Code', 'projects', 'Projects', 'dev', 'repos', 'work', 'workspace'];
+
+// A remote URL as {host, path} (host lowercased, port kept), or null when it is not a
+// network remote (a local path, empty).
+function parseRemote(url) {
+  if (typeof url !== 'string') return null;
+  const s = url.trim();
+  if (s === '' || s.startsWith('/') || s.startsWith('.') || s.startsWith('-')) return null;
+  let host;
+  let rest;
+  const m = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/]+)\/(.*)$/.exec(s);
+  if (m) {
+    host = m[1];
+    rest = m[2];
+  } else {
+    // scp-like: [user@]host:path
+    const n = /^(?:[^@/:]+@)?([^/:]+):(.*)$/.exec(s);
+    if (!n) return null;
+    host = n[1];
+    rest = n[2];
+  }
+  rest = rest.replace(/^\/+/, '').replace(/\/+$/, '').replace(/\.git$/, '').replace(/\/+$/, '');
+  if (host === '' || rest === '') return null;
+  return { host: host.toLowerCase(), path: rest };
+}
+
+// A --repo argument: `owner/name` (any host) or `host/owner/name` (the first segment
+// is a host when there are 3+ segments and it holds a dot or a colon).
+function parseRepoArg(arg) {
+  if (typeof arg !== 'string') return null;
+  const parts = arg.trim().replace(/\/+$/, '').replace(/\.git$/, '').split('/');
+  if (parts.length < 2 || parts.some((p) => p === '')) return null;
+  if (parts.length >= 3 && /[.:]/.test(parts[0])) return { host: parts[0].toLowerCase(), path: parts.slice(1).join('/') };
+  return { host: null, path: parts.join('/') };
+}
+
+// The repo identity the panel token carries: `host/owner/name` by shape (3+ non-empty
+// segments, the first is the host, whatever it looks like: `gitea`, `localhost`).
+function parseRepoShape(text) {
+  if (typeof text !== 'string') return null;
+  const parts = text.split('/');
+  if (parts.length < 3 || parts.some((p) => p === '')) return null;
+  return { host: parts[0].toLowerCase(), path: parts.slice(1).join('/') };
+}
+
+const stripPort = (h) => h.replace(/:\d+$/, '');
+
+// Whether a remote URL is the wanted repo. Host: case-insensitive; a wanted host with
+// no port ignores the remote's port. Path: case-insensitive on github.com only.
+function matches(remoteUrl, repoArg) {
+  const remote = parseRemote(remoteUrl);
+  const want = typeof repoArg === 'string' ? parseRepoArg(repoArg) : repoArg;
+  if (remote === null || want === null) return false;
+  if (want.host !== null) {
+    const same = /:\d+$/.test(want.host) ? remote.host === want.host : stripPort(remote.host) === want.host;
+    if (!same) return false;
+  }
+  if (stripPort(remote.host) === 'github.com') return remote.path.toLowerCase() === want.path.toLowerCase();
+  return remote.path === want.path;
+}
+
+function real(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function defaultOrigin(dir) {
+  const r = spawnSync('git', ['-C', dir, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: gitEnv(), timeout: 5000 });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function toplevelOf(dir) {
+  const r = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: gitEnv(), timeout: 5000 });
+  return r.status === 0 && r.stdout.trim() !== '' ? real(r.stdout.replace(/\n$/, '')) : null;
+}
+
+function uniqueExisting(dirs) {
+  const seen = new Set();
+  const out = [];
+  for (const d of dirs) {
+    const r = d ? real(d) : null;
+    if (r !== null && !seen.has(r)) {
+      seen.add(r);
+      out.push(r);
+    }
+  }
+  return out;
+}
+
+// The default tiers: focused roots, then $HOME.
+function defaultTiers(cwd, home) {
+  const focused = [];
+  if (cwd) {
+    focused.push(path.dirname(path.resolve(cwd)));
+    const top = real(cwd) !== null ? toplevelOf(cwd) : null;
+    if (top !== null) focused.push(path.dirname(top));
+  }
+  for (const n of CODE_DIRS) focused.push(path.join(home, n));
+  const homeReal = real(home);
+  const first = uniqueExisting(focused).filter((d) => d !== '/' && d !== homeReal);
+  return [first, uniqueExisting([home])];
+}
+
+function kindOf(dir) {
+  try {
+    return fs.statSync(path.join(dir, '.git')).isDirectory() ? 'main' : 'linked';
+  } catch {
+    return null; // no .git
+  }
+}
+
+// One tier: breadth-first from its roots. Returns {matches, truncated}.
+function walkTier(roots, repo, o, visited) {
+  const matchesFound = [];
+  let visitedCount = 0;
+  let truncated = false;
+  const queue = roots.map((r) => [r, 0]);
+  for (let i = 0; i < queue.length; i++) {
+    const [dir, depth] = queue[i];
+    const rp = real(dir);
+    if (rp === null || visited.has(rp)) continue;
+    if (visitedCount >= o.cap) {
+      truncated = true;
+      break;
+    }
+    visited.add(rp);
+    visitedCount++;
+    const kind = kindOf(rp);
+    if (kind !== null) {
+      const origin = o.originOf(rp);
+      if (origin && matches(origin, repo)) matchesFound.push({ path: rp, kind });
+      continue;
+    }
+    if (depth >= o.depth) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(rp, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const child = path.join(rp, e.name);
+      let isDir = e.isDirectory();
+      if (!isDir && e.isSymbolicLink()) {
+        try {
+          isDir = fs.statSync(child).isDirectory();
+        } catch {
+          isDir = false;
+        }
+      }
+      if (isDir) queue.push([child, depth + 1]);
+    }
+  }
+  return { matches: matchesFound, truncated };
+}
+
+// findCheckouts(repo, {roots, tiers, cwd, home, depth, cap, originOf}) -> result object.
+// `roots` is one explicit tier; `tiers` several; neither means the defaults from cwd/home.
+function findCheckouts(repo, opts = {}) {
+  const o = {
+    depth: Number.isInteger(opts.depth) && opts.depth >= 0 ? opts.depth : DEFAULT_DEPTH,
+    cap: Number.isInteger(opts.cap) && opts.cap > 0 ? opts.cap : DEFAULT_CAP,
+    originOf: opts.originOf || defaultOrigin,
+  };
+  let tiers;
+  if (Array.isArray(opts.tiers)) tiers = opts.tiers.map(uniqueExisting);
+  else if (Array.isArray(opts.roots)) tiers = [uniqueExisting(opts.roots)];
+  else tiers = defaultTiers(opts.cwd || null, opts.home || process.env.HOME || os.homedir());
+  const visited = new Set();
+  const searched = [];
+  let truncated = false;
+  for (const tier of tiers) {
+    if (tier.length === 0) continue;
+    searched.push(...tier);
+    const r = walkTier(tier, repo, o, visited);
+    truncated = truncated || r.truncated;
+    if (r.matches.length === 0) continue;
+    const candidates = r.matches.sort((a, b) => (a.path < b.path ? -1 : 1));
+    const res = candidates.length === 1 && !r.truncated
+      ? { status: 'found', path: candidates[0].path }
+      : { status: 'ambiguous', candidates };
+    return r.truncated ? { ...res, truncated: true } : res;
+  }
+  return truncated ? { status: 'none', searched, truncated: true } : { status: 'none', searched };
+}
+
+function main(argv) {
+  const get = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+  };
+  const usage = (msg) => {
+    process.stderr.write(`${msg}\nusage: trailhead-checkout-find.js --repo <[host/]owner/name> [--cwd <dir>] [--roots <a:b>] [--depth <n>]\n`);
+    return 2;
+  };
+  const repo = get('--repo');
+  if (repo === null || parseRepoArg(repo) === null) return usage('--repo <[host/]owner/name> is required');
+  const opts = { cwd: get('--cwd') };
+  const roots = get('--roots');
+  if (roots !== null) opts.roots = roots.split(':').filter((r) => r !== '');
+  const depth = get('--depth');
+  if (depth !== null) {
+    if (!/^\d+$/.test(depth)) return usage('--depth must be a non-negative integer');
+    opts.depth = Number(depth);
+  }
+  process.stdout.write(JSON.stringify(findCheckouts(repo, opts)) + '\n');
+  return 0;
+}
+
+module.exports = { parseRemote, parseRepoArg, parseRepoShape, matches, findCheckouts };
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));