@asrunjs/asrun 0.0.0-stage → 0.2.0

package/dist/scripts/build.js

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { commandScript } from '../lib/node-cli.js';
+import { FRAMEWORK_ROOT } from '../lib/paths.js';
+// Compiles the framework to `dist/`: JavaScript and type declarations that Node and Playwright can load from a
+// node_modules folder (Node refuses to strip types there). The plain `.mjs` tools are copied as they are.
+const tsc = commandScript('typescript', 'tsc');
+const result = spawnSync(process.execPath, [tsc, '-p', path.join(FRAMEWORK_ROOT, 'tsconfig.build.json')], {
+    cwd: FRAMEWORK_ROOT,
+    stdio: 'inherit',
+});
+if ((result.status ?? 1) !== 0)
+    process.exit(result.status ?? 1);
+for (const file of ['go.mjs', 'heal-evidence.mjs']) {
+    const from = path.join(FRAMEWORK_ROOT, 'scripts', file);
+    const to = path.join(FRAMEWORK_ROOT, 'dist', 'scripts', file);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+}

package/dist/scripts/check-cases.d.ts

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

package/dist/scripts/check-cases.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import { CASES_DIR } from '../lib/paths.js';
+import { listCaseFileIds, readCaseMeta } from '../lib/cases.js';
+import path from 'node:path';
+import { ROOT } from '../lib/paths.js';
+import { checksNeedingTarget, parseTargets, readCaseText, REQUIRED_FIELDS, targetRefsIn } from '../lib/targets.js';
+import { parseCaseValues } from '../lib/values.js';
+/** Step numbers of the lines marked `[input]` or `[writes]` in "## Steps" (a person does them), and the numbers that "## Inputs" has a bullet for. */
+function inputSteps(id) {
+    const text = fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8');
+    const section = (name) => new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text)?.[1] ?? '';
+    const marked = [...section('Steps').matchAll(/^(\d+)\.\s.*\[(?:input|writes)\]/gm)].map((match) => Number(match[1]));
+    const recorded = [...section('Inputs').matchAll(/^- Step (\d+)\b/gm)].map((match) => Number(match[1]));
+    return { marked, recorded };
+}
+/** Problems with the target cards (`## Targets`) of a case: `fail` stops, `warn` is what `/explore-case` still has to settle. */
+function targetProblems(id) {
+    const text = readCaseText(id);
+    const cards = parseTargets(text);
+    const fail = [];
+    const warn = [];
+    const known = new Set(cards.map((card) => card.id));
+    for (const card of cards) {
+        const missing = REQUIRED_FIELDS.filter((field) => !card.fields[field]);
+        if (missing.length > 0 && !card.blocking)
+            fail.push(`target ${card.id} "${card.name}" has no ${missing.map((field) => `"${field}"`).join(', ')}`);
+        for (const [label, file] of Object.entries(card.references)) {
+            if (/^none\b/i.test(file))
+                continue;
+            // References live in .explore/ (git-ignored, they show logged-in pages), so a fresh checkout has none: a warning.
+            if (!file.startsWith('.explore/'))
+                fail.push(`target ${card.id}: the reference image for ${label} must be saved under .explore/targets/<case-id>/ (got ${file})`);
+            else if (!fs.existsSync(path.join(ROOT, file)))
+                warn.push(`target ${card.id}: the reference image for ${label} is not on this machine: ${file}`);
+        }
+        if (Object.keys(card.references).length === 0 && !card.blocking) {
+            warn.push(`target ${card.id} "${card.name}" has no "Reference <profile-id>:" line (a highlighted screenshot of what the check looks at, or "none: <reason>")`);
+        }
+    }
+    const body = text.replace(/^## Targets\s*$[\s\S]*?(?=^## |(?![\s\S]))/m, '').replace(/^## Source\s*$[\s\S]*?(?=^## |(?![\s\S]))/m, '');
+    for (const ref of targetRefsIn(body))
+        if (!known.has(ref))
+            fail.push(`a check refers to [${ref}] but "## Targets" has no card ${ref}`);
+    for (const check of checksNeedingTarget(text)) {
+        warn.push(`"${check.section}" has a check on an image, file or logo without a target card ([T<n>]): ${check.line.slice(0, 90)}`);
+    }
+    try {
+        const values = parseCaseValues(text, `cases/${id}.md`);
+        if (Object.keys(values).length === 0) {
+            warn.push('has no "## Values" block; a spec that asserts expected values cannot run for any profile');
+        }
+    }
+    catch (error) {
+        fail.push(error.message);
+    }
+    return { fail, warn };
+}
+const ids = process.argv.slice(2).length > 0 ? process.argv.slice(2) : listCaseFileIds();
+let problems = 0;
+for (const id of ids) {
+    try {
+        const meta = readCaseMeta(id);
+        console.log(`ok   ${id}  suites=[${meta.suites.join(', ')}]  writes=[${meta.writes.join(', ')}]` +
+            `${meta.envs ? `  envs=[${meta.envs.join(', ')}]` : ''}`);
+        const targets = targetProblems(id);
+        for (const message of targets.warn)
+            console.log(`warn ${id}: ${message}`);
+        for (const message of targets.fail)
+            throw new Error(message);
+        const { marked, recorded } = inputSteps(id);
+        const missing = marked.filter((step) => !recorded.includes(step));
+        if (missing.length > 0) {
+            console.log(`warn ${id}: step ${missing.join(', ')} is marked [input] or [writes] but has no recipe under "## Inputs" (run /explore-case --attended)`);
+        }
+    }
+    catch (error) {
+        problems++;
+        console.error(`FAIL ${id}: ${error.message}`);
+    }
+}
+process.exit(problems > 0 ? 1 : 0);

package/dist/scripts/cleanup.d.ts

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

package/dist/scripts/cleanup.js

@@ -0,0 +1,25 @@
+import { listEnvs } from '../lib/profiles.js';
+import { describeLeftovers, findLeftovers, forgetLedgers } from '../lib/records.js';
+const args = process.argv.slice(2);
+const envArg = args.find((arg) => arg.startsWith('--env='))?.slice('--env='.length) ?? args[args.indexOf('--env') + 1];
+const forget = args.includes('--forget');
+if (!envArg || !listEnvs().includes(envArg)) {
+    console.error('Usage: pnpm cleanup --env <env> [--forget]\n' +
+        `  --env is required (${listEnvs().join(' | ')}); there is no default.\n` +
+        '  Lists test data that cases created and could not remove (from .tmp/records).\n' +
+        '  Delete it by hand in the product, then run with --forget to clear the list.');
+    process.exit(1);
+}
+const leftovers = findLeftovers({ env: envArg });
+if (leftovers.length === 0) {
+    console.log(`No test data left behind in ${envArg.toUpperCase()}.`);
+    process.exit(0);
+}
+console.log(`Test data left behind in ${envArg.toUpperCase()} (named "[asrun] ..."):\n${describeLeftovers(leftovers)}`);
+if (forget) {
+    console.log(`\nForgot ${forgetLedgers(envArg)} ledger file(s). Only do this after the data is deleted.`);
+}
+else {
+    console.log('\nDelete these by hand in the product, then run: pnpm cleanup --env ' + envArg + ' --forget');
+    process.exit(1);
+}

package/dist/scripts/cli.d.ts

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

package/dist/scripts/cli.js

@@ -0,0 +1,28 @@
+// `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.
+const [command, ...rest] = process.argv.slice(2);
+async function main() {
+    if (command === 'init') {
+        const { main: init } = await import('./init.js');
+        process.exitCode = await init(rest);
+        return;
+    }
+    if (command === 'doctor') {
+        const { main: doctor } = await import('./doctor.js');
+        process.exitCode = await doctor(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.`;
+await main();
+export {};

package/dist/scripts/doctor.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): Promise<number>;

package/dist/scripts/doctor.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+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 { GENERATED, frameworkPath, frameworkVersion, renderTemplate } from './init.js';
+/**
+ * Checks that a workspace is complete and consistent with the framework it points at. It never writes anything.
+ * Errors exit with 1; warnings do not.
+ */
+const SKILLS = ['making-cases', 'exploring-cases', 'generating-specs'];
+function read(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** The ids of the framework rules that a project may not narrow, parsed from the framework's AGENTS.md. */
+function nonNegotiableRules() {
+    const ids = new Set();
+    for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
+        const match = /^- \*\*(F\d+)\b/.exec(line.trim());
+        if (match && line.includes('[non-negotiable]'))
+            ids.add(match[1]);
+    }
+    return ids;
+}
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log('Usage: pnpm asrun doctor');
+        return 0;
+    }
+    const errors = [];
+    const warnings = [];
+    const facts = [];
+    if (path.resolve(ROOT) === path.resolve(FRAMEWORK_ROOT)) {
+        console.error('No workspace found: this is the framework folder. Run the command in the project that uses the framework, ' +
+            'or set ASRUN_ROOT (the framework develops against examples/demo).');
+        return 1;
+    }
+    facts.push(`workspace: ${ROOT}`);
+    const actualPath = frameworkPath(ROOT);
+    facts.push(`framework: ${path.resolve(ROOT, actualPath)}`);
+    // 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.');
+    }
+    else {
+        try {
+            const parsed = JSON.parse(manifest);
+            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".`);
+            }
+            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".`);
+            }
+        }
+        catch {
+            errors.push('.asrun.json is not valid JSON: delete it and run "pnpm asrun init" again.');
+        }
+    }
+    const framework = recordedPath ?? actualPath;
+    // Profiles: they are the only source of environments, and a broken file stops every command.
+    try {
+        const profiles = loadProfiles();
+        if (profiles.length === 0) {
+            errors.push(`${PROFILES_FILE} has no profiles.`);
+        }
+        else {
+            facts.push(`profiles:  ${profiles.length} (${listEnvs(profiles).join(', ')})`);
+        }
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    // How the specs reach the framework: through the package name (`@asrunjs/asrun/fixtures`), so only the file must exist.
+    if (read(path.join(ROOT, 'tsconfig.json')) === null) {
+        errors.push('tsconfig.json is missing: run "pnpm asrun init".');
+    }
+    const config = read(path.join(ROOT, 'playwright.config.ts'));
+    if (config === null) {
+        errors.push('playwright.config.ts is missing: run "pnpm asrun init".');
+    }
+    else {
+        const target = /from\s+['"]([^'"]+)['"]/.exec(config)?.[1];
+        if (!target) {
+            errors.push('playwright.config.ts does not re-export the framework config (see templates/playwright.config.ts).');
+        }
+        else {
+            const resolved = path.resolve(ROOT, target);
+            if (!fs.existsSync(resolved) && !fs.existsSync(`${resolved}.ts`)) {
+                errors.push(`playwright.config.ts points at "${target}", which does not exist. Run "pnpm asrun init --force playwright.config.ts".`);
+            }
+        }
+    }
+    const gitignore = read(path.join(ROOT, '.gitignore')) ?? '';
+    // A bare "*" ignores everything (a folder that only commits selected files); nothing can leak there.
+    const ignoresEverything = gitignore.split('\n').some((line) => line.trim() === '*');
+    for (const entry of ['.auth/', 'reports/']) {
+        if (!ignoresEverything && !gitignore.includes(entry)) {
+            errors.push(`.gitignore does not ignore "${entry}". Saved logins must never be committed.`);
+        }
+    }
+    // Files generated from the templates: missing or edited ones are refreshed with `init --update`.
+    for (const entry of GENERATED) {
+        const current = read(path.join(ROOT, entry.file));
+        const template = renderTemplate(entry.template, ROOT);
+        if (current === null)
+            warnings.push(`${entry.file} is missing: run "pnpm asrun init".`);
+        else if (current !== template) {
+            warnings.push(`${entry.file} differs from the framework template: run "pnpm asrun init --update".`);
+        }
+    }
+    // Skills: the framework's, plus any project override.
+    const missingSkills = SKILLS.filter((skill) => !fs.existsSync(path.join(SKILLS_DIR, skill, 'SKILL.md')));
+    if (missingSkills.length > 0)
+        errors.push(`The framework folder is incomplete: no skill ${missingSkills.join(', ')}.`);
+    const skillsDir = path.join(ROOT, '.claude', 'skills');
+    const overrides = fs.existsSync(skillsDir) ? fs.readdirSync(skillsDir).filter((name) => name.endsWith('.md')) : [];
+    facts.push(`skills:    ${SKILLS.join(', ')}${overrides.length > 0 ? ` (project overrides: ${overrides.map((name) => name.replace(/\.md$/, '')).join(', ')})` : ''}`);
+    // Project rules may only narrow the baseline, never a rule marked [non-negotiable].
+    const agents = read(path.join(ROOT, 'AGENTS.md'));
+    if (agents === null) {
+        warnings.push('AGENTS.md is missing: run "pnpm asrun init" and fill in the project facts.');
+    }
+    else {
+        if (!agents.includes(`${framework}/AGENTS.md`)) {
+            errors.push(`AGENTS.md does not point at the framework baseline (${framework}/AGENTS.md).`);
+        }
+        const locked = nonNegotiableRules();
+        for (const line of agents.split('\n')) {
+            const match = /^\|\s*(F\d+)\s*\|/.exec(line.trim());
+            if (match && locked.has(match[1])) {
+                errors.push(`AGENTS.md narrows ${match[1]}, which the framework marks [non-negotiable].`);
+            }
+        }
+    }
+    // The install and the commands the docs use.
+    const workspaceFile = read(path.join(ROOT, 'pnpm-workspace.yaml'));
+    if (framework.startsWith('..')) {
+        // 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.');
+    }
+    else if (!workspaceFile.includes('allowBuilds')) {
+        warnings.push('pnpm-workspace.yaml has no "allowBuilds": pnpm skips the build scripts of esbuild and ffmpeg-static.');
+    }
+    else if (/^packages\s*:/m.test(workspaceFile)) {
+        warnings.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
+    }
+    let scripts = null;
+    try {
+        const packageJson = read(path.join(ROOT, 'package.json'));
+        if (packageJson !== null)
+            scripts = JSON.parse(packageJson).scripts ?? {};
+    }
+    catch {
+        warnings.push('package.json is not valid JSON.');
+    }
+    for (const name of ['asrun', 'signin', 'ui']) {
+        if (scripts !== null && !scripts[name])
+            warnings.push(`package.json has no "${name}" script: run "pnpm asrun init".`);
+    }
+    const settings = read(path.join(ROOT, '.claude', 'settings.json'));
+    if (settings === null) {
+        warnings.push('.claude/settings.json is missing: run "pnpm asrun init" (Claude Code needs its sandbox exclusions for pnpm asrun).');
+    }
+    else if (!settings.includes('pnpm asrun')) {
+        warnings.push('.claude/settings.json does not exclude "pnpm asrun" from the sandbox: the browser cannot start in it.');
+    }
+    console.log(facts.join('\n'));
+    for (const warning of warnings)
+        console.log(`\n! ${warning}`);
+    for (const error of errors)
+        console.log(`\nx ${error}`);
+    console.log(`\nDoctor: ${errors.length} error(s), ${warnings.length} warning(s).`);
+    return errors.length > 0 ? 1 : 0;
+}

package/dist/scripts/explore.d.ts

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

package/dist/scripts/explore.js

@@ -0,0 +1,54 @@
+import { chromium } from '@playwright/test';
+import { getProfile, listProfiles, profileLabel } from '../lib/profiles.js';
+import { parseCliTarget } from '../lib/cli.js';
+import { authFile } from '../lib/paths.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const parsed = parseCliTarget(process.argv.slice(2));
+const pathname = parsed.rest[0] ?? '/';
+if (!parsed.profileId || parsed.help) {
+    console.log('Usage: pnpm explore <profile-id> [path]   (opens a logged-in browser to look around)\n\n' +
+        'Profiles (the environment is part of each profile):\n' +
+        listProfiles()
+            .map((profile) => `  ${profile.id.padEnd(24)} ${profile.env.padEnd(10)} ${profile.baseURL}`)
+            .join('\n'));
+    process.exit(parsed.help ? 0 : 1);
+}
+if (parsed.envGiven) {
+    console.error('explore takes only the profile: its environment is part of profiles.yaml. Drop --env.');
+    process.exit(1);
+}
+const profile = getProfile(parsed.profileId);
+const file = authFile(profile.id);
+const browser = await chromium.launch({ headless: false });
+const context = await browser.newContext({
+    viewport: null,
+    ...(fs.existsSync(file) && { storageState: file }),
+});
+// Playwright keeps downloads in a temporary folder and deletes it on close, so save each file to ~/Downloads.
+const downloadsDir = path.join(os.homedir(), 'Downloads');
+const freeName = (name) => {
+    const { name: base, ext } = path.parse(path.basename(name) || 'download');
+    let candidate = path.join(downloadsDir, `${base}${ext}`);
+    for (let n = 1; fs.existsSync(candidate); n++)
+        candidate = path.join(downloadsDir, `${base} (${n})${ext}`);
+    return candidate;
+};
+const saveDownload = async (download) => {
+    try {
+        fs.mkdirSync(downloadsDir, { recursive: true });
+        const target = freeName(download.suggestedFilename());
+        await download.saveAs(target);
+        console.log(`Saved download: ${target}`);
+    }
+    catch (error) {
+        console.error(`Could not save download "${download.suggestedFilename()}": ${error.message}`);
+    }
+};
+const watchPage = (page) => page.on('download', (download) => void saveDownload(download));
+context.on('page', watchPage);
+const page = await context.newPage();
+await page.goto(new URL(pathname, profile.baseURL).href);
+console.log(`Opened ${profileLabel(profile)}. Close the browser window to exit.`);
+await new Promise((resolve) => browser.on('disconnected', resolve));

package/dist/scripts/go.mjs

@@ -0,0 +1,188 @@
+// One-liner for a fresh machine: install everything, prepare the workspace, then start the web UI and open it.
+// Plain Node on purpose: it may run before the dependencies are installed.
+//
+//   pnpm add -D @asrunjs/asrun        (or github:wizcas/asrun#v0.1.0)
+//   pnpm exec asrun init
+//   pnpm go
+import {spawn, spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FRAMEWORK = 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 shell = process.platform === 'win32';
+
+// `.env` next to the command, or the framework's own `.env`; a real environment variable always wins.
+function 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'));
+
+// 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.
+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;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+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)) {
+  console.error('No workspace found: run this command in the project that uses asrun, or set ASRUN_ROOT.');
+  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`);
+const fail = (text) => {
+  console.error(`\x1b[31m${text}\x1b[0m`);
+  process.exit(1);
+};
+const run = (command, args, options = {}) =>
+  spawnSync(command, args, {cwd: ROOT, stdio: 'inherit', shell, ...options}).status === 0;
+const exists = (command) => spawnSync(command, ['--version'], {stdio: 'ignore', shell}).status === 0;
+
+/** The JavaScript entry point of a package's command-line tool, without relying on node_modules/.bin shims. */
+function packageBin(name, command = name) {
+  for (const base of [FRAMEWORK, path.dirname(path.dirname(FRAMEWORK)), ROOT]) {
+    const dir = path.join(base, 'node_modules', name);
+    const manifest = path.join(dir, 'package.json');
+    if (!fs.existsSync(manifest)) continue;
+    const bin = JSON.parse(fs.readFileSync(manifest, 'utf8')).bin;
+    const entry = typeof bin === 'string' ? bin : bin?.[command];
+    if (entry) return path.join(dir, entry);
+  }
+  return null;
+}
+
+/** 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');
+/** The workspace's copy of the package, if any. */
+const installed = fs.existsSync(path.join(ROOT, 'node_modules', PACKAGE, 'package.json'));
+const frameworkRelative = installed
+  ? './' + path.relative(ROOT, path.join(ROOT, 'node_modules', PACKAGE)).split(path.sep).join('/')
+  : (() => {
+      const relative = path.relative(ROOT, FRAMEWORK).split(path.sep).join('/');
+      return relative === '' ? '.' : relative.startsWith('.') ? relative : `./${relative}`;
+    })();
+
+/** 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';
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx, ffmpeg-static) compile a binary on install.\n${block}`);
+    return 'created';
+  }
+  const text = fs.readFileSync(file, 'utf8');
+  if (text.includes('allowBuilds')) return 'kept';
+  fs.writeFileSync(file, `${text.replace(/\n*$/, '\n')}\n${block}`);
+  return 'updated';
+}
+
+async function uiIsUp() {
+  try {
+    return (await fetch(`${url}/api/info`, {signal: AbortSignal.timeout(1500)})).ok;
+  } catch {
+    return false;
+  }
+}
+
+function open(target) {
+  const [command, args] =
+    process.platform === 'darwin'
+      ? ['open', [target]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', target]]
+        : ['xdg-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.
+function ensureFfmpeg() {
+  // ffmpeg does not know `--version`, only `-version`.
+  if (spawnSync('ffmpeg', ['-version'], {stdio: 'ignore', shell}).status === 0) return console.log('ffmpeg: ok');
+  const installer =
+    process.platform === 'darwin' && exists('brew')
+      ? ['brew', ['install', 'ffmpeg']]
+      : process.platform === 'win32' && exists('winget')
+        ? ['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');
+  }
+  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.');
+}
+
+step(1, 'Checking this machine');
+const nodeMajor = Number(process.versions.node.split('.')[0]);
+if (nodeMajor < 22) fail(`Node 22 or newer is required (this is ${process.versions.node}). Install it from https://nodejs.org and run "pnpm go" again.`);
+console.log(`Node ${process.versions.node}: ok`);
+console.log(`workspace: ${ROOT}`);
+console.log(`framework: ${FRAMEWORK}${installed ? ' (installed)' : ' (development checkout)'}`);
+ensureFfmpeg();
+if (!exists('claude') && !exists('opencode')) {
+  warn('Neither "claude" (Claude Code) nor "opencode" found. Everything works except the AI steps (make cases, review, generate specs).');
+}
+
+step(2, 'Installing dependencies and the browser (a minute the first time, seconds after that)');
+const workspaceFile = ensurePnpmWorkspace();
+if (workspaceFile === 'created') console.log('pnpm-workspace.yaml: created (allowBuilds)');
+else if (workspaceFile === 'updated') console.log('pnpm-workspace.yaml: updated (allowBuilds)');
+const installRoot = frameworkRelative.startsWith('..') ? FRAMEWORK : ROOT;
+if (!run('pnpm', ['install'], {cwd: installRoot})) fail('Install failed. Fix the error above and run "pnpm go" again.');
+const playwright = packageBin('@playwright/test', 'playwright');
+if (playwright) {
+  if (!run(process.execPath, [playwright, 'install', 'chromium'])) warn('Could not install the Chromium browser; run "pnpm exec playwright install chromium".');
+} else {
+  warn('@playwright/test is not installed yet. Run this command again after the workspace files are in place.');
+}
+
+step(3, 'Preparing the workspace');
+// `--root` names the workspace, but the command runs where the person is: that is where `.env` belongs.
+if (!run(process.execPath, [bin, 'init', '--root', ROOT], {cwd: process.cwd()})) {
+  fail('Could not initialize the workspace. Run "pnpm asrun init" and read the message.');
+}
+run(process.execPath, [bin, 'doctor']);
+
+step(4, `Starting the web UI at ${url}`);
+if (await uiIsUp()) {
+  console.log('The UI is already running.');
+  if (openBrowser) open(url);
+  process.exit(0);
+}
+
+const env = {...process.env, ASRUN_ROOT: ROOT};
+const child = spawn(process.execPath, [bin, 'ui'], {cwd: ROOT, stdio: 'inherit', env, shell});
+// Ctrl+C reaches the UI server directly (same terminal); we only wait for it to shut down.
+process.on('SIGINT', () => {});
+process.on('SIGTERM', () => child.kill('SIGTERM'));
+child.on('exit', (code) => process.exit(code ?? 0));
+
+for (let i = 0; i < 240 && child.exitCode === null; i++) {
+  if (await uiIsUp()) {
+    console.log(`\n\x1b[1;32mReady: ${url}\x1b[0m  (Ctrl+C to stop)`);
+    if (openBrowser) open(url);
+    break;
+  }
+  await new Promise((resolve) => setTimeout(resolve, 500));
+}