@asrunjs/asrun 0.0.0-stage → 0.2.0

package/dist/scripts/render-pdf.d.ts

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

package/dist/scripts/render-pdf.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { corner, openPdf, selectPages } from '../lib/pdf.js';
+import { ROOT } from '../lib/paths.js';
+// Renders the pages of a PDF to PNG files and prints the text of each page, so an exploring agent can LOOK at the
+// pages (open the images) before it writes a target card for a PDF check. It never opens a browser and writes only
+// below `.explore/`.
+const args = process.argv.slice(2);
+const option = (name) => {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+};
+const file = args.find((arg) => !arg.startsWith('--') && arg !== option('--out') && arg !== option('--pages') && arg !== option('--corner'));
+const out = option('--out');
+const pagesArg = option('--pages') ?? 'all';
+const cornerArg = option('--corner');
+if (!file || !out) {
+    console.error('Usage: pnpm pdf:render <file.pdf> --out .explore/targets/<case-id>/<name> [--pages all|first|last|1,3] [--corner top-left|top-right|bottom-left|bottom-right]\n' +
+        'Writes <out>-p<page>.png (the whole page) and, with --corner, <out>-p<page>-<corner>.png (that corner only).');
+    process.exit(1);
+}
+const outBase = path.resolve(ROOT, out);
+if (!outBase.startsWith(path.join(ROOT, '.explore') + path.sep)) {
+    console.error('--out must be inside .explore/ (it is git-ignored, the pages are of logged-in accounts).');
+    process.exit(1);
+}
+const selection = pagesArg === 'all' || pagesArg === 'first' || pagesArg === 'last' ? pagesArg : pagesArg.split(',').map(Number);
+const pdf = await openPdf(fs.readFileSync(path.resolve(file)));
+fs.mkdirSync(path.dirname(outBase), { recursive: true });
+console.log(`${path.basename(file)}: ${pdf.pageCount} page(s)`);
+for (const page of selectPages(selection, pdf.pageCount)) {
+    const whole = await pdf.render(page);
+    const target = `${outBase}-p${page}.png`;
+    fs.writeFileSync(target, whole.png);
+    console.log(`\npage ${page}: ${path.relative(ROOT, target)} (${whole.width}x${whole.height})`);
+    if (cornerArg) {
+        const part = await pdf.render(page, corner(cornerArg));
+        const partFile = `${outBase}-p${page}-${cornerArg}.png`;
+        fs.writeFileSync(partFile, part.png);
+        console.log(`  ${cornerArg}: ${path.relative(ROOT, partFile)}  ink ${(part.inkRatio * 100).toFixed(1)}%${part.inkRatio < 0.002 ? '  (BLANK)' : ''}`);
+    }
+    console.log(`  text: ${pdf.texts[page - 1].slice(0, 300) || '(none)'}`);
+}
+await pdf.close();

package/dist/scripts/report.d.ts

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

package/dist/scripts/report.js

@@ -0,0 +1,14 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ROOT } from '../lib/paths.js';
+import { commandScript } from '../lib/node-cli.js';
+const latestHtml = path.join(ROOT, 'reports', 'latest', 'html');
+if (!fs.existsSync(latestHtml)) {
+    console.error('No report yet. Run: pnpm asrun');
+    process.exit(1);
+}
+spawnSync(process.execPath, [commandScript('@playwright/test', 'playwright'), 'show-report', latestHtml], {
+    cwd: ROOT,
+    stdio: 'inherit',
+});

package/dist/scripts/review-baselines.d.ts

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

package/dist/scripts/review-baselines.js

@@ -0,0 +1,30 @@
+import { listBaselines } from '../lib/baselines.js';
+import { listCaseFileIds } from '../lib/cases.js';
+// Lists the screenshot baselines of the specs, marks the ones that are new or changed (git), and prints for each the
+// target card that says what the image must show. Opening and looking at each image is the review, and it is a
+// person's or an agent's job: this script only lines them up. It never writes anything.
+const onlyNew = process.argv.includes('--new');
+const wanted = process.argv.slice(2).filter((arg) => !arg.startsWith('-'));
+let problems = 0;
+let shown = 0;
+for (const item of listBaselines(wanted.length > 0 ? wanted.filter((id) => listCaseFileIds().includes(id)) : undefined)) {
+    if (onlyNew && !item.changed)
+        continue;
+    shown++;
+    console.log(`${item.changed ? 'NEW/CHANGED' : 'unchanged '}  ${item.rel}`);
+    if (item.problem) {
+        problems++;
+        console.log(`  PROBLEM: ${item.problem}`);
+    }
+    else if (item.card) {
+        console.log(`  must show (${item.card.id} ${item.card.name}): ${item.card.what ?? '(no "What")'}`);
+        console.log(`  where: ${item.card.where ?? '(none)'}`);
+        if (item.card.not)
+            console.log(`  must not show: ${item.card.not}`);
+        const page = /-p(\d+)-[^-]+-[^-]+-[^-]+\.png$/i.exec(item.file)?.[1];
+        if (page)
+            console.log(`  (a region of PDF page ${page}; pages: ${item.card.pages ?? 'all'}, region: ${item.card.region ?? '(see Where)'})`);
+    }
+}
+console.log(`\n${shown} baseline image(s) listed. Open every NEW/CHANGED image and compare it with "must show"; a baseline that shows something else (a content image instead of a logo) must be deleted, not kept.`);
+process.exit(problems > 0 ? 1 : 0);

package/dist/scripts/run.d.ts

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

package/dist/scripts/run.js

@@ -0,0 +1,423 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from '@playwright/test';
+import { listEnvs, listProfiles, loadProfiles } from '../lib/profiles.js';
+import readline from 'node:readline/promises';
+import { listCaseFileIds, listSuites } from '../lib/cases.js';
+import { ROOT } from '../lib/paths.js';
+import { commandScript } from '../lib/node-cli.js';
+import { RUN_SETTINGS_ENV } from '../lib/run-summary.js';
+import { describeLeftovers, findLeftovers } from '../lib/records.js';
+import { filterArgs } from '../lib/run-filters.js';
+import { ALLOW_WRITES_ENV, describeSkippedWriteCases, describeWriteCases, findWriteCases, isProtectedEnv, planRun, } from '../lib/write-gate.js';
+import { checkSession, formatNotLoggedIn, NOT_LOGGED_IN_ENV, skipProfileHint, } from '../lib/session.js';
+const USAGE = `Usage: pnpm asrun --env <env> [--profile a,b] [--skip-profile a,b] [--tag name] [--logged-in] [--suite name] [--grep text] [--read-only] [--allow-writes=<env>] [--update-baselines <case,case>] [--report-id <id>] [playwright options...]
+
+  --env is required and has no default (the environments are listed in profiles.yaml, e.g. production, staging).
+
+  pnpm asrun --env staging            all profiles, all cases
+  pnpm asrun --env production --profile example-production    one profile
+  pnpm asrun --env production --skip-profile example-production    all profiles except these
+  pnpm asrun --env production --tag us             only the profiles that carry the tag "us"
+  pnpm asrun --env production --logged-in         only the profiles that are logged in (the others are left out, not failed)
+  pnpm asrun --env production --suite smoke       only cases whose front matter lists "smoke" under "suites"
+                                         (comma-separated for several: --suite smoke,regression; a case in
+                                         both runs once). --priority is the old name of --suite.
+  pnpm asrun --env production --read-only         leave out the cases that write data (front matter "writes")
+  pnpm asrun --env production --allow-writes=production run cases that write data in production WITHOUT the prompt. For
+                                         people running unattended; AI agents must never add this flag.
+  pnpm asrun --env production --grep landing      one case (matches the test title)
+  pnpm asrun --env staging --grep documents --update-baselines documents/landing-page
+                                         run the chosen cases as usual, except the listed ones: those are run separately
+                                         and their screenshot baselines are overwritten with what the page shows now
+                                         (--update-snapshots=all). Look at the new images afterwards:
+                                         pnpm baselines:review <case-id>
+  pnpm asrun --env staging --ui       interactive mode
+  pnpm asrun --env production --step-text   overlay the current test step on the videos
+                                         (also --step-text=1|true|yes|on; off by default; 0|false|no|off disables)`;
+const TRUE_VALUES = ['1', 'true', 'yes', 'on'];
+const FALSE_VALUES = ['0', 'false', 'no', 'off'];
+const args = process.argv.slice(2);
+if (args.includes('--help')) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const passthrough = [];
+let env;
+let selectedProfiles = [];
+let skippedProfiles = [];
+let selectedTags = [];
+let selectedSuites = [];
+let readOnly = false;
+let loggedInOnly = false;
+let allowWrites;
+let userGrep;
+let stepText = false;
+let updateBaselines = [];
+let reportId;
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--env') {
+        env = args[++i];
+    }
+    else if (arg.startsWith('--env=')) {
+        env = arg.slice('--env='.length);
+    }
+    else if (arg === '--profile') {
+        selectedProfiles = (args[++i] ?? '').split(',').filter(Boolean);
+    }
+    else if (arg.startsWith('--profile=')) {
+        selectedProfiles = arg.slice('--profile='.length).split(',').filter(Boolean);
+    }
+    else if (arg === '--skip-profile') {
+        skippedProfiles = (args[++i] ?? '').split(',').filter(Boolean);
+    }
+    else if (arg.startsWith('--skip-profile=')) {
+        skippedProfiles = arg.slice('--skip-profile='.length).split(',').filter(Boolean);
+    }
+    else if (arg === '--tag') {
+        selectedTags = (args[++i] ?? '').split(',').filter(Boolean);
+    }
+    else if (arg.startsWith('--tag=')) {
+        selectedTags = arg.slice('--tag='.length).split(',').filter(Boolean);
+    }
+    else if (arg === '--suite' || arg === '--priority') {
+        selectedSuites = (args[++i] ?? '').split(',').filter(Boolean);
+    }
+    else if (arg.startsWith('--suite=') || arg.startsWith('--priority=')) {
+        selectedSuites = arg.slice(arg.indexOf('=') + 1).split(',').filter(Boolean);
+    }
+    else if (arg === '--logged-in') {
+        loggedInOnly = true;
+    }
+    else if (arg === '--read-only') {
+        readOnly = true;
+    }
+    else if (arg.startsWith('--allow-writes=')) {
+        allowWrites = arg.slice('--allow-writes='.length);
+    }
+    else if (arg === '--allow-writes') {
+        console.error('--allow-writes needs the environment it applies to, e.g. --allow-writes=production');
+        process.exit(1);
+    }
+    else if (arg === '--report-id') {
+        reportId = args[++i];
+    }
+    else if (arg.startsWith('--report-id=')) {
+        reportId = arg.slice('--report-id='.length);
+    }
+    else if (arg === '--update-baselines') {
+        updateBaselines = (args[++i] ?? '').split(',').filter(Boolean);
+    }
+    else if (arg.startsWith('--update-baselines=')) {
+        updateBaselines = arg.slice('--update-baselines='.length).split(',').filter(Boolean);
+    }
+    else if (arg === '--grep' || arg === '-g') {
+        userGrep = args[++i];
+    }
+    else if (arg.startsWith('--grep=')) {
+        userGrep = arg.slice('--grep='.length);
+    }
+    else if (arg === '--step-text' || arg.startsWith('--step-text=')) {
+        // A bare flag means true; an explicit value may follow as `=value` or as the next argument.
+        let value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : undefined;
+        if (value === undefined && [...TRUE_VALUES, ...FALSE_VALUES].includes(args[i + 1]?.toLowerCase())) {
+            value = args[++i];
+        }
+        value = (value ?? 'true').toLowerCase();
+        if (!TRUE_VALUES.includes(value) && !FALSE_VALUES.includes(value)) {
+            console.error(`Invalid value for --step-text: "${value}". Use 1/true/yes/on or 0/false/no/off.`);
+            process.exit(1);
+        }
+        stepText = TRUE_VALUES.includes(value);
+    }
+    else {
+        passthrough.push(arg);
+    }
+}
+const allProfiles = loadProfiles();
+if (allProfiles.length === 0) {
+    console.error('profiles.yaml has no profiles. Add one entry per environment (see the comments in the file), ' +
+        'then log in with "pnpm signin <profile-id>".');
+    process.exit(1);
+}
+const knownProfileIds = allProfiles.map((profile) => profile.id);
+const knownEnvs = listEnvs(allProfiles);
+const listOnly = passthrough.includes('--list');
+if (!env && !listOnly) {
+    console.error(`Choose the environment to test: --env <env>  (${knownEnvs.join(' | ')}). There is no default.\n` +
+        `Example: pnpm asrun --env ${knownEnvs.includes('staging') ? 'staging' : (knownEnvs[0] ?? '<env>')}`);
+    process.exit(1);
+}
+if (env && !knownEnvs.includes(env)) {
+    console.error(`Unknown environment "${env}". Known: ${knownEnvs.join(', ')}`);
+    process.exit(1);
+}
+const unknown = [...selectedProfiles, ...skippedProfiles].filter((id) => !knownProfileIds.includes(id));
+if (unknown.length > 0) {
+    console.error(`Unknown profile(s): ${unknown.join(', ')}. Known: ${knownProfileIds.join(', ') || '(none)'}`);
+    process.exit(1);
+}
+const knownTags = [...new Set(allProfiles.flatMap((profile) => profile.tags))].sort();
+const unknownTags = selectedTags.filter((tag) => !knownTags.includes(tag));
+if (unknownTags.length > 0) {
+    console.error(`Unknown tag(s): ${unknownTags.join(', ')}. Used by the profiles: ${knownTags.join(', ') || '(none)'}`);
+    process.exit(1);
+}
+const unknownCases = updateBaselines.filter((id) => !listCaseFileIds().includes(id));
+if (unknownCases.length > 0) {
+    console.error(`--update-baselines: unknown case(s): ${unknownCases.join(', ')}`);
+    process.exit(1);
+}
+if (updateBaselines.length > 0 && passthrough.some((arg) => arg === '-u' || arg.startsWith('--update-snapshots'))) {
+    console.error('--update-baselines already sets --update-snapshots for the listed cases; do not pass both.');
+    process.exit(1);
+}
+const knownSuites = listSuites();
+const unknownSuites = selectedSuites.filter((name) => !knownSuites.includes(name));
+if (unknownSuites.length > 0) {
+    console.error(`Unknown suite: ${unknownSuites.join(', ')}. Used by the cases: ${knownSuites.join(', ')}`);
+    process.exit(1);
+}
+if (allowWrites !== undefined && allowWrites !== env) {
+    console.error(`--allow-writes=${allowWrites} does not match --env ${env ?? '(none)'}. Name the environment you mean.`);
+    process.exit(1);
+}
+if (readOnly && allowWrites) {
+    console.error('--read-only and --allow-writes cannot be combined.');
+    process.exit(1);
+}
+// Login is not a test case: a profile without a valid session cannot be tested, so find out up front.
+const profilesInEnv = listProfiles(env);
+const profilesWithTags = selectedTags.length > 0
+    ? profilesInEnv.filter((profile) => profile.tags.some((tag) => selectedTags.includes(tag)))
+    : profilesInEnv;
+const taggedIds = profilesWithTags.map((profile) => profile.id);
+const noEnvProfiles = selectedProfiles.filter((id) => env && !taggedIds.includes(id));
+if (noEnvProfiles.length > 0) {
+    const reason = selectedTags.length > 0 ? `no tag ${selectedTags.join(', ')}` : `no "${env}" environment`;
+    console.error(`Profile(s) with ${reason} in profiles.yaml: ${noEnvProfiles.join(', ')}`);
+    process.exit(1);
+}
+let profilesToRun = (selectedProfiles.length > 0 ? selectedProfiles : taggedIds).filter((id) => !skippedProfiles.includes(id));
+if (profilesToRun.length === 0) {
+    console.error('No profile left to test: every profile was skipped.');
+    process.exit(1);
+}
+// A failed check (network error, timeout) says nothing about the login, so it is retried and, if it keeps
+// failing, left for the workers to re-check instead of being reported as an expired session.
+async function checkWithRetry(browser, profile, attempts = 3) {
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await checkSession(browser, profile);
+        }
+        catch {
+            if (attempt < attempts)
+                await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+        }
+    }
+    return 'unknown';
+}
+const notLoggedIn = new Map();
+const unverified = [];
+// The list of tests needs neither a browser nor a login.
+if (!listOnly) {
+    const browser = await chromium.launch();
+    try {
+        const checks = await Promise.all(profilesInEnv
+            .filter((profile) => profilesToRun.includes(profile.id))
+            .map(async (profile) => [profile.id, await checkWithRetry(browser, profile)]));
+        for (const [id, status] of checks) {
+            if (status === 'unknown')
+                unverified.push(id);
+            else if (status !== 'ok')
+                notLoggedIn.set(id, status);
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}
+if (unverified.length > 0) {
+    console.error(`Could not verify the login of: ${unverified.join(', ')} (network problem?). ` +
+        'Each test worker will check again before running.\n');
+}
+if (notLoggedIn.size > 0 && loggedInOnly) {
+    const left = [...notLoggedIn.entries()].map(([id, status]) => `${id} (${status})`).join(', ');
+    console.log(`Skipped, not logged in (--logged-in): ${left}\n`);
+    profilesToRun = profilesToRun.filter((id) => !notLoggedIn.has(id));
+    if (profilesToRun.length === 0) {
+        console.error('No profile left to test: none of the chosen profiles is logged in.');
+        process.exit(1);
+    }
+}
+else if (notLoggedIn.size > 0) {
+    console.error('Not logged in (tests for these profiles will FAIL):');
+    for (const [id, status] of notLoggedIn) {
+        console.error(`  ${id.padEnd(24)} ${status.padEnd(8)} -> pnpm signin ${id}`);
+    }
+    console.error(`Or skip them for this run:  ${skipProfileHint([...notLoggedIn.keys()], env)}\n`);
+}
+// Which tests will run, as Playwright selects them. Always leaves out the @seed helper test.
+const profilesFilter = selectedProfiles.length > 0 || skippedProfiles.length > 0 || selectedTags.length > 0 || loggedInOnly;
+const filters = {
+    env: env ?? '',
+    profiles: profilesFilter ? profilesToRun : null,
+    suites: selectedSuites,
+    grep: userGrep,
+    readOnly,
+};
+const selectionArgs = filterArgs(filters);
+// Permission to write test data. A case writes only in the environments it lists under `writes`; anywhere else
+// it is skipped with a notice (not failed). Staging needs no confirmation. In any other environment a human has to
+// confirm, every time: by typing the environment name, or up front with --allow-writes=<env> (for unattended runs).
+// An AI agent has no terminal, so the prompt refuses to continue there; agents must not add the flag.
+let writesAllowedIn;
+if (env && !listOnly) {
+    const { writing: writeCases, skipped } = findWriteCases(filters);
+    if (skipped.length > 0 && !readOnly)
+        console.log(`\n${describeSkippedWriteCases(env, skipped)}\n`);
+    if (writeCases.length > 0 && isProtectedEnv(env)) {
+        if (allowWrites === env) {
+            console.log(`${describeWriteCases(env, writeCases)}\nPermission given with --allow-writes=${env}.\n`);
+            writesAllowedIn = env;
+        }
+        else if (process.stdin.isTTY && process.stdout.isTTY) {
+            console.log(`\n\x1b[41;97;1m WRITE CASES IN ${env.toUpperCase()} \x1b[0m\n${describeWriteCases(env, writeCases)}\n`);
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const answer = (await rl.question(`Type "${env}" to run them, or anything else to cancel: `)).trim();
+            rl.close();
+            if (answer !== env) {
+                console.error('Cancelled. Nothing was run. (Leave these cases out with --read-only.)');
+                process.exit(1);
+            }
+            writesAllowedIn = env;
+        }
+        else {
+            console.error(`${describeWriteCases(env, writeCases)}\n\n` +
+                `Refusing to run: these cases write data in ${env.toUpperCase()} and nobody confirmed it.\n` +
+                `  - leave them out:   add --read-only\n` +
+                `  - run them anyway:  a person adds --allow-writes=${env} (AI agents must not)\n` +
+                `  - or test in staging: --env staging`);
+            process.exit(1);
+        }
+    }
+}
+let phases = [{ suffix: '', selection: selectionArgs, extra: [] }];
+if (updateBaselines.length > 0 && !listOnly) {
+    const planned = await planRun(filters);
+    const runnable = planned.filter((item) => item.skip === null).map((item) => item.id);
+    const notInRun = updateBaselines.filter((id) => !runnable.includes(id));
+    if (notInRun.length > 0) {
+        console.error(`--update-baselines: ${notInRun.join(', ')} would not run with these filters (not selected, or skipped in ${env?.toUpperCase()}).`);
+        process.exit(1);
+    }
+    const rest = planned.map((item) => item.id).filter((id) => !updateBaselines.includes(id));
+    phases = [
+        ...(rest.length > 0 ? [{ suffix: '', selection: filterArgs({ ...filters, only: rest }), extra: [], only: rest }] : []),
+        {
+            suffix: '-baselines',
+            selection: filterArgs({ ...filters, only: updateBaselines }),
+            extra: ['--update-snapshots=all'],
+            label: `Updating the screenshot baselines of: ${updateBaselines.join(', ')}`,
+            only: updateBaselines,
+        },
+    ];
+}
+// The environment is part of the run id, so it shows in the report folder, the UI and every path.
+// The UI passes its own id, so it can link to the report of the job before the run has finished.
+const baseRunId = reportId ?? `${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}-${env ?? 'list'}`;
+// Started with the current Node: the shim in `node_modules/.bin` is a shell script on Windows.
+const PHASE_SCRIPT = commandScript('@playwright/test', 'playwright');
+// The permission must come from the confirmation above, never from a variable that was already in the shell.
+const childEnv = { ...process.env };
+delete childEnv[ALLOW_WRITES_ENV];
+function runPhase(phase) {
+    const runId = `${baseRunId}${phase.suffix}`;
+    if (phase.label)
+        console.log(`\n=== ${phase.label} ===`);
+    if (env && !listOnly) {
+        const text = ` ENV: ${env.toUpperCase()} `;
+        const color = env === 'production' ? '\x1b[41;97;1m' : '\x1b[44;97;1m';
+        console.log(`\n${process.stdout.isTTY ? `${color}${text}\x1b[0m` : text.trim()}  ${profilesInEnv
+            .filter((profile) => profilesToRun.includes(profile.id))
+            .map((profile) => profile.baseURL)
+            .join('  ')}\n`);
+    }
+    const result = spawnSync(process.execPath, [PHASE_SCRIPT, 'test', ...phase.selection, ...phase.extra, ...passthrough], {
+        cwd: ROOT,
+        stdio: 'inherit',
+        env: {
+            ...childEnv,
+            ASRUN_RUN_ID: runId,
+            ...(env && { ASRUN_ENV: env }),
+            ...(writesAllowedIn && { [ALLOW_WRITES_ENV]: writesAllowedIn }),
+            ASRUN_STEP_TEXT: stepText ? '1' : '0',
+            [RUN_SETTINGS_ENV]: JSON.stringify({
+                stepText,
+                readOnly,
+                profiles: filters.profiles,
+                suites: selectedSuites,
+                ...(selectedTags.length > 0 && { tags: selectedTags }),
+                ...(userGrep && { grep: userGrep }),
+                ...(phase.only && { only: phase.only }),
+            }),
+            [NOT_LOGGED_IN_ENV]: formatNotLoggedIn(notLoggedIn),
+        },
+    });
+    if (passthrough.includes('--list')) {
+        // Nothing ran, so there are no recordings and the reporters' empty output must not become "latest".
+        fs.rmSync(path.join(ROOT, 'reports', runId), { recursive: true, force: true });
+        return result.status ?? 1;
+    }
+    const resultsDir = path.join(ROOT, '.tmp', 'results');
+    const recordings = [];
+    if (fs.existsSync(resultsDir)) {
+        for (const entry of fs.readdirSync(resultsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const files = fs
+                .readdirSync(path.join(resultsDir, entry.name))
+                .filter((name) => name.endsWith('.webm') || name === 'trace.zip')
+                .sort();
+            if (files.length > 0)
+                recordings.push({ testDir: entry.name, files });
+        }
+    }
+    if (recordings.length > 0) {
+        console.log('\nRecordings (overwritten by the next run):');
+        for (const { testDir, files } of recordings) {
+            console.log(`  ${testDir}`);
+            for (const file of files) {
+                const full = path.join(resultsDir, testDir, file);
+                console.log(`    ${file === 'trace.zip' ? 'trace:' : 'video:'} ${full}`);
+            }
+            if (files.includes('trace.zip')) {
+                console.log(`    open trace: pnpm exec playwright show-trace ${path.join(resultsDir, testDir, 'trace.zip')}`);
+            }
+        }
+    }
+    const leftovers = findLeftovers({ runId });
+    if (leftovers.length > 0) {
+        console.error(`\nTEST DATA LEFT BEHIND in ${env?.toUpperCase()}: delete it by hand, then run "pnpm cleanup --env ${env} --forget"\n${describeLeftovers(leftovers)}`);
+    }
+    const reportDir = path.join(ROOT, 'reports', runId, 'html');
+    if (fs.existsSync(reportDir)) {
+        const latest = path.join(ROOT, 'reports', 'latest');
+        fs.rmSync(latest, { force: true });
+        fs.symlinkSync(path.join(ROOT, 'reports', runId), latest);
+        console.log(`\nReport (videos, screenshots, traces): pnpm report`);
+    }
+    return result.status ?? 1;
+}
+let exitCode = 0;
+for (const phase of phases) {
+    const status = runPhase(phase);
+    if (status !== 0)
+        exitCode = status;
+}
+if (updateBaselines.length > 0 && !listOnly) {
+    console.log(`\nBaselines rewritten for: ${updateBaselines.join(', ')}. Open the new images before you keep them: pnpm baselines:review ${updateBaselines.join(' ')}`);
+}
+process.exit(exitCode);

package/dist/scripts/status.d.ts

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

package/dist/scripts/status.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { chromium } from '@playwright/test';
+import { listEnvs, listProfiles } from '../lib/profiles.js';
+import { authFile } from '../lib/paths.js';
+import { checkSession, signinCommand } from '../lib/session.js';
+const args = process.argv.slice(2);
+const envArg = args.find((arg) => arg.startsWith('--env='))?.slice('--env='.length) ?? (args.includes('--env') ? args[args.indexOf('--env') + 1] : undefined);
+if (envArg && !listEnvs().includes(envArg)) {
+    console.error(`Unknown environment "${envArg}". Known: ${listEnvs().join(', ')}`);
+    process.exit(1);
+}
+const rows = listProfiles(envArg);
+if (rows.length === 0) {
+    console.log(`No profiles${envArg ? ` for ${envArg.toUpperCase()}` : ''}. Add one to profiles.yaml first.`);
+    process.exit(0);
+}
+const browser = await chromium.launch();
+const failing = [];
+console.log('Profile                  Env        Account              Session   Saved at');
+for (const profile of rows) {
+    const status = await checkSession(browser, profile);
+    const file = authFile(profile.id);
+    const savedAt = fs.existsSync(file) ? fs.statSync(file).mtime.toLocaleString() : '-';
+    console.log(`${profile.id.padEnd(24)} ${profile.env.padEnd(10)} ${(profile.account ?? '-').padEnd(20)} ${status.padEnd(9)} ${savedAt}`);
+    if (status !== 'ok')
+        failing.push(profile);
+}
+await browser.close();
+if (failing.length > 0) {
+    console.log(`\nFix with: ${signinCommand({ id: '<profile-id>' })}`);
+}

package/dist/scripts/ui-build.d.ts

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

package/dist/scripts/ui-build.js

@@ -0,0 +1,7 @@
+import { buildUi } from '../lib/ui-build.js';
+const status = buildUi();
+if (status === null) {
+    console.error('No front-end toolchain here: the web UI can only be built in the framework repository.');
+    process.exit(1);
+}
+process.exit(status);

package/dist/scripts/ui-dev.d.ts

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

package/dist/scripts/ui-dev.js

@@ -0,0 +1,3 @@
+// Vite dev server plus the API in watch mode.
+await import('../ui/dev.js');
+export {};

package/dist/scripts/ui.d.ts

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

package/dist/scripts/ui.js

@@ -0,0 +1,13 @@
+import { buildUi, uiIsBuilt } from '../lib/ui-build.js';
+// An installed package ships the built app; the framework repository builds it (or refreshes it with `asrun ui --build`).
+if (!uiIsBuilt() || process.argv.includes('--build')) {
+    const status = buildUi();
+    if (status === null) {
+        console.error('This asrun installation has no built web UI. Reinstall it: "pnpm add -D @asrunjs/asrun".');
+        process.exit(1);
+    }
+    if (status !== 0)
+        process.exit(status);
+}
+// Serves the built app and the API on one port (see ui/server/index.ts).
+await import('../ui/server/index.js');

package/dist/ui/dev.d.ts

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

package/dist/ui/dev.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { commandScript } from '../lib/node-cli.js';
+import { FRAMEWORK_ROOT, ROOT } from '../lib/paths.js';
+const webPort = process.env.ASRUN_UI_WEB_PORT ?? '5173';
+const tools = [
+    {
+        name: 'tsx',
+        script: commandScript('tsx'),
+        args: ['watch', path.join(FRAMEWORK_ROOT, 'ui', 'server', 'index.ts')],
+        env: { ...process.env, ASRUN_UI_DEV_ORIGIN: `http://127.0.0.1:${webPort}` },
+    },
+    {
+        name: 'vite',
+        script: commandScript('vite'),
+        args: ['--config', path.join(FRAMEWORK_ROOT, 'ui', 'web', 'vite.config.ts')],
+        env: process.env,
+    },
+];
+const children = [];
+const stop = () => children.forEach((child) => child.kill('SIGTERM'));
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);
+for (const tool of tools) {
+    const child = spawn(process.execPath, [tool.script, ...tool.args], { cwd: ROOT, stdio: 'inherit', env: tool.env });
+    children.push(child);
+    child.on('error', (error) => {
+        console.error(`Failed to start ${tool.name}: ${error.message}`);
+        stop();
+        process.exit(1);
+    });
+    child.on('exit', (code) => {
+        stop();
+        process.exit(code ?? 0);
+    });
+}