@asrunjs/asrun 0.0.0-stage → 0.5.2

package/dist/scripts/heal-evidence.mjs

@@ -0,0 +1,143 @@
+// 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(',')}`);

package/dist/scripts/init.d.ts

@@ -0,0 +1,22 @@
+/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
+export declare const GENERATED: {
+    file: string;
+    template: string;
+}[];
+/** 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. */
+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
+ * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
+ * Kept relative: the file is committed and must not name a machine.
+ */
+export declare function playwrightBin(root: string): string;
+export declare function frameworkVersion(): {
+    version: string;
+    commit: string;
+};
+export declare function main(args: string[]): Promise<number>;

package/dist/scripts/init.js

@@ -0,0 +1,332 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { FRAMEWORK_ROOT, TEMPLATES_DIR } from '../lib/paths.js';
+/**
+ * Creates the files a workspace needs. It is safe to run many times: it never overwrites a file the project owns, and
+ * `--update` refreshes only the files generated from the framework templates.
+ */
+const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force <path>] [--no-env] [--install [spec]]
+
+  --root <dir>    the workspace to initialize (default: the current folder)
+  --update        refresh the generated files (playwright.config.ts, tests/seed.spec.ts, .claude/commands/*,
+                  .opencode/commands/*)
+  --force <path>  overwrite one file this tool writes, e.g. --force playwright.config.ts (may be repeated)
+  --reset-rules   allow --force on AGENTS.md, CLAUDE.md or .claude/skills/** (project-owned rules)
+  --no-env        do not write .env (ASRUN_ROOT)
+  --install [spec]  also add the dependency (default "asrun"; e.g. --install github:wizcas/asrun#v0.1.0)`;
+/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
+export const GENERATED = [
+    { file: 'playwright.config.ts', template: 'playwright.config.ts' },
+    { file: 'tests/seed.spec.ts', template: 'seed.spec.ts' },
+    { file: '.claude/commands/make-case.md', template: '.claude/commands/make-case.md' },
+    { file: '.claude/commands/explore-case.md', template: '.claude/commands/explore-case.md' },
+    { file: '.claude/commands/gen-spec.md', template: '.claude/commands/gen-spec.md' },
+    { file: '.claude/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
+    // OpenCode does not read `.claude/commands` (only `.claude/skills`), so the same commands live here too.
+    { file: '.opencode/commands/make-case.md', template: '.claude/commands/make-case.md' },
+    { file: '.opencode/commands/explore-case.md', template: '.claude/commands/explore-case.md' },
+    { file: '.opencode/commands/gen-spec.md', template: '.claude/commands/gen-spec.md' },
+    { file: '.opencode/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
+];
+/** Files `init` creates once; after that the project owns them and may edit them freely. */
+const ONCE = [
+    { file: 'AGENTS.md', template: 'AGENTS.md' },
+    { file: 'CLAUDE.md', template: 'CLAUDE.md' },
+    { file: '.mcp.json', template: '.mcp.json' },
+    { file: 'opencode.jsonc', template: 'opencode.jsonc' },
+    { file: '.claude/settings.json', template: '.claude/settings.json' },
+    { file: 'tsconfig.json', template: 'tsconfig.json' },
+    { file: 'pnpm-workspace.yaml', template: 'pnpm-workspace.yaml' },
+    { file: 'profiles.yaml', template: 'profiles.yaml' },
+    { file: 'cases/_template.md', template: 'cases/_template.md' },
+    { file: 'package.json', template: 'package.json' },
+];
+// npm never packs a `.gitignore`, so the template is named `gitignore`; init writes it as `.gitignore`.
+const GITIGNORE_BLOCK = fs.readFileSync(path.join(TEMPLATES_DIR, 'gitignore'), 'utf8').trimEnd();
+const MARKER = '.asrun.json';
+const DOTENV_HEADER = '# asrun: the workspace these commands run against (relative to this file).';
+const PACKAGE = '@asrunjs/asrun';
+function readTemplate(name) {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
+}
+/** True in the framework's own repository (not an installed package). */
+function isRepoCheckout() {
+    return !FRAMEWORK_ROOT.split(path.sep).includes('node_modules') && fs.existsSync(path.join(FRAMEWORK_ROOT, 'examples', 'demo'));
+}
+/** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
+export function frameworkPath(root) {
+    if (!isRepoCheckout()) {
+        // The standard install location, or a hoisted one in a monorepo.
+        for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
+            const candidate = path.join(dir, 'node_modules', PACKAGE);
+            if (fs.existsSync(path.join(candidate, 'package.json'))) {
+                const relative = path.relative(root, candidate).split(path.sep).join('/');
+                return relative.startsWith('.') ? relative : `./${relative}`;
+            }
+            if (path.dirname(dir) === dir)
+                break;
+        }
+        // Not installed yet (a scaffolding run): name the place the package will live.
+        return `./node_modules/${PACKAGE}`;
+    }
+    const relative = path.relative(root, FRAMEWORK_ROOT).split(path.sep).join('/');
+    if (relative === '')
+        return '.';
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
+/** True when this workspace has the package installed (or is the framework's own checkout). */
+export function isInstalled(root) {
+    return fs.existsSync(path.join(path.resolve(root, frameworkPath(root)), 'package.json'));
+}
+/** Fills the `{{framework}}` and `{{playwright}}` placeholders of a template. */
+export function renderTemplate(name, root) {
+    return readTemplate(name)
+        .replaceAll('{{framework}}', frameworkPath(root))
+        .replaceAll('{{playwright}}', playwrightBin(root));
+}
+/**
+ * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
+ * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
+ * Kept relative: the file is committed and must not name a machine.
+ */
+export function playwrightBin(root) {
+    if (fs.existsSync(path.join(root, 'node_modules', '.bin', 'playwright')))
+        return './node_modules/.bin/playwright';
+    const framework = frameworkPath(root);
+    return framework.startsWith('..') ? `${framework}/node_modules/.bin/playwright` : './node_modules/.bin/playwright';
+}
+export function frameworkVersion() {
+    let version = '0.0.0';
+    try {
+        version = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8')).version ?? version;
+    }
+    catch {
+        // keep the default
+    }
+    let commit = 'unknown';
+    try {
+        commit = spawnSync('git', ['-C', FRAMEWORK_ROOT, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).stdout.trim() || 'unknown';
+    }
+    catch {
+        // keep the default
+    }
+    return { version, commit };
+}
+/** Merges the template's npm scripts and devDependencies into an existing package.json (never overwrites). */
+function mergePackageJson(root) {
+    const file = path.join(root, 'package.json');
+    if (!fs.existsSync(file))
+        return [];
+    const current = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const template = JSON.parse(readTemplate('package.json'));
+    const added = [];
+    current.scripts ??= {};
+    for (const [name, command] of Object.entries(template.scripts)) {
+        if (current.scripts[name] === undefined) {
+            current.scripts[name] = command;
+            added.push(`scripts.${name}`);
+        }
+    }
+    current.devDependencies ??= {};
+    for (const [name, range] of Object.entries(template.devDependencies)) {
+        if (current.devDependencies[name] === undefined) {
+            current.devDependencies[name] = range;
+            added.push(`devDependencies.${name}`);
+        }
+    }
+    if (added.length > 0)
+        fs.writeFileSync(file, JSON.stringify(current, null, 2) + '\n');
+    return added;
+}
+/** Adds the ignore block, or refreshes the one that is already there. */
+function ensureGitignore(root, update) {
+    const file = path.join(root, '.gitignore');
+    if (!fs.existsSync(file)) {
+        fs.writeFileSync(file, GITIGNORE_BLOCK + '\n');
+        return 'created';
+    }
+    const text = fs.readFileSync(file, 'utf8');
+    const existing = /# >>> asrun[\s\S]*?# <<< asrun/;
+    if (!existing.test(text)) {
+        fs.writeFileSync(file, text.replace(/\n*$/, '\n\n') + GITIGNORE_BLOCK + '\n');
+        return 'appended';
+    }
+    if (!update)
+        return 'kept';
+    fs.writeFileSync(file, text.replace(existing, GITIGNORE_BLOCK));
+    return 'updated';
+}
+/** Points ASRUN_ROOT at the workspace, in the `.env` of the folder the commands run in. Keeps every other line. */
+function ensureDotEnv(dir, workspaceRoot) {
+    const file = path.join(dir, '.env');
+    const relative = path.relative(dir, workspaceRoot).split(path.sep).join('/') || '.';
+    const line = `ASRUN_ROOT=${relative}`;
+    if (!fs.existsSync(file)) {
+        fs.writeFileSync(file, `${DOTENV_HEADER}\n${line}\n`);
+        return 'created';
+    }
+    const text = fs.readFileSync(file, 'utf8');
+    const cleaned = text.replace(/^#\s*asrun: the workspace.*$/m, DOTENV_HEADER);
+    const pattern = /^ASRUN_ROOT\s*=/m;
+    if (pattern.test(cleaned)) {
+        const next = cleaned.replace(/^ASRUN_ROOT\s*=.*$/m, line);
+        if (next === text)
+            return 'kept';
+        fs.writeFileSync(file, next);
+        return 'updated';
+    }
+    fs.writeFileSync(file, cleaned.replace(/\n*$/, '\n') + `\n${DOTENV_HEADER}\n${line}\n`);
+    return 'updated';
+}
+function readManifest(root) {
+    for (const name of [MARKER]) {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(root, name), 'utf8'));
+        }
+        catch {
+            // try the next name
+        }
+    }
+    return null;
+}
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const value = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 ? args[index + 1] : undefined;
+    };
+    const root = path.resolve(value('--root') ?? process.cwd());
+    const update = args.includes('--update');
+    const installAt = args.indexOf('--install');
+    const install = installAt >= 0;
+    const installSpec = install && args[installAt + 1] && !args[installAt + 1].startsWith('-') ? args[installAt + 1] : PACKAGE;
+    const forced = args
+        .flatMap((arg, index) => (arg === '--force' && args[index + 1] ? [args[index + 1]] : []))
+        .map((file) => file.split('\\').join('/'));
+    const resetRules = args.includes('--reset-rules');
+    const skipEnv = args.includes('--no-env');
+    if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
+        console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun init" inside the project that uses ' +
+            'asrun, or pass --root <dir> (the framework develops against examples/demo).');
+        return 1;
+    }
+    const firstRun = !fs.existsSync(path.join(root, MARKER));
+    const written = [];
+    const kept = [];
+    const notes = [];
+    const framework = frameworkPath(root);
+    // `--force` repairs a file this tool writes. A project's own rules are never overwritten by a framework update:
+    // `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` need `--reset-rules` on top.
+    const owned = [...GENERATED, ...ONCE].map((entry) => entry.file);
+    const projectRules = (file) => file === 'AGENTS.md' || file === 'CLAUDE.md' || file === '.claude/skills' || file.startsWith('.claude/skills/');
+    for (const file of forced) {
+        if (!owned.includes(file)) {
+            console.error(`--force ${file}: init only writes the files it owns (${owned.join(', ')}).`);
+            return 1;
+        }
+        if (projectRules(file) && !resetRules) {
+            console.error(`--force ${file}: this file belongs to the project. Add --reset-rules to replace it with the template.`);
+            return 1;
+        }
+    }
+    const place = (entry, overwrite) => {
+        const target = path.join(root, entry.file);
+        if (fs.existsSync(target) && !overwrite) {
+            kept.push(entry.file);
+            return;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, renderTemplate(entry.template, root));
+        written.push(entry.file);
+    };
+    for (const entry of GENERATED)
+        place(entry, update || forced.includes(entry.file));
+    for (const entry of ONCE) {
+        // The demo workspace lives inside the framework repository: it has no package manager settings of its own.
+        if (framework.startsWith('..') && (entry.file === 'pnpm-workspace.yaml' || entry.file === 'package.json'))
+            continue;
+        place(entry, forced.includes(entry.file));
+    }
+    const gitignore = ensureGitignore(root, update);
+    const merged = mergePackageJson(root);
+    const dotenv = skipEnv ? 'skipped' : ensureDotEnv(process.cwd(), root);
+    if (fs.existsSync(path.join(root, 'tsconfig.json')) && !written.includes('tsconfig.json')) {
+        const tsconfig = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8');
+        if (tsconfig.includes('@asrun/')) {
+            notes.push('Specs import the framework by package name now ("@asrunjs/asrun/fixtures"); the old "@..." path alias in tsconfig.json can go.');
+        }
+    }
+    if (fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) && !written.includes('pnpm-workspace.yaml')) {
+        const workspace = fs.readFileSync(path.join(root, 'pnpm-workspace.yaml'), 'utf8');
+        if (!workspace.includes('allowBuilds')) {
+            notes.push('Add "allowBuilds: {esbuild: true, ffmpeg-static: true}" to pnpm-workspace.yaml, or pnpm skips their build scripts.');
+        }
+        if (/^packages\s*:/m.test(workspace)) {
+            notes.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
+        }
+    }
+    if (fs.existsSync(path.join(root, '.mcp.json')) && !fs.readFileSync(path.join(root, '.mcp.json'), 'utf8').includes('playwright-test')) {
+        notes.push('Add the "playwright-test" MCP server to .mcp.json (see templates/.mcp.json).');
+    }
+    if (fs.existsSync(path.join(root, 'opencode.jsonc')) && !fs.readFileSync(path.join(root, 'opencode.jsonc'), 'utf8').includes('playwright-test')) {
+        notes.push('Add the "playwright-test" MCP server to opencode.jsonc (see templates/opencode.jsonc).');
+    }
+    if (fs.existsSync(path.join(root, 'opencode.jsonc'))) {
+        const text = fs.readFileSync(path.join(root, 'opencode.jsonc'), 'utf8');
+        // A commented-out "model" (the template has one) does not set anything: only a real key counts.
+        const withoutComments = text.replace(/^\s*\/\/.*$/gm, '');
+        if (!/["']?model["']?\s*:/.test(withoutComments)) {
+            notes.push('opencode.jsonc sets no "model": a one-shot "opencode run" then uses OpenCode\'s built-in free model, which has a ' +
+                'daily usage limit. Pick a model in the AsRun web UI (top bar), or set "model" there.');
+        }
+    }
+    if (fs.existsSync(path.join(root, '.claude', 'settings.json'))) {
+        const settings = fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8');
+        if (!settings.includes('pnpm asrun')) {
+            notes.push('Add "pnpm asrun *" to sandbox.excludedCommands in .claude/settings.json (see templates/.claude/settings.json).');
+        }
+    }
+    // Install last, so pnpm-workspace.yaml (the build-script approval) already exists. Its absence is the reason
+    // "pnpm add -D @asrunjs/asrun" fails on pnpm 12 with ERR_PNPM_IGNORED_BUILDS.
+    const installed = isInstalled(root);
+    if (install && !installed) {
+        if (spawnSync('pnpm', ['add', '-D', installSpec], { cwd: root, stdio: 'inherit', shell: process.platform === 'win32' }).status !== 0) {
+            return 1;
+        }
+    }
+    const version = frameworkVersion();
+    fs.writeFileSync(path.join(root, MARKER), JSON.stringify({
+        framework: PACKAGE,
+        frameworkPath: framework,
+        version: version.version,
+        commit: version.commit,
+        generated: GENERATED.map((entry) => entry.file),
+        updatedAt: new Date().toISOString(),
+    }, null, 2) + '\n');
+    const label = firstRun ? 'Initialized' : update ? 'Refreshed' : 'Checked';
+    console.log(`${label} workspace: ${root}`);
+    console.log(`  framework: ${PACKAGE} ${version.version} at ${framework}`);
+    if (written.length > 0)
+        console.log(`  written:   ${written.join(', ')}`);
+    if (kept.length > 0)
+        console.log(`  kept:      ${kept.join(', ')}`);
+    if (merged.length > 0)
+        console.log(`  merged:    package.json -> ${merged.join(', ')}`);
+    if (gitignore !== 'kept')
+        console.log(`  .gitignore: ${gitignore}`);
+    if (dotenv !== 'skipped')
+        console.log(`  .env:      ${dotenv} (ASRUN_ROOT in ${process.cwd()})`);
+    for (const note of notes)
+        console.log(`\n  ! ${note}`);
+    if (!installed && !install) {
+        console.log(`\n  ! ${PACKAGE} is not installed yet. Next: pnpm add -D ${installSpec}`);
+    }
+    if (firstRun) {
+        console.log('\nNext: edit profiles.yaml, run "pnpm install", then "pnpm asrun doctor" and "pnpm signin <profile-id>".');
+    }
+    return 0;
+}

package/dist/scripts/lint-specs.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/lint-specs.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listCaseFileIds } from '../lib/cases.js';
+import { TESTS_DIR } from '../lib/paths.js';
+import { parseTargets, readCaseText, TARGET_REF } from '../lib/targets.js';
+const specFiles = (dir) => fs.existsSync(dir)
+    ? fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            return entry.name.endsWith('-snapshots') ? [] : specFiles(full);
+        return entry.name.endsWith('.spec.ts') && entry.name !== 'seed.spec.ts' ? [full] : [];
+    })
+    : [];
+const IMAGE_WORDS = /\b(logo|image|img|icon|avatar|screenshot|snapshot)\b/i;
+const TARGET_COMMENT = /\/\/\s*target:\s*(T\d+)/;
+const near = (lines, index, back = 4) => lines.slice(Math.max(0, index - back), index + 1).join('\n');
+const withoutStringsAndComments = (line) => line
+    .replace(/\/\/.*$/, '')
+    .replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`/g, '""');
+/**
+ * Marks every line that is inside the callback of `expect(async () => {...}).toPass(...)`. The callback is retried until it
+ * passes, so a single `isVisible()` look in it is not a one-look decision. `toPass` comes after the closing brace, so the
+ * block is found by counting braces from the `expect(async () => {` line.
+ */
+function linesInsideToPass(lines) {
+    const inside = new Array(lines.length).fill(false);
+    const clean = lines.map(withoutStringsAndComments);
+    for (let start = 0; start < lines.length; start++) {
+        if (!/\bexpect\(\s*async\s*\(\s*\)\s*=>\s*\{/.test(clean[start]))
+            continue;
+        let depth = 0;
+        let opened = false;
+        for (let end = start; end < lines.length; end++) {
+            const row = clean[end];
+            for (let col = end === start ? row.search(/\bexpect\(\s*async/) : 0; col < row.length; col++) {
+                if (row[col] === '{') {
+                    depth++;
+                    opened = true;
+                }
+                else if (row[col] === '}') {
+                    depth--;
+                    if (opened && depth === 0) {
+                        const after = row.slice(col) + (clean[end + 1] ?? '');
+                        if (/^\}\s*\)\s*\.toPass\s*\(/.test(after))
+                            for (let line = start; line <= end; line++)
+                                inside[line] = true;
+                        col = row.length;
+                        end = lines.length;
+                    }
+                }
+            }
+        }
+    }
+    return inside;
+}
+function lint(file) {
+    const findings = [];
+    const lines = fs.readFileSync(file, 'utf8').split('\n');
+    const insideToPass = linesInsideToPass(lines);
+    const rel = path.relative(path.join(TESTS_DIR, '..'), file);
+    const add = (level, index, rule, message) => findings.push({ level, file: rel, line: index + 1, rule, message });
+    const caseId = /^\/\/ case: cases\/(.+)\.md/m.exec(lines.join('\n'))?.[1];
+    const cards = caseId && listCaseFileIds().includes(caseId) ? parseTargets(readCaseText(caseId)) : [];
+    const cardIds = new Set(cards.map((card) => card.id));
+    lines.forEach((line, i) => {
+        const code = line.replace(/\/\/.*$/, '');
+        const target = TARGET_COMMENT.exec(near(lines, i));
+        if (/\bwaitForTimeout\s*\(/.test(code))
+            add('fail', i, 'no-sleep', 'waitForTimeout waits for time, not for the page. Wait for the request (actAndWait) or for a visible signal.');
+        if (/networkidle/.test(code))
+            add('fail', i, 'no-networkidle', 'networkidle is not a readiness signal. Wait for the key request or for the content (actAndWait).');
+        if (/waitForEvent\(\s*['"]download['"]/.test(code) || /\.on\(\s*['"]download['"]/.test(code)) {
+            add('fail', i, 'download', 'Verify downloads with verifyDownload() from lib/downloads: start, finish, file exists, file valid.');
+        }
+        if (/kind:\s*['"]pdf['"]/.test(code) && !/expectPdf\s*\(/.test(lines.join('\n'))) {
+            add('warn', i, 'pdf-content', 'A PDF download is opened but its content is never checked. Render the pages and check the text with expectPdf() from lib/pdf.');
+        }
+        if (/expectPdf\s*\(/.test(code) && !target) {
+            add('fail', i, 'pdf-target', 'expectPdf needs "// target: T<n>" (a card in the case\'s "## Targets": which pages, which region, what must be there).');
+        }
+        if (/pages:\s*(['"](?:first|last)['"]|\[)/.test(code) && !/\/\/\s*pages:\s*\S/.test(near(lines, i, 3) + ' ' + line)) {
+            add('fail', i, 'pdf-pages', 'Checking only some pages of a PDF needs "// pages: <the case\'s words>" with the strong requirement (only / exactly / must). Otherwise check every page (pages: \'all\').');
+        }
+        if (/%PDF/.test(code) && !/lib\/downloads/.test(code))
+            add('fail', i, 'download', 'A %PDF magic-number check alone is not a download verification. Use verifyDownload(page, trigger, {kind: "pdf"}).');
+        if (/toHaveScreenshot\s*\(/.test(code)) {
+            if (!target)
+                add('fail', i, 'screenshot-target', 'A screenshot check needs "// target: T<n>" (a card in the case\'s "## Targets": what is shown, where it is, how it is found).');
+        }
+        const imageCheck = /toHaveScreenshot|expectImageLoaded|expectLogo|expectImageSha256|naturalWidth/.test(code);
+        const genericImage = /locator\(\s*['"`](?:img|svg|img,\s*svg|svg,\s*img|img\[alt\][^'"`]*)['"`]\s*\)/.test(code);
+        const pickedByPosition = /\.(first|last)\(\)|\.nth\(/.test(code);
+        if ((imageCheck || IMAGE_WORDS.test(code)) && genericImage && !target) {
+            add('fail', i, 'generic-image-locator', 'A bare img/svg locator can match any image on the page (a content image, an avatar). Locate the exact element by its role, name or test id and mark it "// target: T<n>".');
+        }
+        if (pickedByPosition && IMAGE_WORDS.test(code) && /\b(img|svg|logo|image)\b/i.test(code) && !target) {
+            add('fail', i, 'position-pick', '.first()/.last()/.nth() on an image or logo picks by position, not by identity. Name the exact element and mark it "// target: T<n>".');
+        }
+        if (/\.(isVisible|isHidden)\(\s*\{/.test(code)) {
+            add('fail', i, 'isvisible-timeout', 'isVisible()/isHidden() do not wait and ignore their timeout. Use expect(...).toBeVisible({timeout}), or for an optional confirmation clickOptionalUntilHidden() from lib/ready.');
+        }
+        else if (/\.isVisible\(\s*\)/.test(code) && /\bif\s*\(/.test(code)) {
+            const insideRetry = insideToPass[i];
+            if (/\.click\(/.test(code) && !insideRetry) {
+                add('fail', i, 'isvisible-click', 'if (await x.isVisible()) await x.click() decides from one look: a dialog that shows up a moment later is skipped. Use clickOptionalUntilHidden() from lib/ready, or put it inside expect(...).toPass().');
+            }
+            else if (!insideRetry && !/ready:/.test(near(lines, i, 6))) {
+                add('fail', i, 'isvisible-now', 'if (await x.isVisible()) checks only this instant, before the content may have loaded. Wait for a ready signal and mark it "// ready: <signal>", or move the check into expect(...).toPass().');
+            }
+        }
+        if (/\.catch\(\s*\(\)\s*=>\s*(false|null|undefined)\s*\)/.test(code) && /\b(isVisible|waitFor|toBeVisible)\b/.test(code)) {
+            add('warn', i, 'swallowed-wait', '.catch(() => false) turns a failed wait into "not there". For something that may not appear, use clickOptionalUntilHidden() or wait for a signal that proves the page finished.');
+        }
+        if (/Not verified|not verified on the page|unverified/i.test(line)) {
+            add('warn', i, 'unverified', 'This check was written without seeing it on the page. Say so in the report; confirm it by running /explore-case before trusting it.');
+        }
+        const absence = /toHaveCount\(\s*0\s*\)|\.not\.toBeVisible|\.not\.toBeAttached|toBeEmpty\(\)|toBeHidden/.test(code);
+        if (absence && /missing|empty|no |not (shown|found|listed)|without/i.test(line) && !/ready:/.test(near(lines, i, 6))) {
+            add('warn', i, 'absence-without-ready', 'An absence check passes while the page is still loading. Add a positive ready signal before it and mark it "// ready: <signal>".');
+        }
+        for (const match of line.matchAll(/\/\/\s*target:\s*(T\d+)/g)) {
+            if (!cardIds.has(match[1]))
+                add('fail', i, 'unknown-target', `${match[1]} is not a card in "## Targets" of ${caseId ?? 'the case'}.`);
+            else if (cards.find((card) => card.id === match[1])?.blocking)
+                add('fail', i, 'blocking-target', `${match[1]} still has an open [blocking] question in the case; do not build a check on it (use test.fixme).`);
+        }
+    });
+    TARGET_REF.lastIndex = 0;
+    return findings;
+}
+// A case id is written with `/` (`conduit/header-navigation`), while a path on Windows has `\`: without the
+// normalization this filter matched nothing and reported "0 spec(s)" for a spec that was right there.
+const casePath = (file) => file.replace(/\\/g, '/');
+const wanted = process.argv.slice(2).filter((arg) => !arg.startsWith('-'));
+const files = specFiles(TESTS_DIR).filter((file) => wanted.length === 0 || wanted.some((id) => casePath(file).endsWith(`${casePath(id)}.spec.ts`)));
+const findings = files.flatMap(lint);
+for (const f of findings)
+    console.log(`${f.level.toUpperCase().padEnd(4)} ${f.file}:${f.line}  [${f.rule}] ${f.message}`);
+const fails = findings.filter((f) => f.level === 'fail').length;
+console.log(`\nspec lint: ${files.length} spec(s), ${fails} failure(s), ${findings.length - fails} warning(s)`);
+process.exit(fails > 0 ? 1 : 0);

package/dist/scripts/login.d.ts

@@ -0,0 +1 @@
+export {};