@crvouga/atlas 0.5.0 → 0.6.0

package/llms.txt

@@ -8,10 +8,11 @@ To integrate a project: `bunx @crvouga/atlas init --server <url> --format json`
 
 - [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.
+- [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 +40,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.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",
@@ -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",
@@ -126,7 +145,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",
@@ -135,10 +156,10 @@
     "schemas": "bun packages/schema/scripts/emit-json-schemas.ts",
     "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",
+    "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 +168,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/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,