@elalfner/relevo 0.7.0 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "An automatic issue-to-merge workflow where an agent builds and people verify.",
   "author": {
     "name": "Elias Alfaro"

package/README.es.md

@@ -74,6 +74,7 @@ Además, `/relevo:status` (quién espera a quién) y `/relevo:doctor` (comprueba
 
 - [Primeros pasos](docs/get-started.es.md): de cero a tu primer pull request fusionado, paso a paso.
 - [Instalación](docs/install.es.md): qué necesitas y los primeros pasos.
+- [Actualizar](docs/upgrading.es.md): pasar un proyecto a una versión nueva, en el orden correcto.
 - [Cómo funciona](docs/how-it-works.es.md): la idea, y una corrida real de la idea al pull request mergeado.
 - [Comandos](docs/commands.es.md): los nueve comandos, y las skills que usa `think`.
 - [Configuración](docs/configuration.es.md): el archivo `relevo.yml`.

package/README.md

@@ -74,6 +74,7 @@ Plus `/relevo:status` (who is waiting on what) and `/relevo:doctor` (checks your
 
 - [Get started](docs/get-started.md): from nothing to your first merged pull request, step by step.
 - [Install](docs/install.md): what you need and the first steps.
+- [Upgrading](docs/upgrading.md): moving a project to a new version, in the right order.
 - [How it works](docs/how-it-works.md): the idea, and a real run from idea to merged pull request.
 - [Commands](docs/commands.md): the nine commands, and the skills that `think` uses.
 - [Configuration](docs/configuration.md): the `relevo.yml` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elalfner/relevo",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Relevo: an automatic issue-to-merge workflow where an agent builds and people verify.",
   "type": "module",
   "license": "MIT",

package/scripts/doctor.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Checks that the machine, the repository and GitHub are ready for Relevo. Read-only: it changes nothing.
-//   node scripts/doctor.mjs [--repo owner/name] [--json]
+//   node scripts/doctor.mjs [--repo owner/name] [--all] [--json]
+//   --all lists the checks that passed too; --json always lists every check
 // exit 0: no check failed (warnings allowed)   exit 1: at least one check failed
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { adapterFacts } from './lib/adapters/install.mjs';
-import { gatherFacts, readOnlyGh, renderReport, runChecks } from './lib/doctor.mjs';
+import { exitCode, gatherFacts, readOnlyGh, renderReport, reportHeader, runChecks } from './lib/doctor.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -53,5 +54,5 @@ const facts = gatherFacts({
   repo,
 });
 const results = runChecks(facts);
-console.log(process.argv.includes('--json') ? JSON.stringify(results, null, 2) : renderReport(results));
-process.exit(results.some((x) => x.status === 'fail') ? 1 : 0);
+console.log(process.argv.includes('--json') ? JSON.stringify(results, null, 2) : renderReport(results, { header: reportHeader(facts), all: process.argv.includes('--all') }));
+process.exit(exitCode(results));

package/scripts/init.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // Plans and applies the repository setup. Usage:
-//   node scripts/init.mjs plan  [--answers answers.json] [--repo owner/name] [--json]
-//   node scripts/init.mjs apply [--answers answers.json] [--repo owner/name] [--skip id,id] [--json]
+//   node scripts/init.mjs plan  [--answers answers.json] [--repo owner/name] [--from version] [--json]
+//   node scripts/init.mjs apply [--answers answers.json] [--repo owner/name] [--from version] [--skip id,id] [--json]
+//   --from names the published version a workflow that differs came from, when none is close enough to tell
 // `plan` changes nothing. `apply` carries out the planned changes except installs (the skill asks first).
 // answers.json: { "members": ["a","b"], "specWriter": "a", "reviewMode": "peer", "language": "en", "platforms": { "app": { "stack": "flutter", "path": ".", "targets": ["android"] } }, "stackProfiles": [] }
 // It never reads or writes the model API key.
@@ -11,8 +12,9 @@ import { execFileSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { gatherFacts, readOnlyGh, WORKFLOW_FILES } from './lib/doctor.mjs';
+import { gatherFacts, readOnlyGh, vueWebFacts, WORKFLOW_FILES } from './lib/doctor.mjs';
 import { applyPlan, planInit, renderPlan, skipItems } from './lib/init.mjs';
+import { planUpgrades, publishedTemplates, unifiedDiff } from './lib/workflow-upgrade.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -50,6 +52,8 @@ const facts = gatherFacts({
   repo,
 });
 
+facts.vueWeb = vueWebFacts(facts.config?.platforms ?? answers.platforms ?? {}, { tool, exists: existsSync });
+
 let admin = false;
 try {
   admin = JSON.parse(run('gh', ['api', `repos/${repo}`])).permissions?.admin === true;
@@ -70,9 +74,26 @@ const current = {
   stackProfiles: Object.fromEntries((answers.stackProfiles ?? []).map((s) => [s, existsSync(`.relevo/stacks/${s}.md`)])),
 };
 
+// A workflow that exists and differs may be updated by a merge with the published templates (asked for lazily: it uses npm).
+const published = publishedTemplates({ exec: (cmd, args) => run(cmd, args) });
+process.on('exit', () => published.cleanup());
+let versions;
+const source = { versions: () => (versions ??= published.versions()), read: published.read };
+const upgrades = (file) => {
+  try {
+    const state = planUpgrades({
+      files: [file], ours: current.workflows, templates: templates.workflows, agentBlocks: templates.agentBlocks,
+      labels: facts.config?.runner?.labels ?? answers.runnerLabels, build: answers.agentBuild ?? 'claude', from: arg('from') ?? null, source,
+    })[file];
+    return state.status === 'update' ? { ...state, diff: unifiedDiff(current.workflows[file], state.text) } : state;
+  } catch (err) {
+    return { status: 'error', message: String(err.message ?? err).split('\n')[0] };
+  }
+};
+
 let items;
 try {
-  items = planInit({ facts, answers, templates, current, admin });
+  items = planInit({ facts, answers, templates, current, admin, upgrades });
 } catch (err) {
   fail(err.message);
 }

package/scripts/lib/can-edit-issue.mjs

@@ -14,8 +14,11 @@ const REASON = {
   'qa-failed': 'a branch already exists and the text would no longer match what was built',
   'changes-requested': 'a branch already exists and the text would no longer match what was built',
   'needs-reviewer': 'it is built and waiting for a reviewer',
+  ship: 'its pull request is being merged',
+  // Not a state: it travels next to one, so the state decides whether the text may change.
+  urgent: 'the label asks for an early start and does not commit the issue to a build',
 };
-export const EDITABLE_LABELS = ['needs-spec'];
+export const EDITABLE_LABELS = ['needs-spec', 'urgent'];
 
 /**
  * @param {{state?: string, labels?: Array<string|{name: string}>}} issue  `gh issue view --json state,labels`

package/scripts/lib/cli.mjs

@@ -13,7 +13,7 @@ export const USAGE = [
   '            relevo init [--tools claude,antigravity] [--scope project|machine] [--yes] [--force]',
   '  install   add the marketplace and install the plugin; asks where in a terminal (project by default)',
   '  update    update the marketplace and the plugin (without --scope, the installation of this project), and render again the plugins that init made; --force overwrites files edited by hand',
-  '  doctor    check this repository (the same as /relevo:doctor)',
+  '  doctor    check this repository (the same as /relevo:doctor); --all lists the checks that passed too',
   '  version   print the version of this package',
   '',
   'user: every project of this machine. project: this repository, shared through .claude/settings.json. local: this repository, only you.'
@@ -26,14 +26,16 @@ export function parseArgs(argv) {
   if (!['install', 'update', 'doctor', 'version'].includes(command)) return { error: `unknown command "${command}"` };
   let scope = null;
   let force = false;
+  let all = false;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
     if (arg === '--force' && command === 'update') force = true;
+    else if (arg === '--all' && command === 'doctor') all = true;
     else if (arg === '--scope') { scope = rest[i + 1]; i += 1; } else if (arg.startsWith('--scope=')) scope = arg.slice(8);
     else return { error: `unknown option "${arg}"` };
   }
   if (scope !== null && !SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
-  return force ? { command, scope, force } : { command, scope };
+  return { command, scope, ...(force ? { force } : {}), ...(all ? { all } : {}) };
 }
 
 /** Whether the folder is inside a git work tree; `run` is the injected runner. A missing git counts as no. */
@@ -85,11 +87,11 @@ export function steps(command, scope) {
  * Runs a command. Returns { code, lines }: the lines to print and the exit code. Stops at the first failing step
  * and says which one, so the person knows what was already done.
  */
-export function execute({ command, scope }, { run, has, version, doctorScript, cwd = process.cwd() }) {
+export function execute({ command, scope, all = false }, { run, has, version, doctorScript, cwd = process.cwd() }) {
   const lines = [];
   if (command === 'version') return { code: 0, lines: [version] };
   if (command === 'doctor') {
-    const r = run(process.execPath, [doctorScript]);
+    const r = run(process.execPath, all ? [doctorScript, '--all'] : [doctorScript]);
     return { code: r.code, lines: [r.output.trimEnd()] };
   }
   if (!has('claude')) {

package/scripts/lib/config.mjs

@@ -20,6 +20,8 @@ export const SETTINGS = [
   { path: 'review.merger', type: 'enum', allowed: ['author', 'approver'], default: 'approver' },
   { path: 'review.autopilot', type: 'enum', allowed: ['off', 'precheck', 'verify'], default: 'off' },
   { path: 'review.allowed_origins', type: 'origin-list', default: [] },
+  // Whether the ship workflow may merge when no check ran on any commit; /relevo:ship asks the person instead.
+  { path: 'review.ship_without_ci', type: 'bool', default: false },
   { path: 'limits.built_unreviewed_per_person', type: 'int', min: 1, default: 2 },
   { path: 'limits.concurrent_agents', type: 'int', min: 1, default: 3 },
   { path: 'limits.review_sla_hours', type: 'int', min: 1, default: 8 },
@@ -29,6 +31,8 @@ export const SETTINGS = [
   { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true, default: null, requiredFor: 'claude', missing: 'unattended runs must always have a cost limit (amount in US dollars per run)', rejectedFor: 'antigravity', rejection: 'the agent has no cost limit; set limits.run_max_tokens instead, and note that the quota of the Google Cloud project that owns the key is the ceiling that really holds' },
   { path: 'limits.run_max_tokens', type: 'int', min: 1000, default: null, required: true, requiredFor: 'antigravity', missing: 'unattended runs must always have a limit, and for this agent it is a number of tokens per run', rejectedFor: 'claude', rejection: 'the run is limited by limits.run_max_cost' },
   { path: 'agent.build', type: 'enum', allowed: ['claude', 'antigravity'], default: 'claude' },
+  // The runner of every Relevo workflow: runs-on is read before any step, so init writes these labels into the files.
+  { path: 'runner.labels', type: 'label-list', default: ['ubuntu-latest'] },
   { path: 'qa.retries', type: 'int', min: 0, default: 1 },
   { path: 'qa.rules_from', type: 'path-list', default: [] },
   { path: 'skills.allow_scripts', type: 'string[]', default: [] },
@@ -79,6 +83,15 @@ function checkType(setting, value, errors) {
         errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
       }
       break;
+    case 'label-list':
+      if (!Array.isArray(value)) {
+        errors.push({ path, message: `${path} must be a list of runner labels, for example [self-hosted, linux-build] (got ${JSON.stringify(value)})` });
+      } else if (value.length === 0) {
+        errors.push({ path, message: `${path} needs at least one label; leave the setting out to use ubuntu-latest` });
+      } else if (value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
+      }
+      break;
     case 'path-list':
       if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
         errors.push({ path, message: `${path} must be a file name or a list of file names (got ${JSON.stringify(value)})` });
@@ -161,7 +174,12 @@ export function validateConfig(raw, { knownTargets = null, knownChecks = null }
     }
     const known = new Set(SETTINGS.filter((s) => s.path.startsWith(`${group}.`)).map((s) => s.path.split('.')[1]));
     Object.keys(value).forEach((k) => {
-      if (!known.has(k)) errors.push({ path: `${group}.${k}`, message: `unknown setting "${group}.${k}"` });
+      if (known.has(k)) return;
+      // Relevo cannot verify what a runner is, so it offers no such key: a runner is assumed to persist.
+      const message = `${group}.${k}` === 'runner.ephemeral'
+        ? 'unknown setting "runner.ephemeral": Relevo does not ask whether a runner is ephemeral, it assumes every runner persists between jobs'
+        : `unknown setting "${group}.${k}"`;
+      errors.push({ path: `${group}.${k}`, message });
     });
   });