@mknrt/autotests-overkill 1.2.6 → 1.3.0

package/dist/src/runtime/cypressRuns.js

@@ -0,0 +1,419 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { cypressEnvironment, cypressInstallation, stopProcessTree } from './cypressProcess.js';
+import { redactValue } from './redact.js';
+const readJson = (file) => {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const availablePort = () => new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        server.close((error) => error ? reject(error) : resolve(address.port));
+    });
+});
+const integer = (value, minimum, maximum, name) => {
+    if (!Number.isInteger(value) || value < minimum || value > maximum)
+        throw new Error(`${name} must be ${minimum}..${maximum}`);
+    return value;
+};
+export class CypressRuns {
+    cacheDir;
+    sanitize;
+    runs = new Map();
+    root;
+    lock;
+    ownsLock = false;
+    starting = false;
+    closed = false;
+    constructor(repoRoot, cacheDir, sanitize = (text) => text) {
+        this.cacheDir = cacheDir;
+        this.sanitize = sanitize;
+        this.root = fs.realpathSync(repoRoot);
+        this.lock = path.join(os.tmpdir(), `overkill-cypress-${createHash('sha256').update(this.root).digest('hex').slice(0, 20)}.lock`);
+    }
+    active() {
+        const run = [...this.runs.values()].find((run) => run.status === 'running' || run.child);
+        return run ? { runId: run.runId, mode: run.options.mode } : undefined;
+    }
+    async start(input) {
+        if (this.closed)
+            throw new Error('Cypress runner is closed.');
+        if (this.starting || [...this.runs.values()].some((run) => run.status === 'running' || run.child))
+            throw new Error('A Cypress run is already active for this checkout. Stop it first.');
+        const spec = input.spec.replaceAll('\\', '/');
+        if (!spec.startsWith('cypress/') || !/\.cy\.[cm]?[jt]sx?$/.test(spec) || /[\n\r\0]/.test(spec))
+            throw new Error('spec must be one existing Cypress spec inside cypress/.');
+        const realRoot = fs.realpathSync(this.root);
+        const realSpec = fs.realpathSync(path.resolve(this.root, spec));
+        const relative = path.relative(realRoot, realSpec);
+        if (relative.startsWith('..') || path.isAbsolute(relative) || !fs.statSync(realSpec).isFile())
+            throw new Error('spec escapes the repository.');
+        const browser = input.browser ?? 'chrome-for-testing';
+        if (!['chrome-for-testing', 'chrome', 'chromium', 'edge', 'yandex'].includes(browser))
+            throw new Error('Use an installed Chromium browser name.');
+        const options = {
+            spec, browser, mode: input.mode ?? 'run', repeats: integer(input.repeats ?? 1, 1, 20, 'repeats'),
+            retries: integer(input.retries ?? 0, 0, 5, 'retries'),
+            timeoutSeconds: integer(input.timeoutSeconds ?? 900, 1, 7200, 'timeoutSeconds'), debug: input.debug ?? false,
+        };
+        if (!['run', 'open'].includes(options.mode))
+            throw new Error('mode must be run or open.');
+        if (options.mode === 'open' && options.repeats !== 1)
+            throw new Error('Open mode keeps one session alive; use TAP run for reruns or run mode for independent repeats.');
+        cypressInstallation(this.root, options.mode === 'open');
+        for (const file of ['.codex/cypress-mcp.config.cjs']) {
+            if (!fs.existsSync(path.join(this.root, file)))
+                throw new Error(`Project adapter missing: ${file}`);
+        }
+        this.starting = true;
+        let acquired = false;
+        try {
+            this.acquireLock();
+            acquired = true;
+            const runId = randomUUID();
+            const directory = path.join(this.cacheDir, 'cypress-runs', runId);
+            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const run = { runId, directory, spec, status: 'running', startedAt: new Date().toISOString(), debugPort: await availablePort(), options, repeats: [] };
+            if (this.closed)
+                throw new Error('Cypress runner is closed.');
+            this.runs.set(runId, run);
+            this.save(run);
+            run.finished = this.execute(run);
+            return this.get(runId);
+        }
+        catch (error) {
+            if (acquired)
+                this.releaseLock();
+            throw error;
+        }
+        finally {
+            this.starting = false;
+        }
+    }
+    get(runId) {
+        const run = this.requireRun(runId);
+        const repeats = run.repeats.map((repeat) => ({ ...repeat, results: readJson(path.join(repeat.directory, 'results.json')) ?? repeat.results }));
+        const tests = new Map();
+        for (const repeat of repeats) {
+            for (const spec of repeat.results?.specs ?? [])
+                for (const test of spec.tests ?? []) {
+                    const title = Array.isArray(test.title) ? test.title : [String(test.title)];
+                    const key = JSON.stringify([spec.file, title]);
+                    const record = tests.get(key) ?? { spec: spec.file, title, passed: 0, failed: 0, skipped: 0, flaky: false };
+                    if (test.state === 'passed')
+                        record.passed++;
+                    else if (test.state === 'failed')
+                        record.failed++;
+                    else
+                        record.skipped++;
+                    record.flaky ||= test.state === 'passed' && (test.attempts ?? []).some((attempt) => attempt.state === 'failed');
+                    record.flaky ||= record.passed > 0 && record.failed > 0;
+                    tests.set(key, record);
+                }
+        }
+        let log = '';
+        for (const repeat of repeats) {
+            const file = path.join(repeat.directory, 'cypress.log');
+            if (!fs.existsSync(file))
+                continue;
+            const size = fs.statSync(file).size;
+            const descriptor = fs.openSync(file, 'r');
+            try {
+                const bytes = Buffer.alloc(Math.min(size, 32768));
+                fs.readSync(descriptor, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
+                log += `\n--- repeat ${repeat.repeat} ---\n${bytes.toString('utf8')}`;
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+        }
+        const result = {
+            runId: run.runId, spec: run.spec, mode: run.options.mode ?? 'run', status: run.status, startedAt: run.startedAt, finishedAt: run.finishedAt,
+            directory: run.directory, debugPort: run.debugPort, requestedRepeats: run.options.repeats, repeats,
+            error: run.error, log: log.slice(-65536),
+            flakiness: {
+                completedRepeats: repeats.filter((repeat) => repeat.exitCode !== null).length,
+                failedRepeats: repeats.filter((repeat) => repeat.exitCode !== null && repeat.exitCode !== 0).length,
+                tests: [...tests.values()],
+                note: 'Observed outcomes for these attempts only; skipped tests and incomplete runs are not passes.',
+            },
+            captures: repeats.flatMap((repeat) => {
+                const file = path.join(repeat.directory, 'events.ndjson');
+                if (!fs.existsSync(file))
+                    return [];
+                // Bound evidence returned to the model; full local captures remain available by path.
+                const descriptor = fs.openSync(file, 'r');
+                try {
+                    const size = fs.fstatSync(descriptor).size;
+                    const bytes = Buffer.alloc(Math.min(size, 250000));
+                    fs.readSync(descriptor, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
+                    return bytes.toString('utf8').split('\n').flatMap((line) => {
+                        try {
+                            const parsed = JSON.parse(line);
+                            return (Array.isArray(parsed) ? parsed : [parsed]).map((capture) => ({ repeat: repeat.repeat, ...capture }));
+                        }
+                        catch {
+                            return [];
+                        }
+                    }).slice(-10);
+                }
+                finally {
+                    fs.closeSync(descriptor);
+                }
+            }).slice(-10),
+            captureFiles: repeats.map((repeat) => path.join(repeat.directory, 'events.ndjson')).filter((file) => fs.existsSync(file)),
+        };
+        const captures = new Map();
+        for (const capture of result.captures) {
+            const key = capture.capturedAt
+                ? JSON.stringify([capture.repeat, capture.capturedAt, capture.spec, redactValue(capture.test, this.sanitize), capture.attempt])
+                : JSON.stringify(capture);
+            if (!captures.has(key))
+                captures.set(key, capture);
+        }
+        result.captures = [...captures.values()];
+        const clean = redactValue(result, this.sanitize);
+        // These fields are generated/validated filesystem metadata, not credential payloads.
+        // A password that happens to equal a folder name must not break artifact links.
+        clean.runId = run.runId;
+        clean.status = run.status;
+        clean.directory = run.directory;
+        clean.spec = run.spec;
+        clean.captureFiles = result.captureFiles;
+        for (let index = 0; index < repeats.length; index++) {
+            const repeat = repeats[index];
+            clean.repeats[index].directory = repeat.directory;
+            const withinRepeat = (value) => {
+                if (typeof value !== 'string' || !path.isAbsolute(value))
+                    return false;
+                const relative = path.relative(repeat.directory, value);
+                return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+            };
+            for (const [specIndex, spec] of (repeat.results?.specs ?? []).entries()) {
+                const output = clean.repeats[index].results.specs[specIndex];
+                if (spec.file === run.spec)
+                    output.file = spec.file;
+                if (withinRepeat(spec.video))
+                    output.video = spec.video;
+                for (const [imageIndex, screenshot] of (spec.screenshots ?? []).entries()) {
+                    if (withinRepeat(screenshot.path))
+                        output.screenshots[imageIndex].path = screenshot.path;
+                }
+            }
+        }
+        for (const [index, test] of result.flakiness.tests.entries()) {
+            if (test.spec === run.spec)
+                clean.flakiness.tests[index].spec = run.spec;
+        }
+        for (const [index, capture] of result.captures.entries()) {
+            if (capture.spec === run.spec)
+                clean.captures[index].spec = run.spec;
+        }
+        return clean;
+    }
+    recordCapture(runId, payload) {
+        try {
+            const run = this.requireRun(runId);
+            const repeat = run.repeats.at(-1);
+            if (run.status !== 'running' || !repeat)
+                return false;
+            const clean = redactValue(payload, this.sanitize);
+            for (const [index, capture] of (Array.isArray(payload) ? payload : [payload]).entries()) {
+                if (capture && typeof capture === 'object' && 'spec' in capture && capture.spec === run.spec) {
+                    (Array.isArray(clean) ? clean[index] : clean).spec = run.spec;
+                }
+            }
+            const json = `${JSON.stringify(clean)}\n`;
+            const size = Buffer.byteLength(json);
+            const file = path.join(repeat.directory, 'events.ndjson');
+            if (size > 250000 || (fs.existsSync(file) ? fs.statSync(file).size : 0) + size > 10000000)
+                return false;
+            fs.appendFileSync(file, json, { mode: 0o600 });
+            return true;
+        }
+        catch {
+            // Diagnostics are best effort and must not change the test outcome or lifecycle.
+            return false;
+        }
+    }
+    getDebugPort(runId) {
+        const run = this.requireRun(runId);
+        if (run.status !== 'running')
+            throw new Error('Browser is no longer running; use the captured failure evidence or start another run.');
+        return run.debugPort;
+    }
+    async stop(runId) {
+        const run = this.requireRun(runId);
+        if (run.status === 'running') {
+            run.status = 'stopped';
+            this.terminate(run);
+            await run.finished;
+        }
+        return this.get(runId);
+    }
+    async close() {
+        this.closed = true;
+        await Promise.all([...this.runs.values()].map(async (run) => {
+            if (run.status === 'running')
+                await this.stop(run.runId);
+            else
+                await run.finished;
+        }));
+        this.releaseLock();
+    }
+    terminate(run) {
+        run.stopping ??= stopProcessTree(run.child).catch((error) => {
+            run.error = this.sanitize(`Could not stop Cypress process tree: ${error.message}`);
+            run.status = 'error';
+        });
+    }
+    requireRun(runId) {
+        const existing = this.runs.get(runId);
+        if (existing)
+            return existing;
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(runId))
+            throw new Error(`Unknown Cypress run: ${runId}`);
+        const directory = path.join(this.cacheDir, 'cypress-runs', runId);
+        const stored = readJson(path.join(directory, 'run.json'));
+        if (!stored || stored.runId !== runId || stored.repoRoot !== this.root || !Array.isArray(stored.repeats))
+            throw new Error(`Unknown Cypress run: ${runId}`);
+        const run = { ...stored, directory, repeats: stored.repeats.map((repeat) => ({
+                repeat: repeat.repeat, exitCode: repeat.exitCode, directory: path.join(directory, `repeat-${integer(repeat.repeat, 1, 20, 'repeat')}`),
+            })) };
+        if (run.status === 'running') {
+            run.status = 'error';
+            run.error = 'The owning MCP session ended before recording completion; this archive is incomplete.';
+        }
+        this.runs.set(runId, run);
+        return run;
+    }
+    acquireLock() {
+        // ponytail: one run per checkout avoids shared fixture/report races; isolate projects before adding concurrency.
+        try {
+            fs.writeFileSync(this.lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const lock = readJson(this.lock);
+            const owner = Number(typeof lock === 'number' ? lock : lock?.pid);
+            if (!Number.isInteger(owner) || owner <= 0)
+                throw new Error(`Invalid Cypress lock; inspect ${this.lock}`);
+            try {
+                process.kill(owner, 0);
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    throw error;
+                if (lock?.runnerPid) {
+                    try {
+                        process.kill(lock.runnerPid, 0);
+                        throw new Error('A Cypress process is still active from the previous MCP session.');
+                    }
+                    catch (runnerError) {
+                        if (runnerError.code !== 'ESRCH')
+                            throw runnerError;
+                    }
+                }
+                fs.unlinkSync(this.lock);
+                return this.acquireLock();
+            }
+            throw new Error('A Cypress run is already active for this checkout.');
+        }
+        this.ownsLock = true;
+    }
+    releaseLock() {
+        if (this.ownsLock) {
+            this.ownsLock = false;
+            try {
+                fs.unlinkSync(this.lock);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    save(run) {
+        fs.writeFileSync(path.join(run.directory, 'run.json'), JSON.stringify({ repoRoot: this.root, debugPort: run.debugPort, repeats: run.repeats.map(({ repeat, exitCode }) => ({ repeat, exitCode })), error: run.error, runId: run.runId, spec: run.spec, status: run.status, startedAt: run.startedAt, finishedAt: run.finishedAt, options: run.options }, null, 2), { mode: 0o600 });
+    }
+    async execute(run) {
+        try {
+            for (let index = 1; index <= run.options.repeats && run.status === 'running'; index++) {
+                const directory = path.join(run.directory, `repeat-${index}`);
+                fs.mkdirSync(directory, { mode: 0o700 });
+                const repeat = { repeat: index, directory, exitCode: null };
+                run.repeats.push(repeat);
+                const specPattern = run.spec.replace(/[\[\]]/g, (char) => char === '[' ? '[[]' : '[]]');
+                const env = { ...cypressEnvironment(), OVERKILL_MODE: run.options.mode, SNAPSHOT_PORT: String(await availablePort()),
+                    TESTS: specPattern, NO_COLOR: '1', OVERKILL_RUN_DIR: directory, OVERKILL_DEBUG_PORT: String(run.debugPort),
+                    CYPRESS_REMOTE_DEBUGGING_PORT: String(run.debugPort), OVERKILL_RETRIES: String(run.options.retries),
+                    OVERKILL_DEBUG: String(run.options.debug), OVERKILL_TIMEOUT_SECONDS: String(run.options.timeoutSeconds), OVERKILL_REPEAT: String(index), API_CAPTURE_ENABLED: 'false' };
+                if (run.status !== 'running')
+                    break;
+                const descriptor = fs.openSync(path.join(directory, 'cypress.log'), 'a', 0o600);
+                try {
+                    repeat.exitCode = await new Promise((resolve, reject) => {
+                        const { cli } = cypressInstallation(this.root, run.options.mode === 'open');
+                        const args = [cli, run.options.mode, '--project', this.root, '--browser', run.options.browser,
+                            '--config-file', path.join(this.root, '.codex/cypress-mcp.config.cjs')];
+                        if (run.options.mode === 'open')
+                            args.push('--e2e');
+                        else
+                            args.push('--spec', specPattern, run.options.debug ? '--headed' : '--headless');
+                        const child = spawn(process.execPath, args, { cwd: this.root, env, detached: process.platform !== 'win32', windowsHide: true, stdio: ['ignore', descriptor, descriptor] });
+                        run.child = child;
+                        fs.writeFileSync(this.lock, JSON.stringify({ pid: process.pid, runnerPid: child.pid }), { mode: 0o600 });
+                        this.save(run);
+                        const timer = setTimeout(() => {
+                            if (run.status === 'running')
+                                run.status = 'timed_out';
+                            this.terminate(run);
+                        }, run.options.timeoutSeconds * 1000);
+                        timer.unref();
+                        child.once('error', reject);
+                        child.once('close', (code) => { clearTimeout(timer); resolve(code); });
+                    });
+                }
+                finally {
+                    if (run.stopping)
+                        await run.stopping;
+                    else if (process.platform !== 'win32')
+                        await stopProcessTree(run.child);
+                    fs.closeSync(descriptor);
+                    run.child = undefined;
+                    run.stopping = undefined;
+                }
+                repeat.results = readJson(path.join(directory, 'results.json'));
+                if (repeat.exitCode === 124 && run.status === 'running')
+                    run.status = 'timed_out';
+                if ((!repeat.results || repeat.results.complete === false) && run.status === 'running') {
+                    run.status = 'error';
+                    run.error = 'Cypress exited without this repeat’s result file. Inspect the captured log.';
+                }
+            }
+            if (run.status === 'running')
+                run.status = 'completed';
+        }
+        catch (error) {
+            run.status = 'error';
+            run.error = this.sanitize(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            run.finishedAt = new Date().toISOString();
+            this.releaseLock();
+            this.save(run);
+        }
+    }
+}

package/dist/src/runtime/cypressRuntime.d.ts

@@ -0,0 +1,24 @@
+import type { AppContext } from '../appContext.js';
+import { type BrowserInspection } from './cypressBrowser.js';
+import { type CypressRunOptions } from './cypressRuns.js';
+import { type CypressTapInput } from './cypressTap.js';
+export declare function cypressRuntime(context: AppContext): CypressRuntime;
+export declare function closeCypressRuntime(context: AppContext): Promise<void>;
+export declare class CypressRuntime {
+    private readonly runs;
+    private readonly browsers;
+    private readonly sanitize;
+    private closed;
+    private readonly tap;
+    private readonly tapSessions;
+    constructor(repoRoot: string, cacheDir: string);
+    start(options: CypressRunOptions): Promise<any>;
+    get(runId: string): any;
+    tapCommand(input: CypressTapInput): Promise<any>;
+    inspect(runId: string, input: BrowserInspection): Promise<any>;
+    stop(runId: string): Promise<any>;
+    close(): Promise<void>;
+    private startOpenSpec;
+    private browser;
+    private observe;
+}

package/dist/src/runtime/cypressRuntime.js

@@ -0,0 +1,125 @@
+import { CypressBrowser } from './cypressBrowser.js';
+import { CypressRuns } from './cypressRuns.js';
+import { CypressTap } from './cypressTap.js';
+import { projectRedactor, redactValue } from './redact.js';
+const runtimes = new WeakMap();
+export function cypressRuntime(context) {
+    let runtime = runtimes.get(context);
+    if (!runtime) {
+        runtime = new CypressRuntime(context.config.repos.autotests2, context.config.cacheDir);
+        runtimes.set(context, runtime);
+    }
+    return runtime;
+}
+export async function closeCypressRuntime(context) {
+    await runtimes.get(context)?.close();
+    runtimes.delete(context);
+}
+export class CypressRuntime {
+    runs;
+    browsers = new Map();
+    sanitize;
+    closed = false;
+    tap;
+    tapSessions = new Map();
+    constructor(repoRoot, cacheDir) {
+        this.sanitize = projectRedactor(repoRoot);
+        this.runs = new CypressRuns(repoRoot, cacheDir, this.sanitize);
+        this.tap = new CypressTap(repoRoot, this.sanitize);
+    }
+    async start(options) {
+        if (this.closed)
+            throw new Error('Cypress runtime is closed');
+        if (options.mode === 'open' && (await this.tap.execute({ action: 'sessions' })).length) {
+            throw new Error('An open Cypress session already exists for this project. Use cypress_tap with its sessionId or close it before starting a managed session.');
+        }
+        const run = await this.runs.start(options);
+        this.browsers.set(run.runId, this.browser(run.runId, run.debugPort));
+        void this.observe(run.runId).catch(() => { });
+        if (options.mode === 'open') {
+            this.tapSessions.set(run.runId, { status: 'starting' });
+            void this.startOpenSpec(run.runId, options);
+        }
+        return this.get(run.runId);
+    }
+    get(runId) {
+        const run = this.runs.get(runId);
+        return { ...run, tap: this.tapSessions.get(runId), failures: run.captures.slice(-5) };
+    }
+    async tapCommand(input) {
+        if (this.closed)
+            throw new Error('Cypress runtime is closed');
+        if (['run', 'pin'].includes(input.action)) {
+            const active = this.runs.active();
+            if (active) {
+                const sessionId = this.tapSessions.get(active.runId)?.sessionId;
+                if (active.mode !== 'open' || !sessionId || (input.sessionId !== undefined && input.sessionId !== sessionId)) {
+                    throw new Error('A managed Cypress run is active. Only mutate its ready, owned open session; wait for it or stop it first.');
+                }
+                input = { ...input, sessionId };
+            }
+        }
+        return this.tap.execute(input);
+    }
+    async inspect(runId, input) {
+        const port = this.runs.getDebugPort(runId);
+        let browser = this.browsers.get(runId);
+        if (!browser) {
+            browser = this.browser(runId, port);
+            this.browsers.set(runId, browser);
+        }
+        const result = await browser.inspect(input);
+        return input.action === 'screenshot' ? result : redactValue(result, this.sanitize);
+    }
+    async stop(runId) {
+        const result = await this.runs.stop(runId);
+        await this.browsers.get(runId)?.close();
+        this.browsers.delete(runId);
+        return result;
+    }
+    async close() {
+        this.closed = true;
+        this.tap.close();
+        await this.runs.close();
+        await Promise.all([...this.browsers.values()].map((browser) => browser.close()));
+        this.browsers.clear();
+    }
+    async startOpenSpec(runId, options) {
+        const deadline = Date.now() + Math.min(options.timeoutSeconds ?? 900, 120) * 1000;
+        try {
+            while (!this.closed && this.runs.get(runId).status === 'running' && Date.now() < deadline) {
+                const sessions = await this.tap.execute({ action: 'sessions', timeoutMs: 5000 });
+                if (sessions.length > 1)
+                    throw new Error('Multiple open Cypress sessions appeared; cannot safely select one.');
+                if (sessions.length === 1) {
+                    const sessionId = sessions[0].pid;
+                    const request = await this.tap.execute({ action: 'run', sessionId, spec: options.spec, runTimeoutSeconds: options.timeoutSeconds });
+                    this.tapSessions.set(runId, { status: 'requested', sessionId, requestId: request.requestId });
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 500));
+            }
+            if (!this.closed && this.runs.get(runId).status === 'running')
+                throw new Error('Timed out waiting for the managed Cypress open session.');
+        }
+        catch (error) {
+            if (!this.closed) {
+                this.tapSessions.set(runId, { status: 'error', error: this.sanitize(error instanceof Error ? error.message : String(error)) });
+                await this.stop(runId);
+            }
+        }
+    }
+    browser(runId, port) {
+        return new CypressBrowser(port, this.sanitize, (record) => {
+            this.runs.recordCapture(runId, record);
+        });
+    }
+    async observe(runId) {
+        // Connect as soon as Chrome appears so diagnostics include events before the first inspection.
+        while (!this.closed && this.runs.get(runId).status === 'running') {
+            await this.browsers.get(runId)?.connect().catch(() => { });
+            await new Promise((resolve) => { const timer = setTimeout(resolve, 500); timer.unref(); });
+        }
+        await this.browsers.get(runId)?.close();
+    }
+}

package/dist/src/runtime/cypressTap.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+export declare const cypressTapInput: z.ZodEffects<z.ZodObject<{
+    action: z.ZodEnum<["sessions", "status", "specs", "run", "reporter", "command", "pin", "dom", "aria", "inspect"]>;
+    sessionId: z.ZodOptional<z.ZodNumber>;
+    requestId: z.ZodOptional<z.ZodString>;
+    spec: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    testId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    commandId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    attempt: z.ZodOptional<z.ZodNumber>;
+    depth: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodLiteral<"all">]>>;
+    selector: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    at: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodEffects<z.ZodString, string, string>]>>;
+    clear: z.ZodOptional<z.ZodBoolean>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    maxNodes: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    runTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    action: "status" | "run" | "specs" | "command" | "sessions" | "reporter" | "pin" | "dom" | "aria" | "inspect";
+    at?: string | number | undefined;
+    spec?: string | undefined;
+    selector?: string | undefined;
+    sessionId?: number | undefined;
+    requestId?: string | undefined;
+    testId?: string | undefined;
+    commandId?: string | undefined;
+    attempt?: number | undefined;
+    depth?: number | "all" | undefined;
+    clear?: boolean | undefined;
+    maxChars?: number | undefined;
+    maxNodes?: number | undefined;
+    timeoutMs?: number | undefined;
+    runTimeoutSeconds?: number | undefined;
+}, {
+    action: "status" | "run" | "specs" | "command" | "sessions" | "reporter" | "pin" | "dom" | "aria" | "inspect";
+    at?: string | number | undefined;
+    spec?: string | undefined;
+    selector?: string | undefined;
+    sessionId?: number | undefined;
+    requestId?: string | undefined;
+    testId?: string | undefined;
+    commandId?: string | undefined;
+    attempt?: number | undefined;
+    depth?: number | "all" | undefined;
+    clear?: boolean | undefined;
+    maxChars?: number | undefined;
+    maxNodes?: number | undefined;
+    timeoutMs?: number | undefined;
+    runTimeoutSeconds?: number | undefined;
+}>, {
+    action: "status" | "run" | "specs" | "command" | "sessions" | "reporter" | "pin" | "dom" | "aria" | "inspect";
+    at?: string | number | undefined;
+    spec?: string | undefined;
+    selector?: string | undefined;
+    sessionId?: number | undefined;
+    requestId?: string | undefined;
+    testId?: string | undefined;
+    commandId?: string | undefined;
+    attempt?: number | undefined;
+    depth?: number | "all" | undefined;
+    clear?: boolean | undefined;
+    maxChars?: number | undefined;
+    maxNodes?: number | undefined;
+    timeoutMs?: number | undefined;
+    runTimeoutSeconds?: number | undefined;
+}, {
+    action: "status" | "run" | "specs" | "command" | "sessions" | "reporter" | "pin" | "dom" | "aria" | "inspect";
+    at?: string | number | undefined;
+    spec?: string | undefined;
+    selector?: string | undefined;
+    sessionId?: number | undefined;
+    requestId?: string | undefined;
+    testId?: string | undefined;
+    commandId?: string | undefined;
+    attempt?: number | undefined;
+    depth?: number | "all" | undefined;
+    clear?: boolean | undefined;
+    maxChars?: number | undefined;
+    maxNodes?: number | undefined;
+    timeoutMs?: number | undefined;
+    runTimeoutSeconds?: number | undefined;
+}>;
+export type CypressTapInput = z.infer<typeof cypressTapInput>;
+export declare class CypressTap {
+    private readonly sanitize;
+    private readonly requests;
+    private readonly running;
+    private readonly root;
+    private readonly controller;
+    constructor(repoRoot: string, sanitize?: (value: string) => string);
+    close(): void;
+    execute(raw: CypressTapInput): Promise<any>;
+    private sessions;
+    private call;
+}