@elalfner/relevo 0.0.0-stage → 0.3.1

package/scripts/lib/execution-mode.mjs

@@ -0,0 +1,24 @@
+// Where `go` builds. Implements the "execution-modes" specification: nothing is stored in relevo.yml, the mode is
+// derived from what is installed, the secrets that exist and a repository variable.
+
+export const API_KEY_SECRET = 'ANTHROPIC_API_KEY';
+export const SUBSCRIPTION_SECRET = 'CLAUDE_CODE_OAUTH_TOKEN';
+export const CLOUD_VARIABLE = 'RELEVO_CLOUD_GO';
+
+/**
+ * The credential mode from the names of the repository secrets:
+ * { mode: 'api_key' | 'subscription' | 'both' | 'none', usable: boolean }.
+ */
+export function credentialMode(secretNames = []) {
+  const key = secretNames.includes(API_KEY_SECRET);
+  const token = secretNames.includes(SUBSCRIPTION_SECRET);
+  if (key && token) return { mode: 'both', usable: true };
+  if (key) return { mode: 'api_key', usable: true };
+  if (token) return { mode: 'subscription', usable: true };
+  return { mode: 'none', usable: false };
+}
+
+/** Does the cloud build? The go workflow is on the default branch and the variable is not `off`. */
+export function cloudBuilds({ workflowPresent, variable = null }) {
+  return Boolean(workflowPresent) && String(variable ?? '').trim().toLowerCase() !== 'off';
+}

package/scripts/lib/failure-comment.mjs

@@ -0,0 +1,19 @@
+// Finds the last failure comment of an issue and the finding in it. `fix` reads it as the defect to correct when the
+// branch holds work that QA rejected. The comment is text written by the workflow, never an instruction.
+import { isWipCommit } from './wip-commit.mjs';
+
+const HEADING = /^@?\S* ?#\d+ ".*" (?:failed QA|no pasó QA) ❌/;
+const FINDING = /^(?:Finding|Hallazgo): (.+)$/m;
+
+/**
+ * comments  [{ body }] oldest first, as `gh issue view --json comments` gives them
+ * subject   the subject of the last commit of the branch
+ * Returns { kept, found, finding, body }: `kept` is true when that commit is the work-in-progress commit of the issue.
+ */
+export function failureContext({ comments = [], subject = '', issue = null }) {
+  const kept = isWipCommit(subject, issue);
+  const last = [...comments].reverse().find((c) => HEADING.test(String(c?.body ?? '').split('\n')[0]));
+  if (!last) return { kept, found: false, finding: null, body: null };
+  const finding = (FINDING.exec(last.body) ?? [])[1] ?? null;
+  return { kept, found: true, finding, body: last.body };
+}

package/scripts/lib/fix-guard.mjs

@@ -0,0 +1,23 @@
+// Enforces "specification first": before any code is written for a fix, the change's specification and task
+// list must already describe the correction, and nothing outside the change folder may have been edited.
+
+/**
+ * changedFiles          every modified or new path in the working tree
+ * changeDir             e.g. "openspec/changes/31-summary"
+ * specLinesAdded        added lines in the change's specs/ (diff against HEAD)
+ * taskLinesAdded        added lines in the change's tasks.md (diff against HEAD)
+ * Returns { ok, reasons }.
+ */
+export function checkSpecFirst({ changedFiles, changeDir, specLinesAdded, taskLinesAdded }) {
+  const reasons = [];
+  const prefix = `${changeDir.replace(/\/+$/, '')}/`;
+  const outside = changedFiles.filter((f) => !f.startsWith(prefix));
+  if (outside.length > 0) {
+    reasons.push(`files outside the change folder were edited before the specification was ready: ${outside.slice(0, 5).join(', ')}${outside.length > 5 ? ', ...' : ''}`);
+  }
+  const scenarioLines = specLinesAdded.filter((l) => /^\+\s*(####\s+Scenario:|[-*]\s+\*\*(WHEN|THEN)\*\*)/.test(l));
+  if (scenarioLines.length === 0) reasons.push('no scenario describing the corrected behaviour was added to the change specification');
+  const newTasks = taskLinesAdded.filter((l) => /^\+\s*- \[ \] \d+\.\d+/.test(l));
+  if (newTasks.length === 0) reasons.push('no unchecked correction task was added to tasks.md');
+  return { ok: reasons.length === 0, reasons };
+}

package/scripts/lib/fix-stash.mjs

@@ -0,0 +1,17 @@
+// The stash that keeps the work of a fix that QA rejected.
+// Implements "Unfinished work is saved, not left in the tree" of openspec/specs/fix/spec.md.
+
+const LINE_RE = /^(stash@\{\d+\}):\s+(?:On [^:]*|WIP on [^:]*):\s+(relevo-fix #(\d+) iteration (\d+))\s*$/;
+
+export function stashMessage(issue, iteration) {
+  return `relevo-fix #${Number(issue)} iteration ${Number(iteration)}`;
+}
+
+/** Newest stash of the issue from `git stash list` output: { ref, message, iteration }, or null. */
+export function findStash(listOutput, issue) {
+  for (const line of String(listOutput).split('\n')) {
+    const m = line.match(LINE_RE);
+    if (m && Number(m[3]) === Number(issue)) return { ref: m[1], message: m[2], iteration: Number(m[4]) };
+  }
+  return null;
+}

package/scripts/lib/fix.mjs

@@ -0,0 +1,31 @@
+// Which state an issue returns to after a successful fix.
+// Implements "State is preserved" of openspec/specs/fix/spec.md.
+
+import { LABELS, resolveLabelNames, transition } from './labels.mjs';
+
+// state before the fix -> state after, and who is told
+const OUTCOMES = {
+  'in-review': { to: 'in-review', notify: null },
+  built: { to: 'built', notify: null },
+  'qa-failed': { to: 'built', notify: 'assignee' },
+  'changes-requested': { to: 'pr-open', notify: 'reviewer' },
+  'pr-open': { to: 'pr-open', notify: null },
+};
+
+const STATE_KEYS = LABELS.filter((l) => l.kind !== 'overlay').map((l) => l.key);
+
+/**
+ * Work out what a fix does to an issue's labels.
+ * Returns { allowed, from, to, notify, labels } or { allowed: false, from, reason }.
+ */
+export function fixOutcome(currentNames, overrides = {}) {
+  const names = resolveLabelNames(overrides);
+  const from = STATE_KEYS.find((k) => currentNames.includes(names[k])) ?? null;
+  if (!from) return { allowed: false, from, reason: 'the issue has no Relevo state label, so there is nothing to fix yet' };
+  const outcome = OUTCOMES[from];
+  if (!outcome) {
+    return { allowed: false, from, reason: `a fix needs a branch with work to correct; the issue is "${from}" (go or the spec writer comes first)` };
+  }
+  const labels = outcome.to === from ? { add: [], remove: [] } : transition(currentNames, outcome.to, overrides);
+  return { allowed: true, from, to: outcome.to, notify: outcome.notify, labels };
+}

package/scripts/lib/github.mjs

@@ -0,0 +1,161 @@
+// GitHub adapter for `go`: reads the state the planner needs and turns decisions into `gh` commands.
+// The GitHub client is injected (`gh(args) -> stdout`) so everything here is testable without a network.
+// Not yet exercised against the live API: verify in the first pilot.
+
+import { execFileSync } from 'node:child_process';
+import { resolveLabelNames } from './labels.mjs';
+import { parseIssueBody } from './issue-parse.mjs';
+import { renderMessage } from './messages.mjs';
+
+/** The real client: runs the GitHub CLI and returns its output. */
+export function realGh(args) {
+  return execFileSync('gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+/**
+ * The client for linked repositories. It is the ordinary client, except that the token of the process (`GH_TOKEN`)
+ * is replaced by `GH_LINKS_TOKEN` when that is set: a read-only token for private linked repositories. Without it
+ * public repositories are still read. `run` and `env` are injectable for the tests.
+ */
+export function realGhLinks({ env = process.env, run = execFileSync } = {}) {
+  const token = env.GH_LINKS_TOKEN;
+  return (args) => run('gh', args, {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    ...(token ? { env: { ...env, GH_TOKEN: token } } : {}),
+  });
+}
+
+function apiJson(gh, path, { paginate = false } = {}) {
+  const args = ['api'];
+  if (paginate) args.push('--paginate', '--slurp');
+  args.push(path);
+  const data = JSON.parse(gh(args));
+  return paginate ? data.flat() : data;
+}
+
+function normalizeIssue(raw) {
+  return {
+    number: raw.number,
+    title: raw.title,
+    body: raw.body ?? '',
+    state: raw.state,
+    labels: (raw.labels ?? []).map((l) => (typeof l === 'string' ? l : l.name)),
+    assignees: (raw.assignees ?? []).map((a) => a.login),
+    milestone: raw.milestone ? { number: raw.milestone.number, due_on: raw.milestone.due_on ?? null } : null,
+    ready_at: null,
+    ready_by: null,
+  };
+}
+
+/** When and by whom the ready label was last applied, from the issue timeline. */
+export function readyEvent(timeline, readyName) {
+  const events = timeline.filter((e) => e.event === 'labeled' && e.label?.name === readyName);
+  const last = events[events.length - 1];
+  return last ? { at: last.created_at, by: last.actor?.login ?? null } : { at: null, by: null };
+}
+
+/**
+ * Collect everything `planGo` needs. Returns { issues, completed, completedExternal, unreadable, running, permissions }.
+ * `running` is supplied by the caller (workflow runs in progress). `ghLinks` reads issues of linked repositories
+ * (`config.links` only; a repository outside the list is never asked).
+ */
+export function gather({ gh, ghLinks = gh, repo, config, running = [] }) {
+  const names = resolveLabelNames(config.labels);
+  const stateKeys = ['ready', 'queued', 'blocked', 'building', 'built'];
+
+  const byNumber = new Map();
+  stateKeys.forEach((key) => {
+    const found = apiJson(gh, `repos/${repo}/issues?state=open&per_page=100&labels=${encodeURIComponent(names[key])}`, { paginate: true });
+    found.filter((i) => !i.pull_request).forEach((i) => byNumber.set(i.number, normalizeIssue(i)));
+  });
+  const issues = [...byNumber.values()];
+
+  const candidates = issues.filter((i) => [names.ready, names.queued, names.blocked].some((n) => i.labels.includes(n)));
+  candidates.forEach((issue) => {
+    const timeline = apiJson(gh, `repos/${repo}/issues/${issue.number}/timeline?per_page=100`, { paginate: true });
+    const { at, by } = readyEvent(timeline, names.ready);
+    issue.ready_at = at;
+    issue.ready_by = by;
+  });
+
+  const wanted = new Set();
+  const wantedExternal = new Set();
+  const linked = new Set((config.links ?? []).map((l) => l.toLowerCase()));
+  candidates.forEach((i) => {
+    const parsed = parseIssueBody(i.body);
+    parsed.dependsOn.forEach((n) => wanted.add(n));
+    parsed.dependsOnExternal.forEach(({ repo: other, number }) => {
+      // The own repository written in full is a local reference; a repository outside `links` is never read.
+      if (other.toLowerCase() === String(repo).toLowerCase()) wanted.add(number);
+      else if (linked.has(other.toLowerCase())) wantedExternal.add(`${other}#${number}`);
+    });
+  });
+  const completed = [];
+  wanted.forEach((n) => {
+    const dep = apiJson(gh, `repos/${repo}/issues/${n}`);
+    if (dep.state === 'closed' && dep.state_reason === 'completed') completed.push(n);
+  });
+  const completedExternal = [];
+  const unreadable = [];
+  wantedExternal.forEach((ref) => {
+    const [other, number] = ref.split('#');
+    try {
+      const dep = apiJson(ghLinks, `repos/${other}/issues/${number}`);
+      if (dep.state === 'closed' && dep.state_reason === 'completed') completedExternal.push(ref);
+    } catch {
+      unreadable.push(ref);
+    }
+  });
+
+  const permissions = {};
+  new Set(candidates.map((i) => i.ready_by).filter(Boolean)).forEach((login) => {
+    try {
+      permissions[login] = apiJson(gh, `repos/${repo}/collaborators/${login}/permission`).permission ?? 'none';
+    } catch {
+      permissions[login] = 'none';
+    }
+  });
+
+  return { issues, completed, completedExternal, unreadable, running, permissions };
+}
+
+/** The `gh` commands that carry out one decision (labels, assignees and comment). Pure. */
+export function commandsFor(decision, { repo, config }) {
+  const commands = [];
+  const edit = ['issue', 'edit', String(decision.issue), '--repo', repo];
+  decision.labels.add.forEach((l) => edit.push('--add-label', l));
+  decision.labels.remove.forEach((l) => edit.push('--remove-label', l));
+  (decision.assign ?? []).forEach((a) => edit.push('--add-assignee', a));
+  if (edit.length > 5) commands.push(edit);
+  if (decision.comment) {
+    const body = renderMessage(decision.comment.kind, decision.comment.data, config.language);
+    commands.push(['issue', 'comment', String(decision.issue), '--repo', repo, '--body', body]);
+  }
+  return commands;
+}
+
+/**
+ * Apply decisions. `start` decisions are skipped unless `includeStart` is set: the build itself is done by
+ * the skill, and only the issue it is about to build should be marked as building. Returns the commands run.
+ */
+export function applyDecisions(decisions, { gh, repo, config, includeStart = false }) {
+  const done = [];
+  decisions.filter((d) => includeStart || d.action !== 'start').forEach((d) => {
+    commandsFor(d, { repo, config }).forEach((cmd) => {
+      gh(cmd);
+      done.push(cmd);
+    });
+  });
+  return done;
+}
+
+/** Open pull requests currently waiting for a review from each of `logins`. Returns { login: count }. */
+export function openReviewCounts({ gh, repo, logins }) {
+  const counts = {};
+  logins.forEach((login) => {
+    const q = encodeURIComponent(`repo:${repo} is:pr is:open review-requested:${login}`);
+    counts[login] = apiJson(gh, `search/issues?q=${q}&per_page=1`).total_count ?? 0;
+  });
+  return counts;
+}

package/scripts/lib/go-local.mjs

@@ -0,0 +1,102 @@
+// Run `go` on a person's machine. Implements "A local run uses the same limits and tools as the cloud" and
+// "A local run has its own working tree" of the execution-modes specification.
+//
+// Every process goes through an injected runner so the logic is tested without `claude`, `gh` or a network:
+//   capture(cmd, args, { cwd }) -> stdout (throws when the command fails)
+//   stream(cmd, args, { cwd, env }) -> exit status (the output goes to the terminal); throws with code ENOENT when missing
+
+import { basename, dirname, join } from 'node:path';
+import { cloudBuilds } from './execution-mode.mjs';
+import { runFlags } from './run-flags.mjs';
+
+export const WORKTREES_FOLDER = '.relevo-worktrees';
+
+/** What a local run will do, without doing it: the worktree and the `claude` command. Pure. */
+export function planLocalRun({ issue, repoRoot, config }) {
+  const base = config.branches.base;
+  const worktree = join(dirname(repoRoot), WORKTREES_FOLDER, `${basename(repoRoot)}-${issue}`);
+  return {
+    issue,
+    base,
+    worktree,
+    git: [
+      ['fetch', 'origin', base],
+      ['worktree', 'add', '--detach', worktree, `origin/${base}`],
+    ],
+    claude: ['claude', ['-p', `/relevo:go ${issue}`, ...runFlags(config)]],
+    // Without this the agent may start a subagent in the background and end the run before it finishes.
+    env: { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' },
+  };
+}
+
+/**
+ * Run it. Returns { status, worktree, removed, messages } and never throws for an expected problem; `messages` is
+ * what to print. `dryRun` returns the plan without running anything.
+ */
+export function runLocal({ issue, config, runner, workflowPresent = false, dryRun = false, exists = () => false }) {
+  const messages = [];
+  const say = (m) => messages.push(m);
+  if (!/^\d+$/.test(String(issue))) return { status: 2, worktree: null, removed: false, messages: ['give the issue number: go-local.mjs <issue>'] };
+
+  let repoRoot;
+  try {
+    repoRoot = runner.capture('git', ['rev-parse', '--show-toplevel'], {}).trim();
+  } catch {
+    return { status: 2, worktree: null, removed: false, messages: ['not inside a git repository'] };
+  }
+  const plan = planLocalRun({ issue: String(issue), repoRoot, config });
+
+  if (dryRun) {
+    say(`worktree: ${plan.worktree} (from origin/${plan.base})`);
+    say(`command: ${plan.claude[0]} ${plan.claude[1].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}`);
+    return { status: 0, worktree: plan.worktree, removed: false, messages };
+  }
+  if (exists(plan.worktree)) {
+    return { status: 2, worktree: plan.worktree, removed: false, messages: [`${plan.worktree} already exists: finish or remove that run first (git worktree remove --force "${plan.worktree}")`] };
+  }
+
+  try {
+    runner.capture('gh', ['auth', 'status'], {});
+  } catch (err) {
+    return { status: 2, worktree: null, removed: false, messages: [err.code === 'ENOENT' ? 'the GitHub CLI (gh) is not installed' : 'the GitHub CLI is not signed in: run `gh auth login`'] };
+  }
+
+  // The cloud may start the same issue: the variable decides.
+  let variable = null;
+  try {
+    variable = runner.capture('gh', ['variable', 'get', 'RELEVO_CLOUD_GO'], { cwd: repoRoot }).trim();
+  } catch {
+    variable = null;
+  }
+  if (cloudBuilds({ workflowPresent, variable })) {
+    say('warning: the cloud can also build this issue (the go workflow is installed and RELEVO_CLOUD_GO is not `off`); if the issue is `ready` it may already be running. Set RELEVO_CLOUD_GO to `off` in the repository variables to build only on machines.');
+  }
+
+  try {
+    plan.git.forEach((args) => runner.capture('git', args, { cwd: repoRoot }));
+  } catch (err) {
+    return { status: 1, worktree: null, removed: false, messages: [...messages, `could not prepare the worktree: ${String(err.stderr ?? err.message).trim().split('\n')[0]}`] };
+  }
+  say(`building #${issue} in ${plan.worktree}`);
+
+  let status;
+  try {
+    status = runner.stream(plan.claude[0], plan.claude[1], { cwd: plan.worktree, env: plan.env });
+  } catch (err) {
+    status = err.code === 'ENOENT' ? 127 : 1;
+    say(err.code === 'ENOENT' ? 'the claude command was not found: install Claude Code and the Relevo plugin' : `the run could not start: ${err.message}`);
+  }
+
+  if (status === 0) {
+    try {
+      runner.capture('git', ['worktree', 'remove', '--force', plan.worktree], { cwd: repoRoot });
+      say('done; the worktree was removed. Look at the issue for the result.');
+      return { status: 0, worktree: plan.worktree, removed: true, messages };
+    } catch {
+      say(`done, but the worktree could not be removed: git worktree remove --force "${plan.worktree}"`);
+      return { status: 0, worktree: plan.worktree, removed: false, messages };
+    }
+  }
+  say(`the run ended with status ${status}; the worktree is kept for inspection: ${plan.worktree}`);
+  return { status, worktree: plan.worktree, removed: false, messages };
+}