@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/lib/status.mjs

@@ -0,0 +1,199 @@
+// What is waiting on whom. Implements openspec/specs/status/spec.md. Pure: data in, report out.
+//
+// issues  [{ number, title, labels: [names], assignees: [logins], milestone: number | null }]   open Relevo issues
+// prs     [{ number, issue, url, author, reviewer, requested_at, approved, behind_by }]          open feature pull requests
+// milestones [{ number, title, due_on, closed_issues }]
+// me      login of the person asking (null for the team-level view)
+
+import { resolveLabelNames } from './labels.mjs';
+
+/** Reviews one person can complete per working day; used only for the capacity warning. */
+export const REVIEWS_PER_PERSON_PER_DAY = 1;
+/** A feature branch this many commits behind the base branch is reported. */
+export const BEHIND_ALERT = 10;
+
+const HOUR = 3600 * 1000;
+
+function workingDays(from, to) {
+  let days = 0;
+  for (let t = new Date(from); t < to; t = new Date(t.getTime() + 24 * HOUR)) {
+    const d = t.getUTCDay();
+    if (d !== 0 && d !== 6) days += 1;
+  }
+  return days;
+}
+
+function stateOf(issue, names) {
+  const order = ['needs-spec', 'qa-failed', 'changes-requested', 'blocked', 'in-review', 'pr-open', 'built', 'building', 'queued', 'ready'];
+  return order.find((k) => issue.labels.includes(names[k])) ?? null;
+}
+
+export function buildStatus({ config, issues, prs = [], milestones = [], externalBlocks = {}, cloudBuilds = true, me = null, now = new Date() }) {
+  const names = resolveLabelNames(config.labels);
+  const entries = issues.map((i) => ({
+    number: i.number, title: i.title, state: stateOf(i, names), assignee: i.assignees[0] ?? null, milestone: i.milestone ?? null,
+    needsReviewer: i.labels.includes(names['needs-reviewer']),
+    updatedAt: i.updated_at ?? null,
+    ...(externalBlocks[i.number] ? { blockedBy: externalBlocks[i.number] } : {}),
+  })).filter((e) => e.state);
+
+  const mine = me ? entries.filter((e) => e.assignee === me) : [];
+  const nextCommand = { built: 'review', 'in-review': 'review', 'qa-failed': 'fix', 'changes-requested': 'fix' };
+  const onMe = [];
+  ['built', 'in-review', 'qa-failed', 'changes-requested'].forEach((state) => {
+    mine.filter((e) => e.state === state).forEach((e) => onMe.push({ ...e, command: `/relevo:${nextCommand[state]} ${e.number}` }));
+  });
+  const toReview = me
+    ? prs.filter((p) => p.reviewer === me && !p.approved).map((p) => ({ number: p.issue, pr: p.url, since: p.requested_at }))
+    : [];
+  const toShip = me
+    ? prs.filter((p) => p.approved && (config.review.merger === 'author' ? p.author === me : p.reviewer === me))
+      .map((p) => ({ number: p.issue, pr: p.url, command: `/relevo:ship ${p.issue}` }))
+    : [];
+  const waitingOnOthers = mine.filter((e) => !['built', 'in-review', 'qa-failed', 'changes-requested'].includes(e.state));
+
+  const specWriter = config.team.spec_writer;
+  const isSpecWriter = Boolean(me) && me === specWriter;
+  const specWriterView = isSpecWriter
+    ? {
+        needsSpec: entries.filter((e) => e.state === 'needs-spec'),
+        blocked: entries.filter((e) => e.state === 'blocked'),
+        needsReviewer: entries.filter((e) => e.needsReviewer),
+      }
+    : null;
+
+  // Milestones: merged, in review, queued, and a capacity warning against the due date.
+  const flight = new Set(['building', 'built', 'in-review', 'pr-open', 'changes-requested', 'qa-failed']);
+  const summaries = milestones.map((m) => {
+    const inMs = entries.filter((e) => e.milestone === m.number);
+    const queued = inMs.filter((e) => ['ready', 'queued', 'blocked', 'needs-spec'].includes(e.state)).length;
+    const inFlight = inMs.filter((e) => flight.has(e.state)).length;
+    const out = { number: m.number, title: m.title, merged: m.closed_issues ?? 0, inReview: inMs.filter((e) => ['in-review', 'pr-open', 'changes-requested'].includes(e.state)).length, queued, inFlight, dueOn: m.due_on ?? null, capacity: null, warning: false };
+    if (m.due_on) {
+      const people = config.team.members.filter((x) => x !== specWriter).length;
+      const days = workingDays(now, new Date(m.due_on));
+      out.capacity = { people, workingDays: days, reviews: people * days * REVIEWS_PER_PERSON_PER_DAY };
+      out.warning = queued + inFlight > out.capacity.reviews;
+    }
+    return out;
+  });
+
+  // When the cloud is not building, the ready issues assigned to the person are theirs to build.
+  const readyForMe = !cloudBuilds && me
+    ? mine.filter((e) => e.state === 'ready').map((e) => ({ number: e.number, title: e.title, command: `/relevo:go ${e.number}` }))
+    : [];
+
+  const alerts = [];
+  // A build that stopped reporting: nothing happened on the issue for longer than limits.building_alert_hours.
+  entries.filter((e) => e.state === 'building' && e.updatedAt).forEach((e) => {
+    const hours = Math.floor((new Date(now).getTime() - Date.parse(e.updatedAt)) / HOUR);
+    if (hours >= config.limits.building_alert_hours) alerts.push({ type: 'stuck-build', issue: e.number, hours, command: `/relevo:go ${e.number}` });
+  });
+  prs.forEach((p) => {
+    if (!p.approved && p.reviewer && p.requested_at) {
+      const hours = Math.floor((new Date(now).getTime() - Date.parse(p.requested_at)) / HOUR);
+      if (hours >= config.limits.review_sla_hours) alerts.push({ type: 'stale-review', issue: p.issue, pr: p.url, reviewer: p.reviewer, hours });
+    }
+    if ((p.behind_by ?? 0) >= BEHIND_ALERT) alerts.push({ type: 'stale-branch', issue: p.issue, pr: p.url, behind: p.behind_by });
+  });
+
+  // Who is waiting on what, for the whole team (used by the digest).
+  const waiting = {};
+  const add = (login, line) => {
+    if (!login) return;
+    (waiting[login] ??= []).push(line);
+  };
+  entries.forEach((e) => {
+    if (['built', 'in-review', 'qa-failed', 'changes-requested'].includes(e.state)) add(e.assignee, { number: e.number, state: e.state, command: `/relevo:${nextCommand[e.state]} ${e.number}` });
+    if (e.state === 'needs-spec') add(specWriter, { number: e.number, state: e.state });
+    if (e.needsReviewer) add(specWriter, { number: e.number, state: 'needs-reviewer' });
+  });
+  prs.forEach((p) => {
+    if (!p.approved && p.reviewer) add(p.reviewer, { number: p.issue, state: 'review-requested', pr: p.url });
+    if (p.approved) add(config.review.merger === 'author' ? p.author : p.reviewer, { number: p.issue, state: 'approved', command: `/relevo:ship ${p.issue}` });
+  });
+
+  return {
+    me, view: isSpecWriter ? 'spec-writer' : 'person',
+    onMe, toReview, toShip, readyForMe, waitingOnOthers, specWriter: specWriterView,
+    milestones: summaries, alerts, waiting,
+    readOnly: true,
+  };
+}
+
+const T = {
+  en: {
+    nothing: 'Nothing is waiting on you.', onMe: 'Waiting on you', review: 'Pull requests to review', ship: 'Approved, ready to ship',
+    others: 'Waiting on others', spec: 'Back with the spec writer', blocked: 'Blocked', needsReviewer: 'Need a reviewer', milestone: 'Milestone',
+    noDue: 'has no due date, so no capacity warning is computed', merged: 'merged', inReview: 'in review', queued: 'queued', warn: 'capacity warning: more work than the team can review before the due date',
+    alerts: 'Alerts', staleReview: 'review waiting', staleBranch: 'branch behind the base by',
+    waitingFor: 'waiting for', open: 'open', closed: 'closed, not completed', unreadable: 'could not be read',
+    readyForMe: 'Ready, for you to build (the cloud is not building)', stuck: 'build with no activity for', restart: 'remove relevo:building and apply relevo:ready again, or run',
+  },
+  es: {
+    nothing: 'Nada espera por ti.', onMe: 'Esperando por ti', review: 'Pull requests por revisar', ship: 'Aprobadas, listas para entregar',
+    others: 'Esperando a otros', spec: 'De vuelta con quien escribe las specs', blocked: 'Bloqueadas', needsReviewer: 'Sin revisor', milestone: 'Milestone',
+    noDue: 'no tiene fecha límite, así que no se calcula la advertencia de capacidad', merged: 'fusionadas', inReview: 'en revisión', queued: 'en cola', warn: 'advertencia de capacidad: hay más trabajo del que el equipo puede revisar antes de la fecha límite',
+    alerts: 'Alertas', staleReview: 'revisión esperando', staleBranch: 'rama atrasada respecto a la base por',
+    waitingFor: 'esperando', open: 'abierto', closed: 'cerrado, sin completar', unreadable: 'no se pudo leer',
+    readyForMe: 'Listas, para que las construyas (la nube no está construyendo)', stuck: 'construcción sin actividad desde hace', restart: 'quita relevo:building y vuelve a poner relevo:ready, o ejecuta',
+  },
+};
+
+/** The report as text, in the language of relevo.yml. */
+export function renderStatus(report, language = 'en') {
+  const t = T[String(language).startsWith('es') ? 'es' : 'en'];
+  const out = [];
+  const section = (title, lines) => {
+    if (lines.length) out.push(`${title}:`, ...lines.map((l) => `  ${l}`), '');
+  };
+  const waits = (e) => (e.blockedBy ?? []).map((b) => `${t.waitingFor} ${b.ref} (${b.state === 'unreadable' ? t.unreadable : b.lifecycle ?? t[b.state]})`).join(', ');
+  const withWaits = (e, base) => (e.blockedBy ? `${base} — ${waits(e)}` : base);
+  const sw = report.specWriter;
+  if (sw) {
+    section(t.spec, sw.needsSpec.map((e) => `#${e.number} ${e.title}`));
+    section(t.blocked, sw.blocked.map((e) => withWaits(e, `#${e.number} ${e.title}`)));
+    section(t.needsReviewer, sw.needsReviewer.map((e) => `#${e.number} ${e.title}`));
+  }
+  section(t.onMe, report.onMe.map((e) => `#${e.number} ${e.title} → ${e.command}`));
+  section(t.readyForMe, report.readyForMe.map((e) => `#${e.number} ${e.title} → ${e.command}`));
+  section(t.review, report.toReview.map((r) => `#${r.number} ${r.pr}`));
+  section(t.ship, report.toShip.map((r) => `#${r.number} → ${r.command}`));
+  section(t.others, report.waitingOnOthers.map((e) => withWaits(e, `#${e.number} ${e.title} (${e.state})`)));
+  if (!sw && !report.onMe.length && !report.toReview.length && !report.toShip.length) out.unshift(t.nothing, '');
+  report.milestones.forEach((m) => {
+    out.push(`${t.milestone} "${m.title}": ${m.merged} ${t.merged}, ${m.inReview} ${t.inReview}, ${m.queued} ${t.queued}`);
+    if (!m.dueOn) out.push(`  ${t.milestone} ${t.noDue}`);
+    else if (m.warning) out.push(`  ⚠ ${t.warn} (${m.queued + m.inFlight} > ${m.capacity.reviews})`);
+  });
+  if (report.milestones.length) out.push('');
+  section(t.alerts, report.alerts.map((a) => {
+    if (a.type === 'stuck-build') return `#${a.issue} ${t.stuck} ${a.hours}h: ${t.restart} ${a.command}`;
+    return a.type === 'stale-review'
+      ? `#${a.issue} ${t.staleReview} ${a.hours}h (@${a.reviewer}) ${a.pr}`
+      : `#${a.issue} ${t.staleBranch} ${a.behind} ${a.pr}`;
+  }));
+  while (out.length && out[out.length - 1] === '') out.pop();
+  return out.join('\n');
+}
+
+/** The daily digest: only who is waiting on what, and the alerts. Null when there is nothing to say. */
+export function renderDigest(report, language = 'en') {
+  const es = String(language).startsWith('es');
+  const people = Object.keys(report.waiting).sort();
+  if (!people.length && !report.alerts.length) return null;
+  const lines = [es ? 'Resumen diario de Relevo' : 'Relevo daily digest', ''];
+  people.forEach((login) => {
+    lines.push(`@${login}: ${report.waiting[login].map((w) => `#${w.number} (${w.state})`).join(', ')}`);
+  });
+  if (report.alerts.length) {
+    lines.push('', `${es ? 'Alertas' : 'Alerts'}:`);
+    report.alerts.forEach((a) => {
+      if (a.type === 'stuck-build') lines.push(`- #${a.issue} ${es ? 'construcción sin actividad desde hace' : 'build with no activity for'} ${a.hours}h`);
+      else lines.push(a.type === 'stale-review'
+        ? `- #${a.issue} ${es ? 'revisión esperando' : 'review waiting'} ${a.hours}h (@${a.reviewer})`
+        : `- #${a.issue} ${es ? 'rama atrasada por' : 'branch behind the base by'} ${a.behind}`);
+    });
+  }
+  return lines.join('\n');
+}

package/scripts/lib/tasks-file.mjs

@@ -0,0 +1,81 @@
+// Edits tasks.md of a change: appends a section of corrections for a review iteration.
+// Implements "Specification first" of openspec/specs/fix/spec.md.
+
+const SECTION_RE = /^##\s+(\d+)\.\s+(.*)$/;
+const ITERATION_RE = /Review corrections \[Iteration (\d+)\]/;
+
+/**
+ * Append "## N. Review corrections [Iteration K]" with one unchecked task per title.
+ * Returns { text, section, iteration, ids }.
+ */
+export function addCorrections(tasksText, titles) {
+  const clean = titles.map((t) => String(t).trim()).filter(Boolean);
+  if (clean.length === 0) throw new Error('give at least one correction task');
+  const lines = String(tasksText).split('\n');
+  let last = 0;
+  let iteration = 0;
+  lines.forEach((line) => {
+    const s = line.match(SECTION_RE);
+    if (!s) return;
+    last = Math.max(last, Number(s[1]));
+    const it = line.match(ITERATION_RE);
+    if (it) iteration = Math.max(iteration, Number(it[1]));
+  });
+  const section = last + 1;
+  const next = iteration + 1;
+  const ids = clean.map((_, i) => `${section}.${i + 1}`);
+  const block = [`## ${section}. Review corrections [Iteration ${next}]`, '', ...clean.map((t, i) => `- [ ] ${ids[i]} ${t}`), ''].join('\n');
+  const base = String(tasksText).replace(/\s*$/, '\n');
+  return { text: `${base}\n${block}`, section, iteration: next, ids };
+}
+
+/** Ids of the tasks that are still unchecked. */
+export function uncheckedTasks(tasksText) {
+  return [...String(tasksText).matchAll(/^\s*- \[ \] (\d+\.\d+)\b/gm)].map((m) => m[1]);
+}
+
+/** Tasks of the last "Review corrections" section: { found, ids, tasks } with each task's id and text. */
+export function correctionSection(tasksText) {
+  const lines = String(tasksText).split('\n');
+  let start = -1;
+  lines.forEach((line, i) => {
+    if (ITERATION_RE.test(line) && SECTION_RE.test(line)) start = i;
+  });
+  if (start === -1) return { found: false, ids: [], tasks: [] };
+  const tasks = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (SECTION_RE.test(lines[i])) break;
+    const m = lines[i].match(/^\s*- \[[ x]\] (\d+\.\d+)\s+(.*)$/);
+    if (m) tasks.push({ id: m[1], text: m[2].trim() });
+  }
+  return { found: true, ids: tasks.map((t) => t.id), tasks };
+}
+
+const DEVICE_ONLY_RE = /\(device only\)\s*$/i;
+const TEST_RE = /^test:/i;
+
+/**
+ * Checks the task list around a fix.
+ *   before  the developer has not run: the only unchecked tasks are the corrections, and there is a regression test
+ *           task unless every correction is device-only
+ *   after   QA passed: nothing is unchecked
+ * Returns { ok, reasons }.
+ */
+export function checkFixTasks(tasksText, stage) {
+  const open = uncheckedTasks(tasksText);
+  if (stage === 'after') {
+    return open.length === 0
+      ? { ok: true, reasons: [] }
+      : { ok: false, reasons: [`tasks are still unchecked: ${open.join(', ')}`] };
+  }
+  const section = correctionSection(tasksText);
+  if (!section.found) return { ok: false, reasons: ['tasks.md has no "Review corrections" section: add the corrections first'] };
+  const reasons = [];
+  const old = open.filter((id) => !section.ids.includes(id));
+  if (old.length > 0) reasons.push(`tasks that are not corrections are still unchecked: ${old.join(', ')}`);
+  const allDevice = section.tasks.length > 0 && section.tasks.every((t) => DEVICE_ONLY_RE.test(t.text));
+  if (!allDevice && !section.tasks.some((t) => TEST_RE.test(t.text))) {
+    reasons.push('a regression test is missing: add a correction task that starts with "Test:", or mark the corrections "(device only)"');
+  }
+  return { ok: reasons.length === 0, reasons };
+}

package/scripts/lib/web-review.mjs

@@ -0,0 +1,98 @@
+// The rules of a driven web review that must not vary: which origins a page may reach, what a review script may
+// contain, how a secret is kept out of the output, and the log the audit reads.
+// Implements "The agent operates the app only within fixed limits", "A web review script is reviewed before it runs",
+// "Credentials of a driven review are names, not values" and "The audit understands a browser" of openspec/specs/review/spec.md.
+
+export const WEB_PACKAGE = 'web';
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+// URLs that do not reach the network.
+const OFFLINE_PROTOCOLS = new Set(['data:', 'blob:', 'about:']);
+
+/**
+ * May a request to `url` leave the browser? Only localhost, the origin under review and the listed origins.
+ * `allowed` is the list of origins (review.allowed_origins); `baseUrl` is the page under review.
+ */
+export function isAllowedOrigin(url, { baseUrl, allowed = [] } = {}) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  if (OFFLINE_PROTOCOLS.has(u.protocol)) return true;
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  if (LOCAL_HOSTS.has(u.hostname)) return true;
+  const origins = new Set(allowed);
+  if (baseUrl) {
+    try {
+      origins.add(new URL(baseUrl).origin);
+    } catch { /* an unusable base adds nothing */ }
+  }
+  return origins.has(u.origin);
+}
+
+const ALLOWED_MODULES = new Set(['node:assert', 'node:assert/strict', 'assert', 'assert/strict', 'playwright', '@playwright/test']);
+const FORBIDDEN = [
+  [/\bchild_process\b/, 'it reaches child_process'],
+  [/\beval\s*\(/, 'it calls eval'],
+  [/\bnew\s+Function\b|\bFunction\s*\(/, 'it builds code with Function'],
+  [/\bprocess\s*\.\s*(env|exit|kill|binding|argv)\b/, 'it reaches the process (credentials come from credentials(name))'],
+  [/\bglobalThis\s*\.\s*process\b/, 'it reaches the process'],
+  [/\bfetch\s*\(/, 'it makes a request outside the browser with fetch'],
+  [/\brequire\.resolve\b|\bimport\.meta\b/, 'it inspects the module system'],
+];
+
+/**
+ * A tripwire for a review script written by the agent: it lists what the script must not do. It is not a sandbox;
+ * the real protections are the review by QA, the origin guard and the clean profile.
+ */
+export function scanReviewScript(text) {
+  const source = String(text ?? '');
+  const problems = [];
+  const modules = [
+    ...[...source.matchAll(/\bimport\s+(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/g)].map((m) => m[1]),
+    ...[...source.matchAll(/\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g)].map((m) => m[1]),
+    ...[...source.matchAll(/\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g)].map((m) => m[1]),
+  ];
+  [...new Set(modules)].filter((m) => !ALLOWED_MODULES.has(m)).forEach((m) => problems.push(`it imports "${m}"; only the assertion and browser libraries are allowed`));
+  if (/\bimport\s*\(\s*[^'"\s)]/.test(source) || /\brequire\s*\(\s*[^'"\s)]/.test(source)) problems.push('it loads a module by a computed name');
+  FORBIDDEN.forEach(([re, why]) => {
+    if (re.test(source)) problems.push(why);
+  });
+  return problems;
+}
+
+/** Replace the value of every secret by [redacted:NAME]. `secrets` maps a variable name to its value. */
+export function redact(text, secrets = {}) {
+  let out = String(text ?? '');
+  Object.entries(secrets)
+    .filter(([, value]) => typeof value === 'string' && value.length >= 3)
+    .sort((a, b) => b[1].length - a[1].length)
+    .forEach(([name, value]) => {
+      out = out.split(value).join(`[redacted:${name}]`);
+    });
+  return out;
+}
+
+const pad = (n, width = 2) => String(n).padStart(width, '0');
+const stamp = (d) => `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+
+/**
+ * The browser's errors as a log in the format the audit reads. `events` are { type, text } with type
+ * `console` (a console error), `pageerror` (an uncaught exception), `requestfailed`, `response` (a 4xx or 5xx) or
+ * `blocked` (a request the origin guard stopped). The first line names the "process", so the audit can filter by
+ * the package `web`. Returns '' only when there were no events at all, which the caller still writes with the header.
+ */
+export function formatBrowserLog(events, { origin = 'page', now = new Date() } = {}) {
+  const line = (level, tag, text) => `${stamp(now)}  1  1 ${level} ${tag}: ${String(text).replace(/\s*\n\s*/g, ' ').trim()}`;
+  const out = [line('I', 'ActivityManager', `Start proc 1:${WEB_PACKAGE}/${origin} for browser`)];
+  events.forEach((e) => {
+    if (e.type === 'pageerror') out.push(line('E', WEB_PACKAGE, `Uncaught ${e.text}`));
+    else if (e.type === 'console') out.push(line('E', WEB_PACKAGE, `console.error ${e.text}`));
+    else if (e.type === 'requestfailed') out.push(line('E', WEB_PACKAGE, `requestfailed ${e.text}`));
+    else if (e.type === 'response') out.push(line('E', WEB_PACKAGE, `response ${e.text}`));
+    else if (e.type === 'blocked') out.push(line('E', WEB_PACKAGE, `blocked request ${e.text}`));
+  });
+  return `${out.join('\n')}\n`;
+}

package/scripts/lib/yaml-lite.mjs

@@ -0,0 +1,157 @@
+// Minimal parser for the YAML subset used by relevo.yml. No dependencies.
+//
+// Supported: nested maps (2+ space indentation), block lists of scalars,
+// inline lists of scalars ([a, b]), empty inline map ({}), comments,
+// quoted strings, booleans, null, integers and decimals.
+// Not supported (reported as errors): tabs, anchors, multi-line strings,
+// lists of maps, non-empty inline maps, duplicate keys.
+// Quote any string that contains "#" or quote characters.
+
+export class YamlLiteError extends Error {
+  constructor(message, line) {
+    super(`line ${line}: ${message}`);
+    this.name = 'YamlLiteError';
+    this.line = line;
+  }
+}
+
+function stripComment(raw) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < raw.length; i += 1) {
+    const c = raw[i];
+    if (c === "'" && !inDouble) inSingle = !inSingle;
+    else if (c === '"' && !inSingle) inDouble = !inDouble;
+    else if (c === '#' && !inSingle && !inDouble && (i === 0 || /\s/.test(raw[i - 1]))) {
+      return raw.slice(0, i);
+    }
+  }
+  return raw;
+}
+
+function splitInline(inner, line) {
+  const parts = [];
+  let current = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (const c of inner) {
+    if (c === "'" && !inDouble) inSingle = !inSingle;
+    else if (c === '"' && !inSingle) inDouble = !inDouble;
+    if (c === ',' && !inSingle && !inDouble) {
+      parts.push(current);
+      current = '';
+    } else {
+      current += c;
+    }
+  }
+  if (inSingle || inDouble) throw new YamlLiteError('unterminated quote in inline list', line);
+  parts.push(current);
+  return parts;
+}
+
+export function parseScalar(text, line = 0) {
+  const t = text.trim();
+  if (t === '') return null;
+  if (t.startsWith('"')) {
+    if (t.length < 2 || !t.endsWith('"')) throw new YamlLiteError('unterminated double-quoted string', line);
+    try {
+      return JSON.parse(t);
+    } catch {
+      throw new YamlLiteError('invalid escape in double-quoted string', line);
+    }
+  }
+  if (t.startsWith("'")) {
+    if (t.length < 2 || !t.endsWith("'")) throw new YamlLiteError('unterminated single-quoted string', line);
+    return t.slice(1, -1).replace(/''/g, "'");
+  }
+  if (t.startsWith('[')) {
+    if (!t.endsWith(']')) throw new YamlLiteError('unterminated inline list', line);
+    const inner = t.slice(1, -1).trim();
+    if (inner === '') return [];
+    return splitInline(inner, line).map((part) => parseScalar(part, line));
+  }
+  if (t === '{}') return {};
+  if (t.startsWith('{')) throw new YamlLiteError('inline maps are not supported', line);
+  if (t.startsWith('&') || t.startsWith('*') || t === '|' || t === '>') {
+    throw new YamlLiteError('anchors and multi-line strings are not supported', line);
+  }
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  if (t === 'null' || t === '~') return null;
+  if (/^-?\d+$/.test(t)) return Number.parseInt(t, 10);
+  if (/^-?\d+\.\d+$/.test(t)) return Number.parseFloat(t);
+  return t;
+}
+
+const KEY_RE = /^([A-Za-z0-9_.-]+):(?:\s+(.*))?$/;
+
+export function parse(text) {
+  const rawLines = String(text).replace(/\r\n/g, '\n').split('\n');
+  const items = [];
+  rawLines.forEach((raw, idx) => {
+    const line = idx + 1;
+    const withoutComment = stripComment(raw);
+    if (withoutComment.trim() === '') return;
+    if (/^\s*\t/.test(withoutComment)) throw new YamlLiteError('tabs are not allowed for indentation', line);
+    const m = withoutComment.match(/^( *)(\S.*?)\s*$/);
+    items.push({ indent: m[1].length, content: m[2], line });
+  });
+  if (items.length === 0) return {};
+  if (items[0].indent !== 0) throw new YamlLiteError('top level must not be indented', items[0].line);
+
+  let pos = 0;
+
+  function isListItem(item) {
+    return item.content === '-' || item.content.startsWith('- ');
+  }
+
+  function parseList(indent) {
+    const list = [];
+    while (pos < items.length && items[pos].indent === indent && isListItem(items[pos])) {
+      const item = items[pos];
+      const rest = item.content.slice(1).trim();
+      const quoted = rest.startsWith('"') || rest.startsWith("'");
+      if (!quoted && /^[A-Za-z0-9_.-]+:(\s|$)/.test(rest)) {
+        throw new YamlLiteError('lists of maps are not supported', item.line);
+      }
+      list.push(parseScalar(rest, item.line));
+      pos += 1;
+    }
+    return list;
+  }
+
+  function parseMap(indent) {
+    const map = {};
+    while (pos < items.length && items[pos].indent === indent) {
+      const item = items[pos];
+      if (isListItem(item)) throw new YamlLiteError('unexpected list item in a map', item.line);
+      const m = item.content.match(KEY_RE);
+      if (!m) throw new YamlLiteError(`expected "key: value", got "${item.content}"`, item.line);
+      const key = m[1];
+      if (Object.prototype.hasOwnProperty.call(map, key)) {
+        throw new YamlLiteError(`duplicate key "${key}"`, item.line);
+      }
+      pos += 1;
+      if (m[2] !== undefined && m[2].trim() !== '') {
+        map[key] = parseScalar(m[2], item.line);
+        continue;
+      }
+      const next = items[pos];
+      if (next && next.indent > indent) {
+        map[key] = isListItem(next) ? parseList(next.indent) : parseMap(next.indent);
+      } else if (next && next.indent === indent && isListItem(next)) {
+        map[key] = parseList(indent);
+      } else {
+        map[key] = null;
+      }
+    }
+    if (pos < items.length && items[pos].indent > indent) {
+      throw new YamlLiteError('unexpected indentation', items[pos].line);
+    }
+    return map;
+  }
+
+  const result = parseMap(0);
+  if (pos < items.length) throw new YamlLiteError('unexpected content', items[pos].line);
+  return result;
+}

package/scripts/needs-reviewer.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Used when no reviewer could be chosen: labels the issue `needs-reviewer` (next to its state) and mentions the spec writer.
+//   node scripts/needs-reviewer.mjs --repo owner/name --issue 12 --title "Add total" --pr-url <url> [--config relevo.yml] [--dry-run]
+// Prints the decision as JSON.   exit 0: done   exit 2: invalid configuration or bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { realGh } from './lib/github.mjs';
+import { renderMessage } from './lib/messages.mjs';
+import { noReviewerDecision } from './lib/reviewers.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const fail = (m) => {
+  console.error(m);
+  process.exit(2);
+};
+
+const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+const issue = Number(arg('issue'));
+const title = arg('title');
+const prUrl = arg('pr-url');
+if (!repo || !Number.isInteger(issue) || !title || !prUrl) fail('usage: needs-reviewer.mjs --repo owner/name --issue <n> --title <text> --pr-url <url> [--config relevo.yml] [--dry-run]');
+
+const path = resolve(arg('config') ?? 'relevo.yml');
+if (!existsSync(path)) fail(`relevo.yml not found at ${path}. Run /relevo:init to create it.`);
+const loaded = loadConfig(readFileSync(path, 'utf8'));
+if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
+const { config } = loaded;
+
+const dry = process.argv.includes('--dry-run');
+const labels = dry ? [] : JSON.parse(realGh(['api', `repos/${repo}/issues/${issue}`])).labels.map((l) => (typeof l === 'string' ? l : l.name));
+const decision = noReviewerDecision({ config, issue: { number: issue, title, pr: prUrl, labels } });
+if (!dry) {
+  if (decision.labels.add.length) realGh(['issue', 'edit', String(issue), '--repo', repo, ...decision.labels.add.flatMap((l) => ['--add-label', l])]);
+  if (decision.comment) realGh(['issue', 'comment', String(issue), '--repo', repo, '--body', renderMessage(decision.comment.kind, decision.comment.data, config.language)]);
+}
+console.log(JSON.stringify(decision));

package/scripts/next-step.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Prints the next step of an issue, in the language of the repository. Usage:
+//   node scripts/next-step.mjs --state built --issue 42 [--reason <reason>] [--language es] [--config relevo.yml] [--json]
+// States: the lifecycle labels without the prefix (built, in-review, pr-open, needs-spec, qa-failed, ...).
+// --reason: `missing` or `ambiguous` for needs-spec; `fix` or `delete-branch` for qa-failed.
+// The language comes from --language, else from relevo.yml (if found), else English.
+//   exit 0: printed   exit 2: unknown state or reason, a missing issue number, or bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { NEXT_STEP_STATES, nextStep } from './lib/next-step.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+
+if (!arg('state')) {
+  console.error(`usage: next-step.mjs --state <${NEXT_STEP_STATES.join('|')}> --issue <number> [--reason <reason>] [--language xx] [--json]`);
+  process.exit(2);
+}
+
+let language = arg('language');
+if (!language) {
+  const path = resolve(arg('config') ?? 'relevo.yml');
+  if (existsSync(path)) {
+    const loaded = loadConfig(readFileSync(path, 'utf8'));
+    if (loaded.ok) language = loaded.config.language;
+  }
+}
+
+try {
+  const step = nextStep({ state: arg('state'), reason: arg('reason') ?? null, issue: arg('issue') ?? null, language: language ?? 'en' });
+  console.log(process.argv.includes('--json') ? JSON.stringify(step, null, 2) : step.line);
+} catch (err) {
+  console.error(err.message);
+  process.exit(2);
+}

package/scripts/pick-reviewer.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Picks the reviewer of a pull request. Usage:
+//   node scripts/pick-reviewer.mjs --repo owner/name --author login --pr 40 [--config relevo.yml]
+// Prints {"reviewer": "login"} or {"reviewer": null} when nobody is eligible.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './lib/config.mjs';
+import { openReviewCounts, realGh } from './lib/github.mjs';
+import { pickReviewer } from './lib/reviewers.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const fail = (m) => {
+  console.error(m);
+  process.exit(2);
+};
+
+const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
+const author = arg('author');
+const pr = Number(arg('pr'));
+if (!repo || !author || !Number.isInteger(pr)) fail('usage: pick-reviewer.mjs --repo owner/name --author login --pr <number> [--config relevo.yml]');
+
+const path = resolve(arg('config') ?? 'relevo.yml');
+if (!existsSync(path)) fail(`relevo.yml not found at ${path}. Run /relevo:init to create it.`);
+const loaded = loadConfig(readFileSync(path, 'utf8'));
+if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
+const { config } = loaded;
+
+if (config.review.mode === 'none') {
+  console.log(JSON.stringify({ reviewer: null, reason: 'review.mode is none' }));
+} else {
+  const candidates = config.team.members.filter((m) => m !== author && m !== config.team.spec_writer);
+  const openCounts = openReviewCounts({ gh: realGh, repo, logins: candidates });
+  const reviewer = pickReviewer({
+    members: config.team.members, specWriter: config.team.spec_writer, author,
+    approvers: config.team.approvers, mode: config.review.mode, openCounts, prNumber: pr,
+  });
+  console.log(JSON.stringify({ reviewer }));
+}