tinybeeai 0.0.0-stage → 0.16.1

package/dist/runner/index.js

@@ -0,0 +1,1221 @@
+import { existsSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { config } from '../config.js';
+import { publish } from '../events.js';
+import { githubFor } from '../integrations/github.js';
+import { defaultBranchOf, pickMergeBranch, readPullHead, unlistedBranchNote, verifyCommit } from './verify.js';
+import { targetRepo } from '../repos.js';
+import { currentRunId } from '../queue.js';
+import { killTrackedFor, runTracked, spawnTrackedPiped, terminate } from '../proc.js';
+import { isRunCancelled } from '../agent/runs.js';
+import { redact } from '../agent/redact.js';
+import { CdpGrabber, FrameThrottle, appendArtifact, artifactUrl, collectOutputFiles, copyArtifact, freePort, outputArtifactName, leasePorts, releasePorts, safeName, writeArtifact, } from './artifacts.js';
+import { reportTests, stripAnsi } from './playwright-json.js';
+import { adapterFor } from './adapters/index.js';
+import { playwrightVersion } from './adapters/playwright.js';
+import { MARKER, parseMarkerLine } from './step-reporter.js';
+import { cancelAiVision, runAiVision } from './aivision/index.js';
+import { cancelPwgen } from './pwgen/index.js';
+import { DEFAULT_INSTALL, forwardingArgv, parseCommand, scriptRun, shQuote, splitSetupSteps } from './command.js';
+import { runSetup } from './setup.js';
+import { writePlaywrightObservations } from './observe.js';
+import { collectEvidence, normTitle } from './evidence.js';
+import { copyFilesHint, copyFilesHintFiles, copyFilesIntoWorktree, untrackedDotfiles } from './copyfiles.js';
+import { prepareWorktree, scrubReason } from './worktree.js';
+import { hostVars, passEnvVars, valueMasker } from './host-env.js';
+import { hideTypedValue } from './typed-value.js';
+import { checkoutTestRepo, effectiveRunner, testRepoRefusal } from './test-repo.js';
+// hostVars() is the one filter of the host environment; it lives in host-env.ts with the list of what it holds back.
+export { hostVars };
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** Setup steps (install, browsers, build) get their own budget on top of the test timeout. */
+const SETUP_TIMEOUT_MS = Number(process.env.LOCALDOST_SETUP_TIMEOUT_MS) || 15 * 60_000;
+const DEMO_DIR = path.join(config.demoDir, 'sample-app');
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PW_CONFIGS = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+/** Upper bounds per attempt so a long suite cannot flood the bus or the disk. */
+const MAX_FRAMES = 600;
+const MAX_LOG_EVENTS = 2000;
+/** Files never copied into the Docker test container. A private-registry .npmrc must come from the image. */
+export const SECRET_FILES = [
+    '.env',
+    '.env.*',
+    '*.env',
+    '.npmrc',
+    '.yarnrc',
+    '.yarnrc.yml',
+    '.netrc',
+    '.pgpass',
+    '.git-credentials',
+    '.aws',
+    '.ssh',
+    '.gnupg',
+    '.docker',
+    '.kube',
+    '.config/gcloud',
+    '.terraform',
+    '*.pem',
+    '*.key',
+    '*.p12',
+    '*.pfx',
+    '*.jks',
+    '*.keystore',
+    'id_rsa*',
+    'id_ed25519*',
+    'id_ecdsa*',
+    'credentials.json',
+    'service-account*.json',
+    '*.tfstate',
+    '*.tfvars',
+];
+/** Thrown by run() when the run was cancelled before or while the tests ran. */
+export class RunCancelledError extends Error {
+    runId;
+    constructor(runId) {
+        super('Run cancelled');
+        this.runId = runId;
+        this.name = 'RunCancelledError';
+    }
+}
+// ---------- process registry (cancel) ----------
+const activeProcs = new Map();
+const cancelRequested = new Set();
+const attempts = new Map();
+/** Kills the test process of a run (the whole process group, browsers included). Returns true when one was running. */
+export function cancelRunProcess(runId) {
+    cancelRequested.add(runId);
+    const pw = cancelPwgen(runId);
+    if (cancelAiVision(runId))
+        return true;
+    // Git clones and other tracked children of the run die with its test process.
+    const others = killTrackedFor(runId);
+    if (pw)
+        return true;
+    const kill = activeProcs.get(runId);
+    if (!kill)
+        return others > 0;
+    kill();
+    return true;
+}
+export function hasActiveProcess(runId) {
+    return activeProcs.has(runId);
+}
+function publishLive(e) {
+    publish(e);
+}
+/**
+ * Turns the step reporter's stdout markers into live events and artifacts for one attempt.
+ * Exported for tests: feed it lines with `line()` and read what it published.
+ */
+export class LiveSession {
+    runId;
+    attempt;
+    grabber;
+    emit;
+    titles = new Map();
+    projects = new Map();
+    retries = new Map();
+    frames;
+    frameCount = 0;
+    logCount = 0;
+    copied = new Map();
+    saved = [];
+    /** The `test.step` names of each test attempt, top level only (KAT-377). Key: retry and normalized title. */
+    named = new Map();
+    openSteps = new Map();
+    prefix;
+    constructor(runId, attempt, grabber, emit = publishLive, minFrameGapMs = 500) {
+        this.runId = runId;
+        this.attempt = attempt;
+        this.grabber = grabber;
+        this.emit = emit;
+        this.prefix = `a${attempt}`;
+        this.frames = new FrameThrottle((f) => this.sendFrame(f), minFrameGapMs);
+    }
+    /** Feeds one stdout or stderr line. Returns true when it was a reporter marker. */
+    line(raw) {
+        const ev = parseMarkerLine(raw);
+        if (ev) {
+            appendArtifact(this.runId, `${this.prefix}-steps.jsonl`, `${JSON.stringify({ at: new Date().toISOString(), ...ev })}\n`);
+            this.onEvent(ev);
+            return true;
+        }
+        const text = stripAnsi(raw).replace(/\s+$/, '');
+        if (!text)
+            return false;
+        appendArtifact(this.runId, `${this.prefix}-output.log`, `${text}\n`);
+        this.log(text);
+        return false;
+    }
+    log(line) {
+        if (this.logCount++ >= MAX_LOG_EVENTS)
+            return;
+        this.emit({ type: 'run_log', runId: this.runId, line: line.slice(0, 2000) });
+    }
+    step(label, status, detail, test, project) {
+        const step = { at: new Date().toISOString(), label: label.slice(0, 200), status };
+        if (detail)
+            step.detail = detail.slice(0, 1000);
+        if (test)
+            step.test = test.slice(0, 300);
+        if (test && project)
+            step.project = project.slice(0, 100);
+        this.emit({ type: 'run_step', runId: this.runId, step });
+    }
+    onEvent(ev) {
+        switch (ev.t) {
+            case 'begin':
+                this.log(`Running ${ev.total} test${ev.total === 1 ? '' : 's'}`);
+                break;
+            case 'test_begin':
+                this.titles.set(ev.test, ev.title);
+                this.retries.set(ev.test, ev.retry);
+                if (ev.project)
+                    this.projects.set(ev.test, ev.project);
+                this.step(`Test started: ${ev.title}`, 'info', `${path.basename(ev.file)}${ev.retry ? `, retry ${ev.retry}` : ''}`, ev.title, ev.project);
+                break;
+            case 'step_begin':
+                this.log(`> ${this.titles.get(ev.test) ?? ''}: ${hideTypedValue(ev.step)}`);
+                if (ev.category === 'test.step')
+                    this.openSteps.set(ev.test, (this.openSteps.get(ev.test) ?? 0) + 1);
+                break;
+            case 'step_end': {
+                const test = this.titles.get(ev.test) ?? '';
+                // A fill step is titled with the value it typed, a password included. The title goes into the step list, the live frame and the report as written
+                // below, so the value is hidden here, once, and the label of a frame still equals the name of the step it was taken after.
+                const title = hideTypedValue(ev.step);
+                if (ev.category === 'test.step') {
+                    const open = Math.max(0, (this.openSteps.get(ev.test) ?? 1) - 1);
+                    this.openSteps.set(ev.test, open);
+                    // Steps end last in, first out: a step that ends with none left open was a top-level one.
+                    if (open === 0)
+                        this.nameStep(ev.test, title, !!ev.error);
+                }
+                this.step(title, ev.error ? 'error' : 'ok', ev.error ? `${test}\n${hideTypedValue(ev.error)}` : test, test, this.projects.get(ev.test));
+                if (this.grabber && (ev.category === 'pw:api' || ev.category === 'test.step' || ev.category === 'expect')) {
+                    this.frames.offer({ test, ...this.where(ev.test), step: title });
+                }
+                break;
+            }
+            case 'test_end': {
+                const passed = ev.status === 'passed';
+                const status = passed ? 'ok' : ev.status === 'skipped' ? 'warn' : 'error';
+                const label = passed ? 'Test passed' : ev.status === 'skipped' ? 'Test skipped' : ev.status === 'timedOut' ? 'Test timed out' : 'Test failed';
+                this.step(`${label}: ${ev.title}`, status, ev.error ?? `${(ev.ms / 1000).toFixed(1)} s`, ev.title, ev.project ?? this.projects.get(ev.test));
+                const shot = ev.attachments.filter((a) => a.contentType.startsWith('image/')).pop();
+                if (shot)
+                    this.frames.offer({ test: ev.title, ...this.where(ev.test, ev.project), step: label, file: shot.path });
+                break;
+            }
+            case 'end':
+                this.log(`Playwright finished: ${ev.status}`);
+                break;
+        }
+    }
+    /** One key per attempt of one test in one project: two projects run the same title, and their steps must stay apart. */
+    nameKey(retry, title, project = '') {
+        return `${retry}\u0000${project}\u0000${normTitle(title)}`;
+    }
+    nameStep(id, step, failed = false) {
+        const key = this.nameKey(this.retries.get(id) ?? 0, this.titles.get(id) ?? '', this.projects.get(id));
+        const list = this.named.get(key) ?? [];
+        const label = step.replace(/\s+/g, ' ').trim().slice(0, 160);
+        const last = list[list.length - 1];
+        if (label && last?.name === label) {
+            if (failed)
+                last.failed = true;
+        }
+        else if (label && list.length < 12) {
+            list.push(failed ? { name: label, failed: true } : { name: label });
+        }
+        this.named.set(key, list);
+    }
+    /** The `test.step` blocks of the newest attempt of one test (in one project), by its report title, with the one that threw marked. */
+    namedSteps(title, project = '') {
+        for (let retry = 5; retry >= 0; retry--) {
+            const found = this.named.get(this.nameKey(retry, title, project));
+            if (found?.length)
+                return found.map((s) => ({ ...s }));
+        }
+        return undefined;
+    }
+    /** The `test.step` names of the newest attempt of one test (in one project), by its report title. Undefined when the test named none. */
+    stepNames(title, project = '') {
+        return this.namedSteps(title, project)?.map((s) => s.name);
+    }
+    /** The project and retry a test is running in, for the frames taken in it. */
+    where(id, project) {
+        return { project: project ?? this.projects.get(id), retry: this.retries.get(id) ?? 0 };
+    }
+    async sendFrame(f) {
+        if (this.frameCount >= MAX_FRAMES)
+            return true;
+        const at = new Date().toISOString();
+        const n = String(this.frameCount + 1).padStart(4, '0');
+        let name = null;
+        if (f.file) {
+            name = copyArtifact(this.runId, f.file, `${this.prefix}-frame-${n}-${safeName(f.test, 40)}${path.extname(f.file) || '.png'}`);
+            if (name)
+                this.copied.set(path.resolve(f.file), name);
+        }
+        else if (this.grabber) {
+            const buf = await this.grabber.capture();
+            if (buf)
+                name = writeArtifact(this.runId, `${this.prefix}-frame-${n}.jpg`, buf);
+        }
+        if (!name)
+            return false;
+        this.frameCount++;
+        this.saved.push({ title: f.test, project: f.project, retry: f.retry ?? 0, name, step: f.step });
+        this.emit({
+            type: 'run_frame',
+            runId: this.runId,
+            frame: { at, test: f.test, step: f.step, image: artifactUrl(this.runId, name), ...(f.project ? { project: f.project } : {}) },
+        });
+        return true;
+    }
+    /** Source files already stored as frames, so the end-of-run copy skips them. */
+    alreadyCopied(file) {
+        return this.copied.has(path.resolve(file));
+    }
+    /** The artifact name a copied source file was stored under. */
+    storedName(file) {
+        return this.copied.get(path.resolve(file));
+    }
+    /** The step screenshots saved so far, with the test each was taken in. */
+    shots() {
+        return this.saved;
+    }
+    async close() {
+        await this.frames.flush();
+        this.frames.stop();
+        this.grabber?.close?.();
+    }
+}
+/** Splits a byte stream into lines and hands each complete line to `fn`. */
+function lineSplitter(fn) {
+    let buf = '';
+    return {
+        push(chunk) {
+            buf += chunk;
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                fn(buf.slice(0, i).replace(/\r$/, ''));
+                buf = buf.slice(i + 1);
+            }
+            // A JSON report on stdout can be one very long line; do not hold megabytes waiting for a newline.
+            if (buf.length > 1_000_000) {
+                fn(buf);
+                buf = '';
+            }
+        },
+        end() {
+            if (buf)
+                fn(buf);
+            buf = '';
+        },
+    };
+}
+// ---------- Playwright wiring ----------
+/** Absolute path of the step reporter, .ts under tsx and .js in dist/. */
+export function stepReporterPath() {
+    const own = path.extname(fileURLToPath(import.meta.url)) || '.js';
+    for (const ext of [own, '.js', '.ts']) {
+        const p = path.join(HERE, `step-reporter${ext}`);
+        if (existsSync(p))
+            return p;
+    }
+    return undefined;
+}
+function readScripts(workdir) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(workdir, 'package.json'), 'utf8'));
+        return Object.fromEntries(Object.entries(pkg.scripts ?? {}).filter((e) => typeof e[1] === 'string'));
+    }
+    catch {
+        return {};
+    }
+}
+/** The package.json script an `npm run x` style argv calls, or undefined. */
+function scriptBody(argv, scripts) {
+    const call = scriptRun(argv, scripts);
+    return call ? scripts[call.name] : undefined;
+}
+/**
+ * Wrapper config that turns on screenshots, traces, video, and (optionally) the DevTools port. The video mode
+ * comes from LOCALDOST_VIDEO: retain-on-failure (the default) keeps the videos of tests that did not pass, on keeps
+ * all of them. A mode the repo's config sets itself (on, on-first-retry) stays unless the dot asks for on.
+ */
+export function wrapperConfigSource(baseFile) {
+    const spec = /\.m?ts$/.test(baseFile) ? `./${baseFile.replace(/\.m?ts$/, '')}` : `./${baseFile}`;
+    return `// Generated by localdost for one run and deleted when the run ends.
+import base from ${JSON.stringify(spec)};
+
+const port = process.env.LOCALDOST_CDP_PORT;
+const cfg = base || {};
+const chromium = (u) => !u.browserName && (!u.defaultBrowserType || u.defaultBrowserType === 'chromium') || u.browserName === 'chromium';
+const keep = (v, fallback) => (v && v !== 'off' ? v : fallback);
+const always = process.env.LOCALDOST_VIDEO === 'on';
+const live = (u) => {
+  const out = { ...u, screenshot: 'on', trace: keep(u.trace, 'retain-on-failure'), video: always ? 'on' : keep(u.video, 'retain-on-failure') };
+  if (port && chromium(u)) {
+    const lo = u.launchOptions || {};
+    out.launchOptions = { ...lo, args: [...(lo.args || []), '--remote-debugging-port=' + port] };
+  }
+  return out;
+};
+
+export default {
+  ...cfg,
+  ...(port ? { workers: 1 } : {}),
+  use: live(cfg.use || {}),
+  ...(Array.isArray(cfg.projects) ? { projects: cfg.projects.map((p) => ({ ...p, use: live({ ...(cfg.use || {}), ...(p.use || {}) }) })) } : {}),
+};
+`;
+}
+/** The config file a command line names with `--config x`, `--config=x`, `-c x`, or `-c=x`. The last one wins, as in Playwright. */
+export function configArgOf(words) {
+    let named;
+    words.forEach((w, i) => {
+        const eq = /^(?:--config|-c)=(.+)$/.exec(w);
+        const value = eq ? eq[1] : w === '--config' || w === '-c' ? words[i + 1] : undefined;
+        if (value && !value.startsWith('-'))
+            named = value.replace(/^(['"])(.*)\1$/, '$2');
+    });
+    return named;
+}
+function findPlaywrightConfig(workdir) {
+    return PW_CONFIGS.find((f) => existsSync(path.join(workdir, f)));
+}
+function liveFramesEnabled(mode) {
+    const flag = (process.env.LOCALDOST_LIVE_FRAMES ?? '').trim();
+    if (flag === '0' || flag === 'false')
+        return false;
+    if (flag === '1' || flag === 'true')
+        return mode !== 'docker';
+    return mode === 'demo';
+}
+/** Copies screenshots, traces, videos, and the JSON report into data/artifacts/<runId>/. */
+function saveOutputs(runId, prefix, outDir, live) {
+    const results = path.join(outDir, 'test-results');
+    for (const file of collectOutputFiles(results)) {
+        if (live?.alreadyCopied(file))
+            continue;
+        copyArtifact(runId, file, outputArtifactName(prefix, results, file));
+    }
+    const report = path.join(outDir, 'report.json');
+    if (existsSync(report))
+        copyArtifact(runId, report, `${prefix}-report.json`);
+}
+// ---------- run ----------
+/**
+ * Why the checkout at `dir` cannot give results for commit `sha`, or null when it can or when that cannot be
+ * told (a folder that is not a git checkout). The checkout's HEAD must be `sha`; short shas of 7 or more match.
+ */
+export async function staleCheckout(dir, sha) {
+    const r = await runTracked('git', ['rev-parse', '--verify', 'HEAD'], { cwd: dir, timeoutMs: 10_000, maxBuffer: 1000 });
+    const head = r.code === 0 ? r.stdout.trim().toLowerCase() : '';
+    if (!/^[0-9a-f]{40,64}$/.test(head))
+        return null;
+    const want = sha.trim().toLowerCase();
+    if (want.length >= 7 && (head === want || head.startsWith(want)))
+        return null;
+    return `The tests did not run for ${want.slice(0, 7)}: the checkout in the working folder is on ${head.slice(0, 7)}, so its tests would count results for other code. No test count is shown for this commit.`;
+}
+/**
+ * Renames the cases of a Playwright report from their path under the testDir (`config.rootDir` of the report) to their path under `root`,
+ * the checkout. A case whose file is not under `root` keeps its name.
+ */
+export function repoRelativeFiles(cases, json, root) {
+    const rootDir = json?.config?.rootDir;
+    if (typeof rootDir !== 'string' || !rootDir)
+        return;
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const base = real(root);
+    const tests = real(rootDir);
+    for (const c of cases) {
+        if (!c.file)
+            continue;
+        const rel = path.relative(base, path.join(tests, c.file));
+        if (rel && !rel.startsWith('..') && !path.isAbsolute(rel))
+            c.file = rel.split(path.sep).join('/');
+    }
+}
+/**
+ * Hides what a person must not read in one case of the report. The test login values are masked in the error text (Playwright's call log of a
+ * failed fill prints the value it typed), in the step names and in the label of each screenshot. The label of a screenshot is the title of the step
+ * it was taken after, so it can also name any value a test typed (`Fill "<value>"`), which is hidden whatever it is.
+ */
+export function maskCase(c, mask) {
+    if (c.error)
+        c.error = mask(c.error);
+    if (c.steps)
+        c.steps = c.steps.map(mask);
+    if (c.namedSteps)
+        c.namedSteps = c.namedSteps.map((b) => ({ ...b, name: mask(b.name) }));
+    if (c.evidence)
+        c.evidence.screenshots = c.evidence.screenshots.map((s) => (s.step ? { ...s, step: mask(hideTypedValue(s.step)) } : s));
+}
+/**
+ * Runs the tests of one spec. `onLine` gets every setup and command output line (reporter markers
+ * excluded), for callers without a run id such as Try it in the dot settings.
+ */
+export async function run(spec, opts = {}) {
+    const mode = spec.watch.runner.mode;
+    const runId = opts.runId ?? currentRunId();
+    if (runId && isRunCancelled(runId))
+        throw new RunCancelledError(runId);
+    const attempt = runId ? (attempts.get(runId) ?? 0) + 1 : 0;
+    if (runId)
+        attempts.set(runId, attempt);
+    // AI-Vision cases run on their own backend (src/runner/aivision), never through the Playwright command.
+    if (spec.aivision) {
+        try {
+            const report = await runAiVision(spec, { ...(runId ? { runId, isCancelled: () => isRunCancelled(runId) } : {}), attempt: attempt || 1 });
+            if (runId && (cancelRequested.has(runId) || isRunCancelled(runId)))
+                throw new RunCancelledError(runId);
+            return report;
+        }
+        finally {
+            if (runId)
+                cancelRequested.delete(runId);
+        }
+    }
+    const started = Date.now();
+    const startedAt = new Date(started).toISOString();
+    const baseUrl = spec.baseUrl ?? spec.watch.baseUrl;
+    const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const adapter = adapterFor(spec.testRepo?.config.framework);
+    const baseUrlEnv = spec.testRepo?.config.baseUrlEnv;
+    // A Tests repo run takes its command, setup, folder and test login from the Tests repo; every other run uses the dot's runner.
+    const runner = effectiveRunner(spec);
+    const rawCommand = runner.command?.trim() || adapter.defaultCommand;
+    const setupSteps = splitSetupSteps(runner.setup);
+    // The test login, set after the credential filter, and a mask for its values in everything a person reads.
+    const passVars = passEnvVars(runner.passEnv);
+    const mask = valueMasker(passVars);
+    const notRunReport = (notRun, tail, commandLine = rawCommand) => {
+        const r = {
+            mode,
+            command: commandLine,
+            startedAt,
+            durationMs: Date.now() - started,
+            passed: 0,
+            failed: 0,
+            flaky: 0,
+            skipped: 0,
+            cases: [],
+            stdoutTail: mask(redact(stripAnsi(tail).slice(-4000))),
+            notRun,
+        };
+        if (baseUrl)
+            r.baseUrl = baseUrl;
+        return r;
+    };
+    // The test command runs without a shell. A shell operator in it is a configuration error, not a test result.
+    const parsedCommand = parseCommand(rawCommand);
+    if (!parsedCommand.ok)
+        return notRunReport({ stage: 'command', reason: parsedCommand.error }, '');
+    const cmdVars = parsedCommand.env;
+    // A Tests repo run that must not start (no adapter for its framework, a fork PR outside Docker) ends here, before anything is fetched.
+    const refusal = spec.testRepo ? testRepoRefusal(spec.testRepo, mode, spec.watch.runner.passEnv) : null;
+    if (refusal)
+        return notRunReport({ stage: 'checkout', reason: refusal }, '');
+    const outDir = await mkdtemp(path.join(os.tmpdir(), 'localdost-out-'));
+    let cloneDir;
+    let worktree;
+    /** The working folder a worktree was made from: where runner.copyFiles are read, and where the failure hint looks (KAT-293). */
+    let worktreeSource;
+    let wrapperFile;
+    let live;
+    try {
+        // A Tests repo run starts from a worktree of the Tests repo at the commit that was resolved for it, checked before the tests run.
+        // It never clones or verifies the app repo: only the app's URL crosses over.
+        if (spec.testRepo) {
+            const tr = spec.testRepo;
+            const stopped = () => !!runId && (cancelRequested.has(runId) || isRunCancelled(runId));
+            const checkout = await checkoutTestRepo({
+                repo: tr.repo,
+                sha: tr.sha,
+                id: runId ? `${runId}-a${attempt}-tests` : `adhoc-tests-${process.pid}-${Date.now().toString(36)}`,
+                gh: githubFor(spec.watch, { repo: tr.repo }),
+                ...(runId ? { runId, cancelled: stopped } : {}),
+            });
+            if (stopped()) {
+                if (checkout.ok)
+                    await checkout.worktree.cleanup();
+                throw new RunCancelledError(runId);
+            }
+            if (!checkout.ok)
+                return notRunReport({ stage: 'checkout', reason: checkout.reason }, '');
+            worktree = checkout.worktree;
+        }
+        let workdir = worktree ? worktree.dir : mode === 'demo' ? (runner.workdir ?? DEMO_DIR) : runner.workdir;
+        const cloneEvent = spec.repo ? { repo: spec.repo } : undefined;
+        const cloneRepo = workdir ? null : targetRepo(spec.watch, cloneEvent);
+        if (!workdir && cloneRepo) {
+            // No local checkout configured: clone the commit of the event's repo on the host, then mount it.
+            const gh = githubFor(spec.watch, cloneEvent);
+            if (spec.sha) {
+                // Nothing is fetched or run until GitHub confirms the commit (KAT-291). The event's own fork flag and branch name are not trusted.
+                const target = spec.pr
+                    ? { kind: 'pr', number: spec.pr.number }
+                    : { kind: 'default_branch', ...(spec.merge?.branch ? { named: spec.merge.branch } : {}), testBranches: spec.watch.testBranches };
+                const check = await verifyCommit(gh, cloneRepo, spec.sha, target);
+                if (!check.ok)
+                    return notRunReport({ stage: 'verify', reason: check.reason }, '');
+            }
+            cloneDir = await mkdtemp(path.join(os.tmpdir(), 'localdost-src-'));
+            await gh.cloneTo(cloneDir, spec.sha ?? '');
+            workdir = cloneDir;
+        }
+        if (!workdir)
+            throw new Error(`Watch ${spec.watch.name} has no runner.workdir and no repo to clone`);
+        workdir = path.resolve(workdir);
+        // A configured checkout runs whatever commit it is on, so a run for a commit (a PR head or a merge) must
+        // be on that commit or its results belong to other code (KAT-284).
+        if (!spec.testRepo && !cloneDir && mode !== 'demo' && spec.sha && (spec.pr || spec.merge)) {
+            // A pull request of a fork never runs here: fork code stays off this machine (KAT-201) unless the dot trusts forks.
+            if (spec.pr?.fork && !runner.trustForks) {
+                return notRunReport({
+                    stage: 'checkout',
+                    reason: `The tests did not run for ${spec.sha.slice(0, 7)}: PR #${spec.pr.number} comes from a fork, and localdost does not run fork code on this machine. No test count is shown for this commit.`,
+                    fork: true,
+                }, '');
+            }
+            // A pull request of the repo itself, or a merge commit of its base branch, runs in a temporary worktree of the
+            // working folder at that commit. The folder's own checkout and branch stay as they are; the worktree is removed in the finally below.
+            const repo = targetRepo(spec.watch, cloneEvent);
+            if (repo && !spec.pr?.fork) {
+                // The commit of the event is checked against the base repository and GitHub before it is checked out (see worktree.ts).
+                const github = githubFor(spec.watch, cloneEvent);
+                // Same rules as the clone above (verify.ts): the PR head is read from GitHub and judged by judgePullHead in worktree.ts.
+                const pullHead = async (n) => {
+                    const pull = await readPullHead(github, repo, n);
+                    return pull.ok ? pull.head : null;
+                };
+                // A merge commit must be on the default branch of the repository as GitHub reports it, or on a branch the event
+                // names that the dot lists in testBranches (KAT-292). An unlisted branch the event names decides nothing. With no
+                // GitHub token the default branch recorded for the repo stands in: an event cannot change it.
+                let defaultBranch;
+                let mergeBranch;
+                if (spec.merge) {
+                    if (github.mode === 'demo')
+                        defaultBranch = repo.defaultBranch;
+                    else {
+                        const def = await defaultBranchOf(github, repo, spec.sha);
+                        if (!def.ok) {
+                            return notRunReport({
+                                stage: 'checkout',
+                                reason: scrubReason(`The tests did not run for ${spec.sha.slice(0, 7)}: ${def.reason} No test count is shown for this commit.`),
+                            }, '');
+                        }
+                        defaultBranch = def.branch;
+                    }
+                    mergeBranch = pickMergeBranch(defaultBranch, spec.merge?.branch, spec.watch.testBranches);
+                }
+                const plan = await prepareWorktree({
+                    workdir,
+                    repo,
+                    sha: spec.sha,
+                    ...(spec.pr ? { prNumber: spec.pr.number, pullHead } : {}),
+                    ...(mergeBranch
+                        ? {
+                            branch: mergeBranch.branch,
+                            branchLabel: mergeBranch.listed ? 'test branch' : 'base branch',
+                            ...(mergeBranch.unlisted ? { branchNote: unlistedBranchNote(mergeBranch.unlisted, mergeBranch.branch) } : {}),
+                        }
+                        : {}),
+                    id: runId ? `${runId}-a${attempt}` : `adhoc-${process.pid}-${Date.now().toString(36)}`,
+                    ...(runId ? { runId, cancelled: () => cancelRequested.has(runId) || isRunCancelled(runId) } : {}),
+                });
+                if (plan.kind === 'ready')
+                    worktree = plan.worktree;
+                if (runId && (cancelRequested.has(runId) || isRunCancelled(runId)))
+                    throw new RunCancelledError(runId);
+                if (plan.kind === 'failed')
+                    return notRunReport({ stage: 'checkout', reason: scrubReason(plan.reason) }, '');
+                if (worktree) {
+                    worktreeSource = workdir;
+                    workdir = worktree.dir;
+                }
+            }
+        }
+        // The guard stays on every path: the count is reported only if the checkout the tests ran in is on the commit.
+        // A Tests repo checkout was checked against its own commit when it was made.
+        if (!spec.testRepo && !cloneDir && mode !== 'demo' && spec.sha) {
+            const stale = await staleCheckout(workdir, spec.sha);
+            if (stale)
+                return notRunReport({ stage: 'checkout', reason: stale }, '');
+        }
+        // runner.workingDirectory: setup steps, the Playwright config, and the test command all run in this
+        // folder of the checkout (a CI job's working-directory). Docker still mounts the whole checkout.
+        const checkoutDir = workdir;
+        const subdir = runner.workingDirectory?.trim() || undefined;
+        if (subdir) {
+            workdir = path.join(checkoutDir, subdir);
+            if (!existsSync(workdir))
+                throw new Error(`runner.workingDirectory "${subdir}" does not exist in the checkout of ${spec.watch.name}`);
+        }
+        // `npm run <script>` forwards the runner's options to the script's last command only after a `--`,
+        // and only when that command is Playwright. The same helper decides what the suggestion proposes (KAT-135).
+        const scripts = readScripts(workdir);
+        const forwarded = forwardingArgv(parsedCommand.argv, scripts);
+        const runArgv = forwarded.argv;
+        const command = runArgv === parsedCommand.argv ? rawCommand : `${rawCommand} --`;
+        const playwright = forwarded.playwright;
+        // A VAR=value word of the test command wins over the test login.
+        const extraVars = { ...passVars, ...cmdVars };
+        Object.assign(extraVars, await runPortVars(cmdVars, mode, outDir));
+        Object.assign(extraVars, appServerVars(cmdVars, mode, baseUrl));
+        let reporter;
+        if (runId && mode !== 'docker')
+            live = new LiveSession(runId, attempt);
+        // Setup steps run before the test command, in the workdir, through the shell. Their output
+        // goes to the live terminal and the report tail. Docker runs them inside the container.
+        const local = localSetupSteps({ mode, cloned: !!cloneDir || !!worktree, setupSteps, hasPackageJson: existsSync(path.join(workdir, 'package.json')) });
+        const localSteps = local.steps;
+        // Dev dependencies (@playwright/test) are always installed: the image sets NODE_ENV=production, which would skip them.
+        const installVars = local.defaultInstall
+            ? { ...extraVars, ...DEFAULT_INSTALL_ENV }
+            : { ...extraVars, NPM_CONFIG_INCLUDE: DEFAULT_INSTALL_ENV.NPM_CONFIG_INCLUDE };
+        let setupOut = '';
+        let setup;
+        const log = (line) => {
+            setupOut = `${setupOut}${line}\n`.slice(-64_000);
+            live?.line(line);
+            opts.onLine?.(line);
+        };
+        // Files the worktree lacks (an .env, not tracked by git) come from the working folder, before any setup step (KAT-293).
+        if (worktree && worktreeSource && runner.copyFiles?.length) {
+            for (const note of copyFilesIntoWorktree({ from: worktreeSource, to: worktree.dir, root: worktree.root, files: runner.copyFiles }).notes)
+                log(note);
+        }
+        // When a run in a worktree did not pass, names runner.copyFiles if the working folder has untracked dotfiles that were not copied.
+        const withHint = async (r) => {
+            if (!worktree || !worktreeSource || !(r.notRun || r.failed > 0))
+                return r;
+            const found = await untrackedDotfiles(worktreeSource, runner.copyFiles ?? []);
+            const hint = copyFilesHint(found);
+            if (hint)
+                r.hint = hint;
+            const files = copyFilesHintFiles(found);
+            if (files)
+                r.hintFiles = files;
+            return r;
+        };
+        if (localSteps.length) {
+            setup = await runSetup({
+                workdir,
+                steps: localSteps,
+                log,
+                exec: (step) => runStep({ workdir: workdir, step, timeoutMs: SETUP_TIMEOUT_MS, runId, vars: installVars, mask, onLine: log }),
+            });
+            if (runId && (cancelRequested.has(runId) || isRunCancelled(runId)))
+                throw new RunCancelledError(runId);
+            if (!setup.ok) {
+                const r = notRunReport({
+                    stage: 'setup',
+                    reason: `Setup step "${setup.failedStep}" ${setup.reason || 'failed'}, so the tests did not run.${setup.detail ? `\n\n${setup.detail}` : ''}`,
+                    exitCode: setup.code ?? null,
+                }, setupOut);
+                r.setup = { steps: localSteps.length, cache: setup.cache, durationMs: setup.durationMs };
+                return withHint(r);
+            }
+        }
+        // Live view: local and demo stream reporter markers; docker logs arrive only at the end.
+        if (runId && mode !== 'docker' && playwright) {
+            reporter = stepReporterPath();
+            const words = [...runArgv, ...(scriptBody(runArgv, scripts)?.split(/\s+/) ?? [])];
+            // The config the run uses: the one the command names, else the repo's default. The wrapper sits next to it,
+            // so the paths inside the config keep their meaning, and the video, trace, and screenshot settings apply to it.
+            const named = configArgOf(words);
+            const hasConfigArg = words.some((a) => a === '-c' || a === '--config' || a.startsWith('--config=') || a.startsWith('-c='));
+            let baseConfig;
+            if (named) {
+                const abs = path.resolve(workdir, named);
+                if (existsSync(abs) && statSync(abs).isFile())
+                    baseConfig = abs;
+            }
+            else if (!hasConfigArg) {
+                const found = findPlaywrightConfig(workdir);
+                if (found)
+                    baseConfig = path.join(workdir, found);
+            }
+            if (baseConfig) {
+                wrapperFile = path.join(path.dirname(baseConfig), `.localdost-run-${safeName(runId, 40)}-${attempt}.config.ts`);
+                writeFileSync(wrapperFile, wrapperConfigSource(path.basename(baseConfig)));
+                if (runner.video === 'on')
+                    extraVars.LOCALDOST_VIDEO = 'on';
+                if (liveFramesEnabled(mode)) {
+                    const port = await freePort();
+                    extraVars.LOCALDOST_CDP_PORT = String(port);
+                    await live?.close();
+                    live = new LiveSession(runId, attempt, new CdpGrabber(port));
+                }
+            }
+        }
+        const args = adapter.args(spec, { reporter });
+        if (wrapperFile)
+            args.push(`--config=${path.relative(workdir, wrapperFile)}`);
+        // Per-run artifact dir: Playwright empties its output dir at start, so two concurrent runs
+        // sharing the default test-results/ delete each other's traces mid-run.
+        const playwrightArgs = playwright || (!scriptRun(parsedCommand.argv, scripts) && /playwright/.test(command));
+        if (playwrightArgs) {
+            args.push(`--output=${mode === 'docker' ? '/out/test-results' : path.join(outDir, 'test-results')}`);
+            // A trace of every test is what the Traceability map reads the visited pages from (src/runner/observe.ts).
+            // Traces of tests that passed are deleted once read, so the run keeps what it kept before.
+            if (runId)
+                args.push('--trace=on');
+        }
+        let exec;
+        let commandLine;
+        if (mode === 'docker') {
+            const image = adapter.image(workdir, runner.image);
+            commandLine = `docker ${image} ${command} ${args.join(' ')}`;
+            exec = await runDocker({
+                workdir: checkoutDir,
+                ...(subdir ? { subdir } : {}),
+                outDir,
+                image,
+                argv: runArgv,
+                cmdVars,
+                passVars,
+                setupSteps,
+                args,
+                baseUrl,
+                timeoutMs,
+                runId,
+                adapter,
+                baseUrlEnv,
+            });
+        }
+        else {
+            commandLine = `${command} ${args.join(' ')}`;
+            exec = await runLocal({
+                workdir,
+                outDir,
+                argv: runArgv,
+                args,
+                baseUrl,
+                timeoutMs,
+                runId,
+                extraVars,
+                live,
+                onLine: opts.onLine,
+                mask,
+                adapter,
+                baseUrlEnv,
+            });
+        }
+        await live?.close();
+        if (runId && (cancelRequested.has(runId) || isRunCancelled(runId)))
+            throw new RunCancelledError(runId);
+        // Docker: setup output comes back in the container log; a failed setup step exits 3 with a marker line.
+        // Without runner.setup the container runs its default install, which reports as step 1.
+        if (mode === 'docker') {
+            const m = /LOCALDOST_SETUP_FAILED (\d+) (\d+)/.exec(exec.output);
+            if (m) {
+                const step = setupSteps[Number(m[1]) - 1] ?? DEFAULT_INSTALL;
+                return withHint(notRunReport({ stage: 'setup', reason: `Setup step "${step}" exited with code ${m[2]}, so the tests did not run.`, exitCode: Number(m[2]) }, exec.output, commandLine));
+            }
+        }
+        let parsed = null;
+        const reportFile = path.join(outDir, 'report.json');
+        const read = await adapter.readReport({ reportFile, stdout: exec.stdout });
+        const json = read?.json ?? null;
+        if (read)
+            parsed = read.parsed;
+        if (json && runId) {
+            try {
+                writePlaywrightObservations(runId, attempt, json, outDir);
+            }
+            catch {
+                /* observations are best effort */
+            }
+        }
+        // Name each test's screenshots, video, and trace. After the observations, which delete the traces of tests that passed.
+        if (json && parsed && runId) {
+            try {
+                const evidence = collectEvidence(json, {
+                    outDir,
+                    prefix: `a${attempt}`,
+                    ...(live ? { shots: live.shots(), storedName: (file) => live?.storedName(file) } : {}),
+                });
+                const tests = reportTests(json);
+                parsed.cases.forEach((c, i) => {
+                    const e = evidence[i];
+                    if (e)
+                        c.evidence = e;
+                    // The names the test gave its own steps become the steps to reproduce in a defect draft (KAT-377).
+                    const named = c.status === 'failed' || c.status === 'timedOut' ? live?.stepNames(c.title, tests[i]?.project) : undefined;
+                    if (named)
+                        c.steps = named;
+                    // Every test that ran keeps its step blocks, with the one that threw marked: the evidence pack pairs them with the screenshots.
+                    const blocks = c.status === 'skipped' ? undefined : live?.namedSteps(c.title, tests[i]?.project);
+                    if (blocks)
+                        c.namedSteps = blocks;
+                });
+            }
+            catch {
+                /* evidence is best effort */
+            }
+        }
+        // Playwright names a spec by its path under the testDir. A case of a Tests repo is named by its path in the repo, so a link to the spec
+        // and the file name a retry filters on point at the real file, whatever the testDir is.
+        if (spec.testRepo && parsed && worktree)
+            repoRelativeFiles(parsed.cases, json, worktree.root);
+        // A failed fill() prints the value it typed in Playwright's call log, so the login values are masked in the error text too.
+        if (parsed) {
+            for (const c of parsed.cases)
+                maskCase(c, mask);
+            parsed.errors = parsed.errors.map(mask);
+        }
+        const cmdTail = mask(stripAnsi(exec.output).slice(-4000));
+        const report = {
+            mode,
+            command: commandLine,
+            startedAt,
+            durationMs: Date.now() - started,
+            passed: parsed?.passed ?? 0,
+            failed: parsed?.failed ?? 0,
+            flaky: parsed?.flaky ?? 0,
+            skipped: parsed?.skipped ?? 0,
+            cases: parsed?.cases ?? [],
+            // The tail is shown on the run page and quoted in comments, so credentials in it are masked.
+            stdoutTail: mask(redact(setupOut && cmdTail.trim()
+                ? `${stripAnsi(setupOut).slice(-1500)}\n--- test command ---\n${cmdTail}`
+                : setupOut
+                    ? stripAnsi(setupOut).slice(-4000)
+                    : cmdTail)),
+        };
+        if (baseUrl)
+            report.baseUrl = baseUrl;
+        if (exec.timedOut)
+            report.interrupted = true;
+        if (setup)
+            report.setup = { steps: localSteps.length, cache: setup.cache, durationMs: setup.durationMs };
+        // No parsable report: the tests did not run, or ran without the JSON reporter. That says
+        // nothing about the product, so it is an environment problem, never a failed test.
+        if (!parsed) {
+            const missing = exec.code === -1 || /ENOENT|command not found/i.test(exec.output.slice(-1000));
+            report.notRun = {
+                stage: 'report',
+                reason: exec.timedOut
+                    ? `The test command timed out after ${Math.round(timeoutMs / 60_000)} min before it wrote a Playwright JSON report.`
+                    : missing
+                        ? `The test command could not start (exit code ${exec.code}). Check that "${parsedCommand.argv[0]}" exists in the workdir, or add its install to Setup steps.`
+                        : `The test command produced no Playwright JSON report (exit code ${exec.code}). Check that it runs Playwright and honours --reporter=json.`,
+                exitCode: exec.code,
+            };
+            return withHint(report);
+        }
+        // A crashed run with a report but no failed test must not read as a pass.
+        if (parsed && !exec.timedOut && report.failed === 0 && exec.code !== 0) {
+            const why = parsed.errors.join('\n') || cmdTail.slice(-2000) || `exit code ${exec.code}`;
+            report.cases.push({ title: 'Test run did not complete', file: '', status: 'failed', durationMs: 0, error: why, retries: 0 });
+            report.failed++;
+        }
+        return withHint(report);
+    }
+    finally {
+        try {
+            releaseRunPorts(outDir);
+            await live?.close().catch(() => { });
+            if (runId) {
+                try {
+                    saveOutputs(runId, `a${attempt}`, outDir, live);
+                }
+                catch {
+                    /* artifacts are best effort */
+                }
+                activeProcs.delete(runId);
+                cancelRequested.delete(runId);
+            }
+        }
+        finally {
+            // The temp folders go even when a step above throws.
+            if (wrapperFile)
+                rmSync(wrapperFile, { force: true });
+            await rm(outDir, { recursive: true, force: true }).catch(() => { });
+            if (cloneDir)
+                await rm(cloneDir, { recursive: true, force: true }).catch(() => { });
+            await worktree?.cleanup();
+        }
+    }
+}
+export { playwrightVersion };
+/**
+ * PORT and HOST for a test project that starts its own app (`process.env.PORT ?? 4400`). The localdost server's
+ * own values are not passed on, so they come from the app's address instead: a base URL on this machine
+ * with a port gives that port and host. A value the test command sets itself wins. Docker runs get none.
+ */
+export function appServerVars(cmdVars, mode, baseUrl) {
+    if (mode === 'docker' || !baseUrl)
+        return {};
+    let u;
+    try {
+        u = new URL(baseUrl);
+    }
+    catch {
+        return {};
+    }
+    const loopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
+    if (!loopback || !u.port)
+        return {};
+    const out = {};
+    if (cmdVars.PORT === undefined)
+        out.PORT = u.port;
+    if (cmdVars.HOST === undefined)
+        out.HOST = u.hostname;
+    return out;
+}
+/** Spawns one process in its own group, streams lines, and registers it for cancel. */
+function spawnStreaming(o) {
+    return new Promise((resolve) => {
+        const child = spawnTrackedPiped(o.cmd, o.args, { cwd: o.cwd, env: o.vars, ...(o.runId ? { runId: o.runId } : {}) }); // own group, tracked for shutdown
+        child.stdin.on('error', () => undefined);
+        child.stdin.end();
+        let stdout = '';
+        let output = '';
+        let timedOut = false;
+        const keep = (s, d, max) => (s + d).slice(-max);
+        const outLines = lineSplitter((raw) => {
+            const line = o.mask ? o.mask(raw) : raw;
+            if (o.onOut(line))
+                return;
+            stdout = keep(stdout, `${line}\n`, 20_000_000);
+            output = keep(output, `${line}\n`, 64_000);
+        });
+        const errLines = lineSplitter((raw) => {
+            const line = o.mask ? o.mask(raw) : raw;
+            if (o.onErr(line))
+                return;
+            output = keep(output, `${line}\n`, 64_000);
+        });
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (d) => outLines.push(d));
+        child.stderr.on('data', (d) => errLines.push(d));
+        // Whole group: playwright plus browsers plus webServer.
+        const stop = () => terminate(child, 5000);
+        if (o.runId)
+            activeProcs.set(o.runId, stop);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, o.timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            if (o.runId)
+                activeProcs.delete(o.runId);
+            resolve({ code: -1, timedOut, stdout, output: `${output}\n${err.message}`.trim(), error: err.message });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (o.runId)
+                activeProcs.delete(o.runId);
+            outLines.end();
+            errLines.end();
+            resolve({ code, timedOut, stdout, output, signal });
+        });
+    });
+}
+function runLocal(o) {
+    // Local runs inherit the host env minus anything that looks like a credential.
+    const vars = { ...hostVars(), ...o.adapter.env({ outDir: o.outDir, baseUrl: o.baseUrl, baseUrlEnv: o.baseUrlEnv }), ...(o.extraVars ?? {}) };
+    const [cmd = 'npx', ...cmdArgs] = o.argv;
+    // Markers go to the live session only; the JSON fallback and the stdout tail never see them.
+    const onLine = (line) => {
+        if (line.startsWith(MARKER)) {
+            o.live?.line(line);
+            return true;
+        }
+        o.onLine?.(stripAnsi(line));
+        return !!o.live?.line(line);
+    };
+    return spawnStreaming({
+        cwd: o.workdir,
+        cmd,
+        args: [...cmdArgs, ...o.args],
+        vars,
+        timeoutMs: o.timeoutMs,
+        runId: o.runId,
+        onOut: onLine,
+        onErr: onLine,
+        mask: o.mask,
+    });
+}
+/** One setup step through `sh -c`, with the same filtered environment as the test command. */
+/**
+ * Two distinct free ports per local run (LOCALDOST_RUN_PORT, LOCALDOST_RUN_PORT_2), so suites that start
+ * their own servers can run side by side: the queue runs two jobs at once. A value the test command
+ * sets itself wins. Docker runs get none: each container has its own network namespace.
+ */
+const runPorts = new Map();
+export async function runPortVars(cmdVars, mode, runKey) {
+    if (mode === 'docker')
+        return {};
+    const ports = await leasePorts(2);
+    runPorts.set(runKey, ports);
+    const [a, b] = ports;
+    return { LOCALDOST_RUN_PORT: cmdVars.LOCALDOST_RUN_PORT ?? String(a), LOCALDOST_RUN_PORT_2: cmdVars.LOCALDOST_RUN_PORT_2 ?? String(b) };
+}
+/** Frees the ports a run leased; called when the run ends, whatever the outcome. */
+export function releaseRunPorts(runKey) {
+    const ports = runPorts.get(runKey);
+    if (ports)
+        releasePorts(ports);
+    runPorts.delete(runKey);
+}
+export async function runStep(o) {
+    const vars = { ...hostVars(), CI: '1', FORCE_COLOR: '0', ...(o.vars ?? {}) };
+    let printed = '';
+    const onLine = (line) => {
+        const text = stripAnsi(line).replace(/\s+$/, '');
+        if (text) {
+            printed = `${printed}${text}\n`.slice(-8000);
+            o.onLine(text);
+        }
+        return true;
+    };
+    const r = await spawnStreaming({
+        cwd: o.workdir,
+        cmd: 'sh',
+        args: ['-c', o.step],
+        vars,
+        timeoutMs: o.timeoutMs,
+        runId: o.runId,
+        onOut: onLine,
+        onErr: onLine,
+        mask: o.mask,
+    });
+    if (o.runId && (cancelRequested.has(o.runId) || isRunCancelled(o.runId)))
+        return { code: r.code, timedOut: false, error: 'cancelled', output: printed };
+    // A spawn error carries the real message (ENOENT for a missing workdir, EACCES, ...), never a bare "could not start".
+    const error = r.error ? `could not start sh: ${r.error}` : undefined;
+    return { code: r.code, timedOut: r.timedOut, signal: r.signal ?? null, output: printed, ...(error ? { error } : {}) };
+}
+export { DEFAULT_INSTALL };
+/**
+ * Environment for the default install only. The image has the browsers, so the install must not download
+ * them again. The image sets NODE_ENV=production, which would make npm skip devDependencies such as
+ * @playwright/test, so the install asks for them.
+ */
+export const DEFAULT_INSTALL_ENV = { PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1', NPM_CONFIG_INCLUDE: 'dev' };
+/**
+ * The setup steps a local or demo run executes. A fresh clone (no runner.workdir) has no node_modules,
+ * so without runner.setup it gets the default install, as long as it has a package.json. A configured
+ * runner.workdir is the person's own checkout and already has its dependencies. Docker mode installs
+ * inside the container (dockerScript), so it never gets a host-side step.
+ */
+export function localSetupSteps(o) {
+    if (o.mode === 'docker')
+        return { steps: [], defaultInstall: false };
+    if (o.setupSteps.length)
+        return { steps: o.setupSteps, defaultInstall: false };
+    if (o.cloned && o.hasPackageJson)
+        return { steps: [DEFAULT_INSTALL], defaultInstall: true };
+    return { steps: [], defaultInstall: false };
+}
+const shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** The bash script the Docker container runs: copy the checkout, run setup (or the default install), run the test command. */
+export function dockerScript(o) {
+    // The checkout is mounted read-only and copied into the container; only BASE_URL crosses over.
+    // Repo-local secret and credential files stay behind, so test code cannot read them.
+    const excludes = SECRET_FILES.map((p) => `--exclude=${shq(p)}`).join(' ');
+    const setup = o.setupSteps.length
+        ? o.setupSteps.map((step, i) => `echo ${shq(`Setup ${i + 1}/${o.setupSteps.length}: $ ${step}`)}\nbash -c ${shq(step)} || { rc=$?; echo "LOCALDOST_SETUP_FAILED ${i + 1} $rc"; exit 3; }`)
+        : [`(${DEFAULT_INSTALL}) > /out/install.log 2>&1 || { rc=$?; tail -50 /out/install.log; echo "LOCALDOST_SETUP_FAILED 1 $rc"; exit 3; }`];
+    const assigns = Object.entries(o.cmdVars).map(([k, v]) => shq(`${k}=${v}`));
+    const test = [...(assigns.length ? ['env', ...assigns] : []), ...o.argv.map(shQuote), ...o.args.map(shq)].join(' ');
+    return [
+        'set -e',
+        'mkdir -p /work',
+        `tar -C /src --exclude=./node_modules --exclude=./.git ${excludes} -cf - . | tar -C /work -xf -`,
+        `cd ${shq(o.subdir ? `/work/${o.subdir}` : '/work')}`,
+        ...setup,
+        test,
+    ].join('\n');
+}
+/** The whole environment of a test container: the report paths, BASE_URL, and the test login. No host variable crosses over. */
+export function dockerEnv(baseUrl, passVars = {}, adapter = adapterFor(), baseUrlEnv) {
+    return {
+        ...passVars,
+        ...adapter.env({ outDir: '/out', baseUrl, baseUrlEnv }),
+        PLAYWRIGHT_JSON_OUTPUT_FILE: '/out/report.json',
+        PLAYWRIGHT_JSON_OUTPUT_NAME: '/out/report.json',
+    };
+}
+async function runDocker(o) {
+    const { default: Docker } = await import('dockerode');
+    const docker = new Docker();
+    await ensureImage(docker, o.image);
+    const script = dockerScript(o);
+    const container = await docker.createContainer({
+        Image: o.image,
+        Cmd: ['bash', '-lc', script],
+        Tty: true,
+        Env: Object.entries(dockerEnv(o.baseUrl, o.passVars, o.adapter, o.baseUrlEnv)).map(([k, v]) => `${k}=${v}`),
+        HostConfig: {
+            Binds: [`${o.workdir}:/src:ro`, `${o.outDir}:/out`],
+            IpcMode: 'host',
+            Init: true,
+            Memory: 4 * 1024 ** 3,
+            NanoCpus: 2_000_000_000,
+            ExtraHosts: ['host.docker.internal:host-gateway'],
+        },
+    });
+    let timedOut = false;
+    let code = null;
+    try {
+        await container.start();
+        if (o.runId)
+            activeProcs.set(o.runId, () => void container.kill().catch(() => { }));
+        let timer;
+        const timeout = new Promise((r) => {
+            timer = setTimeout(() => r('timeout'), o.timeoutMs + (o.setupSteps.length ? SETUP_TIMEOUT_MS : 0));
+        });
+        const res = await Promise.race([container.wait(), timeout]);
+        clearTimeout(timer);
+        if (res === 'timeout') {
+            timedOut = true;
+            await container.kill().catch(() => { });
+        }
+        else {
+            code = res.StatusCode;
+        }
+        const logs = (await container.logs({ stdout: true, stderr: true, follow: false }));
+        const text = logs.toString('utf8');
+        return { code, timedOut, stdout: text, output: text.slice(-64_000) };
+    }
+    finally {
+        if (o.runId)
+            activeProcs.delete(o.runId);
+        await container.remove({ force: true }).catch(() => { });
+    }
+}
+async function ensureImage(docker, image) {
+    try {
+        await docker.getImage(image).inspect();
+        return;
+    }
+    catch {
+        /* not present locally */
+    }
+    const stream = await docker.pull(image);
+    await new Promise((resolve, reject) => {
+        docker.modem.followProgress(stream, (err) => (err ? reject(err) : resolve()));
+    });
+}
+//# sourceMappingURL=index.js.map