@crvouga/atlas 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 0.6.1 (2026-10-15)
+
+### Fixes and improvements
+
+- make consumer integration reproducible (#9) ([bfd4e0c](https://github.com/crvouga/atlas/commit/bfd4e0c1c804d1f11fce3299e609af86c50e4732))
+
+## 0.6.0 (2026-10-14)
+
+### 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,34 @@ 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).
 
+## Given this repo link to integrate Atlas?
+
+Start with **[the agent integration playbook](docs/agents.md#given-only-this-repository-link)** in your own
+project. It covers choosing an integration, installing with your package manager, finding docs for your installed
+version, running without a server, connecting real suites, and proving completion. **[Verify Atlas locally](docs/quickstart.md)**
+is a copyable walkthrough with expected JSON and exit codes; it needs no credentials or existing test suite.
+The machine-readable index is [llms.txt](llms.txt), and [llms-full.txt](llms-full.txt) contains the guides in one file.
+
+## Run this repository's example
+
+For contributors working in an Atlas checkout with dependencies installed (`bun install --frozen-lockfile`).
+Consumer projects install the npm package instead; they do not need to clone or build this repository.
+
+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.
@@ -47,20 +75,21 @@ Atlas is built to be integrated and operated by agents, with nothing to click an
 - **`atlas init`** detects a project's test runners, specs and CI and prints a plan (`--format json`) of the exact commands to
   run each suite and send its results; `--write` creates the CI workflow and an `AGENTS.md` section. Running it twice
   changes nothing.
-- **Every command prints JSON on request** (`--format json`), every document has a published JSON Schema, exit codes mean the
-  same everywhere (`0` worked, `1` the answer is no, `2` the command was wrong), and every operation is safe to repeat.
+- **Init and report commands print JSON on request** (`--format json`) with published JSON Schemas and consistent
+  exit codes (`0` worked, `1` the answer is no, `2` the command was wrong). Reapplying init or publishing identical evidence is safe.
 - **The server describes itself:** `GET /api/openapi.json` (OpenAPI 3.1) and `GET /llms.txt` (a guide for an agent given only
   the address) need no token; errors are RFC 9457 problem documents that say what to do.
 - **Documentation is generated from the code beside it:** `llms.txt` / `llms-full.txt` (also in the package), the TypeScript
   reference in [`docs/reference/`](docs/reference/server.md), the CLI and HTTP references, and the settings tables; tests fail when
   any of it drifts.
 
-Start with **[Atlas for AI agents](docs/agents.md)**.
+Start with **[Atlas for AI agents](docs/agents.md)**. A [copyable integration brief](docs/agents.md#an-integration-brief-you-can-give-an-agent)
+lets a user hand an agent this repository URL and a concrete definition of done.
 
 ## Integrate in five minutes
 
 ```sh
-bun add -d @crvouga/atlas            # or npm install -D / pnpm add -D; runs on Bun and Node 22.18+
+bun add -d @crvouga/atlas            # or npm install -D / pnpm add -D
 
 # 1. Each suite publishes a layer of what it ran: a JUnit or CTRF file, an Atlas run, or a checks file.
 bunx atlas report publish --store atlas-reports --producer web-e2e --junit out.xml --specs ./specs --environment desktop-web
@@ -88,7 +117,11 @@ bunx atlas report status --store all --specs ./specs --require-environments desk
 ## One package
 
 Atlas is a single npm package. Each part is its own import path, so a bundler keeps only what you
-import. It runs on Bun and on Node 22.18 or later, with any package manager:
+import. Use your project's package manager:
+
+<!-- generated:runtime-requirements -->
+Supported runtimes (from `package.json`): **node `>=22.18.0`** or **bun `>=1.2.0`**. Node consumers do not need Bun unless they use the Bun WebView driver.
+<!-- /generated:runtime-requirements -->
 
 ```sh
 bun add -d @crvouga/atlas
@@ -105,10 +138,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 +180,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 +196,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 +223,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 +261,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();