@crvouga/atlas 0.5.0 → 0.6.1

package/docs/dogfooding.md

@@ -24,7 +24,11 @@ upgrade, and what to do when something is wrong.
 
 ## Install
 
-Atlas runs on Bun, and on Node 22.18 or later. It is one package:
+<!-- 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 -->
+
+It is one package:
 
 ```sh
 bun add -d @crvouga/atlas
@@ -51,7 +55,7 @@ and nothing runs just because the package is installed.
 | `@crvouga/atlas/reports/<module>` | Publishing, storing, combining, gating and serving test evidence for specs of any kind. |
 
 It also installs two commands: `atlas` (report, lint, plan, run, merge, export) and
-`atlas-visualizer` (browse specs, runs and reports).
+`atlas client` (browse specs, runs and reports).
 
 `playwright` and `detox` are optional peers: install the one your driver uses, as above. The
 documentation ships in the package, matching the version you installed: the README of each part at
@@ -151,7 +155,7 @@ Do this once per project. Check first that the package is on npm:
    | `@crvouga/atlas-schema` | `@crvouga/atlas/schema` |
    | `@crvouga/atlas-schema/schemas/<file>` | `@crvouga/atlas/schemas/<file>` |
    | `@crvouga/atlas-reports/<module>` | `@crvouga/atlas/reports/<module>` |
-   | `@crvouga/atlas-visualizer` (the `atlas-visualizer` command) | installed with `@crvouga/atlas` |
+   | `@crvouga/atlas client` (the `atlas client` command) | installed with `@crvouga/atlas` |
 
    `@crvouga/atlas`, `@crvouga/atlas/spec` and `@crvouga/atlas/signals` are unchanged. One pass
    over a project's sources does the rest:

package/docs/extending.md

@@ -31,7 +31,7 @@ carry any of these. Every one is optional.
 | `attempts[]` | Every try, when the check was retried. |
 | `tags[]` | Free labels to filter by: `smoke`, `payments`. |
 | `labels{}` | Facts about the result that are not its identity: `owner`, `severity`, `browser`, `build`. |
-| `links[]` | Where to read more: the CI run, the issue, the trace viewer. |
+| `links[]` | Where to read more: the CI run, the issue, the trace client. |
 | `extensions{}` | Structured data of your own or a tool's, under a name you own. |
 | `measurements[]` | Numbers, with units and an allowance (already part of the contract). |
 
@@ -224,7 +224,7 @@ Annotation `type`: `note`, `warning`, `deprecation`, `issue`, `accessibility`, `
 | Something that should be shown well | Ask for a renderer (below). |
 | A field every tool should have | Open an issue. It is added as an optional field, and the rules above guarantee nothing breaks. |
 
-**A renderer** is one entry in the viewer's list (`artifactRenderers` in
+**A renderer** is one entry in the client's list (`artifactRenderers` in
 `packages/visualizer/src/evidence/artifacts.tsx`): how to show an attachment of a media type. The first one that
 matches wins:
 
@@ -236,7 +236,7 @@ registerArtifactRenderer({
 });
 ```
 
-The viewer is part of Atlas, so a renderer for a new media type is a contribution to Atlas: file an issue
+The client is part of Atlas, so a renderer for a new media type is a contribution to Atlas: file an issue
 ([reporting issues](reporting-issues.md)) with a sample file. Until it lands, the attachment is still stored,
 listed with its name, role, type and size, and offered for download, and everything else about the result is
 unaffected.

package/docs/integrating.md

@@ -13,6 +13,11 @@ layers over your specs, whatever produced them, whichever machine or branch they
 commands of this guide for your project (`--write` applies them; `--format json` is for agents). See
 [Atlas for AI agents](agents.md). The rest of this guide explains what those commands do.
 
+**Only have the repository link?** Start with [the consumer playbook](agents.md#given-only-this-repository-link)
+for installation choices and version-matched docs. **No server yet?** [Verify Atlas locally](quickstart.md)
+proves publish, repeat-publish, failure and recovery with copyable commands and no credentials. This guide's
+directory/artifact integration works without a server too.
+
 Read [the report contract](report-contract.md) once if you want the exact rules. You do not need it to
 integrate. To run it for a whole team, with a bucket and one node everyone looks at, see
 [running Atlas for a project](deploying.md). This guide ships with the package, matching your version, at
@@ -28,7 +33,7 @@ integrate. To run it for a whole team, with a bucket and one node everyone looks
 ```
  node 1: suite A, ios      ──▶ layer ─┐
  node 2: suite A, android  ──▶ layer ─┤        ┌──▶ atlas report status   (gate: exit 1 on failure)
- node 3: suite B, shard 1  ──▶ layer ─┼──▶ backends ──▶ combine ──┼──▶ the viewer          (browse it)
+ node 3: suite B, shard 1  ──▶ layer ─┼──▶ backends ──▶ combine ──┼──▶ the client          (browse it)
  node 4: suite B, shard 2  ──▶ layer ─┤        └──▶ your own code          (combineBackends)
  a laptop, one scenario    ──▶ layer ─┘
 ```
@@ -60,8 +65,11 @@ bun add -d @crvouga/atlas        # or: npm install -D @crvouga/atlas, pnpm add -
 bunx atlas report --help         # npx atlas report --help
 ```
 
-Expected: the usage text of `atlas report`. Atlas runs on Bun and on Node 22.18 or later. Add the
-directory you publish to (`atlas-reports/`) to `.gitignore`.
+Expected: the usage text of `atlas report`. Add the directory you publish to (`atlas-reports/`) to `.gitignore`.
+
+<!-- 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 -->
 
 ## 3. Make each suite publish a layer
 
@@ -394,7 +402,7 @@ unknown is not a pass.
 
 ## 6. Browse it
 
-The visualizer lays your stores over your specs directory. Add a module to your project:
+The Atlas client lays your stores over your specs directory. Add a module to your project:
 
 ```ts
 // atlas.reports.ts
@@ -404,14 +412,14 @@ export const reportsDevFetch = reportsHost({ specs: './specs', stores: ['./atlas
 ```
 
 ```sh
-ATLAS_REPORTS_MODULE="$(pwd)/atlas.reports.ts" bunx atlas-visualizer dev --specs ./specs
+ATLAS_REPORTS_MODULE="$(pwd)/atlas.reports.ts" bunx atlas client dev --specs ./specs
 ```
 
 `reportsHost(options)` returns `(request: Request, repoRoot: string) => Promise<Response>`, the
-function the viewer calls for every `/api/reports/…` request. `specs` and directory `stores` resolve
-against `repoRoot`, which the viewer sets to where you ran the command (`INIT_CWD`), not against the
+function the client calls for every `/api/reports/…` request. `specs` and directory `stores` resolve
+against `repoRoot`, which the client sets to where you ran the command (`INIT_CWD`), not against the
 module. A wrong path comes back as a JSON error that names it. A `stores` entry that is not a string is
-a backend of your own: `{ id, label?, store }`. You can call it yourself to look at what the viewer
+a backend of your own: `{ id, label?, store }`. You can call it yourself to look at what the client
 sees:
 
 ```ts
@@ -424,11 +432,11 @@ const page = await (await reportsDevFetch(new Request('http://x/api/reports/evid
 
 | Route (after `/api/reports`) | Returns |
 | --- | --- |
-| `/evidence?cursor=` | A page of layer headers, the backends and any notices. The viewer combines them with the specs. |
+| `/evidence?cursor=` | A page of layer headers, the backends and any notices. The client combines them with the specs. |
 | `/evidence/rows/:backend/:id` | One layer's checks. |
 | `/outline`, `/outline/spec?path=` | The specs directory as an outline, and one spec's text. |
 
-The combined result of each spec is computed in the viewer. To get it without a browser, use
+The combined result of each spec is computed in the client. To get it without a browser, use
 `atlas report status --format json`: its `specs` array has each spec's counts per environment.
 
 Specs are the files of the specs directory (`.feature` as Gherkin, `.qnt` as Quint, `.dmn`, `.als`,
@@ -469,7 +477,7 @@ An integration is complete when each of these holds. Run them and keep the outpu
 | `X is unavailable` | A backend is down. The rest were combined; fix it or leave it out. |
 | `check id "…" appears twice` | Your suite emits two checks with one name. Make the names unique. Importers number repeats as `#2`. |
 | `Potentially outdated: spec changed` | The spec changed since the layer was recorded. Advisory: the recorded outcome still counts. Re-run to refresh. |
-| Viewer shows `No report store is configured` | `ATLAS_REPORTS_MODULE` is unset, or `stores` is empty. |
+| Client shows `No report store is configured` | `ATLAS_REPORTS_MODULE` is unset, or `stores` is empty. |
 
 ## Rules
 

package/docs/quickstart.md

@@ -0,0 +1,81 @@
+# Verify Atlas locally
+
+Prove that the installed Atlas can publish, combine and gate evidence before connecting your project's real
+suites. This walkthrough needs no server, token, browser, Docker, existing specs or changes to Atlas itself.
+The checks below are synthetic plumbing checks, not evidence about your product.
+
+First [install Atlas with your project's package manager](agents.md#install-in-the-consumer-project).
+Run the following from your **consumer project's root** using a POSIX shell (macOS, Linux, or Windows with
+WSL/Git Bash). `atlas` means the installed binary: substitute `bunx atlas`, `npm exec -- atlas`,
+`pnpm exec atlas` or `yarn exec atlas` on each command. In a package script, `atlas` works directly.
+
+## Publish one check, twice
+
+Create a scratch directory. Keep this shell open for the rest of the walkthrough. Explicit `--store` flags
+keep these synthetic checks local even if `ATLAS_STORE` points at a shared server.
+
+<!-- smoke:begin -->
+```sh
+atlas_smoke=$(mktemp -d)
+cat > "$atlas_smoke/pass.json" <<'JSON'
+{"producer":"integration-smoke","environment":"local","recordedAtMs":1000,"checks":[{"id":"plumbing","title":"Atlas integration plumbing","status":"passed"}]}
+JSON
+atlas report publish --store "$atlas_smoke/store" --checks "$atlas_smoke/pass.json" --format json
+atlas report status --store "$atlas_smoke/store" --require-environments local --format json
+atlas report publish --store "$atlas_smoke/store" --checks "$atlas_smoke/pass.json" --format json
+atlas report status --store "$atlas_smoke/store" --require-environments local --format json
+```
+<!-- smoke:end -->
+
+Expected: each command exits `0`. Both status documents have `ok: true`, `checks.total: 1`,
+`checks.passed: 1`, and `layers: 1`. Publishing identical evidence did not add a second layer.
+
+## Prove a failure fails the gate
+
+Publish the same check, from the same producer and environment, with a later time and a failure.
+The shell captures the expected nonzero exit so this works under `set -e` too.
+
+<!-- smoke:begin -->
+```sh
+cat > "$atlas_smoke/fail.json" <<'JSON'
+{"producer":"integration-smoke","environment":"local","recordedAtMs":2000,"checks":[{"id":"plumbing","title":"Atlas integration plumbing","status":"failed","detail":"Intentional smoke failure"}]}
+JSON
+atlas report publish --store "$atlas_smoke/store" --checks "$atlas_smoke/fail.json" --format json
+atlas_gate_exit=0
+atlas report status --store "$atlas_smoke/store" --format json || atlas_gate_exit=$?
+test "$atlas_gate_exit" -eq 1
+```
+<!-- smoke:end -->
+
+Expected: publish exits `0` because the upload worked. Status exits `1`, with `ok: false`,
+`checks.failed: 1` and the check in `failing`. The final `test` exits `0`, proving status returned exactly `1`.
+An exit of `2` means a command error and does not satisfy this check.
+
+## Prove a later fix replaces it
+
+Keep the check's identity and publish a newer passing result. Do not delete the failing layer.
+
+<!-- smoke:begin -->
+```sh
+atlas report publish --store "$atlas_smoke/store" --checks "$atlas_smoke/pass.json" --recorded-at 3000 --format json
+atlas report status --store "$atlas_smoke/store" --require-environments local --format json
+```
+<!-- smoke:end -->
+
+Expected: status exits `0`, with `ok: true`, `checks.total: 1`, `checks.passed: 1`, `checks.failed: 0`,
+and `layers: 3`. Three historical layers contribute one current check.
+
+The files are disposable; their location is in `$atlas_smoke`. No file was created in your project.
+For automation, parse the JSON documents rather than console prose; the command schemas are listed in
+[the agent guide](agents.md#what-an-agent-can-rely-on).
+
+## Connect a real suite
+
+Continue with [integrating Atlas](integrating.md#3-make-each-suite-publish-a-layer). Run a real suite,
+publish its JUnit/CTRF file even when it fails, and inspect `status --format json`. A passing synthetic check
+does not complete the integration: preserve your suite's original exit code and verify real evidence and CI
+as described in [the completion checklist](integrating.md#7-done-when).
+
+For a shared server, use [the server setup](server.md), select a stable `ATLAS_PROJECT` slug, and follow
+[the agent workflow](agents.md#the-shortest-path). Statecharts and browser drivers are optional; importing
+existing test reports needs neither.

package/docs/reference/cli.md

@@ -16,8 +16,9 @@ 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)
 
@@ -57,7 +58,7 @@ atlas serve: the Atlas server
               [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]
               [--anonymous-read] [--insecure] [--no-log]
 
-  One process serves the viewer and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
+  One process serves the client and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
   shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more
   backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.
 
@@ -68,12 +69,12 @@ atlas serve: the Atlas server
 ## atlas dev
 
 ```text
-atlas dev: the Atlas server and the viewer, for working on either
+atlas dev: the Atlas server and the client, for working on either
 
   atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
 
-  Starts the server (API only, on a port of its own) and the viewer's dev server, which proxies /api to it, so the
-  browser talks to one host and a change to the viewer shows at once. In production `atlas serve` does both from
+  Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the
+  browser talks to one host and a change to the client shows at once. In production `atlas serve` does both from
   one process.
 ```
 
@@ -101,7 +102,8 @@ atlas report — layered evidence for any kind of spec
   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.

package/docs/reference/core.md

@@ -49,6 +49,8 @@ See docs/statecharts.md
 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. */
@@ -149,6 +151,8 @@ not thrown.
 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). */
@@ -1071,6 +1075,8 @@ export type RunOptions<C> = RunContext<C> & {
   reuse?: { runDir: string; outcomes: Record<string, PathOutcome> };
   /** 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;
 };
 ```