@e2edev/e2e 0.2.0

package/dist/report/live-status.js

@@ -0,0 +1,162 @@
+/**
+ * Live in-progress block for TTY reporters: the currently executing pairs and
+ * one progress counter line, repainted below the permanent log. Constructed
+ * without a raw control channel it is a no-op, so callers never branch.
+ */
+import pc from 'picocolors';
+const ESC = '\u001b';
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL_MS = 120;
+/**
+ * Clamps one status line to the terminal width, skipping ANSI sequences when
+ * counting. The erase sequence counts physical rows, so a line that wraps
+ * would leave stale fragments behind on every repaint.
+ */
+function clampToWidth(text, columns) {
+    // Two columns of margin: the ellipsis takes one, and a line that reaches
+    // the exact width puts some terminals into pending-wrap, which breaks the
+    // erase row count the same way real wrapping does.
+    const max = Math.max(4, columns - 2);
+    let width = 0;
+    let out = '';
+    for (let i = 0; i < text.length;) {
+        const char = text[i];
+        if (char === ESC) {
+            const end = text.indexOf('m', i);
+            if (end === -1)
+                break;
+            out += text.slice(i, end + 1);
+            i = end + 1;
+            continue;
+        }
+        if (width >= max)
+            return `${out}${ESC}[0m…`;
+        out += char;
+        width += 1;
+        i += 1;
+    }
+    return out;
+}
+export class LiveStatus {
+    raw;
+    /**
+     * Entries currently executing, keyed by the caller, in start order. An
+     * undefined text counts toward the progress line without rendering a row,
+     * for entries whose story streams permanently above the block.
+     */
+    running = new Map();
+    /** Lines the status block currently occupies below the log. */
+    statusLines = 0;
+    /** Planned entries; 0 until the plan is announced. */
+    total = 0;
+    /** Entries with a reported result. */
+    done = 0;
+    /** Current spinner frame; advanced by the animation timer. */
+    frame = 0;
+    timer;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** Animates while any entry renders; stopped and unref'd otherwise. */
+    syncTimer(visible) {
+        if (this.raw === undefined)
+            return;
+        if (visible === 0) {
+            if (this.timer !== undefined)
+                clearInterval(this.timer);
+            this.timer = undefined;
+            return;
+        }
+        if (this.timer !== undefined)
+            return;
+        this.timer = setInterval(() => {
+            this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+            this.redraw();
+        }, SPINNER_INTERVAL_MS);
+        this.timer.unref();
+    }
+    /** Announces how many entries the run will execute. */
+    plan(total) {
+        this.total = total;
+        this.redraw();
+    }
+    /** Shows one started entry in the block; undefined counts it invisibly. */
+    start(key, text) {
+        this.running.set(key, text);
+        this.redraw();
+    }
+    /** Counts one finished entry and removes it from the block. */
+    finish(key) {
+        this.done += 1;
+        this.running.delete(key);
+    }
+    /** Counts one finished entry that never appeared in the block. */
+    skip() {
+        this.done += 1;
+        this.redraw();
+    }
+    /** Clears the block so permanent log lines can be appended. */
+    erase() {
+        if (this.raw === undefined || this.statusLines === 0)
+            return;
+        this.raw(`${ESC}[${this.statusLines}A${ESC}[0J`);
+        this.statusLines = 0;
+    }
+    /**
+     * Ends the live block for good: entries still running (an interrupt, a
+     * crashed worker) are dropped and the spinner timer is cleared, so nothing
+     * repaints after the final summary in a long-lived programmatic caller.
+     */
+    stop() {
+        this.running.clear();
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.erase();
+    }
+    /**
+     * Repaints the block below the permanent log. An entry may span several
+     * lines (test header, current step, recent calls); the marker goes on the
+     * first line and every line is clamped so the row count stays exact.
+     */
+    redraw() {
+        if (this.raw === undefined)
+            return;
+        const columns = process.stdout.columns ?? 100;
+        let payload = this.statusLines > 0 ? `${ESC}[${this.statusLines}A${ESC}[0J` : '';
+        let rows = 0;
+        let visible = 0;
+        const marker = SPINNER_FRAMES[this.frame] ?? '▸';
+        for (const text of this.running.values()) {
+            if (text === undefined)
+                continue;
+            visible += 1;
+            const lines = text.split('\n');
+            for (const [index, line] of lines.entries()) {
+                const prefixed = index === 0 ? `${pc.cyan(marker)} ${line}` : line;
+                payload += `${clampToWidth(prefixed, columns)}\n`;
+                rows += 1;
+            }
+        }
+        const progress = this.progressLine();
+        if (progress !== undefined)
+            payload += `${clampToWidth(progress, columns)}\n`;
+        this.statusLines = rows + (progress === undefined ? 0 : 1);
+        if (payload !== '')
+            this.raw(payload);
+        this.syncTimer(visible);
+    }
+    /** One bounded counter line: completed, executing, and waiting entries. */
+    progressLine() {
+        if (this.total === 0)
+            return undefined;
+        const waiting = Math.max(0, this.total - this.done - this.running.size);
+        const parts = [
+            `${this.done}/${this.total} done`,
+            `${this.running.size} running`,
+            `${waiting} waiting`,
+        ];
+        return pc.dim(`  ${parts.join(' · ')}`);
+    }
+}
+//# sourceMappingURL=live-status.js.map

package/dist/report/live-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-status.js","sourceRoot":"","sources":["../../src/report/live-status.ts"],"names":[],"mappings":"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"}

package/dist/report/write.d.ts

@@ -0,0 +1,4 @@
+/** Atomic report persistence (spec 13-reporting.md). */
+/** Atomically writes a wire JSON document with two-space indent and trailing newline. */
+export declare function writeJsonReport(filePath: string, document: unknown): Promise<void>;
+//# sourceMappingURL=write.d.ts.map

package/dist/report/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/report/write.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAOxD,yFAAyF;AACzF,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF"}

package/dist/report/write.js

@@ -0,0 +1,13 @@
+/** Atomic report persistence (spec 13-reporting.md). */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/** Atomically writes a wire JSON document with two-space indent and trailing newline. */
+export async function writeJsonReport(filePath, document) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const temporary = `${filePath}.tmp-${randomBytes(4).toString('hex')}`;
+    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+    await rename(temporary, filePath);
+}
+//# sourceMappingURL=write.js.map

package/dist/report/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/report/write.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB,EAAE,QAAiB;IACvE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,GAAG,QAAQ,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IACtE,MAAM,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7E,MAAM,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC"}

package/dist/run/app-process.d.ts

@@ -0,0 +1,18 @@
+/** Structured app process management (spec 05-config.md). */
+import type { CommandConfig } from '../types.ts';
+export declare class AppProcess {
+    private readonly command;
+    private readonly projectRoot;
+    private readonly readyUrl;
+    private child;
+    constructor(command: CommandConfig, projectRoot: string, readyUrl: string);
+    /**
+     * Spawns the process group and waits for the ready URL. An aborted `signal`
+     * ends the wait early and takes the process down with it; the caller reads
+     * the signal to learn the run was interrupted.
+     */
+    start(signal?: AbortSignal): Promise<void>;
+    /** Gracefully terminates the whole process group, then force-kills. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=app-process.d.ts.map

package/dist/run/app-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-process.d.ts","sourceRoot":"","sources":["../../src/run/app-process.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAM7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAUjD,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,KAAK,CAA6B;IAE1C,YACmB,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAC/B;IAEJ;;;;OAIG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA4D/C;IAED,uEAAuE;IACjE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAyB1B;CACF"}

package/dist/run/app-process.js

@@ -0,0 +1,112 @@
+/** Structured app process management (spec 05-config.md). */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { InfrastructureError } from '../internal/errors.js';
+import { sleep } from '../internal/time.js';
+const INHERITED_ENV = ['PATH', 'HOME', 'TMPDIR', 'TMP', 'TEMP', 'SystemRoot', 'COMSPEC'];
+/** Readiness polling starts fast and backs off; a booting server answers late, not on a schedule. */
+const READY_POLL_MIN_MS = 25;
+const READY_POLL_MAX_MS = 250;
+/** One readiness probe never outlives this, so a half-open server cannot stall the deadline check. */
+const READY_PROBE_TIMEOUT_MS = 2_000;
+export class AppProcess {
+    command;
+    projectRoot;
+    readyUrl;
+    child = null;
+    constructor(command, projectRoot, readyUrl) {
+        this.command = command;
+        this.projectRoot = projectRoot;
+        this.readyUrl = readyUrl;
+    }
+    /**
+     * Spawns the process group and waits for the ready URL. An aborted `signal`
+     * ends the wait early and takes the process down with it; the caller reads
+     * the signal to learn the run was interrupted.
+     */
+    async start(signal) {
+        const env = {};
+        for (const key of INHERITED_ENV) {
+            const value = process.env[key];
+            if (value !== undefined)
+                env[key] = value;
+        }
+        Object.assign(env, this.command.env ?? {});
+        this.child = spawn(this.command.executable, [...(this.command.args ?? [])], {
+            cwd: path.resolve(this.projectRoot, this.command.cwd ?? '.'),
+            env,
+            detached: process.platform !== 'win32',
+            stdio: 'ignore',
+        });
+        let spawnError;
+        this.child.on('error', (error) => {
+            spawnError = error;
+        });
+        const startupTimeout = this.command.startupTimeout ?? 60_000;
+        const deadline = Date.now() + startupTimeout;
+        let pollMs = READY_POLL_MIN_MS;
+        for (;;) {
+            if (signal?.aborted === true) {
+                await this.stop();
+                return;
+            }
+            if (spawnError !== undefined) {
+                throw new InfrastructureError('APP_UNREACHABLE', `app command failed to start: ${spawnError.message}`, { cause: spawnError });
+            }
+            if (this.child.exitCode !== null) {
+                throw new InfrastructureError('APP_UNREACHABLE', `app command exited with code ${this.child.exitCode} before becoming ready`);
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                await this.stop();
+                throw new InfrastructureError('APP_UNREACHABLE', `app was not reachable at ${this.readyUrl} within ${startupTimeout} ms`);
+            }
+            try {
+                const response = await fetch(this.readyUrl, {
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(Math.min(READY_PROBE_TIMEOUT_MS, remaining)),
+                });
+                if (response.status >= 200 && response.status <= 499)
+                    return;
+            }
+            catch {
+                // not ready yet
+            }
+            await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())), signal).catch(() => undefined);
+            pollMs = Math.min(pollMs * 2, READY_POLL_MAX_MS);
+        }
+    }
+    /** Gracefully terminates the whole process group, then force-kills. */
+    async stop() {
+        const child = this.child;
+        this.child = null;
+        if (child === null || child.exitCode !== null)
+            return;
+        const shutdownTimeout = this.command.shutdownTimeout ?? 10_000;
+        const pid = child.pid;
+        const signalGroup = (signal) => {
+            if (pid === undefined)
+                return;
+            try {
+                if (process.platform !== 'win32')
+                    process.kill(-pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch {
+                // process already gone
+            }
+        };
+        signalGroup('SIGTERM');
+        const exited = new Promise((resolve) => {
+            child.once('exit', () => resolve());
+        });
+        const timer = sleep(shutdownTimeout).then(() => 'timeout');
+        const winner = await Promise.race([exited.then(() => 'exited'), timer]);
+        if (winner === 'timeout') {
+            signalGroup('SIGKILL');
+            await exited.catch(() => undefined);
+        }
+    }
+}
+//# sourceMappingURL=app-process.js.map

package/dist/run/app-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-process.js","sourceRoot":"","sources":["../../src/run/app-process.ts"],"names":[],"mappings":"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"}

package/dist/run/artifacts.d.ts

@@ -0,0 +1,51 @@
+/** Attempt-scoped artifact directory and report registration. */
+import type { ArtifactStore } from '../types.ts';
+import type { ArtifactSink } from './fixtures.ts';
+import type { ArtifactRecord } from './records.ts';
+export interface AttemptArtifacts {
+    /** Absolute attempt artifact directory, created eagerly. */
+    readonly dir: string;
+    /** Report-order artifact records; the sink appends to this array. */
+    readonly records: ArtifactRecord[];
+    readonly sink: ArtifactSink;
+    /**
+     * Resolves once every registered file has been measured and hashed.
+     * Registration itself is synchronous and cheap; the size and digest of a
+     * file (a trace zip can be tens of megabytes) are filled in off the event
+     * loop, so awaiting this before the record is read is what makes them
+     * complete.
+     */
+    settle(): Promise<void>;
+}
+/**
+ * Creates the artifact directory for one attempt and a sink that registers
+ * produced files under report-relative paths, measuring and hashing them
+ * asynchronously. With a `store`, each complete artifact is also handed to it
+ * right then — as produced, not at run end — and the store's reference lands
+ * on the record as `ref`.
+ */
+export declare function createAttemptArtifacts(options: {
+    artifactsRoot: string;
+    /** Report path segments, e.g. [targetName, sanitizedTestId, attempt-N]. */
+    segments: readonly string[];
+    attemptId: string;
+    /** When provided, artifacts are attributed to the currently running step. */
+    currentStepId?: () => string | undefined;
+    /** Host store every artifact is handed to once complete; undefined keeps files local only. */
+    store?: ArtifactStore;
+    /**
+     * Report identity handed to the store with each artifact. `attemptId` is
+     * the attempt the REPORT files the artifact under; a serial member's
+     * artifacts land on the group attempt's record, so its store identity is the
+     * group's id while its own ids (`<attemptId>:artifact:N`) still mint from
+     * the member. Defaults to `attemptId`.
+     */
+    identity?: {
+        readonly runId: string;
+        readonly testId: string;
+        readonly attemptId?: string;
+    };
+}): AttemptArtifacts;
+/** Restricts a report path segment to a safe filename alphabet. */
+export declare function sanitizePathSegment(value: string): string;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/run/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/run/artifacts.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAOjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;;;OAMG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACzC,8FAA8F;IAC9F,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7F,GAAG,gBAAgB,CAwEnB;AAcD,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/run/artifacts.js

@@ -0,0 +1,114 @@
+/** Attempt-scoped artifact directory and report registration. */
+import { createHash } from 'node:crypto';
+import { createReadStream, mkdirSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+/**
+ * Creates the artifact directory for one attempt and a sink that registers
+ * produced files under report-relative paths, measuring and hashing them
+ * asynchronously. With a `store`, each complete artifact is also handed to it
+ * right then — as produced, not at run end — and the store's reference lands
+ * on the record as `ref`.
+ */
+export function createAttemptArtifacts(options) {
+    const dir = path.join(options.artifactsRoot, ...options.segments);
+    mkdirSync(dir, { recursive: true });
+    const records = [];
+    const pending = [];
+    const sink = {
+        dir,
+        register: (kind, relativePath) => {
+            const id = `${options.attemptId}:artifact:${records.length}`;
+            const absolute = path.join(dir, relativePath);
+            const stepId = options.currentStepId?.();
+            const record = {
+                id,
+                kind,
+                mediaType: mediaTypeFor(relativePath),
+                redaction: 'complete',
+                producer: stepId === undefined ? { kind: 'attempt' } : { kind: 'step', stepId },
+            };
+            records.push(record);
+            const reportPath = path.posix.join(...options.segments, relativePath);
+            pending.push((async () => {
+                // Without a store the file is streamed for its size and digest only;
+                // with one it is read whole, since the store needs the bytes anyway,
+                // and hashed from that same buffer. A file that never appeared is
+                // recorded without size or digest either way.
+                if (options.store === undefined) {
+                    const measured = await measure(absolute);
+                    if (measured === undefined)
+                        return;
+                    record.path = reportPath;
+                    record.size = measured.size;
+                    record.sha256 = measured.sha256;
+                    return;
+                }
+                const bytes = await readFile(absolute).catch(() => undefined);
+                if (bytes === undefined)
+                    return;
+                record.path = reportPath;
+                record.size = bytes.byteLength;
+                record.sha256 = createHash('sha256').update(bytes).digest('hex');
+                // The store's failure is its own: the record keeps its local path and
+                // simply carries no ref, and the run is never failed by evidence
+                // that did not upload.
+                try {
+                    const { ref } = await options.store.put({
+                        kind,
+                        mediaType: record.mediaType,
+                        bytes,
+                        size: record.size,
+                        sha256: record.sha256,
+                        path: reportPath,
+                        runId: options.identity?.runId ?? '',
+                        testId: options.identity?.testId ?? '',
+                        attemptId: options.identity?.attemptId ?? options.attemptId,
+                        ...(stepId === undefined ? {} : { stepId }),
+                    });
+                    if (typeof ref === 'string' && ref !== '')
+                        record.ref = ref;
+                }
+                catch {
+                    // best-effort by contract
+                }
+            })());
+            return id;
+        },
+    };
+    const settle = async () => {
+        // Registrations may land while earlier ones are still hashing.
+        while (pending.length > 0)
+            await Promise.all(pending.splice(0));
+    };
+    return { dir, records, sink, settle };
+}
+/** Size and SHA-256 of one file, streamed; undefined when it cannot be read. */
+async function measure(absolute) {
+    try {
+        const { size } = await stat(absolute);
+        const hash = createHash('sha256');
+        await pipeline(createReadStream(absolute), hash);
+        return { size, sha256: hash.digest('hex') };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Restricts a report path segment to a safe filename alphabet. */
+export function sanitizePathSegment(value) {
+    return value.replaceAll(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+}
+function mediaTypeFor(relativePath) {
+    if (relativePath.endsWith('.png'))
+        return 'image/png';
+    if (relativePath.endsWith('.zip'))
+        return 'application/zip';
+    if (relativePath.endsWith('.webm'))
+        return 'video/webm';
+    if (relativePath.endsWith('.txt'))
+        return 'text/plain';
+    return 'application/octet-stream';
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/run/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../src/run/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/run/events.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Structured run events (`@e2edev/e2e/run`): the run's single event spine.
+ *
+ * Every event is plain JSON data — the same records the report persists and
+ * the worker IPC already carries, so a host can stream them over any wire
+ * without touching live handles. The list reporter consumes exactly this
+ * stream (`ListReporter.handle`, report/list.ts), so the CLI's rendering and a
+ * host's dashboard can never drift: there is one dispatch, not two. The
+ * report stays the canonical record; the stream exists so consumers can
+ * render progress while the run is still going.
+ *
+ * The emitter is the single writer: it stamps `seq` and `at`, so ordering
+ * survives any transport that preserves per-connection order. A sink that
+ * throws is quarantined for the rest of the run; a sink whose returned
+ * promise rejects is quarantined once the rejection settles, so events
+ * emitted before then may still reach it. Either way a broken consumer can
+ * never fail the run.
+ */
+import type { SerializedError } from '../internal/errors.ts';
+import type { ResultRecord, SerialGroupRecord } from './records.ts';
+import type { StepProgress } from './steps.ts';
+import { type WireResultRecord } from './worker/protocol.ts';
+/** The closed set of process exit codes a run can end with. */
+export type RunExitCode = 0 | 1 | 2 | 3 | 4 | 130;
+/**
+ * `ResultRecord` minus the live resolved target (the wire encoding the worker
+ * IPC already uses), plus the target's stable identity so a consumer can
+ * attribute the result without a side lookup.
+ */
+export interface RunEventResult extends WireResultRecord {
+    readonly target: {
+        readonly name: string;
+        readonly platform: string;
+    };
+}
+/** One fact about the run; the emitter wraps it in the envelope. */
+export type RunEventFact = {
+    readonly type: 'run-started';
+    readonly runId: string;
+    readonly projectId: string;
+    readonly projectRoot: string;
+    readonly ci: boolean;
+    readonly targets: readonly string[];
+} | {
+    readonly type: 'plan';
+    readonly total: number;
+} | {
+    readonly type: 'test-started';
+    readonly testId: string;
+    readonly title: string;
+    readonly target: string;
+} | {
+    readonly type: 'step';
+    readonly testId: string;
+    readonly target: string;
+    readonly progress: StepProgress;
+} | {
+    readonly type: 'test-finished';
+    readonly result: RunEventResult;
+} | {
+    readonly type: 'serial-group';
+    readonly group: SerialGroupRecord;
+} | {
+    readonly type: 'run-error';
+    readonly error: SerializedError;
+} | {
+    readonly type: 'run-finished';
+    readonly status: 'passed' | 'failed' | 'error' | 'interrupted';
+    readonly exitCode: RunExitCode;
+    readonly reportPath?: string;
+    /** Where `--ai-trace` wrote the run's model calls, once the file exists. */
+    readonly aiTracePath?: string;
+};
+/** Envelope stamped by the emitter: monotonic order and wall-clock time. */
+export interface RunEventHeader {
+    readonly seq: number;
+    readonly at: string;
+}
+export type RunEvent = RunEventHeader & RunEventFact;
+/** The fact of one event type, for a consumer that handles types one at a time. */
+export type RunEventOf<Type extends RunEventFact['type']> = Extract<RunEventFact, {
+    type: Type;
+}>;
+/**
+ * An event consumer. Must not block; a throw — or, when it returns a
+ * promise, a rejection — quarantines the sink. An async sink observes events
+ * in emit order but cannot delay them; ordering between its own pending
+ * handlers is its own responsibility.
+ */
+export type RunEventSink = (event: RunEvent) => void | Promise<void>;
+/** Strips the live target from a result, keeping its stable identity. */
+export declare function toEventResult(record: ResultRecord): RunEventResult;
+/**
+ * Builds the run's single event writer over every configured sink. Sinks are
+ * quarantined independently, so a broken host callback cannot silence the
+ * list reporter or vice versa. Returns a no-op when no sink is configured,
+ * so call sites never branch.
+ */
+export declare function createRunEventEmitter(sinks: readonly (RunEventSink | undefined)[]): (fact: RunEventFact) => void;
+//# sourceMappingURL=events.d.ts.map

package/dist/run/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/run/events.ts"],"names":[],"mappings":"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"}