@asrunjs/asrun 0.6.0 → 0.7.0

package/.claude/skills/making-cases/references/splitting.md

@@ -1,28 +1,28 @@
-# Splitting notes into cases
-
-## Principle
-One case = one real user path. Split only when something real differs:
-1. **Starting state** differs (a landing page you simply open, versus a flow that needs data it creates itself).
-2. **Write level** differs (read-only versus `writes: [<env>, ...]`). Keep read-only checks out of write cases: they can
-   run anywhere, without confirmation, in the smoke suite.
-3. **Independence** differs (the checks can pass or fail without the other part, and a failure in one should not hide
-   the other).
-
-Do not split because a case is long, or because the notes list things under separate headings.
-
-## Typical result
-- A read-only landing or overview check (what is on the page): small, fast, `suites: [smoke, regression]`, no `writes` (read-only).
-- A user flow that creates data and cleans it up: `writes: [staging]`, one case, steps in the real order (even if the
-  flow is not linear), ending with the deletion.
-- A logo or visual check of data that already exists, kept read-only: its own case when it does not need the flow.
-
-## Existing cases
-Look at `cases/` before writing. If a new case overlaps an existing one, do not overwrite it: propose keep, merge or
-replace, with the reason, and wait for the user. Never rename or move an existing case yourself; the Cases page of the web UI does that and keeps the spec in step.
-
-## Naming and folders
-Cases of one area live in a folder: `cases/documents/landing-page.md` has the id `documents/landing-page`. The name is
-`<what>` in kebab-case (`hub-landing`, `draft-to-publish`), the folder is the area (`documents`). One folder level only.
-Look at the folders that already exist in `cases/` and reuse them. A case that fits no area stays directly in
-`cases/`. The `title` says what the case proves. Two ids that differ only in `-` versus `/` (`documents-x` and
-`documents/x`) are not allowed: one group level only, so ids stay unambiguous.
+# Splitting notes into cases
+
+## Principle
+One case = one real user path. Split only when something real differs:
+1. **Starting state** differs (a landing page you simply open, versus a flow that needs data it creates itself).
+2. **Write level** differs (read-only versus `writes: [<env>, ...]`). Keep read-only checks out of write cases: they can
+   run anywhere, without confirmation, in the smoke suite.
+3. **Independence** differs (the checks can pass or fail without the other part, and a failure in one should not hide
+   the other).
+
+Do not split because a case is long, or because the notes list things under separate headings.
+
+## Typical result
+- A read-only landing or overview check (what is on the page): small, fast, `suites: [smoke, regression]`, no `writes` (read-only).
+- A user flow that creates data and cleans it up: `writes: [staging]`, one case, steps in the real order (even if the
+  flow is not linear), ending with the deletion.
+- A logo or visual check of data that already exists, kept read-only: its own case when it does not need the flow.
+
+## Existing cases
+Look at `cases/` before writing. If a new case overlaps an existing one, do not overwrite it: propose keep, merge or
+replace, with the reason, and wait for the user. Never rename or move an existing case yourself; the Cases page of the web UI does that and keeps the spec in step.
+
+## Naming and folders
+Cases of one area live in a folder: `cases/documents/landing-page.md` has the id `documents/landing-page`. The name is
+`<what>` in kebab-case (`hub-landing`, `draft-to-publish`), the folder is the area (`documents`). One folder level only.
+Look at the folders that already exist in `cases/` and reuse them. A case that fits no area stays directly in
+`cases/`. The `title` says what the case proves. Two ids that differ only in `-` versus `/` (`documents-x` and
+`documents/x`) are not allowed: one group level only, so ids stay unambiguous.

package/AGENTS.md

@@ -151,6 +151,9 @@ Three steps, each learns one thing: the intent, the facts and inputs, the implem
    writes data and never creates baselines. A tagged step with no `- Recipe:` line (an old `## Inputs` line counts
    until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs is a separate step
    (`pnpm asrun`, or the Run page).
+Workspace maintenance is separate from the AI steps: `pnpm asrun init [--update] [--force]` writes or refreshes the
+workspace files, and `pnpm asrun reset` removes `node_modules` and the files init wrote (edited files, cases, specs,
+`profiles.yaml` and `package.json` stay), so `pnpm dlx @asrunjs/asrun init --install` can scaffold again.
 Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec pass.
 Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
 case's own steps (see the skill's `references/conventions.md`).

package/README.md

@@ -56,7 +56,19 @@ pnpm asrun doctor
 ```
 
 `init --update` refreshes only the generated files; it never overwrites `AGENTS.md`, `CLAUDE.md` or your skill
-overrides. `doctor` checks profiles, generated files, the installed version and the project rules.
+overrides. `doctor` checks profiles, generated files, the installed version and the project rules. `init --force`
+rewrites every file init writes (rules still need `--reset-rules`; `profiles.yaml` and `package.json` stay yours).
+
+To start over with fresh dependencies and a fresh scaffold:
+
+```bash
+pnpm asrun reset          # or: pnpm asrun reset --yes --state
+pnpm dlx @asrunjs/asrun init --install
+pnpm go
+```
+
+`reset` removes `node_modules` and the files init wrote; cases, specs, `profiles.yaml`, `package.json` and files you
+edited are kept.
 
 <details>
 <summary>Manual install or a pinned version</summary>
@@ -68,7 +80,8 @@ pnpm go
 ```
 
 On pnpm 12, run `init` before adding the dependency: it writes the `allowBuilds` entry that `esbuild` and
-`ffmpeg-static` need, or `pnpm add` stops with `ERR_PNPM_IGNORED_BUILDS`. Details and flags:
+`ffmpeg-static` need, or `pnpm add` stops with `ERR_PNPM_IGNORED_BUILDS`. The same file exempts `@asrunjs/asrun` from
+pnpm's 24-hour release age, so a fresh release installs right away. Details and flags:
 [install.md](./docs/install.md).
 
 </details>
@@ -135,6 +148,7 @@ Details: [ai-workflow.md](./docs/ai-workflow.md#customizing-the-prompts).
 | I want to... | Command |
 |---|---|
 | Check the workspace | `pnpm asrun doctor` |
+| Start over with fresh dependencies and scaffold | `pnpm asrun reset [--yes] [--state] [--lockfile]` |
 | See which profiles are logged in | `pnpm status [--env <env>]` |
 | Log in a profile (a person, with 2FA) | `pnpm signin <profile-id>` |
 | Run everything in one environment | `pnpm asrun --env staging` |

package/bin/asrun.mjs

@@ -13,6 +13,7 @@ const args = process.argv.slice(2);
 const SCRIPTS = {
   init: 'cli.js',
   doctor: 'cli.js',
+  reset: 'cli.js',
   go: 'go.mjs',
   ui: 'ui.js',
   'ui:dev': 'ui-dev.js',
@@ -39,7 +40,7 @@ if (!fs.existsSync(script)) {
   process.exit(1);
 }
 
-// `init` and `doctor` are subcommands of cli.js; it reads them from its own arguments.
+// `init`, `doctor` and `reset` are subcommands of cli.js; it reads them from its own arguments.
 const cliArgs = scriptName === 'cli.js' && subcommand ? [subcommand, ...args] : args;
 const child = spawn(process.execPath, [script, ...cliArgs], {cwd: process.cwd(), stdio: 'inherit'});
 child.on('error', (error) => {

package/dist/scripts/cli.js

@@ -12,17 +12,25 @@ 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 === '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] [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.
+  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").`;
 await main();
 export {};

package/dist/scripts/doctor.js

@@ -3,7 +3,7 @@ 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 { GENERATED, frameworkPath, frameworkVersion, renderTemplate } from './init.js';
+import { GENERATED, frameworkPath, frameworkVersion, PACKAGE, renderTemplate } from './init.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.
@@ -83,12 +83,17 @@ export async function main(args) {
     facts.push(`workspace: ${ROOT}`);
     const actualPath = frameworkPath(ROOT);
     facts.push(`framework: ${path.resolve(ROOT, actualPath)}`);
+    if (!fs.existsSync(path.join(path.resolve(ROOT, actualPath), 'package.json'))) {
+        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.
     const manifest = read(path.join(ROOT, '.asrun.json'));
     let recordedPath;
     const installedVersion = frameworkVersion();
     if (manifest === null) {
-        warnings.push('No .asrun.json: run "pnpm asrun init" in this folder.');
+        errors.push('No .asrun.json: this workspace was never initialized, or "init" stopped before it finished (for example the ' +
+            'pnpm add step failed). Run "pnpm asrun init" here.');
     }
     else {
         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,6 +100,13 @@ 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';
@@ -164,6 +189,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

@@ -3,11 +3,19 @@ export declare const GENERATED: {
     file: string;
     template: string;
 }[];
+/** Files `init` creates once; after that the project owns them and may edit them freely. */
+export declare const ONCE: {
+    file: string;
+    template: string;
+}[];
+export declare const MARKER = ".asrun.json";
+export declare const DOTENV_HEADER = "# asrun: the workspace these commands run against (relative to this file).";
+export declare const PACKAGE = "@asrunjs/asrun";
 /** 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). */
 export declare function isInstalled(root: string): boolean;
-/** Fills the `{{framework}}` and `{{playwright}}` placeholders of a template. */
+/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
 export declare function renderTemplate(name: string, root: string): string;
 /**
  * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives