@asrunjs/asrun 0.6.1 → 0.8.0

package/dist/scripts/cli.js

@@ -1,6 +1,11 @@
 // `pnpm asrun <command>`: a thin dispatcher so every subcommand keeps one entry point.
 // Anything that is not a subcommand is passed to the run command unchanged.
+import { announceUpdate } from '../lib/update-check.js';
 const [command, ...rest] = process.argv.slice(2);
+// The same courtesy the installed `asrun` command shows: one line on stderr when the registry has a newer release.
+// `upgrade` reads the registry itself, and `help` has no work to do.
+if (!['upgrade', 'help', '--help-init'].includes(command ?? '') && !process.argv.includes('--help'))
+    announceUpdate();
 async function main() {
     if (command === 'init') {
         const { main: init } = await import('./init.js');
@@ -12,17 +17,38 @@ async function main() {
         process.exitCode = await doctor(rest);
         return;
     }
+    if (command === 'reset') {
+        const { main: reset } = await import('./reset.js');
+        process.exitCode = await reset(rest);
+        return;
+    }
+    if (command === 'upgrade') {
+        const { main: upgrade } = await import('./upgrade.js');
+        process.exitCode = await upgrade(rest);
+        return;
+    }
+    if (command === 'migrate') {
+        const { main: migrate } = await import('./migrate.js');
+        process.exitCode = await migrate(rest);
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor] [options]
-
-  (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
-  init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
-                   --root <dir> targets another folder, --force <path> overwrites one file).
-  doctor           Check the workspace: profiles, tsconfig alias, generated files, skill overrides.`;
+const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate] [options]
+
+  (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
+  init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
+                   --root <dir> targets another folder, --force overwrites every file init writes,
+                   --force <path> overwrites one file).
+  doctor           Check the workspace: profiles, tsconfig alias, generated files, skill overrides, migrations.
+  reset            Remove node_modules and the files init writes, for a clean reinstall (keeps cases, specs,
+                   profiles.yaml, package.json and edited scaffold files; see "pnpm asrun reset --help").
+  upgrade          Install the newest asrun, refresh the workspace files and apply its migrations, after checking the
+                   target release for breaking changes (see "pnpm asrun upgrade --help").
+  migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
+                   --help"). "upgrade" runs it; use it after a manual install.`;
 await main();
-export {};

package/dist/scripts/doctor.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
 import { spawnTarget } from '../lib/command.js';
+import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
 import { GENERATED, frameworkPath, frameworkVersion, PACKAGE, renderTemplate } from './init.js';
+import { BUILD_APPROVALS, RUNTIME_EXTRAS, hasCapability, installedInWorkspace } from '../lib/runtime-deps.js';
 import { builtFile, COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 /**
  * Checks that a workspace is complete and consistent with the framework it points at. It never writes anything.
@@ -87,9 +90,11 @@ export async function main(args) {
         errors.push(`${PACKAGE} is not installed in this workspace: run "pnpm add -D ${PACKAGE}", then "pnpm asrun init". ` +
             'Every script that calls "asrun" fails until then.');
     }
-    // The manifest, written by init: it names where the workspace reaches the framework.
+    // The manifest, written by init: it names where the workspace reaches the framework, and since when the workspace
+    // has been migrated.
     const manifest = read(path.join(ROOT, '.asrun.json'));
     let recordedPath;
+    let marker = null;
     const installedVersion = frameworkVersion();
     if (manifest === null) {
         errors.push('No .asrun.json: this workspace was never initialized, or "init" stopped before it finished (for example the ' +
@@ -98,10 +103,12 @@ export async function main(args) {
     else {
         try {
             const parsed = JSON.parse(manifest);
+            marker = parsed;
             recordedPath = parsed.frameworkPath;
-            facts.push(`version:   asrun ${parsed.version ?? '?'} (${parsed.commit ?? '?'})`);
-            if (parsed.version !== undefined && parsed.version !== installedVersion.version) {
-                warnings.push(`asrun is installed at ${installedVersion.version}, but this workspace was set up with ${parsed.version}: run "pnpm asrun init --update".`);
+            facts.push(`version:   asrun ${typeof parsed.version === 'string' ? parsed.version : '?'} (${parsed.commit ?? '?'})`);
+            if (typeof parsed.version === 'string' && parsed.version !== installedVersion.version) {
+                warnings.push(`asrun is installed at ${installedVersion.version}, but this workspace was set up with ${parsed.version}: ` +
+                    'run "pnpm asrun upgrade" (or reinstall the version this workspace needs).');
             }
             if (recordedPath !== undefined && !fs.existsSync(path.resolve(ROOT, recordedPath))) {
                 errors.push(`.asrun.json points at "${recordedPath}", which does not exist. Run "pnpm add -D @asrunjs/asrun" and then "pnpm asrun init".`);
@@ -112,6 +119,27 @@ export async function main(args) {
         }
     }
     const framework = recordedPath ?? actualPath;
+    // Workspace migrations: `migrations.since` is the release the workspace matches, so newer ones are still to do. A
+    // workspace upgraded by hand (pnpm add + init --update) keeps the old baseline, which is what makes this check work.
+    if (marker !== null) {
+        try {
+            const state = migrationState(marker, installedVersion.version);
+            const outstanding = state.manual.length;
+            facts.push(`migrations: since ${state.since}${outstanding > 0 ? `, ${outstanding} manual step(s) outstanding` : ''}`);
+            const pending = pendingMigrations(MIGRATIONS, state.since, installedVersion.version);
+            if (pending.length > 0) {
+                warnings.push(`${pending.length} workspace migration(s) apply between ${state.since} and ${installedVersion.version} ` +
+                    `(${pending.map((migration) => migration.id).join(', ')}): run "pnpm asrun migrate".`);
+            }
+            if (outstanding > 0) {
+                warnings.push(`Manual migration steps are still open (${state.manual.join(', ')}): run "pnpm asrun migrate --list" to see ` +
+                    'them, then "pnpm asrun migrate --ack <id>" once they are done.');
+            }
+        }
+        catch (error) {
+            errors.push(`The migration registry is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     // The framework repository compiles itself into `dist/`, and `templates/playwright.config.ts` makes every workspace
     // load the config from there. A build older than the sources therefore keeps runs on the previous code.
     const stale = staleDistFiles();
@@ -231,13 +259,27 @@ export async function main(args) {
         // The framework is outside the workspace (examples/demo): the framework repository manages itself.
     }
     else if (workspaceFile === null) {
-        warnings.push('pnpm-workspace.yaml is missing: add the "allowBuilds" block from templates/pnpm-workspace.yaml, or pnpm skips the build scripts of esbuild and ffmpeg-static.');
+        warnings.push(`pnpm-workspace.yaml is missing: run "pnpm asrun init" (it writes the "allowBuilds" entries for ${BUILD_APPROVALS.join(', ')}), or pnpm skips those install scripts.`);
     }
-    else if (!workspaceFile.includes('allowBuilds')) {
-        warnings.push('pnpm-workspace.yaml has no "allowBuilds": pnpm skips the build scripts of esbuild and ffmpeg-static.');
+    else {
+        const missing = BUILD_APPROVALS.filter((pkg) => {
+            const entry = new RegExp(`^\\s+['"]?${pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]?\\s*:`, 'm');
+            return !entry.test(workspaceFile);
+        });
+        if (missing.length > 0) {
+            warnings.push(`pnpm-workspace.yaml has no "allowBuilds" entry for ${missing.join(', ')}: run "pnpm asrun init" (it adds ` +
+                'the entry before installing), or pnpm skips that install script.');
+        }
+        if (/^packages\s*:/m.test(workspaceFile)) {
+            warnings.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
+        }
     }
-    else if (/^packages\s*:/m.test(workspaceFile)) {
-        warnings.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
+    // Optional packages the workspace installs on demand, when this machine does not provide the capability itself.
+    for (const extra of RUNTIME_EXTRAS) {
+        if (hasCapability(extra) || installedInWorkspace(ROOT, extra.pkg) || installedInWorkspace(FRAMEWORK_ROOT, extra.pkg))
+            continue;
+        warnings.push(`${extra.pkg} is not installed and this machine does not provide it: ${extra.provides} is skipped. Run ` +
+            '"pnpm asrun init" (or "pnpm go") to install it, or install the tool yourself and run doctor again.');
     }
     let scripts = null;
     try {

package/dist/scripts/go.mjs

@@ -4,16 +4,25 @@
 //   pnpm add -D @asrunjs/asrun        (or github:wizcas/asrun#<tag>)
 //   pnpm exec asrun init
 //   pnpm go
+//
+// `--no-open` does not open a browser. `--no-ui` stops after step 3 (the workspace is prepared, no server starts).
+// `--dry-run` only prints what the command resolved (workspace, framework, the asrun command) and exits.
 import {spawn, spawnSync} from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
-const FRAMEWORK = path.resolve(import.meta.dirname, '..');
+// The package root: `scripts/go.mjs` in a development checkout, `dist/scripts/go.mjs` in an installed package, so the
+// same rule as lib/paths.ts. `bin/`, `examples/` and the framework's `.env` hang off this folder, never off `dist/`.
+const FRAMEWORK = path.basename(path.dirname(import.meta.dirname)) === 'dist'
+  ? path.resolve(import.meta.dirname, '..', '..')
+  : path.resolve(import.meta.dirname, '..');
 const PACKAGE = '@asrunjs/asrun';
 const MARKERS = ['.asrun.json', 'profiles.yaml'];
 const port = Number(process.env.ASRUN_UI_PORT ?? 4173);
 const url = `http://127.0.0.1:${port}`;
 const openBrowser = !process.argv.includes('--no-open');
+const noUi = process.argv.includes('--no-ui');
+const dryRun = process.argv.includes('--dry-run');
 const shell = process.platform === 'win32';
 
 // `.env` next to the command, or the framework's own `.env`; a real environment variable always wins.
@@ -33,8 +42,9 @@ function loadRootEnv(file) {
 loadRootEnv(path.join(process.cwd(), '.env'));
 if (process.env.ASRUN_ROOT === undefined) loadRootEnv(path.join(FRAMEWORK, '.env'));
 
-// The workspace: the project that owns profiles.yaml, cases/ and tests/. Inside the framework repository
-// (which has none of those) the demo workspace is used, so the framework itself can be developed this way.
+// The workspace: the project that owns profiles.yaml, cases/ and tests/. Inside the framework repository (which has
+// none of those) the demo workspace is used, so the framework itself can be developed this way. An installed package
+// that ships no `examples/` and runs outside a project has neither: it says so instead of preparing a missing folder.
 function findWorkspace(from) {
   for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
     if (MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)))) return dir;
@@ -42,11 +52,16 @@ function findWorkspace(from) {
   }
 }
 const demo = path.join(FRAMEWORK, 'examples', 'demo');
-const ROOT = (process.env.ASRUN_ROOT && path.resolve(process.env.ASRUN_ROOT)) || findWorkspace(process.cwd()) || demo;
-if (ROOT === FRAMEWORK && !fs.existsSync(demo)) {
+const chosen = process.env.ASRUN_ROOT ? path.resolve(process.env.ASRUN_ROOT) : findWorkspace(process.cwd());
+const ROOT = chosen ?? (fs.existsSync(demo) ? demo : null);
+if (ROOT === null) {
   console.error('No workspace found: run this command in the project that uses asrun, or set ASRUN_ROOT.');
   process.exit(1);
 }
+if (!fs.existsSync(ROOT)) {
+  console.error(`${ROOT} does not exist: check ASRUN_ROOT (or the .env that sets it).`);
+  process.exit(1);
+}
 
 const step = (n, text) => console.log(`\n\x1b[1;36m[${n}/4] ${text}\x1b[0m`);
 const warn = (text) => console.log(`\x1b[33m! ${text}\x1b[0m`);
@@ -72,7 +87,10 @@ function packageBin(name, command = name) {
 }
 
 /** The installed command of this workspace, or the framework's own bin while developing it here. */
-const bin = packageBin(PACKAGE) ?? path.join(FRAMEWORK, 'bin', 'asrun.mjs');
+const bin = packageBin(PACKAGE, 'asrun') ?? path.join(FRAMEWORK, 'bin', 'asrun.mjs');
+if (!fs.existsSync(bin)) {
+  fail(`The asrun command is missing: ${bin}\nReinstall the package: "pnpm add -D @asrunjs/asrun".`);
+}
 /** The workspace's copy of the package, if any. */
 const installed = fs.existsSync(path.join(ROOT, 'node_modules', PACKAGE, 'package.json'));
 const frameworkRelative = installed
@@ -82,13 +100,21 @@ const frameworkRelative = installed
       return relative === '' ? '.' : relative.startsWith('.') ? relative : `./${relative}`;
     })();
 
+if (dryRun) {
+  console.log(`workspace: ${ROOT}`);
+  console.log(`framework: ${FRAMEWORK}${installed ? ' (installed)' : ' (development checkout)'}`);
+  console.log(`command: ${bin}`);
+  process.exit(0);
+}
+
 /** pnpm only installs dependencies normally; its build scripts need an explicit approval in pnpm-workspace.yaml. */
 function ensurePnpmWorkspace() {
   if (frameworkRelative.startsWith('..')) return 'skipped';
   const file = path.join(ROOT, 'pnpm-workspace.yaml');
-  const block = 'allowBuilds:\n  esbuild: true\n  ffmpeg-static: true\n';
+  // `init` (step 3) adds the entry of each optional package it installs on demand, e.g. ffmpeg-static.
+  const block = 'allowBuilds:\n  esbuild: true\n';
   if (!fs.existsSync(file)) {
-    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx, ffmpeg-static) compile a binary on install.\n${block}`);
+    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx) compile a binary on install.\n${block}`);
     return 'created';
   }
   const text = fs.readFileSync(file, 'utf8');
@@ -115,7 +141,8 @@ function open(target) {
   spawn(command, args, {stdio: 'ignore', detached: true}).on('error', () => {}).unref();
 }
 
-// ffmpeg joins the videos of a test's browser tabs into one. Never fatal: the optional ffmpeg-static package is the fallback.
+// ffmpeg joins the videos of a test's browser tabs into one. Never fatal: `init` (step 3) installs the bundled
+// ffmpeg-static when this machine has no ffmpeg.
 function ensureFfmpeg() {
   // ffmpeg does not know `--version`, only `-version`.
   if (spawnSync('ffmpeg', ['-version'], {stdio: 'ignore', shell}).status === 0) return console.log('ffmpeg: ok');
@@ -126,11 +153,11 @@ function ensureFfmpeg() {
         ? ['winget', ['install', '--id', 'Gyan.FFmpeg', '-e', '--accept-source-agreements', '--accept-package-agreements']]
         : null;
   if (!installer) {
-    return warn('ffmpeg not found; the bundled ffmpeg-static is used instead. To install it yourself: brew install ffmpeg | winget install Gyan.FFmpeg | sudo apt install ffmpeg');
+    return warn('ffmpeg not found; the bundled ffmpeg-static is installed when the workspace is prepared, in step 3. To install ffmpeg yourself: brew install ffmpeg | winget install Gyan.FFmpeg | sudo apt install ffmpeg');
   }
   console.log(`ffmpeg not found, installing it: ${installer[0]} ${installer[1].join(' ')}`);
   if (run(...installer)) console.log('ffmpeg: installed');
-  else warn('Could not install ffmpeg; the bundled ffmpeg-static is used instead.');
+  else warn('Could not install ffmpeg; the bundled ffmpeg-static is installed when the workspace is prepared, in step 3.');
 }
 
 step(1, 'Checking this machine');
@@ -164,6 +191,11 @@ if (!run(process.execPath, [bin, 'init', '--root', ROOT], {cwd: process.cwd()}))
 }
 run(process.execPath, [bin, 'doctor']);
 
+if (noUi) {
+  console.log(`\n\x1b[1;32mWorkspace ready: ${ROOT}\x1b[0m  (not starting the web UI)`);
+  process.exit(0);
+}
+
 step(4, `Starting the web UI at ${url}`);
 if (await uiIsUp()) {
   console.log('The UI is already running.');

package/dist/scripts/heal-evidence.mjs

@@ -1,143 +1,149 @@
-// Reads the existing run reports (reports/<runId>/summary.json) for one case and prints what they already say,
-// so that healing starts from the evidence instead of from a new run. It never opens a browser and never writes.
-// Plain node (no tsx): it must work inside an agent's sandbox.
-import fs from 'node:fs';
-import path from 'node:path';
-
-// The workspace root: the project that uses the framework. Same rule as lib/paths.ts, in plain Node.
-const findWorkspace = (from) => {
-  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, 'profiles.yaml')) || fs.existsSync(path.join(dir, '.asrun.json'))) return dir;
-    if (path.dirname(dir) === dir) return null;
-  }
-};
-// `.env` next to the command, or the framework's own `.env`; a real environment variable always wins.
-const loadRootEnv = (file) => {
-  try {
-    for (const raw of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
-      if (process.env.ASRUN_ROOT !== undefined) return;
-      const match = /^(?:export\s+)?ASRUN_ROOT\s*=\s*(.*)$/.exec(raw.trim());
-      if (match) {
-        process.env.ASRUN_ROOT = path.resolve(path.dirname(file), match[1].trim().replace(/^(['"])(.*)\1$/, '$2'));
-      }
-    }
-  } catch {
-    // no .env: nothing to do
-  }
-};
-loadRootEnv(path.join(process.cwd(), '.env'));
-if (process.env.ASRUN_ROOT === undefined) loadRootEnv(path.join(path.resolve(import.meta.dirname, '..'), '.env'));
-const ROOT = process.env.ASRUN_ROOT
-  ? path.resolve(process.env.ASRUN_ROOT)
-  : (findWorkspace(process.cwd()) ?? path.resolve(import.meta.dirname, '..'));
-const REPORTS = path.join(ROOT, 'reports');
-const RUN_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(-[a-z0-9]+(-[a-z0-9]+)*)?$/;
-const NOT_LOGGED_IN = /is not logged in to/;
-
-const args = process.argv.slice(2);
-const option = (name) => {
-  const index = args.indexOf(name);
-  return index >= 0 ? args[index + 1] : undefined;
-};
-const caseId = option('--case');
-const env = option('--env');
-const profileFilter = (option('--profile') ?? '').split(',').filter(Boolean);
-const keep = Number(option('--max-reports') ?? 1);
-
-if (args.includes('--help') || !caseId || !env) {
-  console.log('Usage: pnpm heal:evidence --case <case-id> --env <env> [--profile a,b] [--max-reports 1]');
-  process.exit(args.includes('--help') ? 0 : 1);
-}
-
-const readSummary = (id) => {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(REPORTS, id, 'summary.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-};
-const mtime = (file) => (fs.existsSync(file) ? fs.statSync(file).mtimeMs : 0);
-const iso = (ms) => new Date(ms).toISOString().replace(/\.\d+Z$/, 'Z');
-const firstLines = (text, count) => text.split('\n').slice(0, count).join('\n');
-const indent = (text, prefix) => text.split('\n').map((line) => prefix + line).join('\n');
-
-const runIds = fs.existsSync(REPORTS)
-  ? fs.readdirSync(REPORTS).filter((name) => RUN_ID.test(name)).sort().reverse()
-  : [];
-
-const matches = [];
-for (const id of runIds) {
-  const summary = readSummary(id);
-  if (!summary) continue;
-  const runEnv = summary.env ?? /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-(.+)$/.exec(id)?.[1] ?? 'production';
-  if (runEnv !== env) continue;
-  const results = summary.results.filter(
-    (result) => result.caseId === caseId && (profileFilter.length === 0 || profileFilter.includes(result.profile))
-  );
-  if (results.length === 0) continue;
-  matches.push({id, summary, results});
-  if (matches.length >= keep) break;
-}
-
-console.log(`Heal evidence for case "${caseId}" in ${env}`);
-
-if (matches.length === 0) {
-  console.log(`\nNO REPORT: no run in ${env} has results for this case${profileFilter.length ? ` and these profiles (${profileFilter})` : ''}.`);
-  console.log('EVIDENCE: none  -> run the case once: pnpm asrun --env ' + env + ' --logged-in --grep ' + caseId);
-  process.exit(0);
-}
-
-const watched = [
-  ['spec', path.join(ROOT, 'tests', `${caseId}.spec.ts`)],
-  ['case', path.join(ROOT, 'cases', `${caseId}.md`)],
-  ['profiles.yaml', path.join(ROOT, 'profiles.yaml')],
-];
-
-let newest = null;
-for (const {id, summary, results} of matches) {
-  const endedAt = Date.parse(summary.startedAt) + summary.durationMs;
-  const changed = watched
-    .map(([label, file]) => ({label, at: mtime(file)}))
-    .filter((item) => item.at > endedAt);
-  newest ??= {changed};
-
-  console.log(`\n=== Report ${id} (${summary.startedAt}) ===`);
-  console.log(`report: reports/${id}/summary.json   html: reports/${id}/html`);
-  if (changed.length > 0) {
-    console.log(`STALE: changed after this run: ${changed.map((item) => `${item.label} (${iso(item.at)})`).join(', ')}`);
-  } else {
-    console.log('FRESH: the spec, the case and profiles.yaml have not changed since this run.');
-  }
-  if (summary.errors?.length) {
-    console.log('Run-level errors (not tied to a test):');
-    for (const error of summary.errors) console.log(indent(error.headline, '  - '));
-  }
-
-  for (const result of results) {
-    const loginProblem = result.errors.some((error) => NOT_LOGGED_IN.test(error.headline));
-    console.log(`\n[${result.profile}] ${result.status.toUpperCase()}  (${result.attempts} attempt${result.attempts === 1 ? '' : 's'}, ${result.durationMs} ms)`);
-    if (result.status === 'passed' || result.status === 'skipped') continue;
-    if (loginProblem) {
-      console.log('  Not a test failure: the profile was not logged in during this run. Not evidence about the spec.');
-      continue;
-    }
-    if (result.failedStep) console.log(`  failed step: ${result.failedStep}`);
-    for (const error of result.errors) {
-      console.log(indent(error.headline, '  error: '));
-      if (error.context) console.log(indent(firstLines(error.context, 8), '    '));
-      if (error.callLog) console.log(indent(firstLines(error.callLog, 12), '    log: '));
-      if (error.snippet) console.log(indent(firstLines(error.snippet, 8), '    code: '));
-    }
-    for (const file of result.screenshots) console.log(`  screenshot: reports/${id}/html/${file}`);
-    for (const file of result.videos) console.log(`  video: reports/${id}/html/${file}`);
-  }
-}
-
-const usable = matches[0].results.filter(
-  (result) =>
-    (result.status === 'failed' || result.status === 'flaky') &&
-    !result.errors.some((error) => NOT_LOGGED_IN.test(error.headline))
-);
-const state = newest.changed.length > 0 ? 'stale' : usable.length === 0 ? 'no-failure' : 'fresh';
-console.log(`\nEVIDENCE: ${state}`);
-if (usable.length > 0) console.log(`failing profiles in the newest report: ${usable.map((result) => result.profile).join(',')}`);
+// Reads the existing run reports (reports/<runId>/summary.json) for one case and prints what they already say,
+// so that healing starts from the evidence instead of from a new run. It never opens a browser and never writes.
+// Plain node (no tsx): it must work inside an agent's sandbox.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The package root: `scripts/heal-evidence.mjs` in a development checkout, `dist/scripts/heal-evidence.mjs` installed.
+// The same rule as lib/paths.ts: a compiled file sits one folder deeper.
+const FRAMEWORK = path.basename(path.dirname(import.meta.dirname)) === 'dist'
+  ? path.resolve(import.meta.dirname, '..', '..')
+  : path.resolve(import.meta.dirname, '..');
+
+// The workspace root: the project that uses the framework. Same rule as lib/paths.ts, in plain Node.
+const findWorkspace = (from) => {
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'profiles.yaml')) || fs.existsSync(path.join(dir, '.asrun.json'))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+};
+// `.env` next to the command, or the framework's own `.env`; a real environment variable always wins.
+const loadRootEnv = (file) => {
+  try {
+    for (const raw of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+      if (process.env.ASRUN_ROOT !== undefined) return;
+      const match = /^(?:export\s+)?ASRUN_ROOT\s*=\s*(.*)$/.exec(raw.trim());
+      if (match) {
+        process.env.ASRUN_ROOT = path.resolve(path.dirname(file), match[1].trim().replace(/^(['"])(.*)\1$/, '$2'));
+      }
+    }
+  } catch {
+    // no .env: nothing to do
+  }
+};
+loadRootEnv(path.join(process.cwd(), '.env'));
+if (process.env.ASRUN_ROOT === undefined) loadRootEnv(path.join(FRAMEWORK, '.env'));
+const ROOT = process.env.ASRUN_ROOT
+  ? path.resolve(process.env.ASRUN_ROOT)
+  : (findWorkspace(process.cwd()) ?? FRAMEWORK);
+const REPORTS = path.join(ROOT, 'reports');
+const RUN_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(-[a-z0-9]+(-[a-z0-9]+)*)?$/;
+const NOT_LOGGED_IN = /is not logged in to/;
+
+const args = process.argv.slice(2);
+const option = (name) => {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+};
+const caseId = option('--case');
+const env = option('--env');
+const profileFilter = (option('--profile') ?? '').split(',').filter(Boolean);
+const keep = Number(option('--max-reports') ?? 1);
+
+if (args.includes('--help') || !caseId || !env) {
+  console.log('Usage: pnpm heal:evidence --case <case-id> --env <env> [--profile a,b] [--max-reports 1]');
+  process.exit(args.includes('--help') ? 0 : 1);
+}
+
+const readSummary = (id) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(REPORTS, id, 'summary.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+const mtime = (file) => (fs.existsSync(file) ? fs.statSync(file).mtimeMs : 0);
+const iso = (ms) => new Date(ms).toISOString().replace(/\.\d+Z$/, 'Z');
+const firstLines = (text, count) => text.split('\n').slice(0, count).join('\n');
+const indent = (text, prefix) => text.split('\n').map((line) => prefix + line).join('\n');
+
+const runIds = fs.existsSync(REPORTS)
+  ? fs.readdirSync(REPORTS).filter((name) => RUN_ID.test(name)).sort().reverse()
+  : [];
+
+const matches = [];
+for (const id of runIds) {
+  const summary = readSummary(id);
+  if (!summary) continue;
+  const runEnv = summary.env ?? /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-(.+)$/.exec(id)?.[1] ?? 'production';
+  if (runEnv !== env) continue;
+  const results = summary.results.filter(
+    (result) => result.caseId === caseId && (profileFilter.length === 0 || profileFilter.includes(result.profile))
+  );
+  if (results.length === 0) continue;
+  matches.push({id, summary, results});
+  if (matches.length >= keep) break;
+}
+
+console.log(`Heal evidence for case "${caseId}" in ${env}`);
+
+if (matches.length === 0) {
+  console.log(`\nNO REPORT: no run in ${env} has results for this case${profileFilter.length ? ` and these profiles (${profileFilter})` : ''}.`);
+  console.log('EVIDENCE: none  -> run the case once: pnpm asrun --env ' + env + ' --logged-in --grep ' + caseId);
+  process.exit(0);
+}
+
+const watched = [
+  ['spec', path.join(ROOT, 'tests', `${caseId}.spec.ts`)],
+  ['case', path.join(ROOT, 'cases', `${caseId}.md`)],
+  ['profiles.yaml', path.join(ROOT, 'profiles.yaml')],
+];
+
+let newest = null;
+for (const {id, summary, results} of matches) {
+  const endedAt = Date.parse(summary.startedAt) + summary.durationMs;
+  const changed = watched
+    .map(([label, file]) => ({label, at: mtime(file)}))
+    .filter((item) => item.at > endedAt);
+  newest ??= {changed};
+
+  console.log(`\n=== Report ${id} (${summary.startedAt}) ===`);
+  console.log(`report: reports/${id}/summary.json   html: reports/${id}/html`);
+  if (changed.length > 0) {
+    console.log(`STALE: changed after this run: ${changed.map((item) => `${item.label} (${iso(item.at)})`).join(', ')}`);
+  } else {
+    console.log('FRESH: the spec, the case and profiles.yaml have not changed since this run.');
+  }
+  if (summary.errors?.length) {
+    console.log('Run-level errors (not tied to a test):');
+    for (const error of summary.errors) console.log(indent(error.headline, '  - '));
+  }
+
+  for (const result of results) {
+    const loginProblem = result.errors.some((error) => NOT_LOGGED_IN.test(error.headline));
+    console.log(`\n[${result.profile}] ${result.status.toUpperCase()}  (${result.attempts} attempt${result.attempts === 1 ? '' : 's'}, ${result.durationMs} ms)`);
+    if (result.status === 'passed' || result.status === 'skipped') continue;
+    if (loginProblem) {
+      console.log('  Not a test failure: the profile was not logged in during this run. Not evidence about the spec.');
+      continue;
+    }
+    if (result.failedStep) console.log(`  failed step: ${result.failedStep}`);
+    for (const error of result.errors) {
+      console.log(indent(error.headline, '  error: '));
+      if (error.context) console.log(indent(firstLines(error.context, 8), '    '));
+      if (error.callLog) console.log(indent(firstLines(error.callLog, 12), '    log: '));
+      if (error.snippet) console.log(indent(firstLines(error.snippet, 8), '    code: '));
+    }
+    for (const file of result.screenshots) console.log(`  screenshot: reports/${id}/html/${file}`);
+    for (const file of result.videos) console.log(`  video: reports/${id}/html/${file}`);
+  }
+}
+
+const usable = matches[0].results.filter(
+  (result) =>
+    (result.status === 'failed' || result.status === 'flaky') &&
+    !result.errors.some((error) => NOT_LOGGED_IN.test(error.headline))
+);
+const state = newest.changed.length > 0 ? 'stale' : usable.length === 0 ? 'no-failure' : 'fresh';
+console.log(`\nEVIDENCE: ${state}`);
+if (usable.length > 0) console.log(`failing profiles in the newest report: ${usable.map((result) => result.profile).join(',')}`);

package/dist/scripts/init.d.ts

@@ -1,9 +1,17 @@
+import { MARKER, PACKAGE } from '../lib/paths.js';
 /** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
 export declare const GENERATED: {
     file: string;
     template: string;
 }[];
-export declare const PACKAGE = "@asrunjs/asrun";
+/** Files `init` creates once; after that the project owns them and may edit them freely. */
+export declare const ONCE: {
+    file: string;
+    template: string;
+}[];
+export { MARKER };
+export { PACKAGE };
+export declare const DOTENV_HEADER = "# asrun: the workspace these commands run against (relative to this file).";
 /** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
 export declare function frameworkPath(root: string): string;
 /** True when this workspace has the package installed (or is the framework's own checkout). */