@elalfner/relevo 0.6.0 → 0.8.0

package/scripts/lib/web-review.mjs

@@ -1,10 +1,25 @@
 // 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.
+// "Credentials of a driven review are names, not values", "The audit understands a browser",
+// "A browser review takes captures through the runner" and "A failing page is reported as such" of openspec/specs/review/spec.md.
+
+import { createRequire } from 'node:module';
+import { isAbsolute, join, relative } from 'node:path';
+import { safeCaptureName } from './device.mjs';
 
 export const WEB_PACKAGE = 'web';
 
+/** Playwright as the project resolves it, else as the plugin does; null when neither has it. */
+export function loadPlaywright(cwd = process.cwd()) {
+  for (const base of [join(cwd, 'package.json'), import.meta.url]) {
+    try {
+      return createRequire(base)('playwright');
+    } catch { /* try the next place */ }
+  }
+  return null;
+}
+
 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:']);
@@ -41,6 +56,15 @@ const FORBIDDEN = [
   [/\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'],
+  [/\bscreenshot\s*\(|\[\s*['"`]screenshot['"`]\s*\]/, 'it takes a screenshot itself; take it with capture(name, check), which saves it in the output folder'],
+  [/\.\s*pdf\s*\(/, 'it saves a PDF of the page'],
+  [/\btracing\b/, 'it records a trace'],
+  [/\brecord(?:Video|Har)\b/, 'it records a video or a HAR'],
+  [/\brouteFromHAR\b/, 'it reads a HAR file'],
+  [/\.\s*saveAs\s*\(/, 'it saves a download'],
+  [/\.\s*storageState\s*\(/, 'it saves the storage state'],
+  [/\.\s*setInputFiles\s*\(/, 'it uploads a local file to the page'],
+  [/(?:^|[{,\s])['"]?path['"]?\s*:/m, 'it passes a file path to a browser call (a "path:" option)'],
 ];
 
 /**
@@ -63,6 +87,63 @@ export function scanReviewScript(text) {
   return problems;
 }
 
+/**
+ * The capture(name, check, { fullPage }) helper given to a review script. `check` asserts the state the shot shows and
+ * runs first: when it fails no screenshot is taken and the capture is recorded as failed, without throwing into the
+ * script. A good capture is saved as <out>/<name>.png. Nothing is returned, so the image never reaches the script.
+ * `captures` collects { name, ok, path | error }, the path relative to `cwd` when the file is under it; a repeated
+ * name replaces the earlier entry, as its file does.
+ */
+export function makeCapture({ page, out, captures, cwd = process.cwd() }) {
+  const keep = (entry) => {
+    const i = captures.findIndex((c) => c.name === entry.name);
+    if (i === -1) captures.push(entry);
+    else captures[i] = entry;
+  };
+  return async (name, check, options = {}) => {
+    const safe = safeCaptureName(name);
+    if (typeof check !== 'function') throw new Error(`capture("${safe}", check): check is the assertion of the state the shot shows, and it is required`);
+    const unknown = Object.keys(options ?? {}).filter((k) => k !== 'fullPage');
+    if (unknown.length > 0) throw new Error(`capture("${safe}"): the only option is fullPage (got ${unknown.join(', ')})`);
+    try {
+      await check();
+    } catch (error) {
+      keep({ name: safe, ok: false, error: String(error?.message ?? error).split('\n')[0] });
+      return undefined;
+    }
+    const file = join(out, `${safe}.png`);
+    await page.screenshot({ path: file, fullPage: options?.fullPage === true });
+    const near = relative(cwd, file);
+    keep({ name: safe, ok: true, path: near && !near.startsWith('..') && !isAbsolute(near) ? near : file });
+    return undefined;
+  };
+}
+
+/**
+ * The page's own failure during a run, to name before a script error: the first uncaught error of the page or the
+ * first response of 400 or more from the origin under review. `events` are those of formatBrowserLog. Returns a
+ * string or null.
+ */
+export function probableCause(events, baseUrl) {
+  let origin;
+  try {
+    origin = new URL(baseUrl).origin;
+  } catch {
+    return null;
+  }
+  const hit = events.find((e) => {
+    if (e.type === 'pageerror') return true;
+    if (e.type !== 'response') return false;
+    try {
+      return new URL(String(e.text).split(' ').pop()).origin === origin;
+    } catch {
+      return false;
+    }
+  });
+  if (!hit) return null;
+  return hit.type === 'pageerror' ? `uncaught ${hit.text}` : `response ${hit.text}`;
+}
+
 /** 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 ?? '');

package/scripts/review-adapter.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Prints how `review` works for a platform of relevo.yml, as JSON. Usage:
 //   node scripts/review-adapter.mjs --platform web [--target web] [--config relevo.yml]
-// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot }
+// Output: { supported, stack, target, kind, log, capture, driver, needs, reason, platform, needs_autopilot, advice }
+// `advice` is what to tell the person, in the language of relevo.yml, when a browser review cannot start with review.autopilot off.
 //   exit 0: supported   exit 1: no adapter for this platform and target (the reason is in the output)   exit 2: bad usage or invalid relevo.yml
 
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { loadConfig } from './lib/config.mjs';
-import { adapterFor, needsAutopilot, targetOf } from './lib/review-adapters.mjs';
+import { adapterFor, autopilotAdvice, needsAutopilot, targetOf } from './lib/review-adapters.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -28,5 +29,6 @@ if (!platform) fail(`there is no platform "${name}" in relevo.yml (platforms: ${
 
 const target = arg('target') ?? targetOf(platform);
 const adapter = adapterFor({ stack: platform.stack, target });
-console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter) }));
+const advice = autopilotAdvice(adapter, { autopilot: loaded.config.review?.autopilot, language: loaded.config.language });
+console.log(JSON.stringify({ ...adapter, platform: name, needs_autopilot: needsAutopilot(adapter), advice }));
 process.exit(adapter.supported ? 0 : 1);

package/scripts/review-brief.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Prints a short brief of an issue for the person who reviews it. Usage:
 //   node scripts/review-brief.mjs --issue 42 --title "Birthday list" --body-file issue.md [--built-file comment.md] [--language en|es]
+//        [--autopilot off|precheck|verify]
 // exit 0: printed   exit 2: bad arguments
 
 import { readFileSync } from 'node:fs';
@@ -14,7 +15,7 @@ const number = arg('issue');
 const title = arg('title');
 const bodyFile = arg('body-file');
 if (!number || title === undefined || !bodyFile) {
-  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es]');
+  console.error('usage: review-brief.mjs --issue <n> --title "<title>" --body-file <file> [--built-file <file>] [--language en|es] [--autopilot off|precheck|verify]');
   process.exit(2);
 }
 const read = (f) => {
@@ -26,4 +27,4 @@ const read = (f) => {
   }
 };
 const built = arg('built-file') ? read(arg('built-file')) : '';
-console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en' }));
+console.log(reviewBrief({ issue: { number, title, body: read(bodyFile) }, built, language: arg('language') ?? 'en', autopilot: arg('autopilot') ?? 'off' }));

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);

package/scripts/review-state.mjs

@@ -3,7 +3,8 @@
 //   review-state.mjs init <change-dir> [--autopilot off|precheck|verify]   build the checklist from the change's scenarios
 //   review-state.mjs set <id> <ok|fail|pending> [note ...]
 //   review-state.mjs sync <change-dir>            after a fix: keep confirmed lines, retest failed ones, add new scenarios
-//   review-state.mjs capture <path>               record a screenshot that was taken
+//   review-state.mjs capture <path>               record a screenshot that was taken (refused after "agree")
+//   review-state.mjs qa-pass <script>             QA passed this browser review script; the runner runs only this exact content
 //   review-state.mjs audit [<log-file>|-] [--package <id>] [--pid <n>]
 //                                                 audit the device log (stdin by default), write the report;
 //                                                 with --package only that app's lines are audited
@@ -24,7 +25,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } fr
 import { dirname, join } from 'node:path';
 import { checklistFromChange } from './lib/checklist.mjs';
 import { auditLog, auditReport, filterByApp } from './lib/logaudit.mjs';
-import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
+import { applyWaivers, autoItem, autoSection, confirmEnv, decidePr, newState, precheckItem, qaPass, recordCapture, setItem, syncState, waivedSection, waiveFinding } from './lib/review-state.mjs';
 
 const argv = process.argv.slice(2);
 const si = argv.indexOf('--state');
@@ -72,12 +73,18 @@ try {
     }
     case 'capture': {
       if (!rest[0]) fail('usage: review-state.mjs capture <path>');
-      const state = load();
-      state.captures.push(rest[0]);
+      const state = recordCapture(load(), rest[0]);
       save(state);
       console.log(`recorded ${rest[0]}`);
       break;
     }
+    case 'qa-pass': {
+      if (!rest[0] || !existsSync(rest[0])) fail('usage: review-state.mjs qa-pass <script>');
+      const state = qaPass(load(), rest[0], readFileSync(rest[0], 'utf8'));
+      save(state);
+      console.log(`QA passed ${rest[0]} (sha256 ${state.qaScript.sha256.slice(0, 12)}); any change to it needs a new pass`);
+      break;
+    }
     case 'drain': {
       const file = join(dirname(statePath), 'device.log');
       const text = readFileSync(0, 'utf8');
@@ -164,7 +171,7 @@ try {
       break;
     }
     default:
-      fail('usage: review-state.mjs <init|set|sync|capture|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
+      fail('usage: review-state.mjs <init|set|sync|capture|qa-pass|drain|audit|waive|waived|confirm-env|precheck|auto|auto-list|agree|show|decide> [...]');
   }
 } catch (err) {
   fail(err.message);

package/scripts/ship-check.mjs

@@ -11,6 +11,7 @@ import { resolve } from 'node:path';
 import { loadConfig } from './lib/config.mjs';
 import { realGh } from './lib/github.mjs';
 import { shipDecision } from './lib/ship.mjs';
+import { baselineChecks, loadPr } from './lib/ship-github.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -26,9 +27,9 @@ if (!existsSync(configPath)) fail(`relevo.yml not found at ${configPath}. Run /r
 const loaded = loadConfig(readFileSync(configPath, 'utf8'));
 if (!loaded.ok) fail(loaded.errors.map((e) => `error: ${e.message}`).join('\n'));
 
-const FIELDS = 'number,state,isDraft,mergeable,title,author,reviews,statusCheckRollup,headRefName,headRefOid,baseRefName';
 let pr;
 let invoker = arg('invoker');
+let carried;
 
 if (arg('input')) {
   pr = JSON.parse(readFileSync(arg('input'), 'utf8'));
@@ -36,10 +37,10 @@ if (arg('input')) {
   const repo = arg('repo') ?? process.env.GITHUB_REPOSITORY;
   const branch = arg('branch');
   if (!repo || !branch) fail('usage: ship-check.mjs --repo owner/name --branch <branch> [--invoker login] [--config relevo.yml]');
-  const found = JSON.parse(realGh(['pr', 'list', '--repo', repo, '--head', branch, '--state', 'all', '--json', 'number,state', '--limit', '5']));
-  const open = found.find((p) => p.state === 'OPEN') ?? found[0];
-  pr = open ? JSON.parse(realGh(['pr', 'view', String(open.number), '--repo', repo, '--json', FIELDS])) : null;
+  pr = loadPr(realGh, repo, branch);
   invoker ??= realGh(['api', 'user', '--jq', '.login']).trim();
+  // The archive commit may have no checks of its own; the approved head's count when only openspec/ changed since.
+  if (pr && arg('baseline')) carried = baselineChecks(realGh, repo, arg('baseline'), pr.headRefOid);
 }
 
 const decision = shipDecision({
@@ -49,6 +50,7 @@ const decision = shipDecision({
   baseline: arg('baseline'),
   labels: arg('labels') === undefined ? undefined : arg('labels').split(',').map((l) => l.trim()).filter(Boolean),
   issue: arg('issue'),
+  baselineChecks: carried,
 });
 console.log(JSON.stringify(decision, null, 2));
 process.exit(decision.allowed ? 0 : 1);

package/scripts/ship-unattended.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Ships an issue on GitHub, without a model, when a person applied the `relevo:ship` label. Usage (in the workflow):
+//   node scripts/ship-unattended.mjs --repo owner/name --issue 31 --actor login --actor-type User --work <checkout>
+// Environment: GH_TOKEN (the workflow token), GH_PUSH_TOKEN (the App token, or the workflow token), HAS_APP (true|false).
+// Prints the outcome as JSON.   exit 0: merged, stopped with a comment, or ignored   exit 2: bad arguments
+// Any other failure exits non-zero, and the workflow's last step reports it on the issue.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runUnattendedShip } from './lib/ship-unattended.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const [repo, issue, actor, actorType, work] = ['repo', 'issue', 'actor', 'actor-type', 'work'].map(arg);
+if (!repo || !/^\d+$/.test(issue ?? '') || !actor || !actorType || !work) {
+  console.error('usage: ship-unattended.mjs --repo owner/name --issue <n> --actor <login> --actor-type <User|Bot> --work <checkout>');
+  process.exit(2);
+}
+
+const ghWith = (token) => (args) => execFileSync('gh', args, {
+  encoding: 'utf8',
+  maxBuffer: 64 * 1024 * 1024,
+  env: { ...process.env, GH_TOKEN: token ?? process.env.GH_TOKEN },
+});
+const sh = (cmd, args, { cwd, input, env } = {}) => {
+  const r = spawnSync(cmd, args, { cwd, input, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ...env } });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? String(r.error ?? '') };
+};
+
+const outcome = await runUnattendedShip({
+  repo,
+  issue,
+  actor,
+  actorType,
+  hasApp: process.env.HAS_APP === 'true',
+  workDir: resolve(work),
+  pluginRoot: resolve(dirname(fileURLToPath(import.meta.url)), '..'),
+  sh,
+  gh: ghWith(process.env.GH_TOKEN),
+  pushGh: ghWith(process.env.GH_PUSH_TOKEN || process.env.GH_TOKEN),
+});
+console.log(JSON.stringify(outcome, null, 2));

package/scripts/toolchain-check.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Checks that the tools which the profile of a platform lists are on the path of this machine. Usage:
 //   node scripts/toolchain-check.mjs --platform <name> [--config relevo.yml] [--plugin-root <dir>]
-// It prints { platform, stack, tools, missing } as JSON. A tool is there when `<tool> --version` starts. The cloud build
+// It prints { platform, stack, tools, missing } as JSON; `missing` also covers git, gh, jq and node, which every job needs. A tool is there when `<tool> --version` starts. The cloud build
 // runs it before the agent, so that a runner without the SDK stops in seconds and not after a full run.
 //   exit 0: every tool is there (or the profile lists none)   exit 1: a tool is missing, or the profile cannot be resolved
 //   exit 2: bad usage or an invalid relevo.yml
@@ -12,7 +12,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadConfig } from './lib/config.mjs';
 import { resolveProfile } from './lib/stack-profile.mjs';
-import { missingTools } from './lib/toolchain-check.mjs';
+import { missingTools, RUNNER_TOOLS } from './lib/toolchain-check.mjs';
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -44,6 +44,6 @@ const resolved = resolveProfile({ platform, pluginRoot, read });
 if (!resolved.ok) fail(resolved.errors.join('\n'), 1);
 
 const probe = (tool) => spawnSync(tool, ['--version'], { stdio: 'ignore' }).error === undefined;
-const missing = missingTools(resolved.profile.tools, probe);
+const missing = missingTools([...RUNNER_TOOLS, ...(resolved.profile.tools ?? [])], probe);
 console.log(JSON.stringify({ platform: name, stack: resolved.profile.stack, tools: resolved.profile.tools, missing }));
 process.exit(missing.length > 0 ? 1 : 0);

package/scripts/web-hook.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Adds the SessionStart hook that installs OpenSpec in web sessions to .claude/settings.json. Usage:
+//   node scripts/web-hook.mjs [--settings .claude/settings.json]
+// Run by /relevo:init only after the person agreed to the hook. Every other key and hook of the file is kept, and a
+// file that is not a JSON object is left as it is.
+// exit 0: written, or already there   exit 2: the file could not be merged
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mergeWebHook } from './lib/init.mjs';
+
+const i = process.argv.indexOf('--settings');
+const path = i === -1 ? '.claude/settings.json' : process.argv[i + 1];
+
+try {
+  const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const after = mergeWebHook(before);
+  if (after === before) {
+    console.log(`${path} already installs OpenSpec at the start of a web session; nothing changed`);
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, after);
+    console.log(`${path} now installs OpenSpec at the start of a web session; the file is left for you to commit`);
+  }
+} catch (err) {
+  console.error(`could not add the hook to ${path}: ${err.message}`);
+  process.exit(2);
+}

package/scripts/web-preflight.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Checks that a browser review can drive: the project's dependencies, Playwright and its Chromium, and the address
+// under review with the module scripts its page loads. Usage:
+//   node scripts/web-preflight.mjs --url http://localhost:5173 [--timeout 5000] [--wait 30000]
+// With --wait it is also the readiness probe of a server the agent started: the address is retried until it answers.
+// Prints { ok, check, detail, start, env, install } as JSON: `start` is the command that starts the app, `env` the
+// variable names of .env.example (the real environment files are never read), `install` the frozen install command of
+// the lock file (null without one).
+//   exit 0: ready   exit 3: no node_modules   exit 7: node_modules does not match package-lock.json
+//   exit 4: Playwright does not resolve from the project   exit 5: the Chromium of Playwright is missing
+//   exit 6: the address or one of its modules does not answer below 400   exit 2: bad arguments
+
+import { existsSync, readFileSync } from 'node:fs';
+import { loadPlaywright } from './lib/web-review.mjs';
+import { webPreflight } from './lib/web-preflight.mjs';
+
+const arg = (name) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : process.argv[i + 1];
+};
+const number = (name, fallback) => {
+  const v = arg(name);
+  if (v === undefined) return fallback;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) {
+    console.error(`--${name} must be a number of milliseconds`);
+    process.exit(2);
+  }
+  return n;
+};
+
+const url = arg('url');
+try {
+  if (!url || !/^https?:$/.test(new URL(url).protocol)) throw new Error();
+} catch {
+  console.error('usage: web-preflight.mjs --url <http address> [--timeout 5000] [--wait 30000]');
+  process.exit(2);
+}
+const cwd = process.cwd();
+const result = await webPreflight({ cwd, url, timeout: number('timeout', 5000), wait: number('wait', 0) }, {
+  exists: existsSync,
+  readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+  loadPlaywright: () => loadPlaywright(cwd),
+  fetch: globalThis.fetch,
+});
+const { code, ...shown } = result;
+console.log(JSON.stringify(shown));
+process.exit(code);

package/scripts/web-review.mjs

@@ -1,23 +1,34 @@
 #!/usr/bin/env node
 // Runs a review script in a browser of its own and reports what it checked. Usage:
 //   node scripts/web-review.mjs --script evidence/review-web.mjs --url http://localhost:5173 \
-//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence] [--headed]
+//        [--allow-origins https://staging.example.com] [--secret-env TEST_USER,TEST_PASS] [--out evidence]
+//        [--state evidence/review-state.json] [--headed]
 // The script is the agent's, written from the scenarios and reviewed by QA. Its default export receives
-// { page, context, baseUrl, line, credentials }: line(n, how, fn) runs fn and records the checklist line n as
+// { page, context, baseUrl, line, credentials, capture }: line(n, how, fn) runs fn and records the checklist line n as
 // auto-ok or auto-fail; credentials(name) gives a test credential taken from the environment variable `name`,
-// which must be in --secret-env. The browser has a clean profile and can reach only localhost, the page under
-// review and the allowed origins; every secret value is redacted from what is written.
-// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json.
-//   exit 0: the script ran (lines can still have failed)   exit 1: the script was refused, Playwright is missing,
-//   the browser could not start, or the script failed outside a line   exit 2: bad arguments
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+// which must be in --secret-env; capture(name, check, { fullPage }) runs the assertion `check` and, when it holds,
+// saves <out>/<name>.png and records it in the review state (nothing of the image is given back or printed).
+// Before anything runs, the review state must say the autopilot is on, the data was confirmed, the review is not
+// agreed yet, and QA passed this exact script (review-state.mjs qa-pass). The browser has a clean profile and can
+// reach only localhost, the page under review and the allowed origins; every secret value is redacted from what is
+// written, and the script's own console goes to <out>/script-console.txt, never to this output.
+// Writes <out>/web-log.txt (the log the audit reads, with --package web) and <out>/web-result.json. Each run against
+// another server uses an --out of its own; only the log of the normal run is audited.
+//   exit 0: the script ran (lines and captures can still have failed)   exit 1: the review state refused the run,
+//   the script was refused, Playwright is missing, the browser could not start, or the script failed outside a line
+//   exit 2: bad arguments
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { formatBrowserLog, isAllowedOrigin, redact, scanReviewScript } from './lib/web-review.mjs';
+import { format } from 'node:util';
+import { assertDriving, recordCapture, scriptHash } from './lib/review-state.mjs';
+import { formatBrowserLog, isAllowedOrigin, loadPlaywright, makeCapture, probableCause, redact, scanReviewScript } from './lib/web-review.mjs';
 
 const RUN_LIMIT_MS = 120000;
+// The runner's own output. The script's console is taken over while it runs, so these are kept apart.
+const say = console.log.bind(console);
+const tell = console.error.bind(console);
 
 const arg = (name) => {
   const i = process.argv.indexOf(`--${name}`);
@@ -25,13 +36,13 @@ const arg = (name) => {
 };
 const list = (name) => (arg(name) ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 const stop = (code, message) => {
-  console.error(message);
+  tell(message);
   process.exit(code);
 };
 
 const scriptPath = arg('script');
 const baseUrl = arg('url');
-if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--headed]');
+if (!scriptPath || !baseUrl || !existsSync(scriptPath)) stop(2, 'usage: web-review.mjs --script <file> --url <url> [--allow-origins a,b] [--secret-env A,B] [--out evidence] [--state evidence/review-state.json] [--headed]');
 let origin;
 try {
   origin = new URL(baseUrl);
@@ -41,26 +52,38 @@ try {
 const allowed = list('allow-origins');
 const secretNames = list('secret-env');
 const out = resolve(arg('out') ?? 'evidence');
+const statePath = resolve(arg('state') ?? 'evidence/review-state.json');
+
+const readState = () => JSON.parse(readFileSync(statePath, 'utf8'));
+if (!existsSync(statePath)) stop(1, `no review in progress (${statePath} not found): the runner drives only a review started with review-state.mjs init`);
+try {
+  assertDriving(readState(), { open: true });
+} catch (error) {
+  stop(1, `the review state refused the run before any browser started: ${error.message}`);
+}
 
-const problems = scanReviewScript(readFileSync(scriptPath, 'utf8'));
+const source = readFileSync(scriptPath, 'utf8');
+const problems = scanReviewScript(source);
 if (problems.length > 0) stop(1, `the review script was refused before any browser started:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+if (readState().qaScript?.sha256 !== scriptHash(source)) {
+  stop(1, `the review script is not the one QA passed: launch relevo:qa on it, and after QA PASSED run review-state.mjs qa-pass ${scriptPath}`);
+}
 
 const secrets = Object.fromEntries(secretNames.filter((n) => process.env[n]).map((n) => [n, process.env[n]]));
 const hide = (text) => redact(text, secrets);
 
-function loadPlaywright() {
-  for (const base of [join(process.cwd(), 'package.json'), import.meta.url]) {
-    try {
-      return createRequire(base)('playwright');
-    } catch { /* try the next place */ }
-  }
-  return null;
-}
 const playwright = loadPlaywright();
-if (!playwright) stop(1, 'Playwright cannot be resolved from this project: install it with "npm install -D playwright" and "npx playwright install chromium"');
+if (!playwright) stop(1, 'Playwright cannot be resolved from this project: it belongs in its development dependencies; run /relevo:init, or "npm install -D playwright" and "npx playwright install chromium" in the folder of the platform, and commit the change on the base branch');
+
+if (arg('out') === undefined && existsSync(join(out, 'web-log.txt'))) {
+  tell(`warning: ${join(out, 'web-log.txt')} is replaced; a run against another server uses an --out of its own (evidence/run-<port>)`);
+}
+mkdirSync(out, { recursive: true });
 
 const events = [];
 const results = [];
+const captures = [];
+const scriptConsole = [];
 let scriptError = null;
 let pagesLoaded = 0;
 let browser;
@@ -80,6 +103,13 @@ const credentials = (name) => {
   return secrets[name];
 };
 
+// From here on the script's console goes to a file, also after a timeout: the runner prints with say and tell.
+function takeOverConsole() {
+  ['log', 'info', 'warn', 'error', 'debug', 'trace', 'dir', 'table'].forEach((level) => {
+    console[level] = (...args) => { scriptConsole.push(`${level} ${format(...args)}`); };
+  });
+}
+
 async function run() {
   try {
     browser = await playwright.chromium.launch({ headless: !process.argv.includes('--headed') });
@@ -105,11 +135,14 @@ async function run() {
     if (r.request().isNavigationRequest() && r.request().frame() === page.mainFrame() && r.status() < 400) pagesLoaded += 1;
   });
   page.on('response', (r) => { if (r.status() >= 400) events.push({ type: 'response', text: `${r.status()} ${r.request().method()} ${r.url()}` }); });
+  // The real path, so a capture is recorded relative to the working directory even through a symbolic link.
+  const capture = makeCapture({ page, out: realpathSync(out), captures });
 
   try {
+    takeOverConsole();
     const mod = await import(pathToFileURL(resolve(scriptPath)).href);
     if (typeof mod.default !== 'function') throw new Error('the script must export a default async function');
-    await mod.default({ page, context, baseUrl, line, credentials });
+    await mod.default({ page, context, baseUrl, line, credentials, capture });
   } catch (error) {
     scriptError = String(error?.message ?? error).split('\n')[0];
   }
@@ -124,11 +157,29 @@ clearTimeout(timer);
 clearTimeout(backstop);
 if (browser) await browser.close().catch(() => {});
 
-mkdirSync(out, { recursive: true });
 // A browser that never loaded a page proves nothing: the log is left empty so the audit is inconclusive.
 writeFileSync(join(out, 'web-log.txt'), pagesLoaded === 0 ? '' : hide(formatBrowserLog(events, { origin: origin.host })));
-writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
-results.sort((a, b) => a.n - b.n).forEach((r) => console.log(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
-console.log(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
-if (scriptError) stop(1, hide(`the script failed outside a line: ${scriptError}`));
+writeFileSync(join(out, 'web-result.json'), hide(`${JSON.stringify({ url: baseUrl, lines: results, captures, blocked: events.filter((e) => e.type === 'blocked').length, pagesLoaded, scriptError }, null, 2)}\n`));
+writeFileSync(join(out, 'script-console.txt'), hide(scriptConsole.map((l) => `${l}\n`).join('')));
+
+// The state is read again, so a line set while the browser ran is not lost.
+const saved = captures.filter((c) => c.ok);
+if (saved.length > 0) {
+  try {
+    const state = readState();
+    saved.forEach((c) => recordCapture(state, c.path));
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  } catch (error) {
+    tell(`the captures could not be recorded in ${statePath}: ${error.message}`);
+  }
+}
+
+results.sort((a, b) => a.n - b.n).forEach((r) => say(hide(`line ${r.n}: ${r.status} - ${r.how}${r.error ? ` (${r.error})` : ''}`)));
+captures.forEach((c) => say(hide(c.ok ? `captured ${c.path}` : `capture ${c.name}: failed (${c.error})`)));
+say(`${events.length} event(s) written to ${join(out, 'web-log.txt')}; audit it with: review-state.mjs audit --package web`);
+if (scriptError) {
+  const cause = probableCause(events, baseUrl);
+  if (cause) tell(hide(`the page itself failed: ${cause}`));
+  stop(1, hide(`the script failed outside a line: ${scriptError}`));
+}
 process.exit(0);

package/skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor
-description: Checks that this machine, the repository and GitHub are ready for Relevo and reports every check as pass, fail or warning, with the fix next to each failure. It covers the required tools (OpenSpec, git, the GitHub CLI, the toolchain and the targets of each platform's stack profile), the skills that /relevo:think invokes, the extra skills of each role, relevo.yml, labels and branches, branch protection and approvals, the automation secret and workflows, and a CI check. Read-only: it never changes anything. Use when asked to check, diagnose or verify the Relevo setup.
+description: Checks that this machine, the repository and GitHub are ready for Relevo and reports every check as pass, fail or warning, with the fix next to each failure. It covers the required tools (OpenSpec, git, the GitHub CLI, the toolchain and the targets of each platform's stack profile), the skills that /relevo:think invokes, the extra skills of each role, relevo.yml, labels and branches, branch protection and approvals, the automation secret and workflows, what the ship workflow needs, in a web session whether the repository installs OpenSpec at its start, and a CI check. Read-only: it never changes anything. Use when asked to check, diagnose or verify the Relevo setup.
 argument-hint: ""
 ---
 
@@ -21,7 +21,8 @@ Scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `node`. They hol
 1. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs` from the repository root. It finds the repository itself; pass `--repo owner/name` only when it cannot.
 2. Show its output as it is: each check is `pass`, `FAIL` or `warn`, and each failure and warning has its fix on the next line.
 3. If there are failures, say which command fixes most of them: `/relevo:init` for labels, branches, protection, workflows and the ignore line; the install commands shown for tools and skills; adding the model credential to the repository secrets by hand.
-4. If the output says branch protection is not available, say plainly that approving and merging are then enforced only by the written confirmation `ship` asks for, not by the platform.
+4. If a `ship.app` check fails, say that the `relevo:ship` label cannot ship in this repository until a GitHub App and its two secrets exist, because the base branch requires checks, and that `/relevo:ship` still works meanwhile.
+5. If the output says branch protection is not available, say plainly that approving and merging are then enforced only by the written confirmation `ship` asks for, not by the platform.
 
 ## Exit status