@crvouga/atlas 0.5.0 → 0.6.1

package/llms.txt

@@ -1,17 +1,19 @@
 # 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.
+> 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, and a shared Atlas server hosts projects selected by slug and shows each project's combined report, live. Directory stores also work without a server. 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).
+Given only the repository link, start at docs/agents.md: install `@crvouga/atlas` in the consumer project with its own package manager, then read the version-matched docs in the installed package. No clone or Atlas build is needed. docs/quickstart.md verifies local publishing and gating without a server or token. For a shared server, `atlas init --server <url> --format json` prints a plan; `--write` applies it. Report commands and init support JSON with published schemas; exits are 0 (worked), 1 (the answer is no), 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.
+- [Atlas for AI agents](https://raw.githubusercontent.com/crvouga/atlas/main/docs/agents.md): Start here when given the Atlas repository link to integrate it into another project.
+- [Verify Atlas locally](https://raw.githubusercontent.com/crvouga/atlas/main/docs/quickstart.md): Prove that the installed Atlas can publish, combine and gate evidence before connecting your project's real suites.
 - [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.
+- [Native test runner reporters](https://raw.githubusercontent.com/crvouga/atlas/main/docs/runners.md): Projects upload results to a shared Atlas node under their own project slug.
 
 ## 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.
+- [The Atlas server](https://raw.githubusercontent.com/crvouga/atlas/main/docs/server.md): One node for multiple projects 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
@@ -39,6 +41,7 @@ To integrate a project: `bunx @crvouga/atlas init --server <url> --format json`
 - [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: runners](https://raw.githubusercontent.com/crvouga/atlas/main/docs/reference/runners.md): Native reporters that upload to the project server.
 - [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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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",
@@ -92,7 +92,26 @@
     "./schemas/*": "./packages/schema/schemas/*",
     "./openapi.json": "./packages/server/openapi.json",
     "./llms.txt": "./llms.txt",
-    "./llms-full.txt": "./llms-full.txt"
+    "./llms-full.txt": "./llms-full.txt",
+    "./mocha": {
+      "types": "./dist/runners/src/mocha.d.ts",
+      "require": "./packages/runners/compat/mocha.cjs",
+      "default": "./dist/runners/src/mocha.js"
+    },
+    "./codecept": {
+      "types": "./dist/runners/src/codecept.d.ts",
+      "require": "./packages/runners/compat/codecept.cjs",
+      "default": "./dist/runners/src/codecept.js"
+    },
+    "./jest": {
+      "types": "./dist/runners/src/jest.d.ts",
+      "require": "./packages/runners/compat/jest.cjs",
+      "default": "./dist/runners/src/jest.js"
+    },
+    "./node-test": {
+      "types": "./dist/runners/src/node-test.d.ts",
+      "default": "./dist/runners/src/node-test.js"
+    }
   },
   "publishConfig": {
     "access": "public",
@@ -106,6 +125,7 @@
     "llms.txt",
     "llms-full.txt",
     "docs/agents.md",
+    "docs/quickstart.md",
     "docs/reference",
     "packages/visualizer/bin",
     "packages/visualizer/example",
@@ -126,7 +146,9 @@
     "docs/report-backends.md",
     "docs/dogfooding.md",
     "docs/reporting-issues.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/runners.md",
+    "packages/runners/compat"
   ],
   "scripts": {
     "build": "bun scripts/build-package.ts",
@@ -134,11 +156,12 @@
     "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",
     "docs": "bun scripts/docs/generate.ts",
+    "docs:check": "bun test scripts/docs scripts/release/docs-links.test.ts packages/schema/tests/schemas.test.ts packages/server/tests/openapi.test.ts packages/server/tests/settings.test.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",
+    "client:dev": "bun packages/core/bin/atlas.mjs dev",
+    "client:build": "bun packages/core/bin/atlas.mjs client build --no-data",
+    "client:publish-data": "bun packages/visualizer/scripts/publish-data.ts",
+    "client:fixtures": "bun packages/visualizer/scripts/make-fixtures.ts",
     "example:start": "bun examples/todo/server.ts",
     "example:lint": "bun --cwd examples/todo ../../packages/core/bin/atlas.mjs lint --require-implementations",
     "example:plan": "bun --cwd examples/todo ../../packages/core/bin/atlas.mjs plan",
@@ -147,13 +170,14 @@
     "example:clients": "bun --cwd examples/todo ../../packages/core/bin/atlas.mjs run --config clients/atlas.config.ts --mode showcase",
     "example:clients:bun": "ATLAS_DESKTOP=bun bun --cwd examples/todo ../../packages/core/bin/atlas.mjs run --config clients/atlas.config.ts --mode showcase",
     "atlas:run": "status=0; bun run example:clients || status=$?; bun run example:run || status=$?; exit $status",
-    "atlas:viz": "ATLAS_REPORTS_MODULE=\"$(pwd)/examples/todo/reports-dev.ts\" bun packages/visualizer/bin/atlas-visualizer.mjs dev --specs examples/todo/specs --runs examples/todo/atlas-runs",
     "release:plan": "bun scripts/release/plan.ts",
     "release:publish": "bun scripts/release/publish.ts",
     "release:smoke": "bun scripts/release/consumer-smoke.ts",
     "release:seed": "bun scripts/release/seed.ts",
     "health": "bun scripts/health/cli.ts",
-    "prepare": "husky"
+    "prepare": "husky",
+    "example:publish": "bun examples/todo/publish.ts",
+    "atlas": "bun scripts/atlas.mjs"
   },
   "dependencies": {
     "@cucumber/gherkin": "^42.0.1",

package/packages/core/README.md

@@ -9,7 +9,9 @@ any driver, and write a manifest with JUnit, CTRF, Mermaid and WebVTT alongside.
 bun add -d @crvouga/atlas
 ```
 
-Runs on Bun, or on Node 22.18 or later.
+<!-- 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 -->
 
 ## Use
 

package/packages/runners/README.md

@@ -0,0 +1,6 @@
+# Native reporters
+
+Native CodeceptJS, Mocha, Jest and Node test runner reporters upload checks to a project's Atlas server.
+They are entry points of `@crvouga/atlas`, not separate packages.
+
+See [runner setup](../../docs/runners.md) and [generated API reference](../../docs/reference/runners.md).

package/packages/runners/compat/codecept.cjs

@@ -0,0 +1,2 @@
+// CodeceptJS's bundled Mocha loads reporters with require() and expects the constructor itself.
+module.exports = require('../../../dist/runners/src/codecept.js').default;

package/packages/runners/compat/jest.cjs

@@ -0,0 +1,2 @@
+// Jest versions which use require() expect the reporter constructor itself.
+module.exports = require('../../../dist/runners/src/jest.js').default;

package/packages/runners/compat/mocha.cjs

@@ -0,0 +1,2 @@
+// Older Mocha versions require the constructor directly rather than an ESM namespace.
+module.exports = require('../../../dist/runners/src/mocha.js').default;

package/packages/schema/schemas/atlas-change.schema.json

@@ -26,6 +26,10 @@
     },
     "sourceId": {
       "type": "string"
+    },
+    "liveRunId": {
+      "description": "A live lease changed; its bounded snapshot is also sent as a run event",
+      "type": "string"
     }
   },
   "required": [

package/packages/schema/schemas/hello-event.schema.json

@@ -11,6 +11,10 @@
     },
     "time": {
       "type": "number"
+    },
+    "heartbeatMs": {
+      "type": "number",
+      "exclusiveMinimum": 0
     }
   },
   "required": [

package/packages/schema/schemas/live-run-start.schema.json

@@ -0,0 +1,42 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/live-run-start.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+    },
+    "producer": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 2048
+    },
+    "environment": {
+      "type": "string",
+      "maxLength": 200
+    },
+    "branch": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "sha": {
+      "type": "string",
+      "maxLength": 200
+    },
+    "plannedChecks": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1000000
+    }
+  },
+  "required": [
+    "id",
+    "producer"
+  ]
+}

package/packages/schema/schemas/live-run-update.schema.json

@@ -0,0 +1,93 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/live-run-update.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "sequence": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "checks": {
+      "default": [],
+      "maxItems": 1000,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 16384
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "running",
+              "passed",
+              "failed",
+              "not-run"
+            ]
+          },
+          "detail": {
+            "default": "",
+            "type": "string",
+            "maxLength": 8000
+          },
+          "specPath": {
+            "type": "string",
+            "maxLength": 2048
+          },
+          "durationMs": {
+            "type": "number",
+            "minimum": 0
+          },
+          "steps": {
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "maxLength": 2048
+                },
+                "status": {
+                  "type": "string",
+                  "maxLength": 100
+                }
+              },
+              "required": [
+                "name"
+              ]
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "status"
+        ]
+      }
+    },
+    "finish": {
+      "type": "string",
+      "enum": [
+        "completed",
+        "interrupted"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "maxLength": 2000
+    }
+  },
+  "required": [
+    "sequence"
+  ]
+}

package/packages/schema/schemas/live-run.schema.json

@@ -0,0 +1,225 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/live-run.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
+    },
+    "producer": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 2048
+    },
+    "environment": {
+      "type": "string",
+      "maxLength": 200
+    },
+    "branch": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "sha": {
+      "type": "string",
+      "maxLength": 200
+    },
+    "plannedChecks": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1000000
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "running",
+        "completed",
+        "interrupted"
+      ]
+    },
+    "startedAtMs": {
+      "type": "number"
+    },
+    "lastHeartbeatAtMs": {
+      "type": "number"
+    },
+    "lastProgressAtMs": {
+      "type": "number"
+    },
+    "finishedAtMs": {
+      "type": "number"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "sequence": {
+      "type": "number"
+    },
+    "completed": {
+      "type": "number"
+    },
+    "passed": {
+      "type": "number"
+    },
+    "failed": {
+      "type": "number"
+    },
+    "notRun": {
+      "type": "number"
+    },
+    "running": {
+      "type": "number"
+    },
+    "current": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 16384
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "running",
+              "passed",
+              "failed",
+              "not-run"
+            ]
+          },
+          "detail": {
+            "default": "",
+            "type": "string",
+            "maxLength": 8000
+          },
+          "specPath": {
+            "type": "string",
+            "maxLength": 2048
+          },
+          "durationMs": {
+            "type": "number",
+            "minimum": 0
+          },
+          "steps": {
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "maxLength": 2048
+                },
+                "status": {
+                  "type": "string",
+                  "maxLength": 100
+                }
+              },
+              "required": [
+                "name"
+              ]
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "status"
+        ]
+      }
+    },
+    "recent": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 16384
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "running",
+              "passed",
+              "failed",
+              "not-run"
+            ]
+          },
+          "detail": {
+            "default": "",
+            "type": "string",
+            "maxLength": 8000
+          },
+          "specPath": {
+            "type": "string",
+            "maxLength": 2048
+          },
+          "durationMs": {
+            "type": "number",
+            "minimum": 0
+          },
+          "steps": {
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "maxLength": 2048
+                },
+                "status": {
+                  "type": "string",
+                  "maxLength": 100
+                }
+              },
+              "required": [
+                "name"
+              ]
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "status"
+        ]
+      }
+    }
+  },
+  "required": [
+    "id",
+    "producer",
+    "status",
+    "startedAtMs",
+    "lastHeartbeatAtMs",
+    "lastProgressAtMs",
+    "sequence",
+    "completed",
+    "passed",
+    "failed",
+    "notRun",
+    "running",
+    "current",
+    "recent"
+  ]
+}

package/packages/schema/schemas/project-slug.schema.json

@@ -0,0 +1,8 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/project-slug.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "string",
+  "minLength": 1,
+  "maxLength": 64,
+  "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"
+}

package/packages/schema/schemas/project.schema.json

@@ -0,0 +1,22 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/project.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    }
+  },
+  "required": [
+    "slug",
+    "name"
+  ]
+}

package/packages/schema/schemas/projects.schema.json

@@ -0,0 +1,33 @@
+{
+  "$id": "https://github.com/crvouga/atlas/schemas/projects.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "slug",
+          "name"
+        ]
+      }
+    }
+  },
+  "required": [
+    "projects"
+  ]
+}

package/packages/schema/schemas/server-config.schema.json

@@ -178,6 +178,20 @@
       },
       "additionalProperties": false
     },
+    "runTimeoutSeconds": {
+      "description": "Interrupt a live run after this many seconds without a producer heartbeat",
+      "default": 30,
+      "type": "number",
+      "minimum": 10,
+      "maximum": 3600
+    },
+    "runStallSeconds": {
+      "description": "Interrupt after this many seconds without test progress; 0 disables progress expiry",
+      "default": 900,
+      "type": "number",
+      "minimum": 0,
+      "maximum": 86400
+    },
     "heartbeatSeconds": {
       "description": "How often a live connection is touched, so proxies keep it open",
       "default": 15,