@crvouga/atlas 0.3.0 → 0.5.0

package/dist/reports/src/ingest.js

@@ -0,0 +1,210 @@
+/**
+ * @module Importing checks from existing test reports
+ *
+ * Turns the output of tools that already exist (CTRF JSON, JUnit XML, an Atlas run `manifest.json`) into checks a
+ * layer can hold, so any test suite can publish without a custom producer. It owns the mapping of foreign
+ * statuses onto the four Atlas statuses (anything not clearly passed or failed is `not-run`, never a pass) and the
+ * rule for check ids: stable across runs, built from the file, suite and name, with a repeated id numbered
+ * (`#2`, `#3`) so no check is silently counted as another. It reads text it is given and touches no files.
+ *
+ * @see docs/report-contract.md (choosing a check id)
+ */
+import path from 'node:path';
+import { parseJunit } from './junit.js';
+import { specPath } from './layer-merge.js';
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** Never silently count two checks as one: the first check with an id keeps it and a repeat becomes `<id> #2`, `<id> #3`, ... in input order. */
+export function uniqueChecks(checks) {
+    const seen = new Map();
+    return checks.map(check => {
+        const count = (seen.get(check.id) ?? 0) + 1;
+        seen.set(check.id, count);
+        return count === 1 ? check : { ...check, id: `${check.id} #${count}` };
+    });
+}
+const CTRF_STATUS = { passed: 'passed', failed: 'failed', skipped: 'not-run', pending: 'not-run', other: 'not-run' };
+/**
+ * A [CTRF](https://ctrf.io) report (`results.tests`). A check's id is its file, its suites and its
+ * name, so the same test keeps the same id in every run. Skipped, pending and other results are
+ * `not-run`: never a pass; a status this function does not know is also `not-run`.
+ *
+ * Also carries what CTRF has beyond the outcome as evidence: tags, labels (browser, device, flaky, run environment
+ * and tool), steps, attachments (files by `path`, `url` as `uri`, inline screenshot, stdout/stderr, trace), retry
+ * attempts, a snippet annotation and `extra` under the `ctrf.extra` extension. `recordedAtMs` is `summary.stop`,
+ * else `summary.start`. Throws `Not a CTRF report: results.tests is missing` when there is no `results.tests` array.
+ *
+ * @param report The parsed CTRF JSON.
+ */
+export function checksFromCtrf(report) {
+    const results = record(record(report).results);
+    const tests = Array.isArray(results.tests) ? results.tests : [];
+    if (!Array.isArray(results.tests))
+        throw new Error('Not a CTRF report: results.tests is missing');
+    const checks = tests.map((raw, index) => {
+        const test = record(raw);
+        const suite = Array.isArray(test.suite) ? test.suite.map(text) : text(test.suite) ? [text(test.suite)] : [];
+        const file = text(test.filePath);
+        const name = text(test.name) || `test ${index + 1}`;
+        const status = CTRF_STATUS[text(test.status)] ?? 'not-run';
+        const message = text(test.message) || text(test.trace);
+        const duration = finite(test.duration);
+        const tags = Array.isArray(test.tags) ? test.tags.map(text).filter(Boolean) : [];
+        const labels = {};
+        for (const key of ['browser', 'device', 'type', 'os', 'osPlatform'])
+            if (text(test[key]))
+                labels[key] = text(test[key]);
+        if (test.flaky === true)
+            labels.flaky = 'true';
+        const steps = Array.isArray(test.steps) ? test.steps.map(step => { const item = record(step); return { name: text(item.name) || 'step', ...(text(item.status) ? { status: text(item.status) } : {}) }; }) : [];
+        const attachments = [
+            ...(Array.isArray(test.attachments) ? test.attachments.flatMap(raw => { const item = record(raw); return text(item.name) || text(item.path) ? [{ name: text(item.name) || path.basename(text(item.path)), ...(text(item.contentType) ? { contentType: text(item.contentType) } : {}), ...(text(item.path) ? { path: text(item.path) } : {}), ...(text(item.url) ? { uri: text(item.url) } : {}) }] : []; }) : []),
+            ...(text(test.screenshot) ? [{ name: 'screenshot.png', role: 'screenshot', contentType: 'image/png', base64: text(test.screenshot) }] : []),
+            ...logOf(test.stdout, 'stdout'),
+            ...logOf(test.stderr, 'stderr'),
+            ...(text(test.trace) ? [{ name: 'stack trace', role: 'log', contentType: 'text/plain', text: text(test.trace) }] : [])
+        ];
+        const attempts = Array.isArray(test.retryAttempts) ? test.retryAttempts.map((raw, at) => { const item = record(raw); return { index: finite(item.attempt) !== null ? Math.max(0, finite(item.attempt) - 1) : at, status: (CTRF_STATUS[text(item.status)] ?? 'not-run'), ...(finite(item.duration) !== null ? { durationMs: finite(item.duration) } : {}), ...(text(item.message) ? { detail: text(item.message) } : {}) }; }) : [];
+        const annotations = text(test.snippet) ? [{ type: 'snippet', message: text(test.snippet), level: 'info', ...(file ? { source: { file, ...(finite(test.line) !== null ? { line: finite(test.line) } : {}) } } : {}) }] : [];
+        const extra = record(test.extra);
+        return {
+            id: [file, ...suite, name].filter(Boolean).join(' > '),
+            title: name,
+            status,
+            detail: status === 'failed' ? (message || 'failed') : test.flaky === true ? 'Passed on retry (flaky)' : message,
+            ...(file ? { specPath: specPath(file) } : {}),
+            measurements: [],
+            ...(duration === null ? {} : { durationMs: duration }),
+            ...(tags.length ? { tags } : {}),
+            ...(Object.keys(labels).length ? { labels } : {}),
+            ...(steps.length ? { steps } : {}),
+            ...(attachments.length ? { attachments } : {}),
+            ...(attempts.length ? { attempts } : {}),
+            ...(annotations.length ? { annotations } : {}),
+            ...(Object.keys(extra).length ? { extensions: { 'ctrf.extra': extra } } : {})
+        };
+    });
+    const summary = record(results.summary);
+    const hints = tests.map(raw => {
+        const test = record(raw);
+        return [...(Array.isArray(test.suite) ? test.suite.map(text) : [text(test.suite)]), text(test.filePath)].filter(Boolean);
+    });
+    const tool = record(results.tool);
+    const labels = {};
+    for (const [key, value] of Object.entries(record(results.environment)))
+        if (typeof value === 'string' || typeof value === 'number')
+            labels[key] = String(value);
+    if (text(tool.name))
+        labels.tool = text(tool.name);
+    if (text(tool.version))
+        labels['tool.version'] = text(tool.version);
+    return { checks: uniqueChecks(checks), hints, recordedAtMs: finite(summary.stop) ?? finite(summary.start), tool: text(tool.name) || null, ...(Object.keys(labels).length ? { labels } : {}) };
+}
+/** CTRF writes a stream as a list of lines. */
+function logOf(value, name) {
+    const lines = Array.isArray(value) ? value.map(text).join('\n') : text(value);
+    return lines.trim() ? [{ name, role: 'log', contentType: 'text/plain', text: lines }] : [];
+}
+/** Many JUnit writers omit the offset. Read such a time as UTC, so it is the same wherever Atlas runs. */
+function parseTimestamp(value) {
+    return Date.parse(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/.test(value) ? `${value}Z` : value);
+}
+/**
+ * A JUnit XML report: one check per `<testcase>`, identified by its file or class and its name (`file or classname > name`).
+ *
+ * A case with a `<failure>` (an assertion that did not hold) or an `<error>` (an exception) is `failed`, one with
+ * `<skipped>` is `not-run`, any other is `passed`. Durations are seconds converted to milliseconds. Properties become labels, `<system-out>`/`<system-err>` become log
+ * attachments, and a Jenkins `[[ATTACHMENT|path]]` line in the output attaches that file by `path`. `recordedAtMs`
+ * is the newest `<testsuite timestamp>` (a timestamp with no offset is read as UTC). Throws
+ * `Not a JUnit report: no <testsuite> found` when the text has no test cases and no `<testsuite`.
+ */
+export function checksFromJunit(xml) {
+    const cases = parseJunit(xml);
+    if (cases.length === 0 && !/<testsuite/.test(xml))
+        throw new Error('Not a JUnit report: no <testsuite> found');
+    const checks = cases.map((item) => {
+        const where = item.file || item.classname;
+        // Jenkins' convention: a line `[[ATTACHMENT|/path/to/file]]` in a test's output attaches that file.
+        const jenkins = [...`${item.stdout ?? ''}\n${item.stderr ?? ''}`.matchAll(/\[\[ATTACHMENT\|([^\]]+)\]\]/g)].map(match => ({ name: path.basename(match[1]), path: match[1] }));
+        const attachments = [
+            ...(item.stdout ? [{ name: 'stdout', role: 'log', contentType: 'text/plain', text: item.stdout }] : []),
+            ...(item.stderr ? [{ name: 'stderr', role: 'log', contentType: 'text/plain', text: item.stderr }] : []),
+            ...jenkins
+        ];
+        return {
+            id: [where, item.name].filter(Boolean).join(' > '),
+            title: item.name,
+            status: item.status === 'passed' ? 'passed' : item.status === 'failed' ? 'failed' : 'not-run',
+            detail: item.failure ?? '',
+            ...(item.file ? { specPath: specPath(item.file) } : {}),
+            measurements: [],
+            ...(item.time === null ? {} : { durationMs: Math.round(item.time * 1000) }),
+            ...(item.properties ? { labels: item.properties } : {}),
+            ...(attachments.length ? { attachments } : {})
+        };
+    });
+    const hints = cases.map(item => [item.classname, item.suite, item.file].filter(Boolean));
+    const stamps = [...xml.matchAll(/<testsuite\b[^>]*\stimestamp="([^"]+)"/g)].map(match => parseTimestamp(match[1])).filter(Number.isFinite);
+    return { checks: uniqueChecks(checks), hints, recordedAtMs: stamps.length ? Math.max(...stamps) : null, tool: null };
+}
+/**
+ * An Atlas run (`manifest.json`): one check per path. A path's key, which the same start and
+ * events give in every run, is its id. A flaky path passed. While the run is still going, a
+ * running path is `running` and a queued one `not-run`, so a snapshot never reads as finished.
+ *
+ * Every check's `specPath` is the run's root chart file under its spec directory. A run is still going when
+ * `run.finishedAt` is `null`. `recordedAtMs` is `run.finishedAt`, else `run.startedAt` plus `run.durationMs`.
+ * Throws `Not an Atlas manifest: run and paths are required` when `paths` or `run.id` is missing.
+ *
+ * @param manifest The parsed `manifest.json` of an Atlas run.
+ */
+export function checksFromManifest(manifest) {
+    const root = record(manifest);
+    const run = record(root.run);
+    if (!Array.isArray(root.paths) || !run.id)
+        throw new Error('Not an Atlas manifest: run and paths are required');
+    const charts = Array.isArray(root.charts) ? root.charts.map(record) : [];
+    const chart = charts.find(item => item.parentState == null) ?? charts[0];
+    const directory = text(run.specDirectory).replace(/\/+$/, '');
+    const file = text(chart?.file);
+    const path = file ? specPath(directory ? `${directory}/${file}` : file) : null;
+    const live = run.finishedAt === null;
+    const checks = root.paths.map((raw) => {
+        const item = record(raw);
+        const status = text(item.status);
+        const attempts = Array.isArray(item.attempts) ? item.attempts.map(record) : [];
+        const progress = text(item.progress);
+        const mapped = live && progress === 'running' ? 'running' : live && progress === 'queued' ? 'not-run' : status === 'passed' || status === 'flaky' ? 'passed' : status === 'failed' ? 'failed' : 'not-run';
+        const duration = finite(item.durationMs);
+        const steps = Array.isArray(item.steps) ? item.steps.map(raw => {
+            const step = record(raw);
+            const state = text(step.status);
+            return { name: text(step.event) || 'step', kind: 'event', status: state === 'passed' || state === 'flaky' ? 'passed' : state === 'failed' ? 'failed' : 'not-reached', ...(text(step.reason) ? { detail: text(step.reason) } : {}), ...(text(step.transition) ? { extensions: { 'atlas.transition': text(step.transition) } } : {}) };
+        }) : [];
+        const journeys = Array.isArray(item.journeys) ? item.journeys.map(text).filter(Boolean) : [];
+        return {
+            id: text(item.key) || `${text(item.kind)}: ${text(item.name)}`,
+            title: text(item.name) || text(item.id),
+            status: mapped,
+            detail: mapped === 'failed' ? text(attempts.at(-1)?.error) || 'failed' : status === 'flaky' ? 'Passed on retry (flaky)' : '',
+            ...(path ? { specPath: path } : {}),
+            measurements: [],
+            ...(duration === null ? {} : { durationMs: duration }),
+            ...(steps.length ? { steps } : {}),
+            ...(text(item.kind) ? { labels: { kind: text(item.kind), ...(text(item.seed) ? { seed: text(item.seed) } : {}) } } : {}),
+            ...(journeys.length ? { tags: journeys } : {})
+        };
+    });
+    const startedAt = Date.parse(text(run.startedAt));
+    const finishedAt = Date.parse(text(run.finishedAt));
+    const duration = finite(run.durationMs) ?? 0;
+    const at = Number.isFinite(finishedAt) ? finishedAt : Number.isFinite(startedAt) ? startedAt + duration : null;
+    return { checks: uniqueChecks(checks), recordedAtMs: at, tool: 'atlas' };
+}

package/dist/reports/src/init.d.ts

@@ -0,0 +1,40 @@
+import { InitPlanSchema } from '../../schema/src/cli-results.js';
+import type { z } from 'zod/v4';
+/** The document `atlas init` prints, and what {@link planInit} returns. */
+export type InitPlan = z.infer<typeof InitPlanSchema>;
+/** What `planInit` is told: where the project is, which server, and what to do with the plan. */
+export type InitOptions = {
+    /** The project directory. Default: the current directory. */
+    readonly directory: string;
+    /** The Atlas server clients will send results to (`https://atlas.example.com`). Falls back to `ATLAS_STORE` when that is a server. */
+    readonly server?: string;
+    /** Write the files of the plan. Without it nothing is changed. */
+    readonly write?: boolean;
+    /** Ask the server who we are and whether this token may upload. */
+    readonly verify?: boolean;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** For tests: git as a function from arguments to output (or null). Default: the `git` command. */
+    readonly git?: (args: readonly string[], cwd: string) => string | null;
+    readonly fetch?: typeof fetch;
+};
+/**
+ * Detects the project in `options.directory` and returns the plan, writing its files when `options.write` is set.
+ * Never throws for a project it cannot understand: it says so in `warnings` and plans what it can (the `AGENTS.md`
+ * section with no suites, so the next agent knows to add them). Throws only for a directory that does not exist.
+ *
+ * @example
+ * const plan = await planInit({ directory: process.cwd(), server: 'https://atlas.example.com' });
+ * for (const suite of plan.suites) console.log(suite.run, '→', suite.publish);
+ */
+export declare function planInit(options: InitOptions): Promise<InitPlan>;
+/** The plan as the text a person reads: what was found, what is planned, and what to do next. */
+export declare function formatPlan(plan: InitPlan): string;
+/** The usage of `atlas init`, printed by `atlas init --help`. */
+export declare const INIT_USAGE = "atlas init \u2014 integrate a project with an Atlas server\n\n  atlas init [--dir <project>] [--server <url>] [--write] [--verify] [--format json]\n\n  Looks at the project (package manager, test runners, spec files, CI) and prints a plan: for each suite the command\n  that runs it and the command that sends its results, a CI workflow, and an AGENTS.md section that tells the next\n  agent how to use Atlas here. Nothing is changed until --write; running it again changes nothing more.\n\n  --dir <path>     the project (default: the current directory)\n  --server <url>   the Atlas server results go to (default: an http(s) store in ATLAS_STORE)\n  --write          create or update the files of the plan (AGENTS.md between its atlas markers, .github/workflows/atlas.yml)\n  --verify         ask the server who this token is and whether it may upload (token: ATLAS_TOKEN)\n  --format json    print the plan as one JSON document (schema: init-plan.schema.json)\n\n  Exit codes: 0 planned (and verified), 1 --verify failed, 2 the command was wrong.\n";
+/** `atlas init`: parses the arguments, plans, prints the plan as text or JSON, and returns the exit code. */
+export declare function initMain(argv: readonly string[], io: {
+    readonly out: (text: string) => void;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly cwd?: string;
+    readonly fetch?: typeof fetch;
+}): Promise<number>;

package/dist/reports/src/init.js

@@ -0,0 +1,364 @@
+/**
+ * @module Project detection and `atlas init`
+ *
+ * Looks at a project (its package manager, test runners, spec files, CI and git state) and produces a plan to send its
+ * test results to an Atlas server: for each suite the command that runs it and the command that publishes (or streams)
+ * its results, a CI workflow, and a section of `AGENTS.md` that tells the next agent how to use Atlas in this project.
+ * It changes nothing unless asked (`--write`), and applying it twice changes nothing the second time: files are
+ * rewritten only between their `atlas:begin` / `atlas:end` markers (or created whole), never merged by guesswork.
+ *
+ * The plan is one JSON document (`InitPlanSchema`) so an agent can run `atlas init --format json`, read it, and act. See
+ * docs/agents.md for the whole flow. Detection is deliberately conservative: it names what it found and why
+ * (`evidence`), says what it could not tell, and never invents a suite.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+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';
+const BEGIN = '<!-- atlas:begin -->';
+const END = '<!-- atlas:end -->';
+function defaultGit(args, cwd) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** The package manager a project uses, from its lockfile (or `packageManager` in package.json). */
+function packageManagerOf(directory, pkg) {
+    if (existsSync(path.join(directory, 'bun.lock')) || existsSync(path.join(directory, 'bun.lockb')))
+        return 'bun';
+    if (existsSync(path.join(directory, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(path.join(directory, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(path.join(directory, 'package-lock.json')))
+        return 'npm';
+    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'];
+    let best = null;
+    for (const candidate of candidates) {
+        const full = path.join(directory, candidate);
+        if (!existsSync(full) || !statSync(full).isDirectory())
+            continue;
+        const files = await collectSpecFiles(full).catch(() => []);
+        const kinds = {};
+        // Prose and data files are specs only because they sit in a specs folder: count the notations that mean something.
+        for (const file of files) {
+            const kind = specKindOf(file.path);
+            if (['gherkin', 'quint', 'dmn', 'alloy', 'openslo', 'scxml'].includes(kind))
+                kinds[kind] = (kinds[kind] ?? 0) + 1;
+        }
+        const total = Object.values(kinds).reduce((sum, count) => sum + count, 0);
+        if (total > (best?.total ?? 0))
+            best = { dir: candidate, kinds, total };
+    }
+    return best ? { directory: best.dir, kinds: best.kinds } : { directory: null, kinds: {} };
+}
+/** The test runners a project declares, with where each was seen. Order: the more specific first. */
+function runnersOf(directory, pkg) {
+    const found = [];
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    const scripts = Object.values(pkg?.scripts ?? {}).join('\n');
+    const dep = (name, runner) => { if (deps[name])
+        found.push({ runner, evidence: `package.json dependencies: ${name}` }); };
+    dep('vitest', 'vitest');
+    dep('@playwright/test', 'playwright');
+    dep('@cucumber/cucumber', 'cucumber');
+    dep('cypress', 'cypress');
+    dep('jest', 'jest');
+    dep('mocha', 'mocha');
+    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'))
+        found.push({ runner: 'bun-test', evidence: 'bun.lock and test files' });
+    const python = ['pyproject.toml', 'pytest.ini', 'tox.ini', 'setup.cfg', 'requirements.txt', 'requirements-dev.txt'].map(name => path.join(directory, name)).filter(existsSync);
+    for (const file of python)
+        if (/pytest/.test(readFileSync(file, 'utf8'))) {
+            found.push({ runner: 'pytest', evidence: `${path.basename(file)} mentions pytest` });
+            break;
+        }
+    if (existsSync(path.join(directory, 'go.mod')))
+        found.push({ runner: 'go-test', evidence: 'go.mod' });
+    if (existsSync(path.join(directory, 'atlas.config.ts')) || existsSync(path.join(directory, 'atlas.config.js')))
+        found.push({ runner: 'atlas-statecharts', evidence: 'atlas.config.ts' });
+    return found;
+}
+function readdirSafe(directory) {
+    try {
+        return readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+}
+/** 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 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
+    });
+    const out = (id) => `atlas-${id}.xml`;
+    switch (detected.runner) {
+        case 'vitest': return make('vitest', out('vitest'), `${context.exec} vitest run --reporter=default --reporter=junit --outputFile.junit=${out('vitest')}`, null);
+        case 'jest': return make('jest', out('jest'), `JEST_JUNIT_OUTPUT_FILE=${out('jest')} ${context.exec} jest --reporters=default --reporters=jest-junit`, null, [`${context.install} jest-junit`]);
+        case 'playwright': return make('playwright', out('playwright'), `PLAYWRIGHT_JUNIT_OUTPUT_NAME=${out('playwright')} ${context.exec} playwright test --reporter=list,junit`, 'desktop-web');
+        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 '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');
+    }
+}
+/** A suite that does not set its own exit-code handling must still publish: a failure is evidence. */
+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 jobs = suites.map(suite => `  ${suite.id.replace(/[^a-z0-9]+/g, '-')}:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setup}      # A failing suite must still publish: a failure is evidence. The job's own result is the gate's, below.
+      - run: ${suite.run}
+        continue-on-error: true
+      - run: ${suite.publish}
+        if: always()
+`).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.
+name: atlas
+on: [push, pull_request]
+permissions:
+  contents: read
+env:
+  ATLAS_STORE: \${{ vars.ATLAS_URL }}
+  ATLAS_TOKEN: \${{ secrets.ATLAS_PUBLISH_TOKEN }}
+jobs:
+${jobs}
+  gate:
+    needs: [${suites.map(suite => suite.id.replace(/[^a-z0-9]+/g, '-')).join(', ')}]
+    if: always()
+    runs-on: ubuntu-latest
+    env:
+      ATLAS_TOKEN: \${{ secrets.ATLAS_READ_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      # 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' : ''}
+`;
+}
+/** The `AGENTS.md` section: what Atlas is in this project and the commands to use, replaced between its markers. */
+function agentsSection(plan) {
+    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).`,
+        '',
+        '- **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\`.`,
+        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',
+        END
+    ];
+    return `${lines.join('\n')}\n`;
+}
+/** The new text of a file that holds a marked section: the section replaced in place, or appended, or the file created. */
+function withSection(current, section) {
+    if (current === null)
+        return section;
+    const start = current.indexOf(BEGIN);
+    const end = current.indexOf(END);
+    if (start >= 0 && end > start)
+        return `${current.slice(0, start)}${section.trimEnd()}${current.slice(end + END.length)}`;
+    return `${current.trimEnd()}\n\n${section}`;
+}
+/**
+ * Detects the project in `options.directory` and returns the plan, writing its files when `options.write` is set.
+ * Never throws for a project it cannot understand: it says so in `warnings` and plans what it can (the `AGENTS.md`
+ * section with no suites, so the next agent knows to add them). Throws only for a directory that does not exist.
+ *
+ * @example
+ * const plan = await planInit({ directory: process.cwd(), server: 'https://atlas.example.com' });
+ * for (const suite of plan.suites) console.log(suite.run, '→', suite.publish);
+ */
+export async function planInit(options) {
+    const directory = path.resolve(options.directory);
+    if (!existsSync(directory) || !statSync(directory).isDirectory())
+        throw new Error(`Not a directory: ${options.directory}`);
+    const env = options.env ?? {};
+    const git = options.git ?? defaultGit;
+    const pkg = readJson(path.join(directory, 'package.json'));
+    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 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>`.');
+    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)
+        warnings.push('No spec files (Gherkin, Quint, DMN, Alloy, OpenSLO, SCXML) were found in specs/, features/ or the usual places. Results are still reported; they belong to no spec until `--specs <dir>` or `--spec <path>` links them.');
+    if (existsSync(path.join(directory, 'atlas.config.ts')) && suites.some(suite => suite.runner === 'atlas-statecharts'))
+        warnings.push('atlas.config.ts found: the statechart suite runs the whole plan (`atlas run --mode fast`); see docs/statecharts.md to choose modes and shards.');
+    const branch = git(['branch', '--show-current'], directory);
+    const remoteHead = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], directory)?.replace(/^origin\//, '') ?? null;
+    const defaultBranch = remoteHead ?? (git(['rev-parse', '--verify', 'main'], directory) ? 'main' : git(['rev-parse', '--verify', 'master'], directory) ? 'master' : 'main');
+    const ci = existsSync(path.join(directory, '.github')) || /github\.com/.test(git(['remote', 'get-url', 'origin'], directory) ?? '') ? 'github-actions' : existsSync(path.join(directory, '.gitlab-ci.yml')) ? 'gitlab-ci' : existsSync(path.join(directory, '.circleci')) ? 'circleci' : 'none';
+    if (ci === 'gitlab-ci' || ci === 'circleci')
+        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)) }
+    ];
+    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 }) });
+    const files = [];
+    for (const item of wanted) {
+        const full = path.join(directory, item.path);
+        const current = existsSync(full) ? await readFile(full, 'utf8') : null;
+        const content = item.next(current);
+        // A workflow that exists and was not generated by this tool is the project's own: never overwritten.
+        const foreign = item.path.startsWith('.github/') && current !== null && !current.startsWith('# Sends every suite');
+        if (foreign) {
+            warnings.push(`${item.path} already exists and was not generated by atlas init; left alone. The generated version is in this plan's files.`);
+            files.push({ path: item.path, action: 'unchanged', purpose: item.purpose, content });
+            continue;
+        }
+        files.push({ path: item.path, action: current === null ? 'create' : current === content ? 'unchanged' : 'update', purpose: item.purpose, content });
+    }
+    const written = [];
+    if (options.write) {
+        for (const file of files) {
+            if (file.action === 'unchanged')
+                continue;
+            await mkdir(path.dirname(path.join(directory, file.path)), { recursive: true });
+            await writeFile(path.join(directory, file.path), file.content);
+            written.push(file.path);
+        }
+    }
+    let verification = null;
+    if (options.verify && serverUrl) {
+        const token = serverToken(env);
+        const answer = await httpStore({ url: serverUrl, ...(token ? { token } : {}), retries: 1, ...(options.fetch ? { fetch: options.fetch } : {}) }).ping();
+        verification = { reachable: answer.ok || /\b(401|403)\b|wants a token|may not do that/.test(answer.error ?? ''), role: answer.role ?? null, canPublish: answer.role === 'publish' || answer.role === 'admin', error: answer.ok ? null : (answer.error ?? 'no answer') };
+        if (answer.ok && !verification.canPublish)
+            verification = { ...verification, error: `This token's role is "${answer.role}": it can look but not upload. Use a publish token for sending results.` };
+    }
+    else if (options.verify)
+        warnings.push('--verify needs a server: pass --server or set ATLAS_STORE.');
+    const nextSteps = [
+        ...(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.'] : []),
+        ...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;
+    return InitPlanSchema.parse({ ok, directory, project: { name: typeof pkg?.name === 'string' ? pkg.name : path.basename(directory), packageManager: manager, languages: languagesOf(directory, pkg) }, git: base.git, ci, server: base.server, specs, suites, files, written, verification, nextSteps, warnings });
+}
+function languagesOf(directory, pkg) {
+    const languages = [];
+    if (pkg)
+        languages.push(existsSync(path.join(directory, 'tsconfig.json')) ? 'typescript' : 'javascript');
+    if (['pyproject.toml', 'requirements.txt', 'setup.py'].some(name => existsSync(path.join(directory, name))))
+        languages.push('python');
+    if (existsSync(path.join(directory, 'go.mod')))
+        languages.push('go');
+    return languages;
+}
+/** The plan as the text a person reads: what was found, what is planned, and what to do next. */
+export function formatPlan(plan) {
+    const lines = [`Project ${plan.project.name ?? plan.directory}${plan.project.packageManager ? ` (${plan.project.packageManager})` : ''}, CI: ${plan.ci}, server: ${plan.server.url ?? 'not given'}`];
+    lines.push(plan.suites.length ? 'Suites:' : 'Suites: none recognised');
+    for (const suite of plan.suites)
+        lines.push(`  ${suite.id}  (${suite.evidence})`, `    run:     ${suite.run}`, `    publish: ${suite.publish}`);
+    lines.push(plan.specs.directory ? `Specs: ${plan.specs.directory}/ (${Object.entries(plan.specs.kinds).map(([kind, count]) => `${count} ${kind}`).join(', ')})` : 'Specs: none found');
+    lines.push('Files:');
+    for (const file of plan.files)
+        lines.push(`  ${plan.written.includes(file.path) ? 'wrote ' : file.action.padEnd(9)} ${file.path}  ${file.action === 'unchanged' ? '' : `- ${file.purpose}`}`);
+    if (plan.verification)
+        lines.push(`Server: ${plan.verification.reachable ? 'reachable' : 'NOT reachable'}${plan.verification.role ? `, token role ${plan.verification.role}` : ''}${plan.verification.error ? ` — ${plan.verification.error}` : ''}`);
+    for (const warning of plan.warnings)
+        lines.push(`! ${warning}`);
+    lines.push('Next:');
+    plan.nextSteps.forEach((step, i) => lines.push(`  ${i + 1}. ${step}`));
+    return `${lines.join('\n')}\n`;
+}
+/** The usage of `atlas init`, printed by `atlas init --help`. */
+export const INIT_USAGE = `atlas init — integrate a project with an Atlas server
+
+  atlas init [--dir <project>] [--server <url>] [--write] [--verify] [--format json]
+
+  Looks at the project (package manager, test runners, spec files, CI) and prints a plan: for each suite the command
+  that runs it and the command that sends its results, a CI workflow, and an AGENTS.md section that tells the next
+  agent how to use Atlas here. Nothing is changed until --write; running it again changes nothing more.
+
+  --dir <path>     the project (default: the current directory)
+  --server <url>   the Atlas server results go to (default: an http(s) store in ATLAS_STORE)
+  --write          create or update the files of the plan (AGENTS.md between its atlas markers, .github/workflows/atlas.yml)
+  --verify         ask the server who this token is and whether it may upload (token: ATLAS_TOKEN)
+  --format json    print the plan as one JSON document (schema: init-plan.schema.json)
+
+  Exit codes: 0 planned (and verified), 1 --verify failed, 2 the command was wrong.
+`;
+/** `atlas init`: parses the arguments, plans, prints the plan as text or JSON, and returns the exit code. */
+export async function initMain(argv, io) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        io.out(INIT_USAGE);
+        return 0;
+    }
+    const flag = (name) => { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : undefined; };
+    const format = flag('format');
+    const json = format === 'json' || argv.includes('--json');
+    try {
+        if (format !== undefined && format !== 'json' && format !== 'text')
+            throw new Error(`--format takes text|json (got "${format}")`);
+        const plan = await planInit({ directory: path.resolve(io.cwd ?? process.cwd(), flag('dir') ?? '.'), ...(flag('server') ? { server: flag('server') } : {}), write: argv.includes('--write'), verify: argv.includes('--verify'), env: io.env ?? process.env, ...(io.fetch ? { fetch: io.fetch } : {}) });
+        io.out(json ? `${JSON.stringify(plan, null, 2)}\n` : formatPlan(plan));
+        return plan.ok ? 0 : 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(json ? `${JSON.stringify({ ok: false, error: { message, code: 'usage' } })}\n` : `atlas init: ${message}\n`);
+        return 2;
+    }
+}