@crvouga/atlas 0.5.0 → 0.6.1

package/dist/reports/src/init.js

@@ -19,6 +19,7 @@ import { InitPlanSchema } from '../../schema/src/cli-results.js';
 import { collectSpecFiles, specKindOf } from './directory-outline.js';
 import { httpStore } from './http-store.js';
 import { serverToken } from './store-url.js';
+import { PACKAGE_MANAGERS } from './package-managers.js';
 const BEGIN = '<!-- atlas:begin -->';
 const END = '<!-- atlas:end -->';
 function defaultGit(args, cwd) {
@@ -50,9 +51,6 @@ function packageManagerOf(directory, pkg) {
     const declared = typeof pkg?.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
     return declared === 'bun' || declared === 'pnpm' || declared === 'yarn' || declared === 'npm' ? declared : pkg ? 'npm' : null;
 }
-/** How the package manager runs a package's binary without installing it: `bunx`, `pnpm dlx`, `yarn dlx`, `npx`. */
-const EXEC = { bun: 'bunx', pnpm: 'pnpm dlx', yarn: 'yarn dlx', npm: 'npx' };
-const INSTALL_DEV = { bun: 'bun add -d', pnpm: 'pnpm add -D', yarn: 'yarn add -D', npm: 'npm install -D' };
 /** The spec files of a project by kind, and the folder to pass as `--specs`. */
 async function specsOf(directory) {
     const candidates = ['specs', 'spec', 'features', 'docs/specs', 'test/features', 'tests/features'];
@@ -88,6 +86,9 @@ function runnersOf(directory, pkg) {
     dep('cypress', 'cypress');
     dep('jest', 'jest');
     dep('mocha', 'mocha');
+    dep('codeceptjs', 'codeceptjs');
+    if (/\bnode\s+--test\b/.test(scripts))
+        found.push({ runner: 'node-test', evidence: 'package.json scripts: node --test' });
     if (!found.some(item => item.runner === 'vitest' || item.runner === 'jest' || item.runner === 'mocha') && /\bbun test\b/.test(scripts))
         found.push({ runner: 'bun-test', evidence: 'package.json scripts: bun test' });
     else if (!found.length && pkg && (existsSync(path.join(directory, 'bun.lock')) || existsSync(path.join(directory, 'bunfig.toml'))) && readdirSafe(directory).some(name => /\.(test|spec)\.[cm]?[tj]sx?$/.test(name) || name === 'tests' || name === 'test'))
@@ -115,7 +116,7 @@ function readdirSafe(directory) {
 /** The suite for a detected runner: how to run it so it writes a JUnit file (or the run manifest), and how to publish it. */
 function suiteOf(detected, context) {
     const specs = context.specs ? ` --specs ${context.specs}` : '';
-    const publishCommand = (producer, input, environment) => `${context.exec} @crvouga/atlas report publish --producer ${producer} ${input}${specs}${environment ? ` --environment ${environment}` : ''}`;
+    const publishCommand = (producer, input, environment) => `${context.exec} atlas report publish --producer ${producer} ${input}${specs}${environment ? ` --environment ${environment}` : ''}`;
     const make = (id, output, run, environment, prerequisites = [], format = 'junit', stream = null) => ({
         id, runner: detected.runner, evidence: detected.evidence, run, output, format, environment,
         publish: publishCommand(id, format === 'manifest' ? `--manifest ${output} --upload-run` : `--${format} ${output}`, environment), stream, prerequisites
@@ -128,10 +129,12 @@ function suiteOf(detected, context) {
         case 'cypress': return make('cypress', out('cypress'), `${context.exec} cypress run --reporter junit --reporter-options mochaFile=${out('cypress')}`, 'desktop-web');
         case 'cucumber': return make('cucumber', out('cucumber'), `${context.exec} cucumber-js --format summary --format junit:${out('cucumber')}`, null);
         case 'mocha': return make('mocha', out('mocha'), `MOCHA_FILE=${out('mocha')} ${context.exec} mocha --reporter mocha-junit-reporter`, null, [`${context.install} mocha-junit-reporter`]);
+        case 'codeceptjs': return make('codeceptjs', out('codeceptjs'), `MOCHA_FILE=${out('codeceptjs')} ${context.exec} codeceptjs run --reporter mocha-junit-reporter`, 'desktop-web', [`${context.install} mocha-junit-reporter`]);
+        case 'node-test': return make('node-test', out('node-test'), `node --test --test-reporter=junit --test-reporter-destination=${out('node-test')}`, null);
         case 'bun-test': return make('bun-test', out('bun'), `bun test --reporter=junit --reporter-outfile=${out('bun')}`, null);
         case 'pytest': return make('pytest', out('pytest'), `pytest --junitxml=${out('pytest')}`, null);
         case 'go-test': return make('go-test', out('go'), `go test -v ./... 2>&1 | go-junit-report > ${out('go')}`, null, ['go install github.com/jstemmer/go-junit-report/v2@latest']);
-        default: return make('statecharts', 'atlas-runs/latest/manifest.json', `${context.exec} @crvouga/atlas run --mode fast`, null, [], 'manifest');
+        default: return make('statecharts', 'atlas-runs/latest/manifest.json', `${context.exec} atlas run --mode fast`, null, [], 'manifest');
     }
 }
 /** A suite that does not set its own exit-code handling must still publish: a failure is evidence. */
@@ -139,7 +142,7 @@ function githubWorkflow(suites, context) {
     const setup = context.manager === 'bun'
         ? '      - uses: oven-sh/setup-bun@v2\n      - run: bun install --frozen-lockfile\n'
         : `      - uses: actions/setup-node@v4\n        with: { node-version: 22 }\n      - run: ${context.manager === 'pnpm' ? 'corepack enable && pnpm install --frozen-lockfile' : context.manager === 'yarn' ? 'corepack enable && yarn install --immutable' : 'npm ci'}\n`;
-    const exec = EXEC[context.manager ?? 'npm'];
+    const exec = PACKAGE_MANAGERS[context.manager ?? 'npm'].exec;
     const jobs = suites.map(suite => `  ${suite.id.replace(/[^a-z0-9]+/g, '-')}:
     runs-on: ubuntu-latest
     steps:
@@ -152,13 +155,15 @@ ${setup}      # A failing suite must still publish: a failure is evidence. The j
 `).join('\n');
     return `# Sends every suite's results to the project's Atlas server and gates on the combined report.
 # Generated by \`atlas init\`; safe to edit. Needs the repository variable ATLAS_URL (https://atlas.example.com) and the
-# secrets ATLAS_PUBLISH_TOKEN (a \`publish\` token) and ATLAS_READ_TOKEN (a \`read\` token) of that server.
+# variable ATLAS_PROJECT (a stable project slug), and secrets ATLAS_PUBLISH_TOKEN (a \`publish\` token) and
+# ATLAS_READ_TOKEN (a \`read\` token) of that server.
 name: atlas
 on: [push, pull_request]
 permissions:
   contents: read
 env:
   ATLAS_STORE: \${{ vars.ATLAS_URL }}
+  ATLAS_PROJECT: \${{ vars.ATLAS_PROJECT }}
   ATLAS_TOKEN: \${{ secrets.ATLAS_PUBLISH_TOKEN }}
 jobs:
 ${jobs}
@@ -170,26 +175,27 @@ ${jobs}
       ATLAS_TOKEN: \${{ secrets.ATLAS_READ_TOKEN }}
     steps:
       - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
+${setup.trimEnd()}
       # This branch laid over ${context.defaultBranch}: what this run did not re-run is inherited from ${context.defaultBranch}'s latest
       # results, and a laptop's work in progress or another branch's results cannot turn this red.
-      - run: bunx @crvouga/atlas report status --branch "\${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" --branch ${context.defaultBranch} --ignore-modified${context.specs ? ' --require-all-specs' : ''}
+      - run: ${exec} atlas report status --branch "\${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" --branch ${context.defaultBranch} --ignore-modified${context.specs ? ' --require-all-specs' : ''}
 `;
 }
 /** The `AGENTS.md` section: what Atlas is in this project and the commands to use, replaced between its markers. */
-function agentsSection(plan) {
+function agentsSection(plan, exec) {
     const url = plan.server.url ?? '<the project\'s Atlas server>';
     const lines = [
         BEGIN,
         '## Atlas: test evidence for this project',
         '',
         `This project sends the results of its test suites to an [Atlas](https://github.com/crvouga/atlas) server (${url}), which shows everyone one combined, live report. A check is identified by a stable id; the newest completed result of each check wins; unknown is never a pass. Set \`ATLAS_STORE=${url}\` and \`ATLAS_TOKEN\` (a \`publish\` token for sending, a \`read\` token for asking).`,
+        'Set `ATLAS_PROJECT` to the same stable project slug locally and in CI; this selects the project on a shared node. Use the installed `@crvouga/atlas` and the project\'s lockfile. Integration guide: https://github.com/crvouga/atlas/blob/main/docs/agents.md (version-matched copy: `node_modules/@crvouga/atlas/docs/agents.md`).',
         '',
         '- **Machine-readable API:** `' + `${url}/api/openapi.json` + '` (OpenAPI 3.1). **Guide for agents:** `' + `${url}/llms.txt` + '`.',
         '- **After you change behaviour,** run the suite, then send its results (publish even when it fails: a failure is evidence).',
         ...plan.suites.flatMap(suite => ['', `  - **${suite.id}**: \`${suite.run}\``, `    then \`${suite.publish}\`` + (suite.stream ? ` (or stream: \`${suite.stream}\`)` : '')]),
         '',
-        `- **Is it passing?** \`bunx @crvouga/atlas report status --branch ${plan.git.defaultBranch} --ignore-modified --format json\` (exit 0 passes, 1 does not, 2 means the command was wrong). The failing checks are in \`failing\`.`,
+        `- **Is it passing?** \`${exec} atlas report status --branch ${plan.git.defaultBranch} --ignore-modified --format json\` (exit 0 passes, 1 does not, 2 means the command was wrong). The failing checks are in \`failing\`.`,
         plan.specs.directory ? `- **Specs** live in \`${plan.specs.directory}/\` (${Object.entries(plan.specs.kinds).map(([kind, count]) => `${count} ${kind}`).join(', ')}). Results are laid over them by path.` : '- No spec files were found. Pass `--spec <path>` or `--specs <dir>` to `publish` to link checks to specs.',
         '- Keep each check\'s `id` stable across runs: that is what lets a new result replace an old one.',
         '- Evidence (screenshots, videos, traces, logs) rides on checks: https://github.com/crvouga/atlas/blob/main/docs/extending.md',
@@ -223,16 +229,17 @@ export async function planInit(options) {
     const env = options.env ?? {};
     const git = options.git ?? defaultGit;
     const pkg = readJson(path.join(directory, 'package.json'));
+    const dependencies = { ...pkg?.dependencies, ...pkg?.devDependencies };
     const manager = packageManagerOf(directory, pkg);
     const specs = await specsOf(directory);
     const configured = env.ATLAS_STORE?.split(/[\n,]+/).map(item => item.trim()).find(item => /^https?:\/\//i.test(item));
     const serverUrl = (options.server ?? configured ?? null)?.replace(/\/+$/, '') ?? null;
     const warnings = [];
-    const exec = EXEC[manager ?? 'npm'];
-    const context = { exec, install: INSTALL_DEV[manager ?? 'npm'], specs: specs.directory, server: serverUrl };
+    const { exec, installDev } = PACKAGE_MANAGERS[manager ?? 'npm'];
+    const context = { exec, install: installDev, specs: specs.directory, server: serverUrl };
     const suites = runnersOf(directory, pkg).map(found => suiteOf(found, context));
     if (!suites.length)
-        warnings.push('No test runner was recognised (looked for vitest, jest, playwright, cypress, cucumber, mocha, bun test, pytest, go test and Atlas statecharts). Add one suite by hand: run it so it writes a JUnit XML or CTRF file, then `atlas report publish --producer <name> --junit <file>`.');
+        warnings.push('No test runner was recognised (looked for vitest, jest, playwright, cypress, cucumber, mocha, codeceptjs, node --test, bun test, pytest, go test and Atlas statecharts). Add one suite by hand: run it so it writes a JUnit XML or CTRF file, then `atlas report publish --producer <name> --junit <file>`.');
     if (!serverUrl)
         warnings.push('No server given. Pass --server https://… (or set ATLAS_STORE) so the plan can name it; until then the generated text says "the project\'s Atlas server".');
     if (!specs.directory)
@@ -247,7 +254,7 @@ export async function planInit(options) {
         warnings.push(`${ci} detected: no workflow is generated for it. In its jobs run each suite, then its publish command (with ATLAS_STORE and ATLAS_TOKEN set from secrets), then the gate command from AGENTS.md.`);
     const base = { suites, specs, server: { url: serverUrl, tokenEnv: 'ATLAS_TOKEN' }, git: { branch, defaultBranch } };
     const wanted = [
-        { path: 'AGENTS.md', purpose: 'Tells every agent working in this repository how to send and read test evidence.', next: current => withSection(current, agentsSection(base)) }
+        { path: 'AGENTS.md', purpose: 'Tells every agent working in this repository how to send and read test evidence.', next: current => withSection(current, agentsSection(base, exec)) }
     ];
     if (ci === 'github-actions' && suites.length)
         wanted.push({ path: '.github/workflows/atlas.yml', purpose: 'Runs each suite in CI, sends its results to the server even when it fails, and gates on the combined report.', next: () => githubWorkflow(suites, { manager, defaultBranch, specs: specs.directory }) });
@@ -286,10 +293,11 @@ export async function planInit(options) {
     else if (options.verify)
         warnings.push('--verify needs a server: pass --server or set ATLAS_STORE.');
     const nextSteps = [
+        ...(dependencies['@crvouga/atlas'] ? [] : [`Install Atlas in this project before running the planned commands: ${context.install} @crvouga/atlas. Commit the manifest and lockfile so local runs and CI use the same version.`]),
         ...(serverUrl ? [] : ['Decide which server to send results to (run one with `atlas serve`), then run this again with --server <url>.']),
         ...(options.write ? [] : ['Review the plan, then run again with --write to create the files in `files`.']),
         ...suites.flatMap(suite => suite.prerequisites.map(command => `Install what ${suite.id} needs: ${command}`)),
-        ...(serverUrl ? [`Set ATLAS_STORE=${serverUrl} and ATLAS_TOKEN (a publish token) in CI and on each machine that should send results.`, 'Run `atlas report doctor` to prove the server can be written to and read.'] : []),
+        ...(serverUrl ? [`Set ATLAS_STORE=${serverUrl}, ATLAS_PROJECT (the same stable project slug) and ATLAS_TOKEN (a publish token) in CI and on each machine that should send results.`, 'Run `atlas report doctor` to prove the server can be written to and read.'] : []),
         ...suites.map(suite => `Prove ${suite.id}: run \`${suite.run}\`, then \`${suite.publish}\`, then open ${serverUrl ?? 'the server'} and find its results.`)
     ];
     const ok = verification ? verification.reachable && verification.canPublish && verification.error === null : true;

package/dist/reports/src/live-reporter.d.ts

@@ -0,0 +1,34 @@
+import type { z } from 'zod/v4';
+import type { LiveCheck, LiveRunStartSchema } from '../../schema/src/live-run.js';
+/** Fixed identity of a live invocation; a UUID is generated when omitted. */
+export type LiveIdentity = Omit<z.input<typeof LiveRunStartSchema>, 'id'> & {
+    id?: string;
+};
+/** Transport and batching configuration. Defaults: 250 ms batches, 5 s heartbeats and 10 s request timeouts. */
+export type LiveReporterOptions = {
+    url: string;
+    project?: string;
+    token?: string;
+    flushMs?: number;
+    heartbeatMs?: number;
+    timeoutMs?: number;
+    onError?: (error: Error) => void;
+};
+/** Producer handle. check never throws transport errors into a test; finish flushes and rejects if publication failed. */
+export type LiveReporter = {
+    readonly id: string;
+    readonly finishedAtMs?: number;
+    check(check: LiveCheck): void;
+    flush(): Promise<void>;
+    finish(status?: 'completed' | 'interrupted', reason?: string): Promise<void>;
+};
+/**
+ * Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+ * The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+ * @example
+ * const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+ * await run.finish();
+ */
+export declare function createLiveReporter(identity: LiveIdentity, options: LiveReporterOptions): LiveReporter;

package/dist/reports/src/live-reporter.js

@@ -0,0 +1,122 @@
+/** @module Reporting a live run to Atlas
+ * Streams bounded check deltas while tests execute. Heartbeats are independent of progress; finished results are
+ * published by the server as ordinary immutable layers. A final flush is awaited before a runner exits.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+ * The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+ * @example
+ * const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+ * run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+ * await run.finish();
+ */
+export function createLiveReporter(identity, options) {
+    const base = new URL(options.url);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+        throw new Error('Atlas live reporter needs an HTTP(S) server URL without credentials, query or fragment.');
+    const id = identity.id ?? randomUUID();
+    const endpoint = `${base.href.replace(/\/$/, '')}/api/live/${id}`;
+    let sequence = 0;
+    let finishedAtMs;
+    let closed = false;
+    let timer;
+    let error;
+    const pending = new Map();
+    const known = new Map();
+    let failed;
+    const reportError = (caught) => { error = caught instanceof Error ? caught : new Error(String(caught)); options.onError?.(error); };
+    async function request(method, payload, suffix = '') {
+        const text = payload === undefined ? undefined : JSON.stringify(payload);
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await fetch(endpoint + suffix, { method, redirect: 'error', signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+                    headers: { 'content-type': 'application/json', ...(options.project ? { 'x-atlas-project': options.project } : {}), ...(options.token ? { authorization: `Bearer ${options.token}` } : {}) }, body: text });
+                const status = response.status;
+                const json = response.headers.get('content-type')?.includes('application/json');
+                if (response.ok && !json) {
+                    await response.body?.cancel();
+                    throw Object.assign(new Error('Atlas live reporter: the endpoint is not an Atlas server. Start or restart `bun atlas`.'), { permanent: true });
+                }
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw Object.assign(new Error(`Atlas live reporter: HTTP ${status}`), { permanent: status < 500 && status !== 429 });
+                }
+                return await response.json();
+            }
+            catch (caught) {
+                if (attempt >= 2 || caught.permanent)
+                    throw caught;
+                await new Promise(resolve => setTimeout(resolve, 250 * 2 ** attempt));
+            }
+        }
+    }
+    const ready = request('POST', { ...identity, id });
+    void ready.catch(reportError);
+    let queue = Promise.resolve();
+    let draining;
+    const flush = () => {
+        if (draining)
+            return draining;
+        queue = queue.then(async () => {
+            await ready;
+            while (failed || pending.size) {
+                if (!failed) {
+                    const checks = [...pending.values()].slice(0, 1000);
+                    checks.forEach(check => pending.delete(check.id));
+                    failed = { sequence: sequence + 1, checks };
+                }
+                await request('PATCH', failed);
+                sequence = failed.sequence;
+                failed = undefined;
+            }
+            error = undefined;
+        }).catch(reportError);
+        draining = queue.finally(() => { draining = undefined; });
+        return draining;
+    };
+    const heartbeat = setInterval(() => { if (!closed)
+        void ready.then(async () => { await request('POST', undefined, '/heartbeat'); if (!closed && (failed || pending.size))
+            void flush(); }).catch(caught => { if (!closed)
+            reportError(caught); }); }, options.heartbeatMs ?? 5000);
+    heartbeat.unref?.();
+    const check = (given) => {
+        if (closed)
+            throw new Error('This live reporter is closed.');
+        const check = { id: given.id, title: given.title.slice(0, 2048), status: given.status, detail: (given.detail ?? '').slice(0, 8000),
+            ...(given.specPath ? { specPath: given.specPath } : {}), ...(given.durationMs === undefined ? {} : { durationMs: given.durationMs }),
+            ...(given.steps?.length ? { steps: given.steps.slice(-20).map(step => ({ name: step.name.slice(0, 2048), ...(step.status ? { status: step.status.slice(0, 100) } : {}) })) } : {}) };
+        if (JSON.stringify(known.get(check.id)) === JSON.stringify(check))
+            return;
+        known.set(check.id, check);
+        pending.set(check.id, check);
+        if (!timer) {
+            timer = setTimeout(() => { timer = undefined; void flush(); }, options.flushMs ?? 250);
+            timer.unref?.();
+        }
+    };
+    return { id, get finishedAtMs() { return finishedAtMs; }, check, flush, async finish(status = 'completed', reason) {
+            if (closed) {
+                await queue;
+                if (error)
+                    throw error;
+                return;
+            }
+            const unfinished = [...known.values()].filter(check => check.status === 'running');
+            if (unfinished.length) {
+                status = 'interrupted';
+                reason ??= 'The producer ended without a final outcome for running checks.';
+                unfinished.forEach(value => check({ ...value, status: 'not-run', detail: reason }));
+            }
+            closed = true;
+            clearInterval(heartbeat);
+            clearTimeout(timer);
+            await flush();
+            if (error)
+                throw error;
+            const result = await request('PATCH', { sequence: sequence + 1, checks: [], finish: status, ...(reason ? { reason } : {}) });
+            finishedAtMs = result.finishedAtMs;
+            sequence++;
+        } };
+}

package/dist/reports/src/package-managers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module Consumer package-manager commands
+ *
+ * One source for commands emitted by init, the running server's agent guide, and generated documentation.
+ * Execute the installed CLI so a consumer keeps the versions selected by its own manifest and lockfile.
+ */
+/** Supported consumer package managers, their development install command and installed-binary executor. */
+export declare const PACKAGE_MANAGERS: {
+    readonly bun: {
+        readonly label: "Bun";
+        readonly installDev: "bun add -d";
+        readonly exec: "bunx";
+    };
+    readonly npm: {
+        readonly label: "npm";
+        readonly installDev: "npm install -D";
+        readonly exec: "npm exec --";
+    };
+    readonly pnpm: {
+        readonly label: "pnpm";
+        readonly installDev: "pnpm add -D";
+        readonly exec: "pnpm exec";
+    };
+    readonly yarn: {
+        readonly label: "Yarn";
+        readonly installDev: "yarn add -D";
+        readonly exec: "yarn exec";
+    };
+};
+/**
+ * Markdown installation table for consumer and server agent documentation.
+ * @example
+ * const markdown = packageManagerTable(); // the same commands `atlas init` emits
+ */
+export declare function packageManagerTable(): string;

package/dist/reports/src/package-managers.js

@@ -0,0 +1,23 @@
+/**
+ * @module Consumer package-manager commands
+ *
+ * One source for commands emitted by init, the running server's agent guide, and generated documentation.
+ * Execute the installed CLI so a consumer keeps the versions selected by its own manifest and lockfile.
+ */
+/** Supported consumer package managers, their development install command and installed-binary executor. */
+export const PACKAGE_MANAGERS = {
+    bun: { label: 'Bun', installDev: 'bun add -d', exec: 'bunx' },
+    npm: { label: 'npm', installDev: 'npm install -D', exec: 'npm exec --' },
+    pnpm: { label: 'pnpm', installDev: 'pnpm add -D', exec: 'pnpm exec' },
+    yarn: { label: 'Yarn', installDev: 'yarn add -D', exec: 'yarn exec' }
+};
+/**
+ * Markdown installation table for consumer and server agent documentation.
+ * @example
+ * const markdown = packageManagerTable(); // the same commands `atlas init` emits
+ */
+export function packageManagerTable() {
+    return ['| Package manager | Install | Run the installed CLI |', '| --- | --- | --- |',
+        ...Object.values(PACKAGE_MANAGERS).map(manager => `| ${manager.label} | \`${manager.installDev} @crvouga/atlas\` | \`${manager.exec} atlas\` |`)
+    ].join('\n');
+}

package/dist/reports/src/report-cli.d.ts

@@ -13,7 +13,7 @@
  * @see docs/agents.md
  */
 /** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
-export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
+export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
 type Env = Readonly<Record<string, string | undefined>>;
 type Git = (args: readonly string[]) => string | null;
 /** What `reportMain` is given besides arguments: where output goes (`out`), and, for tests and embedding, the environment, working directory, git, clock and standard input (`stdin`, where `stream` reads checks from). Defaults are the real ones. */

package/dist/reports/src/report-cli.js

@@ -54,7 +54,8 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
   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.
@@ -211,7 +212,7 @@ function printChecks(out, label, checks) {
 export async function reportMain(argv, io = { out: text => process.stdout.write(text) }) {
     const [command, ...rest] = argv;
     const base = io.cwd ?? process.cwd();
-    const env = io.env ?? process.env;
+    const env = { ...(io.env ?? process.env), ...(value(rest, 'project') !== undefined ? { ATLAS_PROJECT: value(rest, 'project') } : {}) };
     const clock = io.clock ?? Date.now;
     if (command === 'publish') {
         const target = writeStoreOf(value(rest, 'store'), base, env);

package/dist/reports/src/store-url.js

@@ -77,7 +77,7 @@ export function openStore(spec, options) {
         const token = serverToken(env, options.role ?? { id: '', soleServer: true });
         if (token)
             refuseClearToken(location.url, env);
-        const server = httpStore({ url: location.url, ...(token ? { token } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) });
+        const server = httpStore({ url: location.url, ...(env.ATLAS_PROJECT ? { project: env.ATLAS_PROJECT } : {}), ...(token ? { token } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) });
         return { store: server, label: server.label, location, server };
     }
     const s3 = s3Store({

package/dist/runners/src/codecept.d.ts

@@ -0,0 +1,14 @@
+/** @module CodeceptJS reporter
+ * CodeceptJS's Mocha reporter interface carries scenario outcomes and steps to the singleton Atlas server.
+ */
+import AtlasMochaReporter from './mocha.js';
+/**
+ * Use `codeceptjs run --reporter @crvouga/atlas/codecept` with ATLAS_SERVER_URL and ATLAS_PUBLISH_TOKEN.
+ * Upload failures fail the run; skipped scenarios remain not-run.
+ * @example
+ * // codecept.conf.js
+ * export const config = { tests: './tests/*_test.js', reporter: '@crvouga/atlas/codecept' };
+ */
+export default class AtlasCodeceptReporter extends AtlasMochaReporter {
+    constructor(...args: [ConstructorParameters<typeof AtlasMochaReporter>[0], ConstructorParameters<typeof AtlasMochaReporter>[1]?]);
+}

package/dist/runners/src/codecept.js

@@ -0,0 +1,16 @@
+/** @module CodeceptJS reporter
+ * CodeceptJS's Mocha reporter interface carries scenario outcomes and steps to the singleton Atlas server.
+ */
+import AtlasMochaReporter from './mocha.js';
+/**
+ * Use `codeceptjs run --reporter @crvouga/atlas/codecept` with ATLAS_SERVER_URL and ATLAS_PUBLISH_TOKEN.
+ * Upload failures fail the run; skipped scenarios remain not-run.
+ * @example
+ * // codecept.conf.js
+ * export const config = { tests: './tests/*_test.js', reporter: '@crvouga/atlas/codecept' };
+ */
+export default class AtlasCodeceptReporter extends AtlasMochaReporter {
+    constructor(...args) {
+        super(args[0], args[1], 'codeceptjs');
+    }
+}

package/dist/runners/src/jest.d.ts

@@ -0,0 +1,50 @@
+import { type ReporterOptions } from './publish.js';
+type Result = {
+    testFilePath: string;
+    testExecError?: {
+        message?: string;
+        stack?: string;
+    };
+    failureMessage?: string;
+    testResults: {
+        title: string;
+        fullName: string;
+        status: string;
+        duration?: number | null;
+        failureMessages: string[];
+        invocations?: number;
+    }[];
+};
+/**
+ * Jest's native reporter; retain `default` in the reporter list for console output. Upload errors fail Jest.
+ * @example
+ * export default { reporters: ['default', ['@crvouga/atlas/jest', { url: 'https://atlas.example.com' }]] };
+ */
+export default class AtlasJestReporter {
+    private readonly options;
+    private live;
+    private error;
+    constructor(_config: unknown, options?: ReporterOptions);
+    /** Reset publishing errors for each watch-mode invocation. */
+    onRunStart(result?: {
+        numTotalTests?: number;
+    }): void;
+    /** Publish the test as running before its body executes in a worker. */
+    onTestCaseStart(test: {
+        path: string;
+    }, info: {
+        fullName: string;
+        title: string;
+    }): void;
+    /** Stream each test outcome immediately, without waiting for other files to finish. */
+    onTestCaseResult(test: {
+        path: string;
+    }, result: Result['testResults'][number]): void;
+    /** Await uploading every final result, including test-file failures before any test ran. */
+    onRunComplete(_contexts: unknown, result: {
+        testResults: Result[];
+    }): Promise<void>;
+    /** Jest uses this to turn a publishing error into a failed invocation. */
+    getLastError(): Error | undefined;
+}
+export {};

package/dist/runners/src/jest.js

@@ -0,0 +1,52 @@
+import { testFile, runnerLive, finishRunner } from './publish.js';
+/**
+ * Jest's native reporter; retain `default` in the reporter list for console output. Upload errors fail Jest.
+ * @example
+ * export default { reporters: ['default', ['@crvouga/atlas/jest', { url: 'https://atlas.example.com' }]] };
+ */
+export default class AtlasJestReporter {
+    options;
+    live;
+    error;
+    constructor(_config, options = {}) {
+        this.options = options;
+    }
+    /** Reset publishing errors for each watch-mode invocation. */
+    onRunStart(result) { this.error = undefined; this.live = runnerLive('jest', this.options, result?.numTotalTests || undefined); }
+    /** Publish the test as running before its body executes in a worker. */
+    onTestCaseStart(test, info) {
+        this.live ??= runnerLive('jest', this.options);
+        this.live.check({ id: `${testFile(test.path, this.options.rootDir)} > ${info.fullName}`, title: info.title, status: 'running' });
+    }
+    /** Stream each test outcome immediately, without waiting for other files to finish. */
+    onTestCaseResult(test, result) {
+        this.live ??= runnerLive('jest', this.options);
+        this.live.check({ id: `${testFile(test.path, this.options.rootDir)} > ${result.fullName}`, title: result.title,
+            status: result.status === 'passed' ? 'passed' : result.status === 'failed' ? 'failed' : 'not-run', detail: result.failureMessages.join('\n') });
+    }
+    /** Await uploading every final result, including test-file failures before any test ran. */
+    async onRunComplete(_contexts, result) {
+        const checks = [];
+        for (const suite of result.testResults) {
+            const file = testFile(suite.testFilePath, this.options.rootDir);
+            for (const test of suite.testResults)
+                checks.push({ id: `${file} > ${test.fullName}`, title: test.title,
+                    status: test.status === 'passed' ? 'passed' : test.status === 'failed' ? 'failed' : 'not-run',
+                    detail: test.failureMessages.join('\n'), measurements: [],
+                    ...(typeof test.duration === 'number' && Number.isFinite(test.duration) && test.duration >= 0 ? { durationMs: test.duration } : {}),
+                    ...((test.invocations ?? 1) > 1 ? { labels: { retries: String(test.invocations - 1), ...(test.status === 'passed' ? { flaky: 'true' } : {}) } } : {}) });
+            if (suite.testExecError)
+                checks.push({ id: `${file} > [suite error]`, title: `${file}: suite error`, status: 'failed', detail: suite.testExecError.stack ?? suite.testExecError.message ?? suite.failureMessage ?? 'Suite did not execute', measurements: [] });
+        }
+        this.live ??= runnerLive('jest', this.options);
+        checks.forEach(check => this.live.check(check));
+        try {
+            await finishRunner(this.live, 'jest', checks, this.options);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    /** Jest uses this to turn a publishing error into a failed invocation. */
+    getLastError() { return this.error; }
+}

package/dist/runners/src/mocha.d.ts

@@ -0,0 +1,40 @@
+import { type ReporterOptions } from './publish.js';
+type Test = {
+    title: string;
+    file?: string;
+    duration?: number;
+    fullTitle(): string;
+    err?: {
+        stack?: string;
+        message?: string;
+    };
+    steps?: {
+        name?: string;
+        status?: string;
+    }[];
+    currentRetry?(): number;
+};
+type Runner = {
+    total?: number;
+    on(event: string, listener: (test: Test, error?: Error) => void): unknown;
+};
+/**
+ * Mocha reporter; use `--reporter @crvouga/atlas/mocha` or CodeceptJS `--reporter @crvouga/atlas/codecept`.
+ * Reporter options go in `reporterOptions`; environment variables are supported by every runner.
+ * A failed upload adds a runner failure through Mocha's completion callback.
+ * @example
+ * // mocha configuration
+ * export default { reporter: '@crvouga/atlas/mocha', reporterOptions: { url: 'https://atlas.example.com' } };
+ */
+export default class AtlasMochaReporter {
+    private readonly checks;
+    private readonly options;
+    private readonly runnerName;
+    private readonly live;
+    constructor(runner: Runner, options?: {
+        reporterOptions?: ReporterOptions;
+    }, runnerName?: string);
+    /** Mocha waits for this callback before exiting. Publishing errors fail the invocation. */
+    done(failures: number, callback: (failures: number) => void): void;
+}
+export {};