@asrunjs/asrun 0.0.0-stage → 0.5.2

package/dist/scripts/doctor.js

@@ -0,0 +1,296 @@
+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 { spawnTarget } from '../lib/command.js';
+import { GENERATED, frameworkPath, frameworkVersion, 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.
+ * 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;
+}
+/** Every rule id the framework baseline defines (`F1`..`F10`), so a project cannot name one that does not exist. */
+function frameworkRuleIds() {
+    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)
+            ids.add(match[1]);
+    }
+    return ids;
+}
+/**
+ * The framework sources that `pnpm build` compiles into `dist/` and are older than it, or missing from it. Only the
+ * framework repository has those sources; an installed package ships `dist/` alone, so the list is empty there.
+ */
+function staleDistFiles() {
+    const stale = [];
+    const compare = (source) => {
+        const compiled = path.join(FRAMEWORK_ROOT, builtFile(source));
+        if (!fs.existsSync(compiled))
+            stale.push(`${builtFile(source)} is missing`);
+        else if (fs.statSync(path.join(FRAMEWORK_ROOT, source)).mtimeMs > fs.statSync(compiled).mtimeMs)
+            stale.push(source);
+    };
+    const walk = (dir) => {
+        if (!fs.existsSync(path.join(FRAMEWORK_ROOT, dir)))
+            return;
+        for (const entry of fs.readdirSync(path.join(FRAMEWORK_ROOT, dir), { withFileTypes: true })) {
+            const source = `${dir}/${entry.name}`;
+            if (entry.isDirectory())
+                walk(source);
+            // The plain `.mjs` tools are copied as they are; every other file is TypeScript and becomes JavaScript.
+            else if (source.endsWith('.ts') || COPIED_SCRIPTS.includes(entry.name))
+                compare(source);
+        }
+    };
+    walk('lib');
+    walk('scripts');
+    return stale;
+}
+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;
+    // The framework repository compiles itself into `dist/`, and `templates/playwright.config.ts` makes every workspace
+    // load the config from there. A build older than the sources therefore keeps runs on the previous code.
+    const stale = staleDistFiles();
+    if (stale.length > 0) {
+        const shown = stale.slice(0, 3).join(', ');
+        warnings.push(`dist/ is out of date (${shown}${stale.length > 3 ? `, and ${stale.length - 3} more` : ''}): run "pnpm build". ` +
+            'Workspaces load playwright.config.ts from dist, so they keep the previous configuration until then.');
+    }
+    // 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(', ')})` : ''}`);
+    for (const name of overrides) {
+        const text = read(path.join(skillsDir, name)) ?? '';
+        // An override refines a skill's procedure; redefining a safety rule is never an override.
+        if (/^\s*[-*]?\s*\*{0,2}F[1-6]\b/m.test(text)) {
+            errors.push(`.claude/skills/${name} redefines a safety rule (F1–F6); project rules never change those.`);
+        }
+        const frameworkSkill = read(path.join(SKILLS_DIR, name.replace(/\.md$/, ''), 'SKILL.md'));
+        if (frameworkSkill !== null && text.trim() === frameworkSkill.trim()) {
+            warnings.push(`.claude/skills/${name} is a copy of the framework skill; delete it, or it will never see an update.`);
+        }
+    }
+    // Project rules: a project may narrow or replace a baseline rule, never one of F1–F6. Rows are
+    // `| <id> | <the project's rule> | <narrows|replaces> |`.
+    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();
+        const known = frameworkRuleIds();
+        let fenced = false;
+        for (const line of agents.split('\n')) {
+            // A fenced block is documentation (an example table), not the project's rules.
+            if (line.trim().startsWith('```')) {
+                fenced = !fenced;
+                continue;
+            }
+            if (fenced)
+                continue;
+            const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim());
+            if (!/^F\d+$/.test(cells[0]))
+                continue;
+            const id = cells[0];
+            const effect = (cells[2] ?? '').toLowerCase();
+            if (!known.has(id))
+                errors.push(`AGENTS.md names ${id}, which is not a rule of the framework baseline.`);
+            else if (locked.has(id))
+                errors.push(`AGENTS.md changes ${id}, which the framework marks [non-negotiable].`);
+            else if (effect === '')
+                warnings.push(`AGENTS.md rule ${id} has no Effect column: add "narrows" or "replaces" (a table written before 0.3.0 predates it).`);
+            else if (effect !== 'narrows' && effect !== 'replaces')
+                errors.push(`AGENTS.md rule ${id} has Effect "${cells[2]}"; use "narrows" or "replaces".`);
+        }
+    }
+    // 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".`);
+    }
+    // The agent CLIs the AI commands start. Only those commands need one, so a missing one is a warning, not an error.
+    // Checked the way the web UI starts them, so a Windows `.cmd` shim is reported instead of failing later.
+    const tools = ['claude', 'opencode']
+        .map((name) => ({ name, target: spawnTarget(name) }))
+        .filter((tool) => tool.target !== null);
+    if (tools.length === 0) {
+        warnings.push('Neither "claude" (Claude Code) nor "opencode" was found on PATH: the AI commands (make cases, explore a case, generate a spec) cannot start.');
+    }
+    else {
+        facts.push(`ai tools:  ${tools
+            .map((tool) => `${tool.name} -> ${tool.target.path}${tool.target.throughShell ? ' (through cmd.exe)' : ''}`)
+            .join(', ')}`);
+    }
+    // The MCP servers the AI commands explore with: OpenCode reads only `opencode.jsonc`, Claude Code only `.mcp.json`.
+    for (const [file, tool] of [
+        ['.mcp.json', 'Claude Code'],
+        ['opencode.jsonc', 'OpenCode'],
+    ]) {
+        const text = read(path.join(ROOT, file));
+        if (text === null) {
+            warnings.push(`${file} is missing: ${tool} has no "playwright-test" MCP server. Run "pnpm asrun init".`);
+            continue;
+        }
+        if (!text.includes('playwright-test')) {
+            warnings.push(`${file} does not define the "playwright-test" MCP server: run "pnpm asrun init --force ${file}".`);
+            continue;
+        }
+        const command = /"command"\s*:\s*(?:\[\s*)?"([^"]*playwright[^"]*)"/.exec(text)?.[1];
+        if (command !== undefined && !fs.existsSync(path.resolve(ROOT, command)) && !fs.existsSync(path.resolve(ROOT, `${command}.cmd`))) {
+            warnings.push(`${file} starts the MCP server with "${command}", which does not exist: run "pnpm asrun init --force ${file}".`);
+        }
+    }
+    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,75 @@
+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.`);
+// Chromium keeps its process alive after the last window is closed, so waiting for `disconnected` alone
+// never finishes. Closing the last window does close its pages, and that is the signal to stop.
+await new Promise((resolve) => {
+    let settled = false;
+    const done = () => {
+        if (settled)
+            return;
+        settled = true;
+        resolve();
+    };
+    browser.on('disconnected', done);
+    context.on('close', done);
+    const watch = (open) => open.on('close', () => {
+        if (context.pages().length === 0)
+            done();
+    });
+    context.pages().forEach(watch);
+    context.on('page', watch);
+});
+// The window is gone, but its browser process can still be running: end it so no orphan process is left.
+await browser.close().catch(() => { });
+console.log('Browser closed.');

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