@marcomigozzi/trailhead 0.15.0 → 0.16.0

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

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto queue (self-contained, ships in templates/ so it reaches every
+// install channel). Builds the ordered work queue of an autonomous run for a chosen
+// run scope: one map, the whiteboard, or everything. #280.
+//
+// CLI:
+//   node trailhead-auto-queue.js scopes [--repo <owner/name>]
+//   node trailhead-auto-queue.js queue --scope map:<n>|whiteboard|everything
+//        [--skip <csv>] [--repo <owner/name>]
+//
+// The frontier is the canonical frontier query (substrate-commands.md): open,
+// `trailhead:ticket`, unassigned, not blocked / unverified / paused. The
+// `trailhead:blocked` label is the source of truth for blockers; this helper adds
+// no dependency logic. The run's own read also skips `trailhead:needs-you` (a ticket
+// a run parked for the human); the human frontier does not. Groups are ordered by
+// map number ascending, the whiteboard last; tickets inside a group ascending by
+// number. `--skip` names the tickets the
+// run already marked needs-you or stopped on; `next` is the lowest ticket of the first
+// group that still has one (null when the scope is drained). A read that hits the
+// 1000 limit fails closed (never a partial queue).
+//
+// Prints exactly one JSON line on stdout:
+//   scopes: {"status":"ok","maps":[{"number","title","frontier"}],"whiteboard":{"frontier"}}
+//   queue:  {"status":"ok","scope","groups":[{"kind","map","title","tickets":[{"number","title","type"}],"resume":[...]}],"drift":[...],"next":{...}|null}
+//   error:  {"status":"error","reason":"..."}
+// Exit 0 on ok, 1 on an error, 2 on a usage error (stderr).
+
+const { spawnSync } = require('child_process');
+
+const LIMIT = 1000;
+const FRONTIER_SEARCH = 'no:assignee -label:trailhead:blocked -label:trailhead:unverified -label:trailhead:paused';
+const NEEDS_YOU = 'trailhead:needs-you';
+// The run's own frontier read: the canonical frontier minus the tickets a run parked
+// for the human. Humans still see those on the frontier (FRONTIER_SEARCH is unchanged).
+const RUN_SEARCH = FRONTIER_SEARCH + ' -label:' + NEEDS_YOU;
+const WHITEBOARD = 'trailhead:whiteboard';
+const MAP_LABEL_RE = /^trailhead:map-(\d+)$/;
+const TYPES = ['decision', 'research', 'prototype', 'build', 'bug', 'task'];
+
+function defaultGh(args) {
+  const r = spawnSync('gh', 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 names = (labels) => (labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+const byNumber = (a, b) => a.number - b.number;
+
+function parseScope(v) {
+  if (v === 'everything' || v === 'whiteboard') return v;
+  return /^map:[1-9]\d*$/.test(String(v)) ? v : null;
+}
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (cmd !== 'scopes' && cmd !== 'queue') return { error: `usage: expected scopes or queue, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const o = { cmd, repo: null, scope: null, skip: [] };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    const allowed = cmd === 'queue' ? ['--repo', '--scope', '--skip'] : ['--repo'];
+    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 === '--repo') {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(v)) return { error: `usage: --repo must be owner/name, got: ${v}` };
+      o.repo = v;
+    } else if (flag === '--scope') {
+      o.scope = parseScope(v);
+      if (!o.scope) return { error: `usage: --scope must be map:<n>, whiteboard or everything, got: ${v}` };
+    } else {
+      const parts = v.split(',').map((s) => s.trim()).filter(Boolean);
+      if (!parts.every((s) => /^[1-9]\d*$/.test(s))) return { error: `usage: --skip must be a csv of ticket numbers, got: ${v}` };
+      o.skip = parts.map(Number);
+    }
+  }
+  if (cmd === 'queue' && !o.scope) return { error: 'usage: queue requires --scope' };
+  return o;
+}
+
+const typeOf = (labelNames) => {
+  const t = TYPES.find((x) => labelNames.includes(`trailhead:${x}`));
+  return t || null;
+};
+
+// Places each ticket: on its open map, else the whiteboard, else nowhere. A ticket
+// on more than one open map is drift (placed on none).
+function place(openMaps, issues) {
+  const open = new Set(openMaps.map((m) => m.number));
+  const byMap = new Map(openMaps.map((m) => [m.number, []]));
+  const whiteboard = [];
+  const drift = [];
+  for (const i of issues) {
+    const ln = names(i.labels);
+    const mapNums = ln.map((l) => (MAP_LABEL_RE.exec(l) || [])[1]).filter(Boolean).map(Number).filter((n) => open.has(n));
+    const row = { number: i.number, title: i.title, type: typeOf(ln) };
+    if (mapNums.length > 1) drift.push({ ...row, maps: [...new Set(mapNums)].sort((a, b) => a - b), whiteboard: ln.includes(WHITEBOARD) });
+    else if (mapNums.length === 1) byMap.get(mapNums[0]).push(row);
+    else if (ln.includes(WHITEBOARD)) whiteboard.push(row);
+  }
+  return { byMap, whiteboard, drift };
+}
+
+// Pure: openMaps [{number,title}], frontier / paused issues [{number,title,labels}],
+// scope, skip [n]. Returns { groups, drift, next } or { error }.
+function buildQueue(openMaps, frontier, paused, scope, skip) {
+  const skipSet = new Set(skip || []);
+  // A needs-you ticket is dropped even when the search index lagged and returned it.
+  const live = (list) => list.filter((i) => !skipSet.has(i.number) && !names(i.labels).includes(NEEDS_YOU));
+  const maps = [...openMaps].sort(byNumber);
+  let wantMaps = maps;
+  let wantWhiteboard = scope === 'whiteboard' || scope === 'everything';
+  if (scope === 'whiteboard') wantMaps = [];
+  else if (scope.startsWith('map:')) {
+    const n = Number(scope.slice(4));
+    wantMaps = maps.filter((m) => m.number === n);
+    if (!wantMaps.length) return { error: `map #${n} is not an open trailhead:map` };
+    wantWhiteboard = false;
+  }
+  const f = place(maps, live(frontier));
+  const p = place(maps, live(paused));
+  const sorted = (rows) => [...rows].sort(byNumber);
+  const groups = wantMaps.map((m) => ({ kind: 'map', map: m.number, title: m.title, tickets: sorted(f.byMap.get(m.number)), resume: sorted(p.byMap.get(m.number)) }));
+  if (wantWhiteboard) groups.push({ kind: 'whiteboard', map: null, title: 'Whiteboard', tickets: sorted(f.whiteboard), resume: sorted(p.whiteboard) });
+  const inScope = (d) => (scope === 'everything'
+    || (scope === 'whiteboard' && d.whiteboard)
+    || (scope.startsWith('map:') && d.maps.includes(Number(scope.slice(4)))));
+  const seen = new Set();
+  const drift = [...f.drift, ...p.drift].filter(inScope).filter((d) => !seen.has(d.number) && seen.add(d.number)).sort(byNumber)
+    .map(({ number, title, type, maps: ms }) => ({ number, title, type, maps: ms }));
+  const first = groups.find((g) => g.tickets.length);
+  const next = first ? { ...first.tickets[0], map: first.map } : null;
+  return { groups, drift, next };
+}
+
+function readList(run, args, what) {
+  const r = run(args);
+  if (r.status !== 0) return { error: `gh issue list (${what}) failed: ${firstLine(r.stderr) || 'exit ' + r.status}` };
+  let rows;
+  try { rows = JSON.parse(r.stdout); } catch { return { error: `gh issue list (${what}) returned unparseable JSON` }; }
+  if (!Array.isArray(rows)) return { error: `gh issue list (${what}) returned unexpected JSON` };
+  if (rows.length >= LIMIT) return { error: `incomplete list: the ${what} read hit the ${LIMIT} limit` };
+  return { rows };
+}
+
+function main(argv, { gh, stdout, stderr } = {}) {
+  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 run = gh || defaultGh;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason) => { emit({ status: 'error', reason }); return 1; };
+  const R = o.repo ? ['-R', o.repo] : [];
+  const lim = ['--limit', String(LIMIT)];
+
+  const maps = readList(run, ['issue', 'list', '--label', 'trailhead:map', '--state', 'open', ...lim, '--json', 'number,title', ...R], 'open maps');
+  if (maps.error) return fail(maps.error);
+  const frontier = readList(run, ['issue', 'list', '--label', 'trailhead:ticket', '--state', 'open', '--search', RUN_SEARCH, ...lim, '--json', 'number,title,labels', ...R], 'frontier');
+  if (frontier.error) return fail(frontier.error);
+
+  if (o.cmd === 'scopes') {
+    const q = buildQueue(maps.rows, frontier.rows, [], 'everything', []);
+    const wb = q.groups.find((g) => g.kind === 'whiteboard');
+    emit({
+      status: 'ok',
+      maps: q.groups.filter((g) => g.kind === 'map').map((g) => ({ number: g.map, title: g.title, frontier: g.tickets.length })),
+      whiteboard: { frontier: wb.tickets.length },
+    });
+    return 0;
+  }
+
+  const paused = readList(run, ['issue', 'list', '--label', 'trailhead:ticket', '--label', 'trailhead:paused', '--assignee', '@me', '--state', 'open', ...lim, '--json', 'number,title,labels', ...R], 'paused claims');
+  if (paused.error) return fail(paused.error);
+  const q = buildQueue(maps.rows, frontier.rows, paused.rows, o.scope, o.skip);
+  if (q.error) return fail(q.error);
+  emit({ status: 'ok', scope: o.scope, groups: q.groups, drift: q.drift, next: q.next });
+  return 0;
+}
+
+module.exports = { main, parseArgs, buildQueue, FRONTIER_SEARCH, RUN_SEARCH, NEEDS_YOU };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}

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

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto run record (self-contained, ships in templates/ so it reaches
+// every install channel: bin/trailhead.js copies templates/ wholesale for
+// Claude/npm and Codex). Persists the start-up choices and the working lists of
+// an autonomous run in <repo>/.trailhead/auto-run.json, so a run survives a
+// context compaction (and a crash) without asking again. #295.
+// Written at the main checkout only, never in a slot workspace.
+//
+// CLI:
+//   node trailhead-auto-run.js start --repo <dir> --scope <s> --slots <n> --review <r> [--replace]
+//   node trailhead-auto-run.js read --repo <dir>
+//   node trailhead-auto-run.js skip --repo <dir> --ticket <n>
+//   node trailhead-auto-run.js unmerged --repo <dir> --ticket <n> --branch <b>
+//        [--file <path> ...] [--merge-ticket <n>]
+//   node trailhead-auto-run.js clear --repo <dir>
+// --repo defaults to cwd. File shape:
+//   { version: 1, scope, slots, review, session, skip: [<n>...],
+//     unmerged: [{ ticket, branch, files: [...], mergeTicket: <n>|null }],
+//     startedAt, updatedAt }
+// scope: map:<n> | whiteboard | everything (trailhead-auto-queue.js tokens).
+// slots: 1 to 4. review: config | 1 | 2 | 3 | until (plan-review-rounds
+// tokens) or skip (the ask was skipped). session: CLAUDE_CODE_SESSION_ID at
+// start (null when unset, as on Codex).
+// Prints one JSON line {"status","path","record"?,"sameSession"?,"message"?}.
+//   start:    written | exists (record on file, kept unless --replace) | skipped
+//   read:     found (+ sameSession) | absent | corrupt | skipped
+//   skip, unmerged: written | absent | corrupt | skipped
+//   clear:    cleared | absent | skipped
+// A corrupt file (unparseable, or an invalid version/scope/slots/review) is
+// reported and never rewritten except by `start --replace`; invalid list
+// entries (skip, unmerged) are dropped from an otherwise found record.
+// Exit 0 on every normal outcome and on any unexpected I/O error (it must never
+// block the run: status skipped with the message); exit 2 only on a usage or
+// validation error (nothing is written).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const STATE_DIR = '.trailhead';
+const STATE_FILE = 'auto-run.json';
+const VERSION = 1;
+const REVIEWS = ['config', '1', '2', '3', 'until', 'skip'];
+const SCOPE_RE = /^(map:[1-9]\d*|whiteboard|everything)$/;
+const COMMANDS = ['start', 'read', 'skip', 'unmerged', 'clear'];
+const FLAGS = {
+  start: ['--repo', '--scope', '--slots', '--review', '--replace'],
+  read: ['--repo'],
+  skip: ['--repo', '--ticket'],
+  unmerged: ['--repo', '--ticket', '--branch', '--file', '--merge-ticket'],
+  clear: ['--repo'],
+};
+
+const isPosInt = (v) => Number.isInteger(v) && v > 0;
+const isLine = (v) => typeof v === 'string' && v.trim() !== '' && !/[\u0000-\u001f\u007f]/.test(v);
+
+// Strict parse of a positive integer from a CLI string; null if invalid.
+function parsePosInt(text) {
+  return /^[1-9]\d*$/.test(text) ? Number(text) : null;
+}
+
+// Lista di ticket: solo interi positivi, senza doppioni, in ordine crescente.
+function cleanTickets(list) {
+  if (!Array.isArray(list)) return [];
+  return [...new Set(list.filter(isPosInt))].sort((a, b) => a - b);
+}
+
+// Una voce unmerged valida o null (la voce invalida viene scartata).
+function cleanUnmerged(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!isPosInt(raw.ticket) || !isLine(raw.branch)) return null;
+  return {
+    ticket: raw.ticket,
+    branch: raw.branch.trim(),
+    files: Array.isArray(raw.files) ? raw.files.filter(isLine) : [],
+    mergeTicket: isPosInt(raw.mergeTicket) ? raw.mergeTicket : null,
+  };
+}
+
+// Una voce per ticket (l'ultima vince), in ordine di ticket.
+function cleanUnmergedList(list) {
+  if (!Array.isArray(list)) return [];
+  const byTicket = new Map();
+  for (const item of list) {
+    const entry = cleanUnmerged(item);
+    if (entry) byTicket.set(entry.ticket, entry);
+  }
+  return [...byTicket.values()].sort((a, b) => a.ticket - b.ticket);
+}
+
+// Normalizza un oggetto qualunque in un record. Un campo obbligatorio invalido
+// (version, scope, slots, review) rende il record corrotto: { error }.
+function sanitizeRecord(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { error: 'not an object' };
+  if (raw.version !== VERSION) return { error: 'invalid version' };
+  if (typeof raw.scope !== 'string' || !SCOPE_RE.test(raw.scope)) return { error: 'invalid scope' };
+  if (!Number.isInteger(raw.slots) || raw.slots < 1 || raw.slots > 4) return { error: 'invalid slots' };
+  if (!REVIEWS.includes(raw.review)) return { error: 'invalid review' };
+  return {
+    record: {
+      version: VERSION,
+      scope: raw.scope,
+      slots: raw.slots,
+      review: raw.review,
+      session: typeof raw.session === 'string' && raw.session !== '' ? raw.session : null,
+      skip: cleanTickets(raw.skip),
+      unmerged: cleanUnmergedList(raw.unmerged),
+      startedAt: typeof raw.startedAt === 'string' ? raw.startedAt : null,
+      updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : null,
+    },
+  };
+}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (!COMMANDS.includes(command)) {
+    return { error: `usage: expected one of ${COMMANDS.join(', ')}, got: ${command === undefined ? '(nothing)' : command}` };
+  }
+  const allowed = FLAGS[command];
+  const out = { command, repo: null, replace: false, files: [] };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    if (flag === '--replace') { out.replace = true; continue; }
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const value = argv[i];
+    if (flag === '--repo') out.repo = value;
+    else if (flag === '--scope') {
+      if (!SCOPE_RE.test(value)) return { error: `usage: --scope must be map:<n>, whiteboard or everything, got: ${value}` };
+      out.scope = value;
+    } else if (flag === '--slots') {
+      const n = parsePosInt(value);
+      if (n === null || n > 4) return { error: `usage: --slots must be 1 to 4, got: ${value}` };
+      out.slots = n;
+    } else if (flag === '--review') {
+      if (!REVIEWS.includes(value)) return { error: `usage: --review must be one of ${REVIEWS.join(', ')}, got: ${value}` };
+      out.review = value;
+    } else if (flag === '--ticket') {
+      if (parsePosInt(value) === null) return { error: `usage: --ticket must be a positive integer, got: ${value}` };
+      out.ticket = parsePosInt(value);
+    } else if (flag === '--merge-ticket') {
+      if (parsePosInt(value) === null) return { error: `usage: --merge-ticket must be a positive integer, got: ${value}` };
+      out.mergeTicket = parsePosInt(value);
+    } else if (flag === '--branch') {
+      if (!isLine(value)) return { error: 'usage: --branch must be a single non-empty line' };
+      out.branch = value.trim();
+    } else if (flag === '--file') {
+      if (!isLine(value)) return { error: 'usage: --file must be a single non-empty line' };
+      out.files.push(value);
+    }
+  }
+  const missing = { start: ['scope', 'slots', 'review'], skip: ['ticket'], unmerged: ['ticket', 'branch'] }[command] || [];
+  for (const key of missing) {
+    if (out[key] === undefined) return { error: `usage: ${command} needs --${key}` };
+  }
+  return out;
+}
+
+// Legge il file: { status: 'absent' } | { status: 'corrupt', message } | { status: 'found', record }.
+// Un errore di I/O (non di parsing) risale al chiamante, che risponde skipped.
+function readFile(file, fsMod) {
+  if (!fsMod.existsSync(file)) return { status: 'absent' };
+  const text = fsMod.readFileSync(file, 'utf8');
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { status: 'corrupt', message: 'unparseable: ' + err.message };
+  }
+  const s = sanitizeRecord(raw);
+  return s.error ? { status: 'corrupt', message: s.error } : { status: 'found', record: s.record };
+}
+
+// Scrittura atomica: temp univoco nella stessa cartella, poi rename sul file;
+// il temp viene rimosso se qualcosa fallisce.
+function writeAtomic(dir, file, text, fsMod) {
+  fsMod.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${STATE_FILE}.${process.pid}-${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fsMod.writeFileSync(tmp, text);
+    fsMod.renameSync(tmp, file);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmp); } catch { /* pulizia best effort */ }
+    throw err;
+  }
+}
+
+function writeResult(stdout, result) {
+  stdout.write(JSON.stringify(result) + '\n');
+}
+
+function main(argv, { cwd, stdout, stderr, env, fs: fsMod, now } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const err_ = stderr || process.stderr;
+  const env_ = env || process.env;
+  const fs_ = fsMod || fs;
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    err_.write(parsed.error + '\n');
+    return 2;
+  }
+
+  const repoDir = parsed.repo ? path.resolve(cwd_, parsed.repo) : cwd_;
+  const dir = path.join(repoDir, STATE_DIR);
+  const file = path.join(dir, STATE_FILE);
+  const stamp = (now || new Date()).toISOString();
+  const save = (record) => writeAtomic(dir, file, JSON.stringify(record, null, 2) + '\n', fs_);
+
+  try {
+    if (parsed.command === 'clear') {
+      if (!fs_.existsSync(file)) {
+        writeResult(out, { status: 'absent', path: file });
+        return 0;
+      }
+      fs_.unlinkSync(file);
+      writeResult(out, { status: 'cleared', path: file });
+      return 0;
+    }
+
+    const sessionEnv = env_.CLAUDE_CODE_SESSION_ID;
+    const session = typeof sessionEnv === 'string' && sessionEnv !== '' ? sessionEnv : null;
+    const existing = readFile(file, fs_);
+
+    if (parsed.command === 'read') {
+      if (existing.status !== 'found') {
+        const result = { status: existing.status, path: file };
+        if (existing.message) result.message = existing.message;
+        writeResult(out, result);
+        return 0;
+      }
+      const sameSession = session !== null && existing.record.session !== null && existing.record.session === session;
+      writeResult(out, { status: 'found', path: file, record: existing.record, sameSession });
+      return 0;
+    }
+
+    if (parsed.command === 'start') {
+      if (existing.status !== 'absent' && !parsed.replace) {
+        // Un record corrotto non si sovrascrive in silenzio: serve --replace.
+        writeResult(out, { status: 'exists', path: file, record: existing.record || null, ...(existing.message ? { message: existing.message } : {}) });
+        return 0;
+      }
+      const record = {
+        version: VERSION,
+        scope: parsed.scope,
+        slots: parsed.slots,
+        review: parsed.review,
+        session,
+        skip: [],
+        unmerged: [],
+        startedAt: stamp,
+        updatedAt: stamp,
+      };
+      save(record);
+      writeResult(out, { status: 'written', path: file, record });
+      return 0;
+    }
+
+    // skip / unmerged: servono un record leggibile.
+    if (existing.status !== 'found') {
+      const result = { status: existing.status, path: file };
+      if (existing.message) result.message = existing.message;
+      writeResult(out, result);
+      return 0;
+    }
+    const base = existing.record;
+    const next = parsed.command === 'skip'
+      ? { ...base, skip: cleanTickets([...base.skip, parsed.ticket]) }
+      : {
+        ...base,
+        unmerged: cleanUnmergedList([
+          ...base.unmerged,
+          { ticket: parsed.ticket, branch: parsed.branch, files: parsed.files, mergeTicket: parsed.mergeTicket === undefined ? null : parsed.mergeTicket },
+        ]),
+      };
+    const record = { ...next, updatedAt: stamp };
+    save(record);
+    writeResult(out, { status: 'written', path: file, record });
+    return 0;
+  } catch (err) {
+    writeResult(out, { status: 'skipped', path: file, message: 'error: ' + (err && err.message ? err.message : String(err)) });
+    return 0;
+  }
+}
+
+module.exports = { REVIEWS, sanitizeRecord, parseArgs, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, env: process.env });
+  process.exit(code);
+}