@crvouga/atlas 0.5.0 → 0.6.0

package/dist/reports/src/report-cli.d.ts

@@ -13,7 +13,7 @@
  * @see docs/agents.md
  */
 /** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
-export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
+export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
 type Env = Readonly<Record<string, string | undefined>>;
 type Git = (args: readonly string[]) => string | null;
 /** What `reportMain` is given besides arguments: where output goes (`out`), and, for tests and embedding, the environment, working directory, git, clock and standard input (`stdin`, where `stream` reads checks from). Defaults are the real ones. */

package/dist/reports/src/report-cli.js

@@ -54,7 +54,8 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
   atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]
 
   A store is a directory or s3://bucket/prefix (add ?region=…&endpoint=… for R2, MinIO and the
-  rest). When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set
+  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.
+  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set
   AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with \`aws sso login\`, or use a role.
 
   publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.
@@ -211,7 +212,7 @@ function printChecks(out, label, checks) {
 export async function reportMain(argv, io = { out: text => process.stdout.write(text) }) {
     const [command, ...rest] = argv;
     const base = io.cwd ?? process.cwd();
-    const env = io.env ?? process.env;
+    const env = { ...(io.env ?? process.env), ...(value(rest, 'project') !== undefined ? { ATLAS_PROJECT: value(rest, 'project') } : {}) };
     const clock = io.clock ?? Date.now;
     if (command === 'publish') {
         const target = writeStoreOf(value(rest, 'store'), base, env);

package/dist/reports/src/store-url.js

@@ -77,7 +77,7 @@ export function openStore(spec, options) {
         const token = serverToken(env, options.role ?? { id: '', soleServer: true });
         if (token)
             refuseClearToken(location.url, env);
-        const server = httpStore({ url: location.url, ...(token ? { token } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) });
+        const server = httpStore({ url: location.url, ...(env.ATLAS_PROJECT ? { project: env.ATLAS_PROJECT } : {}), ...(token ? { token } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) });
         return { store: server, label: server.label, location, server };
     }
     const s3 = s3Store({

package/dist/runners/src/codecept.d.ts

@@ -0,0 +1,14 @@
+/** @module CodeceptJS reporter
+ * CodeceptJS's Mocha reporter interface carries scenario outcomes and steps to the singleton Atlas server.
+ */
+import AtlasMochaReporter from './mocha.js';
+/**
+ * Use `codeceptjs run --reporter @crvouga/atlas/codecept` with ATLAS_SERVER_URL and ATLAS_PUBLISH_TOKEN.
+ * Upload failures fail the run; skipped scenarios remain not-run.
+ * @example
+ * // codecept.conf.js
+ * export const config = { tests: './tests/*_test.js', reporter: '@crvouga/atlas/codecept' };
+ */
+export default class AtlasCodeceptReporter extends AtlasMochaReporter {
+    constructor(...args: [ConstructorParameters<typeof AtlasMochaReporter>[0], ConstructorParameters<typeof AtlasMochaReporter>[1]?]);
+}

package/dist/runners/src/codecept.js

@@ -0,0 +1,16 @@
+/** @module CodeceptJS reporter
+ * CodeceptJS's Mocha reporter interface carries scenario outcomes and steps to the singleton Atlas server.
+ */
+import AtlasMochaReporter from './mocha.js';
+/**
+ * Use `codeceptjs run --reporter @crvouga/atlas/codecept` with ATLAS_SERVER_URL and ATLAS_PUBLISH_TOKEN.
+ * Upload failures fail the run; skipped scenarios remain not-run.
+ * @example
+ * // codecept.conf.js
+ * export const config = { tests: './tests/*_test.js', reporter: '@crvouga/atlas/codecept' };
+ */
+export default class AtlasCodeceptReporter extends AtlasMochaReporter {
+    constructor(...args) {
+        super(args[0], args[1], 'codeceptjs');
+    }
+}

package/dist/runners/src/jest.d.ts

@@ -0,0 +1,50 @@
+import { type ReporterOptions } from './publish.js';
+type Result = {
+    testFilePath: string;
+    testExecError?: {
+        message?: string;
+        stack?: string;
+    };
+    failureMessage?: string;
+    testResults: {
+        title: string;
+        fullName: string;
+        status: string;
+        duration?: number | null;
+        failureMessages: string[];
+        invocations?: number;
+    }[];
+};
+/**
+ * Jest's native reporter; retain `default` in the reporter list for console output. Upload errors fail Jest.
+ * @example
+ * export default { reporters: ['default', ['@crvouga/atlas/jest', { url: 'https://atlas.example.com' }]] };
+ */
+export default class AtlasJestReporter {
+    private readonly options;
+    private live;
+    private error;
+    constructor(_config: unknown, options?: ReporterOptions);
+    /** Reset publishing errors for each watch-mode invocation. */
+    onRunStart(result?: {
+        numTotalTests?: number;
+    }): void;
+    /** Publish the test as running before its body executes in a worker. */
+    onTestCaseStart(test: {
+        path: string;
+    }, info: {
+        fullName: string;
+        title: string;
+    }): void;
+    /** Stream each test outcome immediately, without waiting for other files to finish. */
+    onTestCaseResult(test: {
+        path: string;
+    }, result: Result['testResults'][number]): void;
+    /** Await uploading every final result, including test-file failures before any test ran. */
+    onRunComplete(_contexts: unknown, result: {
+        testResults: Result[];
+    }): Promise<void>;
+    /** Jest uses this to turn a publishing error into a failed invocation. */
+    getLastError(): Error | undefined;
+}
+export {};

package/dist/runners/src/jest.js

@@ -0,0 +1,52 @@
+import { testFile, runnerLive, finishRunner } from './publish.js';
+/**
+ * Jest's native reporter; retain `default` in the reporter list for console output. Upload errors fail Jest.
+ * @example
+ * export default { reporters: ['default', ['@crvouga/atlas/jest', { url: 'https://atlas.example.com' }]] };
+ */
+export default class AtlasJestReporter {
+    options;
+    live;
+    error;
+    constructor(_config, options = {}) {
+        this.options = options;
+    }
+    /** Reset publishing errors for each watch-mode invocation. */
+    onRunStart(result) { this.error = undefined; this.live = runnerLive('jest', this.options, result?.numTotalTests || undefined); }
+    /** Publish the test as running before its body executes in a worker. */
+    onTestCaseStart(test, info) {
+        this.live ??= runnerLive('jest', this.options);
+        this.live.check({ id: `${testFile(test.path, this.options.rootDir)} > ${info.fullName}`, title: info.title, status: 'running' });
+    }
+    /** Stream each test outcome immediately, without waiting for other files to finish. */
+    onTestCaseResult(test, result) {
+        this.live ??= runnerLive('jest', this.options);
+        this.live.check({ id: `${testFile(test.path, this.options.rootDir)} > ${result.fullName}`, title: result.title,
+            status: result.status === 'passed' ? 'passed' : result.status === 'failed' ? 'failed' : 'not-run', detail: result.failureMessages.join('\n') });
+    }
+    /** Await uploading every final result, including test-file failures before any test ran. */
+    async onRunComplete(_contexts, result) {
+        const checks = [];
+        for (const suite of result.testResults) {
+            const file = testFile(suite.testFilePath, this.options.rootDir);
+            for (const test of suite.testResults)
+                checks.push({ id: `${file} > ${test.fullName}`, title: test.title,
+                    status: test.status === 'passed' ? 'passed' : test.status === 'failed' ? 'failed' : 'not-run',
+                    detail: test.failureMessages.join('\n'), measurements: [],
+                    ...(typeof test.duration === 'number' && Number.isFinite(test.duration) && test.duration >= 0 ? { durationMs: test.duration } : {}),
+                    ...((test.invocations ?? 1) > 1 ? { labels: { retries: String(test.invocations - 1), ...(test.status === 'passed' ? { flaky: 'true' } : {}) } } : {}) });
+            if (suite.testExecError)
+                checks.push({ id: `${file} > [suite error]`, title: `${file}: suite error`, status: 'failed', detail: suite.testExecError.stack ?? suite.testExecError.message ?? suite.failureMessage ?? 'Suite did not execute', measurements: [] });
+        }
+        this.live ??= runnerLive('jest', this.options);
+        checks.forEach(check => this.live.check(check));
+        try {
+            await finishRunner(this.live, 'jest', checks, this.options);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    /** Jest uses this to turn a publishing error into a failed invocation. */
+    getLastError() { return this.error; }
+}

package/dist/runners/src/mocha.d.ts

@@ -0,0 +1,40 @@
+import { type ReporterOptions } from './publish.js';
+type Test = {
+    title: string;
+    file?: string;
+    duration?: number;
+    fullTitle(): string;
+    err?: {
+        stack?: string;
+        message?: string;
+    };
+    steps?: {
+        name?: string;
+        status?: string;
+    }[];
+    currentRetry?(): number;
+};
+type Runner = {
+    total?: number;
+    on(event: string, listener: (test: Test, error?: Error) => void): unknown;
+};
+/**
+ * Mocha reporter; use `--reporter @crvouga/atlas/mocha` or CodeceptJS `--reporter @crvouga/atlas/codecept`.
+ * Reporter options go in `reporterOptions`; environment variables are supported by every runner.
+ * A failed upload adds a runner failure through Mocha's completion callback.
+ * @example
+ * // mocha configuration
+ * export default { reporter: '@crvouga/atlas/mocha', reporterOptions: { url: 'https://atlas.example.com' } };
+ */
+export default class AtlasMochaReporter {
+    private readonly checks;
+    private readonly options;
+    private readonly runnerName;
+    private readonly live;
+    constructor(runner: Runner, options?: {
+        reporterOptions?: ReporterOptions;
+    }, runnerName?: string);
+    /** Mocha waits for this callback before exiting. Publishing errors fail the invocation. */
+    done(failures: number, callback: (failures: number) => void): void;
+}
+export {};

package/dist/runners/src/mocha.js

@@ -0,0 +1,39 @@
+import { testFile, runnerLive, finishRunner } from './publish.js';
+/**
+ * Mocha reporter; use `--reporter @crvouga/atlas/mocha` or CodeceptJS `--reporter @crvouga/atlas/codecept`.
+ * Reporter options go in `reporterOptions`; environment variables are supported by every runner.
+ * A failed upload adds a runner failure through Mocha's completion callback.
+ * @example
+ * // mocha configuration
+ * export default { reporter: '@crvouga/atlas/mocha', reporterOptions: { url: 'https://atlas.example.com' } };
+ */
+export default class AtlasMochaReporter {
+    checks = new Map();
+    options;
+    runnerName;
+    live;
+    constructor(runner, options = {}, runnerName = 'mocha') {
+        this.options = options.reporterOptions ?? {};
+        this.runnerName = runnerName;
+        this.live = runnerLive(runnerName, this.options, runner.total);
+        const add = (test, status, error) => {
+            const file = testFile(test.file, this.options.rootDir);
+            const retry = test.currentRetry?.() ?? 0;
+            this.checks.set(test, { id: [file, test.fullTitle()].filter(Boolean).join(' > '), title: test.title, status,
+                detail: error?.stack ?? error?.message ?? (status === 'failed' ? test.err?.stack ?? test.err?.message ?? 'failed' : ''), measurements: [],
+                ...(typeof test.duration === 'number' && Number.isFinite(test.duration) && test.duration >= 0 ? { durationMs: test.duration } : {}),
+                ...(retry ? { labels: { retries: String(retry), ...(status === 'passed' ? { flaky: 'true' } : {}) } } : {}),
+                ...(test.steps?.length ? { steps: test.steps.map(step => ({ name: step.name ?? 'step', ...(step.status ? { status: step.status } : {}) })) } : {}) });
+            const check = this.checks.get(test);
+            this.live.check({ ...check, steps: check.steps?.map(step => ({ name: step.name, status: step.status })) });
+        };
+        runner.on('test', test => add(test, 'running'));
+        runner.on('pass', test => add(test, 'passed'));
+        runner.on('fail', (test, error) => add(test, 'failed', error));
+        runner.on('pending', test => add(test, 'not-run'));
+    }
+    /** Mocha waits for this callback before exiting. Publishing errors fail the invocation. */
+    done(failures, callback) {
+        void finishRunner(this.live, this.runnerName, [...this.checks.values()], this.options).then(() => callback(failures), error => { console.error(error instanceof Error ? error.message : String(error)); callback(failures + 1); });
+    }
+}

package/dist/runners/src/node-test.d.ts

@@ -0,0 +1,28 @@
+type Event = {
+    type: string;
+    data: {
+        name?: string;
+        file?: string;
+        nesting?: number;
+        type?: string;
+        skip?: boolean | string;
+        todo?: boolean | string;
+        details?: {
+            type?: string;
+            duration_ms?: number;
+            error?: {
+                stack?: string;
+                message?: string;
+                failureType?: string;
+            };
+        };
+    };
+};
+/**
+ * Async generator reporter. Use alongside Node's spec reporter to keep normal output.
+ * Upload errors reject the stream; skips and TODOs never count as passed. Successful suite containers are excluded; hook failures are retained.
+ * @example
+ * // node --test --test-reporter=spec --test-reporter=@crvouga/atlas/node-test
+ */
+export default function atlasNodeReporter(source: AsyncIterable<Event>): AsyncGenerator<string>;
+export {};

package/dist/runners/src/node-test.js

@@ -0,0 +1,44 @@
+import { testFile, runnerLive, finishRunner } from './publish.js';
+/**
+ * Async generator reporter. Use alongside Node's spec reporter to keep normal output.
+ * Upload errors reject the stream; skips and TODOs never count as passed. Successful suite containers are excluded; hook failures are retained.
+ * @example
+ * // node --test --test-reporter=spec --test-reporter=@crvouga/atlas/node-test
+ */
+export default async function* atlasNodeReporter(source) {
+    const checks = [];
+    const live = runnerLive('node-test');
+    const kinds = new Map();
+    try {
+        const parents = [];
+        for await (const { type, data } of source) {
+            const nesting = data.nesting ?? 0;
+            const identity = `${data.file ?? ''}|${nesting}|${data.name ?? ''}`;
+            if (type === 'test:enqueue' && data.type)
+                kinds.set(identity, data.type);
+            if (type === 'test:start') {
+                parents[nesting] = data.name ?? '';
+                parents.length = nesting + 1;
+                if (kinds.get(identity) === 'test')
+                    live.check({ id: [testFile(data.file), ...parents.slice(0, nesting), data.name].filter(Boolean).join(' > '), title: data.name ?? 'test', status: 'running' });
+            }
+            if (type !== 'test:pass' && type !== 'test:fail')
+                continue;
+            if (data.details?.type === 'suite' && (type === 'test:pass' || data.details.error?.failureType === 'subtestsFailed'))
+                continue;
+            const file = testFile(data.file);
+            const status = data.skip || data.todo ? 'not-run' : type === 'test:pass' ? 'passed' : 'failed';
+            checks.push({ id: [file, ...parents.slice(0, nesting), data.name].filter(Boolean).join(' > '), title: data.name ?? 'test', status,
+                detail: data.details?.error?.stack ?? data.details?.error?.message ?? '', measurements: [],
+                ...(typeof data.details?.duration_ms === 'number' && Number.isFinite(data.details.duration_ms) && data.details.duration_ms >= 0 ? { durationMs: data.details.duration_ms } : {}) });
+            live.check(checks.at(-1));
+        }
+        checks.forEach(check => live.check(check));
+        await finishRunner(live, 'node-test', checks);
+        yield `Atlas: uploaded ${checks.length} checks\n`;
+    }
+    catch (error) {
+        await live.finish('interrupted', 'The test event stream ended unexpectedly.').catch(() => { });
+        throw error;
+    }
+}

package/dist/runners/src/publish.d.ts

@@ -0,0 +1,30 @@
+import type { EvidenceCheck } from '../../reports/src/explorer-types.js';
+/** Reporter options; explicit values override ATLAS_SERVER_URL, ATLAS_PUBLISH_TOKEN, ATLAS_ENVIRONMENT, ATLAS_BRANCH and ATLAS_SHA. */
+export type ReporterOptions = {
+    /** Project namespace; defaults to ATLAS_PROJECT. */
+    readonly project?: string;
+    readonly url?: string;
+    readonly token?: string;
+    readonly producer?: string;
+    readonly environment?: string;
+    readonly branch?: string;
+    readonly sha?: string;
+    readonly timeoutMs?: number;
+    readonly rootDir?: string;
+    /** Explicit final evidence time; normally generated when publication finishes. */
+    readonly recordedAtMs?: number;
+};
+/** A portable check identity: paths relative to the project, using forward slashes on every OS. */
+export declare function testFile(file: string | undefined, root?: string): string;
+/**
+ * Upload one completed runner invocation. Unknown outcomes stay not-run, repeated identities are numbered.
+ * Throws on missing configuration, timeouts or refused uploads so CI cannot silently lose its evidence.
+ * No storage credentials or backend URL are needed by the runner.
+ * @example
+ * await uploadChecks('mocha', checks, { url: 'https://atlas.example.com', token: process.env.ATLAS_PUBLISH_TOKEN });
+ */
+export declare function uploadChecks(runner: string, checks: readonly EvidenceCheck[], options?: ReporterOptions): Promise<void>;
+/** Start the native runner's live feed with the same endpoint and identity as its final report. */
+export declare function runnerLive(runner: string, options?: ReporterOptions, plannedChecks?: number): import('../../reports/src/live-reporter.js').LiveReporter;
+/** Flush live progress, then publish the full final evidence even if the lease was interrupted. Reject either failure. */
+export declare function finishRunner(live: import('../../reports/src/live-reporter.js').LiveReporter, runner: string, checks: readonly EvidenceCheck[], options?: ReporterOptions): Promise<void>;

package/dist/runners/src/publish.js

@@ -0,0 +1,68 @@
+/** @module Publishing native runner results
+ * Native reporters send checks to the project's Atlas server. Only the server knows its storage backend.
+ */
+import path from 'node:path';
+import { createLiveReporter } from '../../reports/src/live-reporter.js';
+import { uniqueChecks } from '../../reports/src/ingest.js';
+/** A portable check identity: paths relative to the project, using forward slashes on every OS. */
+export function testFile(file, root = process.cwd()) {
+    return file ? path.relative(root, path.resolve(root, file)).replaceAll('\\', '/') : '';
+}
+/**
+ * Upload one completed runner invocation. Unknown outcomes stay not-run, repeated identities are numbered.
+ * Throws on missing configuration, timeouts or refused uploads so CI cannot silently lose its evidence.
+ * No storage credentials or backend URL are needed by the runner.
+ * @example
+ * await uploadChecks('mocha', checks, { url: 'https://atlas.example.com', token: process.env.ATLAS_PUBLISH_TOKEN });
+ */
+export async function uploadChecks(runner, checks, options = {}) {
+    const url = options.url ?? process.env.ATLAS_SERVER_URL;
+    if (!url)
+        throw new Error('Atlas reporter: set ATLAS_SERVER_URL to the project Atlas server');
+    const target = new URL(url);
+    if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.search || target.hash)
+        throw new Error('Atlas reporter: use an HTTP(S) server URL without credentials, query or fragment');
+    target.pathname = `${target.pathname.replace(/\/$/, '')}/api/checks`;
+    const token = options.token ?? process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN;
+    const response = await fetch(target, {
+        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+        headers: { 'content-type': 'application/json', ...((options.project ?? process.env.ATLAS_PROJECT) ? { 'x-atlas-project': options.project ?? process.env.ATLAS_PROJECT } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify({ producer: options.producer ?? runner, recordedAtMs: options.recordedAtMs ?? Date.now(),
+            environment: options.environment ?? process.env.ATLAS_ENVIRONMENT,
+            branch: options.branch ?? process.env.ATLAS_BRANCH, sha: options.sha ?? process.env.ATLAS_SHA,
+            checks: uniqueChecks(checks) })
+    });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`Atlas reporter: upload refused (HTTP ${response.status})`);
+    }
+    await response.body?.cancel();
+}
+/** Start the native runner's live feed with the same endpoint and identity as its final report. */
+export function runnerLive(runner, options = {}, plannedChecks) {
+    const url = options.url ?? process.env.ATLAS_SERVER_URL;
+    if (!url)
+        throw new Error('Atlas reporter: set ATLAS_SERVER_URL to the project Atlas server');
+    return createLiveReporter({ producer: options.producer ?? runner, plannedChecks, title: `${runner} tests`, environment: options.environment ?? process.env.ATLAS_ENVIRONMENT,
+        branch: options.branch ?? process.env.ATLAS_BRANCH, sha: options.sha ?? process.env.ATLAS_SHA }, { url, project: options.project ?? process.env.ATLAS_PROJECT, token: options.token ?? process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN, timeoutMs: options.timeoutMs });
+}
+/** Flush live progress, then publish the full final evidence even if the lease was interrupted. Reject either failure. */
+export async function finishRunner(live, runner, checks, options = {}) {
+    let error;
+    const finalChecks = uniqueChecks(checks);
+    finalChecks.forEach(check => live.check(check));
+    try {
+        await live.finish();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    try {
+        await uploadChecks(runner, finalChecks, { ...options, recordedAtMs: Math.max(Date.now(), (live.finishedAtMs ?? 0) + 1) });
+    }
+    catch (caught) {
+        error ??= caught;
+    }
+    if (error)
+        throw error;
+}

package/dist/schema/src/api.d.ts

@@ -774,6 +774,7 @@ export declare const HelloEventSchema: z.ZodObject<{
     version: z.ZodString;
     ready: z.ZodBoolean;
     time: z.ZodNumber;
+    heartbeatMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** The data of the `report` event: layers arrived. Enough to say who sent what, without asking. */
 export declare const ReportEventSchema: z.ZodObject<{

package/dist/schema/src/api.js

@@ -186,7 +186,7 @@ export const ChecksResultSchema = z.looseObject({
     checks: z.number().int().nonnegative()
 });
 /** The data of the `hello` event: sent first on `/api/events`. */
-export const HelloEventSchema = z.looseObject({ version: z.string(), ready: z.boolean(), time: z.number() });
+export const HelloEventSchema = z.looseObject({ version: z.string(), ready: z.boolean(), time: z.number(), heartbeatMs: z.number().positive().optional() });
 /** The data of the `report` event: layers arrived. Enough to say who sent what, without asking. */
 export const ReportEventSchema = z.looseObject({
     version: z.string().describe('The report version after these layers'),

package/dist/schema/src/index.d.ts

@@ -17,3 +17,5 @@ export * from './layer.js';
 export * from './server-config.js';
 export * from './api.js';
 export * from './cli-results.js';
+export * from './live-run.js';
+export * from './project.js';

package/dist/schema/src/index.js

@@ -17,3 +17,5 @@ export * from './layer.js';
 export * from './server-config.js';
 export * from './api.js';
 export * from './cli-results.js';
+export * from './live-run.js';
+export * from './project.js';

package/dist/schema/src/live-run.d.ts

@@ -0,0 +1,123 @@
+/** @module Live run protocol
+ * A live run is a producer lease, separate from immutable report layers. Server receipt times determine liveness.
+ * Expiration means interrupted, never passed; completed check results retain the stable layer contract.
+ */
+import { z } from 'zod/v4';
+/** Small progress messages: no attachment bytes, bounded step history and text. */
+export declare const LiveCheckSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        running: "running";
+        "not-run": "not-run";
+    }>;
+    detail: z.ZodDefault<z.ZodString>;
+    specPath: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** The producer starts one UUID-named run. Identity stays fixed for its lifetime. */
+export declare const LiveRunStartSchema: z.ZodObject<{
+    id: z.ZodString;
+    producer: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    sha: z.ZodOptional<z.ZodString>;
+    plannedChecks: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Ordered deltas. A retried sequence must have identical content; terminal runs never accept more progress. */
+export declare const LiveRunUpdateSchema: z.ZodObject<{
+    sequence: z.ZodNumber;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodDefault<z.ZodString>;
+        specPath: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    finish: z.ZodOptional<z.ZodEnum<{
+        completed: "completed";
+        interrupted: "interrupted";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The bounded live feed response; completed and interrupted runs remain visible as recent history. */
+export declare const LiveRunSchema: z.ZodObject<{
+    id: z.ZodString;
+    producer: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    sha: z.ZodOptional<z.ZodString>;
+    plannedChecks: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodEnum<{
+        running: "running";
+        completed: "completed";
+        interrupted: "interrupted";
+    }>;
+    startedAtMs: z.ZodNumber;
+    lastHeartbeatAtMs: z.ZodNumber;
+    lastProgressAtMs: z.ZodNumber;
+    finishedAtMs: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+    sequence: z.ZodNumber;
+    completed: z.ZodNumber;
+    passed: z.ZodNumber;
+    failed: z.ZodNumber;
+    notRun: z.ZodNumber;
+    running: z.ZodNumber;
+    current: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodDefault<z.ZodString>;
+        specPath: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    recent: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodDefault<z.ZodString>;
+        specPath: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The shape a producer uses for a progress check. */
+export type LiveCheck = z.input<typeof LiveCheckSchema>;
+/** A server's live run snapshot. */
+export type LiveRun = z.output<typeof LiveRunSchema>;

package/dist/schema/src/live-run.js

@@ -0,0 +1,30 @@
+/** @module Live run protocol
+ * A live run is a producer lease, separate from immutable report layers. Server receipt times determine liveness.
+ * Expiration means interrupted, never passed; completed check results retain the stable layer contract.
+ */
+import { z } from 'zod/v4';
+/** Small progress messages: no attachment bytes, bounded step history and text. */
+export const LiveCheckSchema = z.object({
+    id: z.string().min(1).max(16384), title: z.string().min(1).max(2048),
+    status: z.enum(['running', 'passed', 'failed', 'not-run']), detail: z.string().max(8000).default(''),
+    specPath: z.string().max(2048).optional(), durationMs: z.number().finite().nonnegative().optional(),
+    steps: z.array(z.object({ name: z.string().max(2048), status: z.string().max(100).optional() })).max(20).optional()
+});
+/** The producer starts one UUID-named run. Identity stays fixed for its lifetime. */
+export const LiveRunStartSchema = z.object({
+    id: z.string().uuid(), producer: z.string().min(1).max(200), title: z.string().max(2048).optional(),
+    environment: z.string().max(200).optional(), branch: z.string().max(500).optional(), sha: z.string().max(200).optional(),
+    plannedChecks: z.number().int().nonnegative().max(1_000_000).optional()
+});
+/** Ordered deltas. A retried sequence must have identical content; terminal runs never accept more progress. */
+export const LiveRunUpdateSchema = z.object({
+    sequence: z.number().int().positive(), checks: z.array(LiveCheckSchema).max(1000).refine(checks => new Set(checks.map(check => check.id)).size === checks.length, 'Check ids must be unique in a batch').default([]),
+    finish: z.enum(['completed', 'interrupted']).optional(), reason: z.string().max(2000).optional()
+});
+/** The bounded live feed response; completed and interrupted runs remain visible as recent history. */
+export const LiveRunSchema = LiveRunStartSchema.extend({
+    status: z.enum(['running', 'completed', 'interrupted']), startedAtMs: z.number(), lastHeartbeatAtMs: z.number(), lastProgressAtMs: z.number(),
+    finishedAtMs: z.number().optional(), reason: z.string().optional(), sequence: z.number(),
+    completed: z.number(), passed: z.number(), failed: z.number(), notRun: z.number(), running: z.number(),
+    current: z.array(LiveCheckSchema), recent: z.array(LiveCheckSchema)
+});