@marcomigozzi/trailhead 0.16.1 → 0.17.0

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

@@ -4,35 +4,61 @@
 // 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.
+// whether the session is already there. It fails closed: never a blind search for
+// another checkout, only a lookup by the repo's origin remote when the path is gone
+// and the token names the repo (trailhead-checkout-find.js). #312, #329.
 //
 // 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.
+// with spaces, quotes or a leading `-` travels as one shell-safe word. It may carry
+// the repo identity as a second part: base64url(path) + '.' + base64url(host/owner/name)
+// (`.` is outside the alphabet, so an old helper rejects it and stays fail-closed).
 //
 // CLI:
-//   node trailhead-checkout-in.js --in <b64url> --cwd <dir>
+//   node trailhead-checkout-in.js --in <token> --cwd <dir> [--roots <a:b>]
+// `--roots` replaces the default search roots of the remote lookup (tests).
 //
 // Prints exactly one JSON line on stdout:
-//   {"status":"here"|"move"|"invalid","path":"...","reason":"...","cd":"..."}
+//   {"status":"here"|"move"|"choose"|"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).
+// `relocatedFrom` (the old path) is added to `here`/`move` when the checkout was
+// found by its remote. `choose` (path gone, several checkouts match) carries
+// `candidates` ([{path, kind}]) and `reason`.
+// Exit 0 for the four statuses, 2 on a usage error (stderr).
 
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+const { findCheckouts, parseRepoShape } = require('./trailhead-checkout-find.js');
+
 const PREFIX = '--in=';
 
-function encodeIn(p) {
-  return PREFIX + Buffer.from(String(p), 'utf8').toString('base64url');
+const b64 = (s) => Buffer.from(String(s), 'utf8').toString('base64url');
+
+function encodeIn(p, repo) {
+  return PREFIX + b64(p) + (repo ? '.' + b64(repo) : '');
+}
+
+// One base64url part back to its string, or null when it is not canonical.
+function decodePart(part) {
+  if (!/^[A-Za-z0-9_-]+$/.test(part)) return null;
+  const s = Buffer.from(part, 'base64url').toString('utf8');
+  // Round-trip guard: a part that does not re-encode to itself is not ours.
+  return s !== '' && b64(s) === part ? s : null;
 }
 
+// {path, repo} (repo null for a one-part token), or null for a malformed token.
 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;
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length > 2) return null;
+  const p = decodePart(parts[0]);
+  if (p === null) return null;
+  if (parts.length === 1) return { path: p, repo: null };
+  const repo = decodePart(parts[1]);
+  // The repo part is `host/owner/name` by shape (the host may be dotless, e.g. `gitea`).
+  if (repo === null || parseRepoShape(repo) === null) return null;
+  return { path: p, repo };
 }
 
 function real(p) {
@@ -55,12 +81,8 @@ 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' };
+// here/move for a path that must be a checkout root.
+function resolveRoot(p, canon, cwd) {
   // 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;
@@ -68,6 +90,38 @@ function check(token, cwd) {
   return { status: 'move', path: p, cd: cdCommand(p) };
 }
 
+// The path is gone: look the repo up by its remote (only when the token names it).
+function relocate(old, repo, cwd, opts) {
+  const found = findCheckouts(parseRepoShape(repo), opts.roots ? { roots: opts.roots } : { cwd });
+  if (found.status === 'found') {
+    const root = resolveRoot(found.path, found.path, cwd);
+    return { ...root, relocatedFrom: old };
+  }
+  if (found.status === 'ambiguous') {
+    const cut = found.truncated ? ' (the search was cut short)' : '';
+    return {
+      status: 'choose',
+      path: old,
+      candidates: found.candidates,
+      reason: `the path does not exist and ${found.candidates.length === 1 ? 'a checkout' : 'several checkouts'} of ${repo} may match${cut}`,
+    };
+  }
+  return { status: 'invalid', path: old, reason: `the path does not exist and no checkout of ${repo} was found` };
+}
+
+function check(token, cwd, opts = {}) {
+  const d = decodeIn(token);
+  if (d === null) return { status: 'invalid', path: '', reason: 'the token does not decode to a path' };
+  const p = d.path;
+  if (!path.isAbsolute(p)) return { status: 'invalid', path: p, reason: 'the path is not absolute' };
+  const canon = real(p);
+  if (canon === null) {
+    if (d.repo === null) return { status: 'invalid', path: p, reason: 'the path does not exist' };
+    return relocate(p, d.repo, cwd, opts);
+  }
+  return resolveRoot(p, canon, cwd);
+}
+
 function main(argv) {
   const get = (flag) => {
     const i = argv.indexOf(flag);
@@ -75,11 +129,13 @@ function main(argv) {
   };
   const token = get('--in');
   const cwd = get('--cwd');
+  const roots = get('--roots');
   if (token === null || cwd === null) {
-    process.stderr.write('usage: trailhead-checkout-in.js --in <b64url> --cwd <dir>\n');
+    process.stderr.write('usage: trailhead-checkout-in.js --in <token> --cwd <dir> [--roots <a:b>]\n');
     return 2;
   }
-  process.stdout.write(JSON.stringify(check(token, cwd)) + '\n');
+  const opts = roots === null ? {} : { roots: roots.split(':').filter((r) => r !== '') };
+  process.stdout.write(JSON.stringify(check(token, cwd, opts)) + '\n');
   return 0;
 }
 

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

@@ -7,11 +7,18 @@
 // updatedAt check, post-write conflict check, secret scan). #253.
 //
 // CLI:
-//   node trailhead-dashboard.js [--repo <owner/name>] [--set-last-audit <ISO-8601 UTC>] [--dry-run]
+//   node trailhead-dashboard.js [--repo <owner/name>] [--set-last-audit <ISO-8601 UTC>] [--dry-run] [--update-only]
 // --set-last-audit replaces the `<!-- trailhead:last-audit ... -->` marker (the
 // audit's only writer path); without it the marker is copied verbatim from the
 // 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.
+// --update-only refreshes an existing dashboard and never opens one: with no open
+// dashboard issue it creates, pins and labels nothing (the label ensure is skipped
+// too) and prints `skipped: no dashboard issue (update-only)`, exit 0. A capture
+// uses it so it cannot open a second issue; the check lives here, in the helper,
+// so there is no check-then-call race. That is all it forbids: it never creates the
+// dashboard. With a dashboard present it is a normal refresh (the label ensure and
+// the re-pin run as usual, both idempotent).
 //
 // Singleton labels (dashboard, codebase, conventions): more than one open issue
 // aborts before any write, naming every duplicate by title and number.
@@ -23,6 +30,7 @@
 //
 // Prints exactly one line on stdout:
 //   dashboard #33: 4 maps, whiteboard 1, flags: map-14 exhausted, map-98 near cap 92/100 (body 21034 -> 2210 bytes)
+//   skipped: no dashboard issue (update-only)
 //   aborted: <reason>
 // Exit 0 on success, 1 on an abort or a conflict, 2 on a usage error (stderr).
 // A pin check or pin failure AFTER the body was written is not an abort: the line
@@ -266,10 +274,11 @@ function createDashboard(gh, repo, body, tmpdir) {
 // --- CLI ---------------------------------------------------------------------
 
 function parseArgs(argv) {
-  const o = { repo: null, setLastAudit: null, dryRun: false };
+  const o = { repo: null, setLastAudit: null, dryRun: false, updateOnly: false };
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
     if (flag === '--dry-run') { o.dryRun = true; continue; }
+    if (flag === '--update-only') { o.updateOnly = true; continue; }
     if (flag !== '--repo' && flag !== '--set-last-audit') return { error: `usage: unknown argument: ${flag}` };
     i++;
     if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
@@ -304,6 +313,10 @@ function main(argv, { gh, stdout, stderr, guard, tmpdir, firstEditDelta2 } = {})
     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.updateOnly && singles.dashboard === null) {
+      out.write('skipped: no dashboard issue (update-only)\n');
+      return 0;
+    }
     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, singles);
     const marker = o.setLastAudit ? `<!-- trailhead:last-audit ${o.setLastAudit} -->` : null;

package/plugins/trailhead/templates/trailhead-issue-body.js

@@ -116,20 +116,80 @@ function bodyLines(text) {
   return t === '' ? [] : t.split('\n');
 }
 
-// A list entry: a top-level `- ` line plus the indented lines that follow it.
+// A list entry: a top-level bullet (`- `, `* `, `+ `) or ordered item (`1. `, `1) `)
+// plus the indented lines that follow it (a continuation paragraph may follow blank
+// lines; the entry's end excludes trailing blanks). Ordered entries carry their number and
+// delimiter (null for a bullet); an indented `1.` is a continuation, not an entry.
 function listEntries(lines, sec) {
   const entries = [];
   const end = contentEnd(lines, sec);
   for (let i = sec.from; i < end; i++) {
-    if (!/^[-*+][ \t]/.test(lines[i])) continue;
+    const m = /^(?:[-*+]|(\d+)([.)]))[ \t]/.exec(lines[i]);
+    if (!m) continue;
     let j = i + 1;
-    while (j < end && /^[ \t]+\S/.test(lines[j])) j++;
-    entries.push({ start: i, end: j, text: lines.slice(i, j).join('\n') });
+    for (;;) {
+      // Blank lines belong to the entry only when an indented line follows them.
+      let k = j;
+      while (k < end && isBlank(lines[k])) k++;
+      if (k >= end || !/^[ \t]+\S/.test(lines[k])) break;
+      j = k + 1;
+    }
+    entries.push({
+      start: i,
+      end: j,
+      text: lines.slice(i, j).join('\n'),
+      num: m[1] === undefined ? null : Number(m[1]),
+      numText: m[1] === undefined ? '' : m[1],
+      delim: m[2] || null,
+    });
     i = j - 1;
   }
   return entries;
 }
 
+// After removing entry `h`, the following ordered entries with the same delimiter are
+// renumbered from h's own number. Entries separated only by blank lines (a loose list)
+// stay in the run; a paragraph, a bullet or another delimiter ends it. A list that
+// repeats one number (`1. 1. 1.`) is left alone, and zero padding is kept.
+// Returns a new lines array.
+function renumberAfter(lines, entries, h) {
+  if (h.num === null) return lines;
+  const run = [];
+  let prev = h;
+  for (const e of entries.filter((x) => x.start > h.start)) {
+    const gap = lines.slice(prev.end, e.start);
+    if (e.num === null || e.delim !== h.delim || !gap.every(isBlank)) break;
+    run.push(e);
+    prev = e;
+  }
+  if ([h, ...run].every((e) => e.num === h.num)) return lines;
+  const padded = (t) => /^0\d/.test(t);
+  const fixed = new Map(run.map((e, k) => {
+    const width = Math.max(...[h, e].filter((x) => padded(x.numText)).map((x) => x.numText.length), 0);
+    const num = String(h.num + k).padStart(width, '0');
+    return [e.start, `${num}${h.delim}${lines[e.start].replace(/^\d+[.)]/, '')}`];
+  }));
+  return lines.map((l, i) => (fixed.has(i) ? fixed.get(i) : l));
+}
+
+// The line range [from, to) to drop for entry `h`: the entry plus, in a loose list, one
+// adjoining run of blank lines so no double blank or stray leading blank is left.
+function removalRange(lines, entries, h, sec) {
+  const k = entries.indexOf(h);
+  const prev = entries[k - 1];
+  const next = entries[k + 1];
+  const blankGap = (from, to) => to > from && lines.slice(from, to).every(isBlank);
+  const blankAfter = next && blankGap(h.end, next.start);
+  const blankBefore = prev && blankGap(prev.end, h.start);
+  const tightBefore = prev && prev.end === h.start;
+  if (blankAfter && !tightBefore) return [h.start, next.start];
+  if (blankBefore && !next) return [prev.end, h.end];
+  // Sole entry of a spaced section before a heading: drop one trailing blank too.
+  const soleSpaced = !prev && !next && h.start > sec.from && isBlank(lines[h.start - 1]) && h.end < sec.to && isBlank(lines[h.end]);
+  if (soleSpaced && sec.to < lines.length) return [h.start, h.end + 1];
+  return [h.start, h.end];
+}
+
 // The non-blank content lines of a section, or null when the section is missing.
 function readSection(body, name) {
   const { lines } = splitBody(String(body));
@@ -179,13 +239,16 @@ function applyOp(body, op) {
   }
 
   if (op.kind === 'remove') {
-    const hits = listEntries(lines, sec).filter((e) => e.text.includes(op.match));
+    const entries = listEntries(lines, sec);
+    const hits = entries.filter((e) => e.text.includes(op.match));
     if (hits.length === 0) {
       return { body: String(body), changed: false, summary: `no entry matching "${op.match}" in ${label}, nothing written` };
     }
     if (hits.length > 1) return { error: `ambiguous: ${hits.length} entries in ${label} contain "${op.match}"` };
     const h = hits[0];
-    const next = [...lines.slice(0, h.start), ...lines.slice(h.end)];
+    const renumbered = renumberAfter(lines, entries, h);
+    const [from, to] = removalRange(lines, entries, h, sec);
+    const next = [...renumbered.slice(0, from), ...renumbered.slice(to)];
     return { body: joinBody({ ...parts, lines: next }), changed: true, summary: `removed 1 entry from ${label}` };
   }
 

package/plugins/trailhead/templates/trailhead-report-status.js

@@ -3,20 +3,21 @@
 // trailhead report status check (self-contained, ships in templates/ so it reaches
 // every install channel). Checks the leading `status:` line of an engine-agent
 // report (Code review, Goal-backward verification #250; executor, fix, plan, debug,
-// research, codebase-map #249) before the engine branches on it, and returns the
+// research, codebase-map #249; grill #323) before the engine branches on it, and returns the
 // report's fields.
 //
 // CLI:
-//   node trailhead-report-status.js --technique <technique> [--file <path>]
+//   node trailhead-report-status.js --technique <technique> [--file <path> | --task-output <path>]
 // <technique> is verify | code-review | executor | fix | plan | debug | research |
-// codebase-map. Reads the report from --file, or from stdin when there is none.
+// codebase-map | grill. Reads the report from --file, from the last assistant message
+// of a background agent's task .output with --task-output, or from stdin when neither.
 // Prints exactly one JSON line {"action","verdict","problem","report","fields","body"}:
 //   action   accept | normalise | reask
 //   verdict  the canonical token, or null on reask
 //   problem  null | missing | unknown-token | conflicting | counts | fields (null iff not reask)
 //   report   the original text on accept and reask; the normalised text on normalise
 //   fields   label -> trimmed value for the report's fields (executor, fix, plan, debug,
-//            research, codebase-map); {} for verify and code-review; null on reask
+//            research, codebase-map, grill); {} for verify and code-review; null on reask
 //   body     plan with `ready` only: the normalised report without its status line, the
 //            PLAN to post verbatim; null otherwise
 // Exit 0 for all three actions; exit 2 on a usage error (missing or unknown
@@ -89,6 +90,19 @@ const CONTRACTS = Object.freeze({
       Object.freeze({ when: frozen(['needs_input']), field: 'questions', rule: 'non-empty' }),
     ]),
   }),
+  grilling: Object.freeze({
+    tokens: frozen(['question', 'review']),
+    required: frozen(['settled', 'frontier', 'amendments', 'conflicts']),
+    optional: frozen(['question', 'recommended', 'areas', 'facts']),
+    invariants: Object.freeze([
+      Object.freeze({ when: frozen(['question']), field: 'question', rule: 'non-empty' }),
+      Object.freeze({ when: frozen(['question']), field: 'recommended', rule: 'non-empty' }),
+      Object.freeze({ when: frozen(['question']), field: 'amendments', rule: 'none' }),
+      Object.freeze({ when: frozen(['question']), field: 'conflicts', rule: 'none' }),
+      Object.freeze({ when: frozen(['review']), field: 'frontier', rule: 'none' }),
+      Object.freeze({ when: frozen(['review']), field: 'question', rule: 'none' }),
+    ]),
+  }),
 });
 
 // Technique -> field family.
@@ -99,6 +113,7 @@ const FAMILY_OF = Object.freeze({
   research: 'investigating',
   'codebase-map': 'investigating',
   plan: 'plan',
+  grill: 'grilling',
 });
 
 // Technique -> its closed set of status tokens.
@@ -296,14 +311,38 @@ function checkReport(text, technique) {
   return { action: 'normalise', verdict, problem: null, report: [...head, ...rest].join('\n'), fields, body };
 }
 
+// The report of a background agent, read from the host's task .output (JSONL, often a
+// symlink to the subagent transcript): the text of the last assistant message that has
+// any, its blocks joined in order. One message can span several lines sharing
+// message.id; lines that are not JSON are skipped. null when there is no assistant text.
+function reportFromTaskOutput(raw) {
+  const entries = raw.split('\n').flatMap((l) => {
+    if (!l.trim()) return [];
+    try { return [JSON.parse(l)]; } catch (_) { return []; }
+  });
+  const texts = (e) => {
+    const c = e && e.message && e.message.content;
+    if (typeof c === 'string') return [c];
+    return Array.isArray(c) ? c.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text) : [];
+  };
+  const assistant = entries.filter((e) => e && e.type === 'assistant' && e.message);
+  const last = [...assistant].reverse().find((e) => texts(e).length > 0);
+  if (!last) return null;
+  const id = last.message.id;
+  const parts = id === undefined ? texts(last) : assistant.filter((e) => e.message.id === id).flatMap(texts);
+  return parts.join('');
+}
+
+const VALUE_FLAGS = { '--technique': 'technique', '--file': 'file', '--task-output': 'taskOutput' };
+
 function parseArgs(argv) {
-  const opts = { technique: null, file: null };
+  const opts = { technique: null, file: null, taskOutput: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--technique' || a === '--file') {
+    if (Object.prototype.hasOwnProperty.call(VALUE_FLAGS, a)) {
       const v = argv[i + 1];
       if (v === undefined || v === '' || v.startsWith('--')) throw new Error(`${a} needs a value`);
-      opts[a === '--technique' ? 'technique' : 'file'] = v;
+      opts[VALUE_FLAGS[a]] = v;
       i++;
     } else {
       throw new Error(`unknown argument: ${a}`);
@@ -311,9 +350,18 @@ function parseArgs(argv) {
   }
   if (!opts.technique) throw new Error(`--technique <${Object.keys(TOKENS).join('|')}> is required`);
   if (!Object.prototype.hasOwnProperty.call(TOKENS, opts.technique)) throw new Error(`unknown technique: ${opts.technique}`);
+  if (opts.file !== null && opts.taskOutput !== null) throw new Error('--file and --task-output are mutually exclusive');
   return opts;
 }
 
+function readReport(opts, readFile, readStdin) {
+  if (opts.file !== null) return readFile(opts.file);
+  if (opts.taskOutput === null) return readStdin();
+  const report = reportFromTaskOutput(readFile(opts.taskOutput));
+  if (report === null) throw new Error(`no assistant report in ${opts.taskOutput}`);
+  return report;
+}
+
 function main(argv, io = {}) {
   const stdout = io.stdout || process.stdout;
   const stderr = io.stderr || process.stderr;
@@ -322,7 +370,7 @@ function main(argv, io = {}) {
   let result;
   try {
     const opts = parseArgs(argv);
-    const text = opts.file !== null ? readFile(opts.file) : readStdin();
+    const text = readReport(opts, readFile, readStdin);
     result = checkReport(text, opts.technique);
   } catch (e) {
     stderr.write(`${JSON.stringify({ error: e.message })}\n`);
@@ -335,4 +383,4 @@ function main(argv, io = {}) {
 // exitCode, not process.exit(): exiting at once truncates piped stdout at 64 KB.
 if (require.main === module) process.exitCode = main(process.argv.slice(2));
 
-module.exports = { checkReport, parseArgs, main, TOKENS, CONTRACTS, FAMILY_OF, VERIFY_CLASSES };
+module.exports = { checkReport, reportFromTaskOutput, parseArgs, main, TOKENS, CONTRACTS, FAMILY_OF, VERIFY_CLASSES };