@elalfner/relevo 0.7.0 → 0.9.0

package/scripts/lib/ship-unattended.mjs

@@ -0,0 +1,271 @@
+// The ship that the `relevo:ship` label starts on GitHub: the steps of /relevo:ship, run by a workflow with no model.
+// Implements "A label starts an unattended ship" and the requirements after it in openspec/specs/ship/spec.md.
+//
+// Everything that touches the outside is injected, so the whole sequence is testable without a network:
+//   sh(cmd, args, { cwd, input }) -> { status, stdout, stderr }   git, openspec and the plugin's scripts
+//   gh(args) -> stdout                                            reads, comments and labels (workflow token)
+//   pushGh(args) -> stdout                                        merge and close (App token, or the workflow token)
+//   sleep(ms), now()                                              waiting for the checks of the archive commit
+// Nothing from the feature branch is executed: git runs without hooks, and the scripts come from `pluginRoot`.
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from './config.mjs';
+import { clearAll, resolveLabelNames } from './labels.mjs';
+import { renderMessage } from './messages.mjs';
+import { shipDecision } from './ship.mjs';
+import { baselineChecks, loadPr, requiredChecks } from './ship-github.mjs';
+
+const ARCHIVE_SUBJECT = 'chore(openspec): archive ';
+const CONFLICT_REASON = /has conflicts/;
+
+const NOTES = {
+  baseline: {
+    en: (sha) => `The archive commit changes only openspec/ and had no checks of its own, so the checks of the approved head ${sha} were used.`,
+    es: (sha) => `El commit del archivo solo cambia openspec/ y no tuvo checks propios, así que se usaron los checks del head aprobado ${sha}.`,
+  },
+  none: {
+    en: () => 'No check ran on this code: only the review vouched for it (review.ship_without_ci is true).',
+    es: () => 'No corrió ningún check sobre este código: solo la revisión lo respalda (review.ship_without_ci es true).',
+  },
+};
+
+/**
+ * What a label cannot do that a person in a session can. Returns null when the label may ship, or the message to post.
+ * - a decision that stops, stops;
+ * - an eligible person who did not approve must say so in writing, which a label cannot;
+ * - no checks at all need the person's word, unless review.ship_without_ci says the label is enough.
+ */
+export function labelRules({ decision, config }) {
+  if (!decision.allowed) return { kind: 'ship_stopped', data: { reasons: decision.reasons.join('; ') } };
+  if (decision.confirm.includes('not-approver')) {
+    return { kind: 'ship_not_approver', data: { approvers: decision.summary.approvedBy.map((l) => `@${l}`).join(', ') } };
+  }
+  if (decision.confirm.includes('no-ci') && !config.review.ship_without_ci) return { kind: 'ship_no_ci', data: {} };
+  return null;
+}
+
+class Stop {
+  constructor(kind, data = {}) {
+    this.kind = kind;
+    this.data = data;
+  }
+}
+const stopWith = (kind, data) => {
+  throw new Stop(kind, data);
+};
+const stopReasons = (...reasons) => stopWith('ship_stopped', { reasons: reasons.join('; ') });
+const firstLines = (text, n = 6) => String(text ?? '').trim().split('\n').slice(0, n).join(' / ');
+
+/** The change folder of the issue on the branch, and whether it is still to be archived. */
+export function findChange(workDir, issue) {
+  const changes = join(workDir, 'openspec', 'changes');
+  const prefix = `${issue}-`;
+  const active = existsSync(changes) ? readdirSync(changes).filter((n) => n.startsWith(prefix) && n !== 'archive') : [];
+  if (active.length === 1) return { name: active[0], state: 'active' };
+  if (active.length > 1) return { name: null, state: 'ambiguous', found: active };
+  const archiveDir = join(changes, 'archive');
+  const dated = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-(${issue}-.+)$`);
+  const archived = existsSync(archiveDir) ? readdirSync(archiveDir).map((n) => n.match(dated)?.[1]).filter(Boolean) : [];
+  if (archived.length === 1) return { name: archived[0], state: 'archived' };
+  return { name: null, state: archived.length > 1 ? 'ambiguous' : 'missing', found: archived };
+}
+
+export async function runUnattendedShip(ctx) {
+  const { repo, issue, actor, actorType, hasApp, workDir, pluginRoot, sh, gh, pushGh } = ctx;
+  const sleep = ctx.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = ctx.now ?? (() => Date.now());
+  const waitLimitMs = ctx.waitLimitMs ?? 30 * 60 * 1000;
+  const settleMs = ctx.settleMs ?? 3 * 60 * 1000;
+  const pollMs = ctx.pollMs ?? 20 * 1000;
+  const headPollMs = ctx.headPollMs ?? 10 * 1000;
+  const n = String(issue);
+
+  const run = (cmd, args, opts = {}) => sh(cmd, args, { cwd: workDir, ...opts });
+  const git = (args, opts = {}) => {
+    const r = run('git', ['-c', 'core.hooksPath=/dev/null', ...args], opts);
+    if (r.status !== 0 && !opts.allowFail) stopReasons(`git ${args[0]} failed: ${firstLines(r.stderr || r.stdout)}`);
+    return r;
+  };
+  const script = (name, args, opts = {}) => run(process.execPath, [join(pluginRoot, 'scripts', name), ...args], opts);
+  const openspec = (args) => run('openspec', args, { env: { OPENSPEC_TELEMETRY: '0' } });
+
+  // The configuration of the default branch only names the base branch; the one that applies is the base branch's.
+  const readConfig = (text, where) => {
+    const loaded = loadConfig(text);
+    if (!loaded.ok) stopReasons(`relevo.yml on ${where} is not valid: ${loaded.errors.map((e) => e.message).join('; ')}`);
+    return loaded.config;
+  };
+
+  let config = loadConfig('limits:\n  run_max_cost: 1\n').config;
+  let names = resolveLabelNames({});
+  const removeShipLabel = () => {
+    try {
+      gh(['issue', 'edit', n, '--repo', repo, '--remove-label', names.ship]);
+    } catch {
+      // The label may already be gone; the comment still says what happened.
+    }
+  };
+
+  if (actorType !== 'User') {
+    removeShipLabel();
+    return { outcome: 'ignored', reason: 'the label was not applied by a person' };
+  }
+
+  try {
+    const fromDefault = run('git', ['show', 'HEAD:relevo.yml']);
+    if (fromDefault.status !== 0) stopReasons('relevo.yml not found on the default branch: run /relevo:init');
+    const base = readConfig(fromDefault.stdout, 'the default branch').branches.base;
+    git(['fetch', '--no-tags', 'origin', base]);
+    const fromBase = run('git', ['show', `origin/${base}:relevo.yml`]);
+    if (fromBase.status !== 0) stopReasons(`relevo.yml not found on ${base}`);
+    config = readConfig(fromBase.stdout, base);
+    names = resolveLabelNames(config.labels);
+    const language = config.language;
+
+    const issueData = JSON.parse(gh(['issue', 'view', n, '--repo', repo, '--json', 'state,labels']));
+    const labels = issueData.labels.map((l) => l.name);
+    if (issueData.state !== 'OPEN') stopReasons('the issue is closed');
+
+    // The issue's branch, looked up on the remote: never a branch named by the event.
+    const heads = git(['ls-remote', '--heads', 'origin']).stdout.split('\n')
+      .map((l) => l.split('\t')[1]?.replace('refs/heads/', ''))
+      .filter((b) => b && b.startsWith(`feature/${n}-`));
+    if (heads.length === 0) stopReasons(`there is no branch feature/${n}-* on the remote`);
+    if (heads.length > 1) stopReasons(`more than one branch matches feature/${n}-*: ${heads.join(', ')}`);
+    const branch = heads[0];
+    git(['fetch', '--no-tags', 'origin', branch]);
+    git(['switch', '--force-create', branch, `origin/${branch}`]);
+    const head = () => git(['rev-parse', 'HEAD']).stdout.trim();
+
+    const change = findChange(workDir, n);
+    if (change.state === 'missing') stopReasons(`no change folder openspec/changes/${n}-* on ${branch}`);
+    if (change.state === 'ambiguous') stopReasons(`more than one change folder for #${n}: ${change.found.join(', ')}`);
+
+    // The head the approval was given on: the current one, or the one before the archive when a previous run archived.
+    const subject = (ref) => git(['log', '-1', '--format=%s', ref]).stdout.trim();
+    let baseline = head();
+    if (change.state === 'archived') baseline = subject('HEAD').startsWith(ARCHIVE_SUBJECT) ? git(['rev-parse', 'HEAD^']).stdout.trim() : undefined;
+
+    const decide = (pr, withBaseline) => shipDecision({
+      config, pr, invoker: actor, labels, issue: n,
+      baseline: withBaseline,
+      baselineChecks: withBaseline ? baselineChecks(gh, repo, withBaseline, pr?.headRefOid) : undefined,
+    });
+    // GitHub takes a moment to see a push on the pull request; a head that never matches means someone else pushed.
+    const check = async (withBaseline) => {
+      const local = head();
+      let pr = loadPr(gh, repo, branch);
+      for (let tries = 0; pr && pr.headRefOid !== local && tries < 6; tries += 1) {
+        await sleep(headPollMs);
+        pr = loadPr(gh, repo, branch);
+      }
+      if (pr && pr.headRefOid !== local) stopReasons('the branch moved while shipping: apply the label again');
+      return { pr, decision: decide(pr, withBaseline) };
+    };
+
+    let { pr, decision } = await check(baseline);
+    const rule = labelRules({ decision, config });
+    if (rule) stopWith(rule.kind, rule.data);
+
+    const required = requiredChecks(gh, repo, base);
+    if (required.required && !hasApp) stopWith('ship_needs_app', { base });
+
+    const diff = git(['diff', `origin/${base}...HEAD`]).stdout;
+    const scan = script('scan-diff.mjs', [], { input: diff });
+    if (scan.status !== 0) stopReasons(`the diff has findings: ${firstLines(scan.stdout || scan.stderr)}`);
+
+    const archive = () => {
+      const steps = [
+        () => openspec(['validate', change.name]),
+        () => script('fix-tasks.mjs', ['--file', `openspec/changes/${change.name}/tasks.md`, '--stage', 'after']),
+        () => openspec(['archive', change.name, '-y']),
+        () => script('check-archive.mjs', []),
+        () => script('stage.mjs', ['openspec/changes', 'openspec/specs']),
+      ];
+      steps.forEach((step) => {
+        const r = step();
+        if (r.status !== 0) stopReasons(`the archive stopped: ${firstLines(r.stdout || r.stderr)}`);
+      });
+      git(['commit', '-m', `${ARCHIVE_SUBJECT}${change.name} (#${n})`]);
+      git(['push', 'origin', `HEAD:refs/heads/${branch}`]);
+    };
+
+    let pushed = false;
+    if (change.state === 'active') {
+      archive();
+      pushed = true;
+    }
+
+    // With the App, the push started the project's checks: wait for them, for a bounded time.
+    if (pushed && hasApp) {
+      const started = now();
+      for (;;) {
+        const current = loadPr(gh, repo, branch);
+        const rollup = current?.statusCheckRollup ?? [];
+        const running = rollup.some((c) => (c.__typename === 'StatusContext' ? !['SUCCESS', 'FAILURE', 'ERROR'].includes(c.state) : c.status !== 'COMPLETED'));
+        if (rollup.length > 0 && !running) break;
+        if (rollup.length === 0 && now() - started >= settleMs) break;
+        if (now() - started >= waitLimitMs) {
+          stopReasons(`the checks of the archive commit did not finish within ${Math.round(waitLimitMs / 60000)} minutes; apply the label again: the specification is already archived, so it resumes from the merge`);
+        }
+        await sleep(pollMs);
+      }
+    }
+
+    ({ pr, decision } = await check(baseline));
+    if (!decision.allowed && decision.reasons.length === 1 && CONFLICT_REASON.test(decision.reasons[0]) && subject('HEAD').startsWith(ARCHIVE_SUBJECT)) {
+      // The base branch changed the specifications the archive wrote: undo the archive, bring in the base, archive again.
+      git(['revert', '--no-edit', 'HEAD']);
+      const merge = git(['merge', '--no-edit', `origin/${base}`], { allowFail: true });
+      if (merge.status !== 0) {
+        const scope = script('conflict-scope.mjs', []);
+        git(['merge', '--abort'], { allowFail: true });
+        if (scope.status !== 0) stopReasons(`bringing in ${base} conflicts in code, which is for the author: ${firstLines(scope.stdout)}`);
+        stopReasons(`bringing in ${base} conflicts inside openspec/: run /relevo:ship ${n} to resolve it in a session`);
+      }
+      archive();
+      // The head now holds more than the archive, so the approval must be on it.
+      ({ pr, decision } = await check(undefined));
+    }
+    const again = labelRules({ decision, config });
+    if (again) stopWith(again.kind, again.data);
+
+    const merged = head();
+    try {
+      pushGh(['pr', 'merge', String(pr.number), '--repo', repo, '--squash', '--delete-branch', '--subject', pr.title, '--body', `Issue #${n}`, '--match-head-commit', merged]);
+    } catch (err) {
+      stopReasons(`GitHub refused the merge: ${firstLines(err.stderr || err.message)}`);
+    }
+
+    const after = JSON.parse(gh(['issue', 'view', n, '--repo', repo, '--json', 'state,labels']));
+    if (after.state === 'OPEN') pushGh(['issue', 'close', n, '--repo', repo, '--reason', 'completed']);
+    const { remove } = clearAll(after.labels.map((l) => l.name), config.labels);
+    if (remove.length > 0) pushGh(['issue', 'edit', n, '--repo', repo, ...remove.flatMap((l) => ['--remove-label', l])]);
+
+    let commit = merged.slice(0, 7);
+    try {
+      commit = (gh(['pr', 'view', String(pr.number), '--repo', repo, '--json', 'mergeCommit', '--jq', '.mergeCommit.oid']).trim() || merged).slice(0, 7);
+    } catch {
+      // The short head is close enough for the report.
+    }
+    const lang = language === 'es' ? 'es' : 'en';
+    const note = decision.summary.checksFrom === 'baseline' ? NOTES.baseline[lang](String(baseline).slice(0, 7)) : decision.summary.checks === 'none' ? NOTES.none[lang]() : '';
+    gh(['issue', 'comment', n, '--repo', repo, '--body', renderMessage('ship_done', { issue: n, pr: `#${pr.number}`, base, commit, actor, checks_note: note }, language)]);
+
+    // A close made with the workflow token starts no workflow: tell the queue, so dependent issues are unblocked now.
+    if (!hasApp) {
+      try {
+        gh(['workflow', 'run', 'relevo-queue.yml', '--repo', repo]);
+      } catch {
+        // No queue workflow: nothing waits on it.
+      }
+    }
+    return { outcome: 'merged', pr: pr.number, commit };
+  } catch (err) {
+    if (!(err instanceof Stop)) throw err;
+    removeShipLabel();
+    gh(['issue', 'comment', n, '--repo', repo, '--body', renderMessage(err.kind, { actor, issue: n, ...err.data }, config.language)]);
+    return { outcome: 'stopped', kind: err.kind, ...err.data };
+  }
+}

package/scripts/lib/ship.mjs

@@ -67,11 +67,13 @@ export function checkRollup(rollup = []) {
  * baseline optional: the head commit recorded when ship started; an approval given on it still counts
  * labels   optional: the names of the issue's labels; when given, the issue must be pr-open
  * issue    optional: the issue number, used in the messages about the state
+ * baselineChecks optional: { archiveOnly, rollup } of the baseline. When the head differs from it only under
+ *          `openspec/` (archiveOnly) and the head has no checks of its own, the baseline's checks are judged.
  * Returns { allowed, reasons, confirm, summary }.
  *   reasons  why it must stop (empty when allowed)
  *   confirm  what the person must still confirm in writing, always including "merge"
  */
-export function shipDecision({ config, pr, invoker, baseline, labels, issue }) {
+export function shipDecision({ config, pr, invoker, baseline, labels, issue, baselineChecks }) {
   const reasons = [];
   const warnings = [];
   const confirm = ['merge'];
@@ -95,7 +97,17 @@ export function shipDecision({ config, pr, invoker, baseline, labels, issue }) {
   if (pr.mergeable === 'CONFLICTING') reasons.push('the pull request has conflicts: the author must synchronise the branch with the base branch');
   else if (pr.mergeable !== 'MERGEABLE') reasons.push('GitHub has not finished checking whether the pull request can be merged: try again in a minute');
 
-  const checks = checkRollup(pr.statusCheckRollup);
+  // A push with the workflow token starts no workflows, so the archive commit may have no checks: the checks of the
+  // approved head still vouch for the code when only the specifications changed since.
+  let checks = checkRollup(pr.statusCheckRollup);
+  let checksFrom = 'head';
+  if (checks.state === 'none' && baselineChecks?.archiveOnly) {
+    const carried = checkRollup(baselineChecks.rollup);
+    if (carried.state !== 'none') {
+      checks = carried;
+      checksFrom = 'baseline';
+    }
+  }
   if (checks.state === 'failing') reasons.push(`checks are failing: ${checks.failing.join(', ')}`);
   else if (checks.state === 'pending') reasons.push(`checks are still running: ${checks.pending.join(', ')}`);
   else if (checks.state === 'none') confirm.push('no-ci');
@@ -156,6 +168,6 @@ export function shipDecision({ config, pr, invoker, baseline, labels, issue }) {
     allowed: reasons.length === 0,
     reasons,
     confirm,
-    summary: { pr: pr.number, title: pr.title, author, branch: pr.headRefName, base: pr.baseRefName, mode, approvedBy, checks: checks.state, ...(warnings.length > 0 ? { warnings } : {}) },
+    summary: { pr: pr.number, title: pr.title, author, branch: pr.headRefName, base: pr.baseRefName, head: pr.headRefOid ?? null, mode, approvedBy, checks: checks.state, checksFrom, ...(warnings.length > 0 ? { warnings } : {}) },
   };
 }

package/scripts/lib/toolchain-check.mjs

@@ -1,6 +1,12 @@
 // Which of the tools that a profile lists are not on the path. `probe(tool)` says whether one answers; it is injected
 // so that a test does not need the tools. An empty list checks nothing.
 
+/**
+ * What every Relevo job needs on the runner whatever the stack: a GitHub-hosted runner has them, a self-hosted one may not.
+ * They are checked with the tools of the profile, so a runner without one stops before the agent, like one without Flutter.
+ */
+export const RUNNER_TOOLS = ['git', 'gh', 'jq', 'node'];
+
 /** The tools that are missing, in the order of the profile and without repeats. */
 export function missingTools(tools, probe) {
   const seen = new Set();

package/scripts/lib/web-preflight.mjs

@@ -2,7 +2,14 @@
 // address under review with the module scripts its page loads. Everything that touches the machine is injected.
 // Implements "A browser review checks its tools and the app before driving" of openspec/specs/review/spec.md.
 
-export const EXIT = { node_modules: 3, playwright: 4, browser: 5, url: 6 };
+export const EXIT = { node_modules: 3, playwright: 4, browser: 5, url: 6, deps_stale: 7 };
+
+// The frozen install of each lock file, first match wins. None runs package scripts where the tool can skip them.
+const LOCKS = [
+  { file: 'package-lock.json', install: 'npm ci --ignore-scripts' },
+  { file: 'pnpm-lock.yaml', install: 'pnpm install --frozen-lockfile --ignore-scripts' },
+  { file: 'yarn.lock', install: 'yarn install --immutable' },
+];
 
 const START_SCRIPTS = ['dev', 'serve', 'start'];
 
@@ -34,6 +41,38 @@ export function moduleScripts(html, pageUrl) {
     .map((u) => u.href);
 }
 
+/** The lock file of the folder and its frozen install command; null when the folder has none. */
+export function lockOf(cwd, exists) {
+  return LOCKS.find((l) => exists(`${cwd}/${l.file}`)) ?? null;
+}
+
+const parse = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Do the installed dependencies differ from package-lock.json? Compares each package of the lock file with the one
+ * npm recorded in node_modules/.package-lock.json. An optional package that is not installed (a binary for another
+ * platform) is not a difference. Returns true, false, or null when it cannot tell (never treated as stale).
+ */
+export function npmStale(lockText, hiddenText) {
+  const lock = parse(lockText)?.packages;
+  if (!lock || typeof lock !== 'object') return null;
+  if (hiddenText === null) return true;
+  const hidden = parse(hiddenText)?.packages;
+  if (!hidden || typeof hidden !== 'object') return null;
+  return Object.entries(lock).some(([key, wanted]) => {
+    if (key === '') return false;
+    const installed = hidden[key];
+    if (!installed) return !(wanted?.optional || wanted?.devOptional);
+    return wanted?.version !== undefined && installed.version !== wanted.version;
+  });
+}
+
 /** Does the page answer below 400 after redirects, and so do its module scripts? Returns { ok, detail }. */
 export async function checkUrl(url, { fetch, timeout = 5000 }) {
   const get = async (address) => {
@@ -56,7 +95,8 @@ export async function checkUrl(url, { fetch, timeout = 5000 }) {
 }
 
 /**
- * Runs the checks in order and stops at the first failure. Returns { ok, check, detail, start, env, code }.
+ * Runs the checks in order and stops at the first failure. Returns { ok, check, detail, start, env, install, code }:
+ * `install` is the frozen install command of the folder's lock file, or null without one.
  * deps: exists(path), readFile(path) (null when missing), loadPlaywright(), fetch, sleep(ms), now().
  * Only `.env.example` is read for variable names; the real environment files never are.
  * With `wait`, the address is retried every 500 ms until it answers or the time is over.
@@ -66,9 +106,15 @@ export async function webPreflight({ cwd, url, timeout = 5000, wait = 0 }, deps)
   const at = (name) => `${cwd}/${name}`;
   const start = startCommand(readFile(at('package.json')));
   const env = envNames(readFile(at('.env.example')));
-  const result = (check, detail) => ({ ok: check === null, check, detail, start, env, code: check === null ? 0 : EXIT[check] });
+  const lock = lockOf(cwd, exists);
+  const install = lock?.install ?? null;
+  const result = (check, detail) => ({ ok: check === null, check, detail, start, env, install, code: check === null ? 0 : EXIT[check] });
 
-  if (!exists(at('node_modules'))) return result('node_modules', 'the project has no node_modules: run npm install first');
+  if (!exists(at('node_modules'))) return result('node_modules', lock ? 'the project has no node_modules' : 'the project has no node_modules and no lock file to install from');
+  // Only npm records what it installed in a form comparable with its lock file; pnpm and yarn are checked for presence.
+  if (lock?.file === 'package-lock.json' && npmStale(readFile(at('package-lock.json')), readFile(at('node_modules/.package-lock.json'))) === true) {
+    return result('deps_stale', 'the installed dependencies do not match package-lock.json');
+  }
   const playwright = loadPlaywright();
   if (!playwright) return result('playwright', 'Playwright does not resolve from the project');
   let executable = null;

package/scripts/lib/workflow-upgrade.mjs

@@ -0,0 +1,198 @@
+// Updates a workflow of a repository to the current template by a three-way merge. Implements the requirements "Init
+// updates a workflow by a three-way merge", "A merged workflow is written only when clean and confirmed" and "The pin and
+// the stamp are set, not merged" of openspec/specs/init-doctor/spec.md.
+//
+//   base    the published template closest to the file (the pin is no guide: a person can raise it by hand)
+//   ours    the file as it is
+//   theirs  the current template, rendered with the runner and the agent of the repository, so that a person's runner
+//           or agent block is the same on both sides and is not reported as a change
+//
+// The pin and the stamp are not merged: both are set to the base's value in the file before the merge (otherwise the
+// person's own pin conflicts with every release) and to the current value after it. Nothing here writes a workflow: the
+// caller decides, and a conflict gives back text that must not be written.
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { agentWorkflow } from './agent-workflow.mjs';
+import { runnerLine } from './init.mjs';
+
+const PIN_RE = /^(\s*RELEVO_VERSION:\s*)(['"]?)([\w.+-]+)\2[ \t]*$/m;
+const STAMP_RE = /^# relevo-template: (\d+\.\d+\.\d+)[ \t]*$/m;
+const MARKERS = ['credential', 'agent-step'];
+
+export const pinOf = (text) => PIN_RE.exec(text)?.[3] ?? null;
+export const stampOf = (text) => STAMP_RE.exec(text)?.[1] ?? null;
+const setPin = (text, version) => text.replace(PIN_RE, (_, head, quote) => `${head}${quote}${version}${quote}`);
+const setStamp = (text, version) => text.replace(STAMP_RE, `# relevo-template: ${version}`);
+
+/** How many lines two workflows do not share (as multisets), with the pin and the stamp set aside. */
+export function distance(a, b) {
+  const lines = (t) => setStamp(setPin(t, 'X'), 'X').split('\n');
+  const count = new Map();
+  lines(a).forEach((l) => count.set(l, (count.get(l) ?? 0) + 1));
+  lines(b).forEach((l) => count.set(l, (count.get(l) ?? 0) - 1));
+  return [...count.values()].reduce((sum, n) => sum + Math.abs(n), 0);
+}
+
+/**
+ * The candidate whose text is closest to the file; the newest among equals. `from` names the base instead. null when no
+ * candidate is close enough: more than half of the lines of the file different is not a version of this template.
+ */
+export function chooseBase(file, candidates, { from = null } = {}) {
+  if (from !== null) {
+    const named = candidates.find((c) => c.version === from);
+    return named ? { ...named, distance: distance(file, named.rendered) } : null;
+  }
+  const ranked = candidates.map((c) => ({ ...c, distance: distance(file, c.rendered) }))
+    .sort((a, b) => a.distance - b.distance || compareVersions(b.version, a.version));
+  const limit = Math.max(20, Math.floor(file.split('\n').length / 2));
+  return ranked.length > 0 && ranked[0].distance <= limit ? ranked[0] : null;
+}
+
+const compareVersions = (a, b) => a.split('.').map(Number).reduce((r, n, i) => r || n - Number(b.split('.')[i]), 0);
+
+/** `git merge-file -p`: the exit status is the number of conflicts (1 to 127); anything else is an error. */
+export function gitMergeFile(ours, base, theirs) {
+  const dir = mkdtempSync(join(tmpdir(), 'relevo-merge-'));
+  try {
+    const paths = [['ours', ours], ['base', base], ['theirs', theirs]].map(([name, text]) => {
+      const path = join(dir, name);
+      writeFileSync(path, text);
+      return path;
+    });
+    try {
+      return { status: 0, stdout: execFileSync('git', ['merge-file', '-p', ...paths], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }) };
+    } catch (err) {
+      return { status: err.status ?? 255, stdout: String(err.stdout ?? '') };
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The blocks of conflict of a merged text: [{ yours, theirs }]. */
+export function conflictsOf(text) {
+  const out = [];
+  const re = /^<<<<<<<[^\n]*\n([\s\S]*?)^=======\n([\s\S]*?)^>>>>>>>[^\n]*\n/gm;
+  let m;
+  while ((m = re.exec(text)) !== null) out.push({ yours: m[1].trimEnd(), theirs: m[2].trimEnd() });
+  return out;
+}
+
+/** A merge that lost what other code depends on is not safe to write, whatever git says. */
+function structureProblem(merged, current) {
+  if ((merged.match(/^\s*RELEVO_VERSION:/gm) ?? []).length !== 1) return 'it does not have exactly one RELEVO_VERSION';
+  if (stampOf(current) !== null && (merged.match(/^# relevo-template:/gm) ?? []).length !== 1) return 'it does not have exactly one stamp';
+  for (const name of MARKERS) {
+    const count = (t, kind) => (t.match(new RegExp(`^\\s*# relevo:${name} ${kind}\\s*$`, 'gm')) ?? []).length;
+    for (const kind of ['begin', 'end']) {
+      if (count(merged, kind) !== count(current, kind)) return `the block "${name}" (${kind}) is not as in the template`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The state of one workflow against the current template.
+ *   { status: 'current' }                        nothing to update
+ *   { status: 'update', from, to, text }         a clean merge; `text` is what to write
+ *   { status: 'conflict', from, conflicts }      lines both sides changed, or a merge that is not safe; write nothing
+ *   { status: 'nobase' }                         no published template is close to the file
+ *   { status: 'error', message }                 git failed
+ * `candidates` are [{ version, template, blocks }] (the raw template of a published version and its agent blocks, or
+ * null). `render` turns a raw template into what `init` would write for this repository.
+ */
+export function upgradeWorkflow({ ours, current, candidates, from = null, render, merge = gitMergeFile }) {
+  const theirs = render(current.template, current.blocks);
+  const rendered = candidates.map((c) => ({ ...c, rendered: render(c.template, c.blocks) }));
+  const base = chooseBase(ours, rendered, { from });
+  if (!base) return { status: 'nobase' };
+
+  let prepared = ours;
+  if (pinOf(prepared) !== null && pinOf(base.rendered) !== null) prepared = setPin(prepared, pinOf(base.rendered));
+  if (stampOf(prepared) !== null && stampOf(base.rendered) !== null) prepared = setStamp(prepared, stampOf(base.rendered));
+
+  const result = merge(prepared, base.rendered, theirs);
+  if (result.status === 0) {
+    let text = result.stdout;
+    if (pinOf(theirs) !== null) text = setPin(text, pinOf(theirs));
+    if (stampOf(theirs) !== null && stampOf(text) !== null) text = setStamp(text, stampOf(theirs));
+    const problem = structureProblem(text, theirs);
+    if (problem) return { status: 'conflict', from: base.version, conflicts: [], message: `the merge is not safe: ${problem}` };
+    if (text === ours) return { status: 'current' };
+    return { status: 'update', from: base.version, to: stampOf(theirs) ?? pinOf(theirs), text };
+  }
+  if (result.status >= 1 && result.status <= 127) return { status: 'conflict', from: base.version, conflicts: conflictsOf(result.stdout) };
+  return { status: 'error', message: 'git merge-file failed' };
+}
+
+/** The published versions of the package and their templates, fetched with `npm`; `exec(cmd, args)` returns stdout. */
+export function publishedTemplates({ exec, tmp = mkdtempSync(join(tmpdir(), 'relevo-published-')), pkg = '@elalfner/relevo' }) {
+  const unpacked = new Map();
+  const dirOf = (version) => {
+    if (!unpacked.has(version)) {
+      const dir = join(tmp, version);
+      mkdirSync(dir, { recursive: true });
+      try {
+        exec('npm', ['pack', `${pkg}@${version}`, '--silent', '--pack-destination', dir]);
+        const tarball = join(dir, `${pkg.replace(/^@/, '').replace('/', '-')}-${version}.tgz`);
+        exec('tar', ['-xzf', tarball, '-C', dir]);
+        unpacked.set(version, join(dir, 'package'));
+      } catch {
+        unpacked.set(version, null);
+      }
+    }
+    return unpacked.get(version);
+  };
+  return {
+    versions: () => JSON.parse(exec('npm', ['view', pkg, 'versions', '--json'])).filter((v) => /^\d+\.\d+\.\d+$/.test(v) && v !== '0.0.0'),
+    read: (version, path) => {
+      const dir = dirOf(version);
+      if (dir === null) return null;
+      try {
+        return readFileSync(join(dir, path), 'utf8');
+      } catch {
+        return null;
+      }
+    },
+    cleanup: () => rmSync(tmp, { recursive: true, force: true }),
+  };
+}
+
+/**
+ * The state of each workflow of the repository that exists and differs from what `init` would write. `ours` and
+ * `templates` map a file name to its text; `repo` brings `runnerLabels` and `build`; `source` is `publishedTemplates`.
+ */
+export function planUpgrades({ files, ours, templates, agentBlocks, labels, build, from = null, source, merge }) {
+  const render = (template, blocks) => runnerLine(agentWorkflow(template, build, blocks), labels);
+  const versions = files.some((f) => ours[f] != null) ? source.versions() : [];
+  const out = {};
+  files.filter((f) => ours[f] != null).forEach((file) => {
+    const candidates = versions.map((version) => {
+      const template = source.read(version, `templates/workflows/${file}`);
+      return template === null ? null : { version, template, blocks: build === 'claude' ? null : source.read(version, `templates/agents/${build}-step.yml`) };
+    }).filter(Boolean);
+    out[file] = upgradeWorkflow({ ours: ours[file], current: { template: templates[file], blocks: agentBlocks }, candidates, from, render, merge });
+  });
+  return out;
+}
+
+/** A readable unified difference between the file and its update, for the plan. */
+export function unifiedDiff(before, after) {
+  const dir = mkdtempSync(join(tmpdir(), 'relevo-diff-'));
+  try {
+    const a = join(dir, 'before');
+    const b = join(dir, 'after');
+    writeFileSync(a, before);
+    writeFileSync(b, after);
+    try {
+      return execFileSync('git', ['diff', '--no-index', '--no-color', '--unified=2', a, b], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      return String(err.stdout ?? '').split('\n').slice(4).join('\n');
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/scripts/review-event.mjs

@@ -52,7 +52,16 @@ if (eventName === 'pull_request_review') {
 
 const pr = { number: prData.number, url: prData.html_url, author: prData.user.login };
 const labels = JSON.parse(realGh(['api', `repos/${repo}/issues/${number}`])).labels.map((l) => (typeof l === 'string' ? l : l.name));
-const decision = planReviewEvent({ config, event, pr, issue: { number, labels } });
+// The approval names the ship label only where the ship workflow runs: it runs from the default branch.
+const shipWorkflow = event.kind === 'review' && event.state === 'approved' && (() => {
+  try {
+    realGh(['api', `repos/${repo}/contents/.github/workflows/relevo-ship.yml`, '--silent']);
+    return true;
+  } catch {
+    return false;
+  }
+})();
+const decision = planReviewEvent({ config, event, pr, issue: { number, labels }, shipWorkflow });
 if (!decision) {
   console.log(JSON.stringify({ action: 'none' }));
   process.exit(0);