@crvouga/atlas 0.3.0 → 0.5.0

package/llms.txt

@@ -0,0 +1,47 @@
+# Atlas
+
+> Atlas shows whether a product still does what it was specified to do. Test results from any suite on any machine are published as immutable layers; a report is computed from layers, never partitioned, and one Atlas server per project keeps them and shows everyone the combined report, live. Specs of any kind (Gherkin, Quint, DMN, Alloy, OpenSLO, statecharts); evidence of any kind (screenshots, videos, traces, logs). Distributed as the npm package `@crvouga/atlas`; runs on Bun and Node.
+
+To integrate a project: `bunx @crvouga/atlas init --server <url> --format json` prints a plan; `--write` applies it. Everything prints JSON on request, has a JSON Schema, and exits 0 (worked), 1 (the answer is no) or 2 (the command was wrong).
+
+## Start here
+
+- [Atlas for AI agents](https://raw.githubusercontent.com/crvouga/atlas/main/docs/agents.md): Everything an agent needs to integrate a project with Atlas, send it test results, and read them back, with nothing to click and nothing to guess.
+- [Integrating Atlas into a project](https://raw.githubusercontent.com/crvouga/atlas/main/docs/integrating.md): This guide takes a project from nothing to a layered, gated report of its specs.
+
+## Run and use the server
+
+- [The Atlas server](https://raw.githubusercontent.com/crvouga/atlas/main/docs/server.md): One process per project that takes in results from every environment, keeps them, and shows everyone the combined report, live.
+- [Running Atlas for a project: one server](https://raw.githubusercontent.com/crvouga/atlas/main/docs/deploying.md): This is the production setup. A project runs one Atlas server.
+
+## Formats and rules
+
+- [The report contract](https://raw.githubusercontent.com/crvouga/atlas/main/docs/report-contract.md): This is the normative description of what Atlas reads and writes when it reports on specs of any kind:
+- [Evidence: attachments, timelines, snapshots and everything else](https://raw.githubusercontent.com/crvouga/atlas/main/docs/extending.md): Atlas is opinionated about specs and open about evidence.
+- [Report backends and live snapshots](https://raw.githubusercontent.com/crvouga/atlas/main/docs/report-backends.md): Atlas maps the product's areas, screens, events and journeys from a spec, then overlays evidence of what the product did.
+- [Executable statecharts](https://raw.githubusercontent.com/crvouga/atlas/main/docs/statecharts.md): Write down how a product behaves as statecharts in open formats, then let Atlas lint them, plan paths that cover every transition, run those paths against the real product through any driver (a browser, a phone, a pla…
+
+## Working with this project
+
+- [Dogfooding Atlas from another project](https://raw.githubusercontent.com/crvouga/atlas/main/docs/dogfooding.md): Atlas is developed by using it in real projects.
+- [Reporting issues](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reporting-issues.md): How people and coding agents in a project that uses Atlas report a bug or a missing feature.
+
+## Reference (generated from the code)
+
+- [HTTP API (OpenAPI 3.1)](https://raw.githubusercontent.com/crvouga/atlas/main/packages/server/openapi.json): every endpoint of the server, machine-readable. A running server serves it at /api/openapi.json and a guide for itself at /llms.txt.
+- [HTTP API, in words](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/http-api.md): the same operations as Markdown.
+- [Command line](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/cli.md): the usage of every command.
+- [TypeScript API: core](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/core.md): Executable statecharts: loading, composing, linting, planning and running specs against real apps, and the `atlas` command.
+- [TypeScript API: reports](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/reports.md): Layered evidence for any kind of spec: publishing layers, stores (folder, S3, an Atlas server), combining and gating, the incremental report, init.
+- [TypeScript API: schema](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/schema.md): The contract: Zod schemas, and the JSON Schemas generated from them, for layers, checks, report status, command results, server responses and configuration.
+- [TypeScript API: server](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/server.md): The Atlas server: the API results are uploaded to, the live report, and the viewer on one host.
+- [TypeScript API: playwright](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/playwright.md): The Playwright driver for statechart runs.
+- [TypeScript API: bun](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/bun.md): The Bun WebView driver for statechart runs.
+- [TypeScript API: webdriver](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/webdriver.md): The W3C WebDriver / Appium driver for statechart runs.
+- [TypeScript API: detox](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/detox.md): The Detox driver for statechart runs of React Native apps.
+- [TypeScript API: vitest](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/vitest.md): Run a statechart plan as Vitest tests.
+- [JSON Schemas](https://unpkg.com/@crvouga/atlas/packages/schema/schemas/): the layer format, checks file, report status, command results, server responses, server configuration.
+
+## Optional
+
+- [Releasing](https://raw.githubusercontent.com/crvouga/atlas/main/docs/releasing.md): How @crvouga/atlas gets from main to npm.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.3.0",
-  "description": "Atlas: executable statecharts. Spec a product's flows as statecharts, run them against the real app with any driver, and browse what happened.",
+  "version": "0.5.0",
+  "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -17,6 +17,11 @@
     "url": "https://github.com/crvouga/atlas/issues"
   },
   "keywords": [
+    "test-reports",
+    "ctrf",
+    "junit",
+    "gherkin",
+    "specifications",
     "statecharts",
     "scxml",
     "xstate",
@@ -76,11 +81,18 @@
       "types": "./dist/schema/src/index.d.ts",
       "default": "./dist/schema/src/index.js"
     },
+    "./server": {
+      "types": "./dist/server/src/index.d.ts",
+      "default": "./dist/server/src/index.js"
+    },
     "./reports/*": {
       "types": "./dist/reports/src/*.d.ts",
       "default": "./dist/reports/src/*.js"
     },
-    "./schemas/*": "./packages/schema/schemas/*"
+    "./schemas/*": "./packages/schema/schemas/*",
+    "./openapi.json": "./packages/server/openapi.json",
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt"
   },
   "publishConfig": {
     "access": "public",
@@ -90,6 +102,11 @@
     "dist",
     "packages/core/bin",
     "packages/schema/schemas",
+    "packages/server/openapi.json",
+    "llms.txt",
+    "llms-full.txt",
+    "docs/agents.md",
+    "docs/reference",
     "packages/visualizer/bin",
     "packages/visualizer/example",
     "packages/visualizer/fixtures",
@@ -100,14 +117,25 @@
     "packages/visualizer/vite.config.ts",
     "packages/*/README.md",
     "packages/reports/STORAGE.md",
+    "docs/integrating.md",
+    "docs/deploying.md",
+    "docs/server.md",
+    "docs/extending.md",
+    "docs/statecharts.md",
+    "docs/report-contract.md",
+    "docs/report-backends.md",
+    "docs/dogfooding.md",
+    "docs/reporting-issues.md",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "bun scripts/build-package.ts",
     "test": "bun test && bun test --cwd packages/visualizer --preload ./tests/preload.ts tests",
-    "type-check": "for dir in packages/* scripts examples/todo; do tsc --noEmit -p \"$dir\" || exit 1; done",
+    "type-check": "for dir in packages/* scripts scripts/docs examples/todo; do tsc --noEmit -p \"$dir\" || exit 1; done",
     "schemas": "bun packages/schema/scripts/emit-json-schemas.ts",
-    "viz:dev": "cd packages/visualizer && INIT_CWD=\"$OLDPWD\" bun --bun vite --configLoader runner",
+    "docs": "bun scripts/docs/generate.ts",
+    "dev": "bun packages/core/bin/atlas.mjs dev --data .atlas-data",
+    "viz:dev": "bun packages/visualizer/bin/atlas-visualizer.mjs dev --specs \"$(pwd)/packages/visualizer/fixtures/full/specs\" --runs \"$(pwd)/packages/visualizer/fixtures/full/runs\"",
     "viz:build": "cd packages/visualizer && INIT_CWD=\"$OLDPWD\" bun --bun vite build --configLoader runner",
     "viz:publish-data": "bun packages/visualizer/scripts/publish-data.ts",
     "viz:fixtures": "bun packages/visualizer/scripts/make-fixtures.ts",

package/packages/core/README.md

@@ -1,6 +1,7 @@
 # @crvouga/atlas
 
-Executable statecharts. Load charts in W3C SCXML or XState v5 machine config, compose child charts,
+Executable statecharts, and the `atlas report` command for layered evidence of specs of any kind
+([integrating Atlas](../../docs/integrating.md)). Load charts in W3C SCXML or XState v5 machine config, compose child charts,
 lint them, plan paths that cover every transition, run those paths against a real system through
 any driver, and write a manifest with JUnit, CTRF, Mermaid and WebVTT alongside.
 

package/packages/reports/README.md

@@ -1,5 +1,68 @@
 # Atlas reports
 
+Evidence for specs of any kind, kept as immutable **layers** and read back as one report. Start with
+[integrating Atlas](../../docs/integrating.md); the exact rules are in
+[the report contract](../../docs/report-contract.md).
+
+## The short API
+
+Every module is its own import path: `@crvouga/atlas/reports/<module>`. Nothing runs at import.
+
+| Module | Exports | For |
+| --- | --- | --- |
+| `publish-checks` | `publishChecks(store, input)` | Publish the checks of one producer as one layer. Validates, is idempotent, reads no clock. |
+| `ingest` | `checksFromCtrf`, `checksFromJunit`, `checksFromManifest` | Turn a CTRF report, JUnit XML or an Atlas run into checks, with stable ids. |
+| `compose` | `combineBackends(backends, options?)`, `summarize` | Read every layer of every backend and lay them over the specs. A down backend or unreadable layer becomes a notice. |
+| `report-status` | `reportStatus(report, { requireEnvironments? })`, `formatStatusText`, `formatStatusMarkdown` | The gate: `ok`, `reasons`, `failing`, counts per environment. Fails closed. |
+| `directory-store` | `directoryStore(dir)` | A backend on a directory, with atomic writes. |
+| `s3-store` | `s3Store({ bucket, prefix, region, endpoint })`, `S3Error` | A backend on AWS S3, R2, MinIO and anything with the S3 protocol. No SDK: SigV4 over `fetch`, retries, region redirects, a request cap. |
+| `aws-credentials` | `credentialChain()` | Credentials the way an AWS SDK finds them: environment, IRSA, ECS, shared file, the AWS CLI (SSO), EC2. Refreshed before they expire. |
+| `store-url` | `openStore(url)`, `parseStoreLocation`, `storeSpecs` | `s3://bucket/prefix?…`, a folder, or `ATLAS_STORE`, as a store. |
+| `spec-set` | `publishSpecSet`, `latestSpecSet`, `collectSpecFiles` | Publish the specs of a commit, and pick the newest committed set of `main` as the outline. |
+| `run-bundle` | `publishRunBundle`, `listRunSummaries` | Upload a finished statechart run with its media (privacy-gated). |
+| `report-index` | `ReportIndex` | The report, maintained incrementally: each layer read once, only winners kept. |
+| `http-store` | `httpStore({ url, token })`, `AtlasHttpError` | An `ObjectStore` on an Atlas server (`/api/store`): everything that publishes to a store publishes to a server. Retries, and says what to do about each refusal. |
+| `reporter` | `createReporter(identity, { store })` | Stream a run as it happens: each flush is one immutable layer, a retry is byte for byte the same layer, and it never throws into the suite. |
+| `effective-delta` | `applyEffectiveDelta`, `isEffectiveDelta` | A viewer holding a version of the report is sent only what changed since; this makes it whole again. |
+| `doctor` | `inspectStore`, `iamPolicy` | Check a store end to end; the least-privilege IAM policy. |
+| `object-store` | `ObjectStore` | The backend interface: seven methods, no transactions. |
+| `object-store-conformance` | `verifyObjectStore(store)` | Prove a backend you wrote meets the interface. Runs under any test runner. |
+| `copy-store` | `copyStore(from, to)` | Copy the layers a store is missing. Idempotent and commutative: how partial reports meet. |
+| `host` | `reportsHost({ specs, stores })` | The reports half of the viewer for your stores and specs directory. |
+| `layer-merge` | `combineEvidence`, `layerEvidence`, `textFingerprint` | The composition rule itself, over layers already in memory. |
+| `directory-outline` | `loadDirectoryOutline(dir)` | A specs directory as the outline reports are laid over. |
+
+The server itself, `createAtlasServer({ backends, write, site, tokens, include })` and `listen`, is
+[`@crvouga/atlas/server`](../server/README.md), with its own import path.
+
+```ts
+import { combineBackends } from '@crvouga/atlas/reports/compose';
+import { directoryStore } from '@crvouga/atlas/reports/directory-store';
+import { publishChecks } from '@crvouga/atlas/reports/publish-checks';
+import { reportStatus } from '@crvouga/atlas/reports/report-status';
+
+const store = directoryStore('atlas-reports');
+await publishChecks(store, {
+  producer: 'quint',
+  environment: 'desktop-web',
+  recordedAtMs: Date.now(),
+  checks: [{ id: 'specs/booking.qnt > no double booking', title: 'No double booking', status: 'passed', specPath: 'specs/booking.qnt' }]
+});
+
+const report = await combineBackends([{ id: 'local', store }]);
+const status = reportStatus(report);   // { ok, reasons, checks, byEnvironment, failing, notices, … }
+```
+
+The CLI is the same API for people without code: `atlas report publish | status | merge`.
+
+## Recordings, commit-keyed parts and the viewer's API
+
+Everything below is the machinery under the viewer: recorded timelines and captured files
+(`publishSource`), commit-keyed parts (`publishPart`) that older stores hold, and the read-only API
+(`createReportsApp`) the viewer calls. Most projects need only the API above: plain checks need none
+of it, and `reportsHost` wraps `createReportsApp` for your stores.
+
+
 Atlas owns reusable evidence publication, storage, retention, APIs, report navigation and snapshot interpretation. All nondeterministic work is provided through structural `ObjectStore`, `Clock`, `Timers` and `HttpClient` ports. There are no consumer-repository dependencies.
 
 Consumers capture `RunReport` timelines and use `publishSource`, `publishPart` and `publishInventory` to publish them. Existing commit-keyed and compressed report stores remain readable, including reusable sources and independent producer evidence. `createReportsApp` mounts a read-only Hono API over injected stores; it is hosted alongside Atlas, not the product under test.
@@ -10,11 +73,11 @@ The Atlas visualizer shows each kind of spec in its own tab, with every spec's r
 
 ## Combining evidence
 
-Current specs define the outline. `combineEvidence` fills it with the newest completed result for each producer, check and parameter set, across backends, branches and commits. Equal-time conflicts favor failure. Unfinished runs do not erase completed outcomes. Missing specs stay visible and removed specs retain their evidence outside the outline. `evidenceView` groups those results by check: the outcomes, the recorded timings that qualify them, and a summary per spec. A timing over its allowance never fails a check. `checkHistory` returns every layer's own record of one check, so a superseded result stays readable. Leaving a backend, a branch or one layer out (`contributes`) is how earlier outcomes are inspected.
+Current specs define the outline. A layer is one focused recording: the checks it actually ran, on one environment, from one version and branch, in one store. `combineEvidence` fills the outline from every layer. The newest completed result wins only its own producer, check, environment and parameter set. Desktop web, mobile web, iOS and Android of the same check all stay visible, and any other recorded environment does too. A layer that ran one scenario leaves every other scenario as the newest layer that did run it, so the report fills without one suite that runs everything. Equal-time conflicts favor failure. Unfinished runs do not erase completed outcomes. Missing specs stay visible and removed specs retain their evidence outside the outline. `evidenceView` groups those results by check: the outcomes, the recorded timings that qualify them, and a summary per spec. A timing over its allowance never fails a check. `checkHistory` returns every layer's own record of one check, so a superseded result stays readable. Leaving a backend, an environment, a branch, a version or one layer out (`contributes`) is how earlier outcomes are inspected.
 
 ## Backends
 
-`createReportsApp` combines layers from several stores. `localStore` is the backend `local` ("This machine"), `store` is `shared` ("Shared reports"), and `backends` adds any number of further named stores, such as another team's bucket or a device lab. Every layer says which backend it came from. An unavailable backend is named in the page's notices and leaves the others usable; `GET /evidence?retry=1` asks it again without waiting.
+`createReportsApp` combines layers from several stores. `localStore` is the backend `local` ("This machine"), `store` is `shared` ("Shared reports"), and `backends` adds any number of further named stores. A backend is any `ObjectStore`: the local disk, a shared bucket, S3, or a device lab. Every layer says which backend, version, branch and environment it came from. An unavailable backend is named in the page's notices and leaves the others usable; `GET /evidence?retry=1` asks it again without waiting.
 
 | Route | Returns |
 | --- | --- |
@@ -38,8 +101,12 @@ Freshness warnings preserve the recorded outcome. Changed spec fingerprints or r
 
 ## Standalone development
 
+For your own stores and specs directory, use `reportsHost` ([integrating Atlas](../../docs/integrating.md#6-browse-it)). The rest of this section is for hosts that compose the API themselves.
+
 Configure `ATLAS_REPORTS_MODULE` with a host composition module exporting `reportsDevFetch(request, repoRoot)`. Atlas's Vite middleware serves it at `/api/reports`, alongside specs and chart runs. `INIT_CWD` identifies the consuming repository. Credentials stay in that server module.
 
+When that module is unset and the open specs are the coffee example or the todo example, the visualizer dev server serves an in-memory layered report for those documents instead. Any other spec set is left alone. The todo example's own module serves that same layered report and adds the desktop web layer `example:run` writes.
+
 For a separately hosted reports API, set `VITE_ATLAS_REPORTS_URL` when building the visualizer. Otherwise a built site reads `data/evidence/`, populated with `exportEvidence`. Atlas still browses specs if evidence is absent.
 
 ## Verification

package/packages/reports/STORAGE.md

@@ -5,9 +5,13 @@ storage and time ports from its caller.
 
 ## Immutable layers
 
+The layer document is a versioned contract with a JSON Schema: see
+[the report contract](../../docs/report-contract.md). A suite with no timelines to record publishes
+plain checks with `publishChecks`; the rest of this page covers recordings and commit-keyed parts.
+
 `layers/index/<inverted-time>-<digest>.json` discovers immutable manifests at `layers/manifests/<digest>.json`. Each records producer, origin, parameters, checks, spec fingerprints and a recording bundle. The manifest is written after its blobs and the index last. Distinct results at the same timestamp retain separate identities. Compressed blobs under `layers/blobs/` are addressed by content and reused across runs; ordinary source publication shares its bundle directly with its layer without recompressing snapshots.
 
-Git commits are provenance and exact historical recording addresses, never a report partition. `combineEvidence` chooses completed results per check and parameters, retaining gaps from older layers. `publishSource` accepts `parameters`, and standalone parts may include them too. Inventory must be published before results for fingerprint comparison to be available.
+Git commits are provenance and exact historical recording addresses, never a report partition. `combineEvidence` chooses the newest completed result per check, environment and parameters, and keeps every other cell. An environment is the client that was checked (`desktop-web`, `mobile-web`, `ios`, `android`, or any other recorded name). The same check on two environments contributes twice. A layer that checks one scenario fills only that scenario. `publishSource` accepts `environment` and `parameters`, and a part may name its environment in `parameters.environment`. Inventory must be published before results for fingerprint comparison to be available.
 
 ## Commit inventory
 

package/packages/schema/README.md

@@ -12,6 +12,11 @@ The Atlas contract, as Zod schemas and as JSON Schema (draft 2020-12) documents
 | `timeline-entry.schema.json` | One step of a clip's timeline (taps, typing, system events) |
 | `cloud-event.schema.json` | A CloudEvents 1.0 business event a run observed |
 | `runs-index.schema.json` | `runs/index.json`: the runs a host serves |
+| `layer.schema.json` | A layer: the checks one producer ran on one environment, and any evidence they carry (attachments, steps, annotations, attempts, tags, labels, links, extensions). The unit of evidence for specs of any kind |
+| `publish-checks.schema.json` | The input of `publishChecks` and `atlas report publish --checks` |
+| `report-status.schema.json` | The output of `atlas report status --format json` |
+| `server-config.schema.json` | The configuration of `atlas serve` and `atlas dev` |
+| `spec-set.schema.json` | The specs of one commit as published, which the report is laid over |
 
 Regenerate the JSON Schemas after changing a Zod schema:
 
@@ -19,5 +24,14 @@ Regenerate the JSON Schemas after changing a Zod schema:
 bun run schemas
 ```
 
+## Stability
+
+The layer contract is versioned by `schemaVersion` (currently 1). Within a version, changes only add
+optional fields, and readers ignore fields they do not know. The closed vocabularies (`status`,
+`freshness`) change only with a new major version, and a reader refuses a layer of a newer major
+version by name instead of guessing. `packages/reports/tests/fixtures/layer-v1.json` must keep
+parsing, and a test keeps these files equal to what the Zod schemas emit. The full policy is in
+[the report contract](../../docs/report-contract.md#versioning-and-stability).
+
 Readers validate each record on its own and keep the ones that parse, so a newer or partly broken
 manifest still renders what it can.