@crvouga/atlas 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 0.6.0 (2026-10-15)
+
+### Features
+
+- add project-scoped live test reporting (#8) ([70936ab](https://github.com/crvouga/atlas/commit/70936ab5b2c6bec5e50b458fc1c3030a3f20bc55))
+
 ## 0.5.0 (2026-10-14)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ backends, and tells you in one command whether the product still does what it wa
 
 - **Any spec, any runner.** Anything that ends in "this check passed or failed" publishes a *layer*:
   from a JUnit or CTRF file, a ten-line script, or code. No runner and no notation is privileged.
-- **Layered, never partitioned.** A report is computed from layers, not stored as "the run". Partial
+- **Layered within each project.** A report is computed from layers, not stored as "the run". Partial
   runs on separate nodes, branches and devices are how a report is built, and they compose without
   coordinating: the same layers give the same report in any order, split any way.
 - **Open evidence.** A result carries whatever your framework produces: screenshots, videos, traces, logs, DOM
@@ -16,9 +16,9 @@ backends, and tells you in one command whether the product still does what it wa
   Gherkin, Quint, DMN, Alloy, OpenSLO); evidence stays open.
 - **Open standards, stable schemas.** JUnit XML and CTRF in, JSON Schema 2020-12 contracts, a
   versioned layer format with a golden fixture, and an `ObjectStore` interface any bucket fits.
-- **One server, live.** A project runs one `atlas serve`: a Bun API that serves the viewer from the same host.
+- **One node, many projects.** `atlas server` runs a Bun API and serves the Atlas client from the same host. Reports, specs, recordings and live progress are partitioned by project slug.
   Every laptop and CI job sends results to it as they finish (`atlas report publish`, or `atlas report stream` while
-  a suite runs), it keeps them on its own disk (or in S3, R2, MinIO), and every viewer sees the combined report
+  a suite runs), it keeps them on its own disk (or in S3, R2, MinIO), and every client sees the combined report
   update live, receiving only what changed ([the server](docs/server.md), [deploying](docs/deploying.md)).
 - **Fast and fail-closed.** Publishing is two small writes. A thousand layers of a hundred checks
   combine in about a second. An unreadable layer, a downed backend or a check still running is never
@@ -28,7 +28,7 @@ backends, and tells you in one command whether the product still does what it wa
 
 ```
  any suite   ──▶ layer ─┐                              atlas report status   exit 1 unless it passes
- any node    ──▶ layer ─┼─▶ backends ─▶ combine ─▶     the visualizer        browse it beside the specs
+ any node    ──▶ layer ─┼─▶ backends ─▶ combine ─▶     the Atlas client        browse it beside the specs
  any branch  ──▶ layer ─┘   (directories, buckets, …)   combineBackends()     your own code
 ```
 
@@ -40,6 +40,23 @@ backends, and tells you in one command whether the product still does what it wa
 > [using Atlas from another project](docs/dogfooding.md) and [reporting issues](docs/reporting-issues.md).
 > Releases are automatic: see [releasing](https://github.com/crvouga/atlas/blob/main/docs/releasing.md).
 
+## Run this repository's example
+
+Use two terminals:
+
+```sh
+bun atlas          # starts the project-agnostic Atlas node at http://localhost:5180
+bun example:run    # runs tests and streams results, current steps and progress as they execute
+```
+
+The server starts independently with data in `./atlas-data`; it never loads example specs or reports. `bun example:run` publishes the Todo example under `todo-app`. Select a project using the top-right picker, then use the spec dropdown breadcrumbs to navigate. Other projects set `ATLAS_SERVER_URL`, `ATLAS_PROJECT` (for example `checkout-service`) and their publish token. Every uploader talks to the node; storage credentials stay on the server.
+
+Every Gherkin scenario runs, including sharing and renaming. Test reports show running spinners,
+live step logs and a Running status filter. Producers send heartbeats every
+5 seconds. A run becomes interrupted after 30 seconds without a heartbeat, or 15 minutes without progress;
+configure `ATLAS_RUN_TIMEOUT_SECONDS` and `ATLAS_RUN_STALL_SECONDS` (0 disables the progress timeout),
+or edit these settings in the client. An interruption never turns missing outcomes into passes.
+
 ## For AI agents
 
 Atlas is built to be integrated and operated by agents, with nothing to click and nothing to guess.
@@ -105,10 +122,10 @@ bun add -d @crvouga/atlas
 | [`@crvouga/atlas/webdriver`](packages/webdriver) | W3C WebDriver driver with no dependencies: Safari, Chrome, Firefox and Edge, and native iOS and Android apps through Appium. |
 | [`@crvouga/atlas/detox`](packages/detox) | Detox driver for iOS and Android apps, inside a Detox test run. |
 | [`@crvouga/atlas/vitest`](packages/vitest) | Run a config as a test suite in Vitest, `bun test` or any Jest-style runner, one test per planned path. |
-| [`atlas-visualizer`](packages/visualizer) (command) | Browse specs, charts and layered reports: every spec with its result per environment, every state with its screenshots, every transition with its clip. |
+| [`atlas client`](packages/visualizer) (command) | Browse specs, charts and layered reports: every spec with its result per environment, every state with its screenshots, every transition with its clip. |
 
 Two commands install with it: `atlas` (`report`, `lint`, `plan`, `run`, `merge`, `export`) and
-`atlas-visualizer`.
+`atlas client`.
 
 ## Reports for any spec
 
@@ -147,10 +164,10 @@ has results. `--format json` is a [stable schema](packages/schema/schemas/report
 means the report does not pass; 2 means the command itself was wrong (a missing store directory, a bad
 flag).
 
-**The server** is `atlas serve`: one process that serves the viewer, takes in results and streams the report to
-every viewer. Point `ATLAS_STORE` at it and every developer's laptop and every CI job sends results with the same
+**The server** is `atlas serve`: one process that serves the client, takes in results and streams the report to
+every client. Point `ATLAS_STORE` at it and every developer's laptop and every CI job sends results with the same
 commands that write to a folder; everyone then looks at one report, live. Results are kept in its data folder
-unless you choose a bucket. `atlas dev` runs the same server with the viewer's dev server in front, so
+unless you choose a bucket. `atlas dev` runs the same server with the client's dev server in front, so
 development is one host too. See [the server](docs/server.md) and
 [running Atlas for a project](docs/deploying.md).
 
@@ -163,7 +180,7 @@ my-suite --json | atlas report stream --producer e2e --environment ios  # or as
 atlas report status --branch main --ignore-modified  # the gate, answered by the server
 ```
 
-**The viewer** shows each spec (Gherkin, Quint, DMN, Alloy, OpenSLO, and the rest by file type) with
+**The client** shows each spec (Gherkin, Quint, DMN, Alloy, OpenSLO, and the rest by file type) with
 its combined result per environment and the layer behind it. See
 [integrating Atlas](docs/integrating.md#6-browse-it).
 
@@ -190,7 +207,7 @@ understand, or a JSON Schema it publishes.
 | [JUnit XML](https://github.com/testmoapp/junitxml) | Read: any test runner's results become a layer. Written: `junit.xml`, one test case per statechart path. |
 | [CTRF](https://ctrf.io) | Read: any CTRF report becomes a layer. Written: `ctrf.json` for each statechart run. |
 | [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) | The contract: layers, check files, report status, run manifests, journeys, state nodes, timelines and the runs index (`@crvouga/atlas/schemas/*.schema.json`) |
-| [Gherkin](https://cucumber.io/docs/gherkin/), [Quint](https://quint-lang.org), [DMN](https://www.omg.org/spec/DMN), [Alloy](https://alloytools.org), [OpenSLO](https://openslo.com) | Spec kinds the viewer lays results over, each in its own tab. Any other file is a spec of its own type. |
+| [Gherkin](https://cucumber.io/docs/gherkin/), [Quint](https://quint-lang.org), [DMN](https://www.omg.org/spec/DMN), [Alloy](https://alloytools.org), [OpenSLO](https://openslo.com) | Spec kinds the client lays results over, each in its own tab. Any other file is a spec of its own type. |
 | [W3C SCXML](https://www.w3.org/TR/scxml/) | Statecharts (`*.scxml`), with business metadata in an `atlas` XML namespace |
 | [XState v5](https://stately.ai/docs/machines) machine config | Statecharts (`*.machine.json`, `*.machine.yaml`): the JSON shape Stately Studio imports and exports |
 | [WebVTT](https://www.w3.org/TR/webvtt1/) | Captions for every clip: each tap, keystroke, system call and screen change |
@@ -228,3 +245,5 @@ in **[Executable statecharts](docs/statecharts.md)**, which starts with a runnab
 ## License
 
 [MIT](LICENSE)
+
+Native [CodeceptJS, Mocha, Jest and Node test reporters](docs/runners.md) upload directly to the project server. Open **Settings** in the client to configure storage and report settings for the next restart.

package/dist/core/src/cli.d.ts

@@ -9,6 +9,6 @@
  * @see docs/reference/cli.md
  */
 /** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
-export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas serve  [--data <dir>] [--port 8080] [--store <url>]...   the Atlas server: results in, the live report out\n  atlas dev    [--port 5180]                                     the server and the viewer's dev server, on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
+export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client\n  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client\n  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
 /** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
 export declare function main(argv?: string[]): Promise<number>;

package/dist/core/src/cli.js

@@ -28,8 +28,9 @@ export const USAGE = `atlas — executable statecharts
                [--no-retry] [--output <dir>]
   atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
   atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
-  atlas serve  [--data <dir>] [--port 8080] [--store <url>]...   the Atlas server: results in, the live report out
-  atlas dev    [--port 5180]                                     the server and the viewer's dev server, on one host
+  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client
+  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client
+  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
   atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
   atlas report publish|stream|status|merge|doctor|policy …       layered evidence for any kind of spec (atlas report --help)
 
@@ -88,10 +89,14 @@ async function loadConfig(file) {
 export async function main(argv = process.argv.slice(2)) {
     const [command] = argv;
     // Loaded on demand: lint, plan and run do not pay for the reports.
-    if (command === 'serve') {
+    if (command === 'serve' || command === 'server') {
         const { serveMain } = await import('../../server/src/main.js');
         return serveMain(argv.slice(1), { out: text => process.stdout.write(text) });
     }
+    if (command === 'client') {
+        const { clientMain } = await import('../../server/src/site.js');
+        return clientMain(argv.slice(1));
+    }
     if (command === 'dev') {
         const { devMain } = await import('../../server/src/dev.js');
         return devMain(argv.slice(1), { out: text => process.stdout.write(text) });

package/dist/core/src/config.d.ts

@@ -1,3 +1,4 @@
+import { type LiveReporterOptions } from '../../reports/src/live-reporter.js';
 import type { StateValue } from './graph.js';
 import type { Shard } from './run/execute.js';
 import type { Driver, EventMatcher, EventSource, Implementation, PrivacyRules, RunMode } from './run/types.js';
@@ -8,6 +9,8 @@ import type { Driver, EventMatcher, EventSource, Implementation, PrivacyRules, R
 export type AtlasConfig<C = unknown> = {
     /** The directory holding the charts (`*.scxml`, `*.machine.{json,yaml}`) and `journeys.yaml`. */
     specs: string;
+    /** Live reporting endpoint. Defaults to ATLAS_SERVER_URL when set; false disables streaming. */
+    reporting?: LiveReporterOptions | false;
     /** The chart to run; the root chart when omitted. */
     chart?: string;
     /** Where generated paths start (an XState state value); the initial state when omitted. */
@@ -125,6 +128,8 @@ export declare function prepare<C>(config: AtlasConfig<C>, baseDirectory?: strin
 export type RunCommandOptions = PrepareOptions & {
     /** `fast` when omitted. */
     mode?: RunMode;
+    /** Override live reporting. Defaults to config.reporting or ATLAS_SERVER_URL. */
+    reporting?: LiveReporterOptions | false;
     /** Only these paths, by id. */
     paths?: string[];
     /** Only paths that start from these seeds ("start" for paths that `setup` starts). */
@@ -260,6 +265,7 @@ export declare function runConfig<C>(config: AtlasConfig<C>, options?: RunComman
             key: string;
             name: string;
             kind: import('./plan.js').PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: import('./index.js').Status;
             attempts: {
                 status: "passed" | "failed";
@@ -458,6 +464,7 @@ export declare function mergeConfigRuns<C>(config: AtlasConfig<C>, runDirs: stri
             key: string;
             name: string;
             kind: import('./plan.js').PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: import('./index.js').Status;
             attempts: {
                 status: "passed" | "failed";

package/dist/core/src/config.js

@@ -11,6 +11,11 @@
  */
 import { availableParallelism } from 'node:os';
 import path from 'node:path';
+import { createLiveReporter } from '../../reports/src/live-reporter.js';
+import { httpStore } from '../../reports/src/http-store.js';
+import { publishChecks } from '../../reports/src/publish-checks.js';
+import { publishRunBundle } from '../../reports/src/run-bundle.js';
+import { checksFromManifest } from '../../reports/src/ingest.js';
 import { lintBundle } from './lint.js';
 import { chartScope, planChart } from './plan.js';
 import { assertAllowedTarget, mergePrivacy } from './privacy.js';
@@ -129,20 +134,49 @@ export async function runConfig(config, options = {}, baseDirectory = process.cw
     const reused = reuseDir ? readOutcomes(reuseDir) : null;
     if (options.reuse && !reused)
         throw new Error(`There is no earlier run to reuse${reuseDir ? ` at ${reuseDir}` : ''}`);
-    return runPaths({
-        ...contextOf(config, prepared),
-        paths,
-        driver,
-        mode: options.mode ?? 'fast',
-        outputRoot,
-        ...(options.retry === undefined ? {} : { retry: options.retry }),
-        ...(config.stepTimeoutMs === undefined ? {} : { stepTimeoutMs: config.stepTimeoutMs }),
-        eventSources: config.eventSources ? await config.eventSources() : [],
-        workers: options.workers ?? config.workers ?? availableParallelism(),
-        ...(options.shard ? { shard: options.shard } : {}),
-        ...(reused && reuseDir ? { reuse: { runDir: reuseDir, outcomes: reused.outcomes } } : {}),
-        ...(options.log ? { log: options.log } : {})
-    });
+    const requestedReporting = options.reporting ?? config.reporting ?? (process.env.ATLAS_SERVER_URL ? { url: process.env.ATLAS_SERVER_URL, token: process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN } : undefined);
+    const reporting = requestedReporting ? { ...requestedReporting, project: requestedReporting.project ?? process.env.ATLAS_PROJECT, token: requestedReporting.token ?? process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN } : undefined;
+    let live;
+    const onProgress = reporting ? (manifest) => {
+        if (!manifest.privacy.passed)
+            return;
+        live ??= createLiveReporter({ producer: process.env.ATLAS_PRODUCER ?? 'atlas-statecharts', title: `${prepared.scope.chart} · ${options.mode ?? 'fast'}`,
+            plannedChecks: paths.length, environment: process.env.ATLAS_ENVIRONMENT ?? 'desktop-web', branch: manifest.run.branch ?? undefined, sha: manifest.run.commit ?? undefined }, reporting);
+        const ingested = checksFromManifest(manifest);
+        ingested.checks.forEach((check, index) => {
+            if (manifest.paths[index]?.progress === 'queued' && !manifest.run.finishedAt)
+                return;
+            live.check({ ...check, steps: check.steps?.slice(-20).map(step => ({ name: step.name, status: step.status })) });
+        });
+    } : undefined;
+    try {
+        const outcome = await runPaths({
+            ...contextOf(config, prepared),
+            paths,
+            driver,
+            mode: options.mode ?? 'fast',
+            outputRoot,
+            ...(options.retry === undefined ? {} : { retry: options.retry }),
+            ...(config.stepTimeoutMs === undefined ? {} : { stepTimeoutMs: config.stepTimeoutMs }),
+            eventSources: config.eventSources ? await config.eventSources() : [],
+            workers: options.workers ?? config.workers ?? availableParallelism(),
+            ...(options.shard ? { shard: options.shard } : {}),
+            ...(reused && reuseDir ? { reuse: { runDir: reuseDir, outcomes: reused.outcomes } } : {}),
+            ...(options.log ? { log: options.log } : {}), ...(onProgress ? { onProgress } : {})
+        });
+        await live?.finish(outcome.manifest.privacy.passed ? 'completed' : 'interrupted', outcome.manifest.privacy.passed ? undefined : 'Run failed its privacy scan; unsafe progress was withheld.');
+        if (reporting && outcome.manifest.privacy.passed) {
+            const store = httpStore({ url: reporting.url, project: reporting.project, token: reporting.token });
+            await publishChecks(store, { producer: process.env.ATLAS_PRODUCER ?? 'atlas-statecharts', environment: process.env.ATLAS_ENVIRONMENT ?? 'desktop-web',
+                branch: outcome.manifest.run.branch, sha: outcome.manifest.run.commit, recordedAtMs: Math.max(Date.now(), (live?.finishedAtMs ?? 0) + 1), checks: checksFromManifest(outcome.manifest).checks.map(check => ({ ...check, measurements: [...check.measurements] })) });
+            await publishRunBundle(store, outcome.runDir);
+        }
+        return outcome;
+    }
+    catch (error) {
+        await live?.finish('interrupted', 'The producer exited before completing the run.').catch(() => { });
+        throw error;
+    }
 }
 /**
  * Composes runs of a config (its shards, or a rerun and the run before it) into one new run

package/dist/core/src/run/execute.d.ts

@@ -58,6 +58,8 @@ export type RunOptions<C> = RunContext<C> & {
     };
     /** Receives progress lines; writes to stdout when omitted. */
     log?: (line: string) => void;
+    /** Receives privacy-checked manifest snapshots as paths and steps change. */
+    onProgress?: (manifest: Manifest) => void;
 };
 type StepResult = {
     transition: string;
@@ -268,6 +270,7 @@ export declare function buildManifest<C>(context: RunContext<C>, paths: PlannedP
         key: string;
         name: string;
         kind: PlannedPath["kind"];
+        progress?: "queued" | "running" | "complete";
         status: Status;
         attempts: Attempt[];
         steps: StepResult[];
@@ -447,6 +450,7 @@ export declare function writeRun<C>(runDir: string, context: RunContext<C>, path
         key: string;
         name: string;
         kind: PlannedPath["kind"];
+        progress?: "queued" | "running" | "complete";
         status: Status;
         attempts: Attempt[];
         steps: StepResult[];
@@ -638,6 +642,7 @@ export declare function mergeRuns<C>(context: RunContext<C>, paths: PlannedPath[
             key: string;
             name: string;
             kind: PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: Status;
             attempts: Attempt[];
             steps: StepResult[];
@@ -832,6 +837,7 @@ export declare function runPaths<C>(options: RunOptions<C>): Promise<{
             key: string;
             name: string;
             kind: PlannedPath["kind"];
+            progress?: "queued" | "running" | "complete";
             status: Status;
             attempts: Attempt[];
             steps: StepResult[];

package/dist/core/src/run/execute.js

@@ -891,7 +891,8 @@ export async function runPaths(options) {
         }
     });
     function publish() {
-        writeRun(runDir, options, options.paths, new Map([...outcomes, ...activeOutcomes]), runInfo(false));
+        const snapshot = writeRun(runDir, options, options.paths, new Map([...outcomes, ...activeOutcomes]), runInfo(false));
+        options.onProgress?.(snapshot);
     }
     const history = durationHistory(options.outputRoot);
     const cost = (p) => history[p.key] ?? estimateMs(p);
@@ -899,7 +900,7 @@ export async function runPaths(options) {
     if (reused.size)
         log(`Reusing ${reused.size} passed path(s) from ${path.basename(options.reuse.runDir)}`);
     log(`Running ${queue.length} path(s) on ${workers} worker(s)`);
-    writeRun(runDir, options, options.paths, outcomes, runInfo(false));
+    options.onProgress?.(writeRun(runDir, options, options.paths, outcomes, runInfo(false)));
     // A driver can throw outside any awaited call (a message for a context that just closed); it
     // belongs to one attempt, so it is logged and the run goes on instead of the process dying.
     const stray = (error) => log(`  (ignored an error thrown outside any step: ${(error instanceof Error ? error.message : String(error)).split('\n')[0]})`);
@@ -924,5 +925,6 @@ export async function runPaths(options) {
     await driver.dispose?.();
     await Promise.all(sources.map((s) => s.close?.()));
     const manifest = writeRun(runDir, options, options.paths, outcomes, runInfo(true));
+    options.onProgress?.(manifest);
     return { runDir, manifest, ok: manifest.privacy.passed && manifest.paths.every((r) => r.status !== 'failed') };
 }

package/dist/reports/src/doctor.d.ts

@@ -16,7 +16,7 @@ export type Check = {
     readonly detail: string;
     readonly fix?: string;
 };
-/** The least an account needs, as an AWS IAM policy. R2, MinIO and the rest have their own policy languages: grant the same actions. */
+/** The least an account needs, as an AWS IAM policy. The combined server role also stores operational leases under server/live/. R2, MinIO and the rest have their own policy languages: grant the same actions. */
 export declare function iamPolicy(location: {
     bucket: string;
     prefix: string;

package/dist/reports/src/doctor.js

@@ -10,7 +10,7 @@
  */
 import { LAYER_INDEX } from './layer-store.js';
 import { verifyObjectStore } from './object-store-conformance.js';
-/** The least an account needs, as an AWS IAM policy. R2, MinIO and the rest have their own policy languages: grant the same actions. */
+/** The least an account needs, as an AWS IAM policy. The combined server role also stores operational leases under server/live/. R2, MinIO and the rest have their own policy languages: grant the same actions. */
 export function iamPolicy(location, role) {
     const base = location.prefix ? `${location.prefix}/` : '';
     const bucketArn = `arn:aws:s3:::${location.bucket}`;
@@ -21,6 +21,8 @@ export function iamPolicy(location, role) {
     if (role !== 'publisher') {
         statements.push({ Sid: 'AtlasRead', Effect: 'Allow', Action: 's3:GetObject', Resource: `${bucketArn}/${base}layers/*` });
     }
+    if (role === 'both')
+        statements.push({ Sid: 'AtlasLiveRuns', Effect: 'Allow', Action: ['s3:GetObject', 's3:PutObject'], Resource: `${bucketArn}/${base}server/live/*` }, { Sid: 'AtlasProjects', Effect: 'Allow', Action: ['s3:GetObject', 's3:PutObject', 's3:DeleteObject'], Resource: [`${bucketArn}/${base}projects/*`, `${bucketArn}/${base}server/projects/*`] });
     // Publishers need this too: without it S3 answers 403, not 404, when asked whether a layer exists yet.
     statements.push({ Sid: 'AtlasList', Effect: 'Allow', Action: 's3:ListBucket', Resource: bucketArn, // IfExists: a listing always carries a prefix and is held to it; a HEAD or GET of one object carries none, and
         // must still be answered "not found" rather than "forbidden".

package/dist/reports/src/http-store.d.ts

@@ -11,6 +11,8 @@
 import type { ObjectStore, PagedListing } from './object-store.js';
 /** How to reach a server: its `url`, the `token` to send (never in the URL), and, for tests and special runtimes, `fetch`, the retry count, the per-attempt timeout and `sleep`. */
 export type HttpStoreOptions = {
+    /** Project namespace on a shared Atlas node. Omit for the legacy default project. */
+    readonly project?: string;
     /** The Atlas server, such as `https://atlas.example.com`. A path on it (`/atlas`) is kept. */
     readonly url: string;
     /** A publish or admin token to write with, a read token to read with. Never put it in the URL. */
@@ -30,6 +32,8 @@ export declare class AtlasHttpError extends Error {
 }
 /** An `ObjectStore` (with paged listing) over an Atlas server, plus what only a server can answer: `ping` (is it there, and what may this token do) and `status` (the gate, worked out by the server). */
 export type HttpStore = ObjectStore & PagedListing & {
+    /** The same authenticated node connection, scoped to another project. */
+    forProject(project: string): HttpStore;
     /** `https://atlas.example.com`, with no secrets. */
     readonly label: string;
     readonly url: string;

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

@@ -9,6 +9,7 @@
  * @see docs/server.md#the-store-protocol
  */
 import { ObjectStoreWithPrefix } from './store-prefix.js';
+import { ProjectSlugSchema } from '../../schema/src/project.js';
 /** What an Atlas server said no to, with what to do about it. */
 export class AtlasHttpError extends Error {
     status;
@@ -40,7 +41,8 @@ function explain(status, base, message) {
  */
 export function httpStore(options) {
     const base = options.url.replace(/\/+$/, '');
-    const root = `${base}/api/store`;
+    const api = options.project ? `${base}/api/projects/${ProjectSlugSchema.parse(options.project)}` : `${base}/api`;
+    const root = `${api}/store`;
     const doFetch = options.fetch ?? fetch;
     const retries = options.retries ?? 4;
     const timeoutMs = options.timeoutMs ?? 30_000;
@@ -66,7 +68,7 @@ export function httpStore(options) {
                     await response.body?.cancel();
                     return null;
                 }
-                const said = await response.json().then((body) => body.error ?? null, () => null);
+                const said = await response.json().then((body) => body && typeof body === 'object' && 'error' in body && typeof body.error === 'string' ? body.error : null, () => null);
                 failure = new AtlasHttpError(explain(response.status, base, said), response.status, response.status >= 500 || response.status === 429 || response.status === 408);
             }
             catch (error) {
@@ -78,6 +80,7 @@ export function httpStore(options) {
         }
     }
     const store = {
+        forProject: project => httpStore({ ...options, project }),
         label: base,
         url: base,
         async get(key) {
@@ -127,7 +130,7 @@ export function httpStore(options) {
         },
         async status(query = new URLSearchParams()) {
             const suffix = query.size ? `?${query}` : '';
-            return (await request('GET', `${base}/api/status${suffix}`)).json();
+            return (await request('GET', `${api}/status${suffix}`)).json();
         },
         async ping() {
             const started = performance.now();

package/dist/reports/src/init.js

@@ -88,6 +88,9 @@ function runnersOf(directory, pkg) {
     dep('cypress', 'cypress');
     dep('jest', 'jest');
     dep('mocha', 'mocha');
+    dep('codeceptjs', 'codeceptjs');
+    if (/\bnode\s+--test\b/.test(scripts))
+        found.push({ runner: 'node-test', evidence: 'package.json scripts: node --test' });
     if (!found.some(item => item.runner === 'vitest' || item.runner === 'jest' || item.runner === 'mocha') && /\bbun test\b/.test(scripts))
         found.push({ runner: 'bun-test', evidence: 'package.json scripts: bun test' });
     else if (!found.length && pkg && (existsSync(path.join(directory, 'bun.lock')) || existsSync(path.join(directory, 'bunfig.toml'))) && readdirSafe(directory).some(name => /\.(test|spec)\.[cm]?[tj]sx?$/.test(name) || name === 'tests' || name === 'test'))
@@ -128,6 +131,8 @@ function suiteOf(detected, context) {
         case 'cypress': return make('cypress', out('cypress'), `${context.exec} cypress run --reporter junit --reporter-options mochaFile=${out('cypress')}`, 'desktop-web');
         case 'cucumber': return make('cucumber', out('cucumber'), `${context.exec} cucumber-js --format summary --format junit:${out('cucumber')}`, null);
         case 'mocha': return make('mocha', out('mocha'), `MOCHA_FILE=${out('mocha')} ${context.exec} mocha --reporter mocha-junit-reporter`, null, [`${context.install} mocha-junit-reporter`]);
+        case 'codeceptjs': return make('codeceptjs', out('codeceptjs'), `MOCHA_FILE=${out('codeceptjs')} ${context.exec} codeceptjs run --reporter mocha-junit-reporter`, 'desktop-web', [`${context.install} mocha-junit-reporter`]);
+        case 'node-test': return make('node-test', out('node-test'), `node --test --test-reporter=junit --test-reporter-destination=${out('node-test')}`, null);
         case 'bun-test': return make('bun-test', out('bun'), `bun test --reporter=junit --reporter-outfile=${out('bun')}`, null);
         case 'pytest': return make('pytest', out('pytest'), `pytest --junitxml=${out('pytest')}`, null);
         case 'go-test': return make('go-test', out('go'), `go test -v ./... 2>&1 | go-junit-report > ${out('go')}`, null, ['go install github.com/jstemmer/go-junit-report/v2@latest']);
@@ -232,7 +237,7 @@ export async function planInit(options) {
     const context = { exec, install: INSTALL_DEV[manager ?? 'npm'], specs: specs.directory, server: serverUrl };
     const suites = runnersOf(directory, pkg).map(found => suiteOf(found, context));
     if (!suites.length)
-        warnings.push('No test runner was recognised (looked for vitest, jest, playwright, cypress, cucumber, mocha, bun test, pytest, go test and Atlas statecharts). Add one suite by hand: run it so it writes a JUnit XML or CTRF file, then `atlas report publish --producer <name> --junit <file>`.');
+        warnings.push('No test runner was recognised (looked for vitest, jest, playwright, cypress, cucumber, mocha, codeceptjs, node --test, bun test, pytest, go test and Atlas statecharts). Add one suite by hand: run it so it writes a JUnit XML or CTRF file, then `atlas report publish --producer <name> --junit <file>`.');
     if (!serverUrl)
         warnings.push('No server given. Pass --server https://… (or set ATLAS_STORE) so the plan can name it; until then the generated text says "the project\'s Atlas server".');
     if (!specs.directory)

package/dist/reports/src/live-reporter.d.ts

@@ -0,0 +1,34 @@
+import type { z } from 'zod/v4';
+import type { LiveCheck, LiveRunStartSchema } from '../../schema/src/live-run.js';
+/** Fixed identity of a live invocation; a UUID is generated when omitted. */
+export type LiveIdentity = Omit<z.input<typeof LiveRunStartSchema>, 'id'> & {
+    id?: string;
+};
+/** Transport and batching configuration. Defaults: 250 ms batches, 5 s heartbeats and 10 s request timeouts. */
+export type LiveReporterOptions = {
+    url: string;
+    project?: string;
+    token?: string;
+    flushMs?: number;
+    heartbeatMs?: number;
+    timeoutMs?: number;
+    onError?: (error: Error) => void;
+};
+/** Producer handle. check never throws transport errors into a test; finish flushes and rejects if publication failed. */
+export type LiveReporter = {
+    readonly id: string;
+    readonly finishedAtMs?: number;
+    check(check: LiveCheck): void;
+    flush(): Promise<void>;
+    finish(status?: 'completed' | 'interrupted', reason?: string): Promise<void>;
+};
+/**
+ * Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+ * The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+ * @example
+ * const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+ * await run.finish();
+ */
+export declare function createLiveReporter(identity: LiveIdentity, options: LiveReporterOptions): LiveReporter;

package/dist/reports/src/live-reporter.js

@@ -0,0 +1,122 @@
+/** @module Reporting a live run to Atlas
+ * Streams bounded check deltas while tests execute. Heartbeats are independent of progress; finished results are
+ * published by the server as ordinary immutable layers. A final flush is awaited before a runner exits.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+ * The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+ * @example
+ * const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+ * await run.finish();
+ */
+export function createLiveReporter(identity, options) {
+    const base = new URL(options.url);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+        throw new Error('Atlas live reporter needs an HTTP(S) server URL without credentials, query or fragment.');
+    const id = identity.id ?? randomUUID();
+    const endpoint = `${base.href.replace(/\/$/, '')}/api/live/${id}`;
+    let sequence = 0;
+    let finishedAtMs;
+    let closed = false;
+    let timer;
+    let error;
+    const pending = new Map();
+    const known = new Map();
+    let failed;
+    const reportError = (caught) => { error = caught instanceof Error ? caught : new Error(String(caught)); options.onError?.(error); };
+    async function request(method, payload, suffix = '') {
+        const text = payload === undefined ? undefined : JSON.stringify(payload);
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await fetch(endpoint + suffix, { method, redirect: 'error', signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+                    headers: { 'content-type': 'application/json', ...(options.project ? { 'x-atlas-project': options.project } : {}), ...(options.token ? { authorization: `Bearer ${options.token}` } : {}) }, body: text });
+                const status = response.status;
+                const json = response.headers.get('content-type')?.includes('application/json');
+                if (response.ok && !json) {
+                    await response.body?.cancel();
+                    throw Object.assign(new Error('Atlas live reporter: the endpoint is not an Atlas server. Start or restart `bun atlas`.'), { permanent: true });
+                }
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw Object.assign(new Error(`Atlas live reporter: HTTP ${status}`), { permanent: status < 500 && status !== 429 });
+                }
+                return await response.json();
+            }
+            catch (caught) {
+                if (attempt >= 2 || caught.permanent)
+                    throw caught;
+                await new Promise(resolve => setTimeout(resolve, 250 * 2 ** attempt));
+            }
+        }
+    }
+    const ready = request('POST', { ...identity, id });
+    void ready.catch(reportError);
+    let queue = Promise.resolve();
+    let draining;
+    const flush = () => {
+        if (draining)
+            return draining;
+        queue = queue.then(async () => {
+            await ready;
+            while (failed || pending.size) {
+                if (!failed) {
+                    const checks = [...pending.values()].slice(0, 1000);
+                    checks.forEach(check => pending.delete(check.id));
+                    failed = { sequence: sequence + 1, checks };
+                }
+                await request('PATCH', failed);
+                sequence = failed.sequence;
+                failed = undefined;
+            }
+            error = undefined;
+        }).catch(reportError);
+        draining = queue.finally(() => { draining = undefined; });
+        return draining;
+    };
+    const heartbeat = setInterval(() => { if (!closed)
+        void ready.then(async () => { await request('POST', undefined, '/heartbeat'); if (!closed && (failed || pending.size))
+            void flush(); }).catch(caught => { if (!closed)
+            reportError(caught); }); }, options.heartbeatMs ?? 5000);
+    heartbeat.unref?.();
+    const check = (given) => {
+        if (closed)
+            throw new Error('This live reporter is closed.');
+        const check = { id: given.id, title: given.title.slice(0, 2048), status: given.status, detail: (given.detail ?? '').slice(0, 8000),
+            ...(given.specPath ? { specPath: given.specPath } : {}), ...(given.durationMs === undefined ? {} : { durationMs: given.durationMs }),
+            ...(given.steps?.length ? { steps: given.steps.slice(-20).map(step => ({ name: step.name.slice(0, 2048), ...(step.status ? { status: step.status.slice(0, 100) } : {}) })) } : {}) };
+        if (JSON.stringify(known.get(check.id)) === JSON.stringify(check))
+            return;
+        known.set(check.id, check);
+        pending.set(check.id, check);
+        if (!timer) {
+            timer = setTimeout(() => { timer = undefined; void flush(); }, options.flushMs ?? 250);
+            timer.unref?.();
+        }
+    };
+    return { id, get finishedAtMs() { return finishedAtMs; }, check, flush, async finish(status = 'completed', reason) {
+            if (closed) {
+                await queue;
+                if (error)
+                    throw error;
+                return;
+            }
+            const unfinished = [...known.values()].filter(check => check.status === 'running');
+            if (unfinished.length) {
+                status = 'interrupted';
+                reason ??= 'The producer ended without a final outcome for running checks.';
+                unfinished.forEach(value => check({ ...value, status: 'not-run', detail: reason }));
+            }
+            closed = true;
+            clearInterval(heartbeat);
+            clearTimeout(timer);
+            await flush();
+            if (error)
+                throw error;
+            const result = await request('PATCH', { sequence: sequence + 1, checks: [], finish: status, ...(reason ? { reason } : {}) });
+            finishedAtMs = result.finishedAtMs;
+            sequence++;
+        } };
+}