@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/init.js

@@ -0,0 +1,369 @@
+/**
+ * @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');
+    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'))
+        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 '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');
+    }
+}
+/** 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, 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)
+        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;
+    }
+}

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

@@ -1,23 +1,50 @@
 /**
- * Overlay test-runner outcomes (JUnit XML) onto a report bundle. A harness run
- * only sees failures raised inside its own steps; assertions in the test body
- * surface through the runner's report instead.
+ * @module JUnit XML parsing
+ *
+ * Reads the `<testcase>` elements of a JUnit XML document without an XML library, and overlays test-runner
+ * outcomes (JUnit XML) onto a report bundle. A harness run only sees failures raised inside its own steps;
+ * assertions in the test body surface through the runner's report instead. Parsing is tolerant by design
+ * (nested suites, self-closing elements, CDATA) and never drops a case silently, because a result that goes
+ * missing reads as a pass. `ingest.ts` turns the cases into checks.
  */
 import type { HtmlReportBundle } from './recording-bundle.js';
+/** One `<testcase>` as read, with the suite it is in. */
 export type JunitCase = {
+    /** The case's `file` attribute, else its suite's, else empty. */
     readonly file: string;
+    /** The `classname` attribute, which many runners use for the suite or the file. */
+    readonly classname: string;
+    /** The `name` of the `<testsuite>` the case is in. */
+    readonly suite: string;
+    /** Seconds, when the runner emits it. */
+    readonly time: number | null;
     readonly name: string;
     /** 1-based line of the test declaration, when the runner emits it. */
     readonly line: number | null;
+    /** `failed` when the case has a `<failure>` or an `<error>`, `skipped` when it has `<skipped>`, otherwise `passed`. */
     readonly status: 'passed' | 'failed' | 'skipped';
+    /** The failure's text (else its `message`, else `failed`), or null when the case did not fail. */
     readonly failure: string | null;
+    /** The case's `<system-out>`, when it has one. */
+    readonly stdout?: string;
+    /** The case's `<system-err>`, when it has one. */
+    readonly stderr?: string;
+    /** The case's `<properties>`, then its suite's: names a runner chose to record. */
+    readonly properties?: Readonly<Record<string, string>>;
 };
-/** Parse the `<testcase>` elements of a JUnit XML document. */
+/** Parses every `<testcase>` of a JUnit XML document, in document order, whatever the nesting of its suites. Returns `[]` for text with none; never throws. */
 export declare function parseJunit(xml: string): JunitCase[];
 /**
  * The test case whose declaration precedes `sourceLine` in the same file and
- * is the nearest one (bodies follow declarations).
+ * is the nearest one (bodies follow declarations). Files match when equal or when one path ends with the other
+ * (after normalising backslashes). With one case in the file, or no line, the first case in the file is used.
+ * Null when no case is in the file, or none declared at or before the line.
  */
 export declare function matchJunitCase(cases: readonly JunitCase[], sourceFile: string, sourceLine: number | undefined): JunitCase | null;
-/** Apply runner outcomes / titles to every test with a known source file. */
+/**
+ * Applies runner outcomes and titles to every test of a bundle that has a known source file and a matching case:
+ * the test takes the case's name as title, its failure as error (a harness error is kept), and fails if either the
+ * runner or the harness failed. The bundle fails if any test does. Tests without a match are returned unchanged;
+ * the input is not mutated.
+ */
 export declare function applyJunitOutcomes(bundle: HtmlReportBundle, cases: readonly JunitCase[]): HtmlReportBundle;

package/dist/reports/src/junit.js

@@ -1,7 +1,11 @@
 /**
- * Overlay test-runner outcomes (JUnit XML) onto a report bundle. A harness run
- * only sees failures raised inside its own steps; assertions in the test body
- * surface through the runner's report instead.
+ * @module JUnit XML parsing
+ *
+ * Reads the `<testcase>` elements of a JUnit XML document without an XML library, and overlays test-runner
+ * outcomes (JUnit XML) onto a report bundle. A harness run only sees failures raised inside its own steps;
+ * assertions in the test body surface through the runner's report instead. Parsing is tolerant by design
+ * (nested suites, self-closing elements, CDATA) and never drops a case silently, because a result that goes
+ * missing reads as a pass. `ingest.ts` turns the cases into checks.
  */
 const ENTITIES = {
     '&lt;': '<',
@@ -21,24 +25,49 @@ function attr(tag, name) {
     return m === null ? null : decodeXml(m[1] ?? '');
 }
 function failureText(body) {
-    const m = /<failure\b([^>]*)(?:\/>|>([\s\S]*?)<\/failure>)/.exec(body);
+    // `<failure>` is an assertion that did not hold, `<error>` an unexpected exception: both are a check that failed.
+    const m = /<(failure|error)\b([^>]*)(?:\/>|>([\s\S]*?)<\/\1>)/.exec(body);
     if (m === null)
         return null;
-    const message = attr(m[1] ?? '', 'message');
-    const inner = (m[2] ?? '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1');
+    const message = attr(m[2] ?? '', 'message');
+    const inner = (m[3] ?? '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1');
     const text = decodeXml(inner).trim();
     return text.length > 0 ? text : (message ?? 'failed');
 }
-function parseCase(tag, inner, suiteFile) {
+function streamText(body, name) {
+    const found = new RegExp(`<${name}\\b[^>]*>([\\s\\S]*?)</${name}>`).exec(body);
+    if (!found)
+        return undefined;
+    const text = decodeXml((found[1] ?? '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1')).trim();
+    return text.length ? text : undefined;
+}
+function propertiesOf(body) {
+    const out = {};
+    for (const match of body.matchAll(/<property\b([^>]*?)\/?>/g)) {
+        const name = attr(match[1] ?? '', 'name');
+        const value = attr(match[1] ?? '', 'value');
+        if (name)
+            out[name] = value ?? '';
+    }
+    return out;
+}
+function parseCase(tag, inner, suiteFile, suiteName, suiteProperties = {}) {
     const lineRaw = attr(tag, 'line');
     const line = lineRaw === null ? null : Number(lineRaw);
     const failure = failureText(inner);
+    const time = Number(attr(tag, 'time'));
     return {
         file: attr(tag, 'file') ?? suiteFile,
+        classname: attr(tag, 'classname') ?? '',
+        suite: suiteName,
+        time: attr(tag, 'time') !== null && Number.isFinite(time) ? time : null,
         name: attr(tag, 'name') ?? '',
         line: line !== null && Number.isFinite(line) ? line : null,
         status: caseStatus(failure, inner),
         failure,
+        ...(streamText(inner, 'system-out') ? { stdout: streamText(inner, 'system-out') } : {}),
+        ...(streamText(inner, 'system-err') ? { stderr: streamText(inner, 'system-err') } : {}),
+        ...(Object.keys({ ...suiteProperties, ...propertiesOf(inner) }).length ? { properties: { ...suiteProperties, ...propertiesOf(inner) } } : {}),
     };
 }
 function caseStatus(failure, inner) {
@@ -48,22 +77,52 @@ function caseStatus(failure, inner) {
         return 'skipped';
     return 'passed';
 }
-function parseSuite(tag, body, out) {
-    const suiteFile = attr(tag, 'file') ?? '';
-    const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
-    for (let c = caseRe.exec(body); c; c = caseRe.exec(body)) {
-        out.push(parseCase(c[1] ?? '', c[2] ?? '', suiteFile));
-    }
-}
-/** Parse the `<testcase>` elements of a JUnit XML document. */
-export function parseJunit(xml) {
+/**
+ * Every `<testcase>` of the document, whatever the nesting of its suites: a suite inside a suite, a case after
+ * an inner suite, an empty self-closing suite. Each case is read with the suite it is in, and that suite's own
+ * `<properties>`. A case is never skipped silently, because a result that goes missing reads as a pass.
+ */
+function allCases(xml) {
     const cases = [];
-    const suiteRe = /<testsuite\b([^>]*)>([\s\S]*?)<\/testsuite>/g;
-    for (let suite = suiteRe.exec(xml); suite; suite = suiteRe.exec(xml)) {
-        parseSuite(suite[1] ?? '', suite[2] ?? '', cases);
+    const stack = [];
+    const tags = /<(\/?)(testsuite|testcase|properties)\b([^>]*?)(\/?)>/g;
+    for (let tag = tags.exec(xml); tag; tag = tags.exec(xml)) {
+        const [, closing, name, attributes = '', selfClosing] = tag;
+        if (name === 'testsuite') {
+            if (closing) {
+                stack.pop();
+                continue;
+            }
+            const suite = { file: attr(attributes, 'file') ?? '', name: attr(attributes, 'name') ?? '', properties: {} };
+            if (!selfClosing)
+                stack.push(suite);
+        }
+        else if (name === 'testcase' && !closing) {
+            let inner = '';
+            if (!selfClosing) {
+                const end = xml.indexOf('</testcase>', tags.lastIndex);
+                if (end < 0)
+                    continue;
+                inner = xml.slice(tags.lastIndex, end);
+                tags.lastIndex = end + '</testcase>'.length;
+            }
+            const suite = stack.at(-1);
+            cases.push(parseCase(attributes, inner, suite?.file ?? '', suite?.name ?? '', Object.assign({}, ...stack.map(item => item.properties))));
+        }
+        else if (name === 'properties' && !closing && !selfClosing && stack.length) {
+            const end = xml.indexOf('</properties>', tags.lastIndex);
+            if (end < 0)
+                continue;
+            Object.assign(stack.at(-1).properties, propertiesOf(xml.slice(tags.lastIndex, end)));
+            tags.lastIndex = end + '</properties>'.length;
+        }
     }
     return cases;
 }
+/** Parses every `<testcase>` of a JUnit XML document, in document order, whatever the nesting of its suites. Returns `[]` for text with none; never throws. */
+export function parseJunit(xml) {
+    return allCases(xml);
+}
 function sameFile(a, b) {
     const na = a.replace(/\\/g, '/');
     const nb = b.replace(/\\/g, '/');
@@ -71,7 +130,9 @@ function sameFile(a, b) {
 }
 /**
  * The test case whose declaration precedes `sourceLine` in the same file and
- * is the nearest one (bodies follow declarations).
+ * is the nearest one (bodies follow declarations). Files match when equal or when one path ends with the other
+ * (after normalising backslashes). With one case in the file, or no line, the first case in the file is used.
+ * Null when no case is in the file, or none declared at or before the line.
  */
 export function matchJunitCase(cases, sourceFile, sourceLine) {
     const inFile = cases.filter((c) => sameFile(c.file, sourceFile));
@@ -105,7 +166,12 @@ function overlayTest(test, c) {
         },
     };
 }
-/** Apply runner outcomes / titles to every test with a known source file. */
+/**
+ * Applies runner outcomes and titles to every test of a bundle that has a known source file and a matching case:
+ * the test takes the case's name as title, its failure as error (a harness error is kept), and fails if either the
+ * runner or the harness failed. The bundle fails if any test does. Tests without a match are returned unchanged;
+ * the input is not mutated.
+ */
 export function applyJunitOutcomes(bundle, cases) {
     const tests = bundle.tests.map((test) => {
         const { sourceFile, sourceLine } = test.report.meta;

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

@@ -1,16 +1,36 @@
 import type { FlatFrame } from './frames.js';
 import type { Route } from './hash.js';
 import type { ReportData } from './types.js';
+/** What {@link onReportKeyDown} may ask the host to do, and what it reads from it. */
 export type KeyNavHandlers = {
+    /** Opens or closes the shortcut help. */
     toggleHelp: () => void;
+    /** Whether the help is open. */
     showHelp: () => boolean;
+    /** Whether the command palette is open; while it is, no other shortcut acts. */
     showPalette: () => boolean;
     togglePalette: () => void;
+    /** Stops frame playback. */
     stopPlay: () => void;
+    /** Goes to a route (writes the URL hash). */
     navigate: (route: Route) => void;
+    /** Selects a frame, optionally of a given client (`node`). */
     goFrame: (frame: FlatFrame | null, node?: string) => void;
     togglePlay: () => void;
+    /** Sets a URL param on the current route; the empty string removes it. */
     setParam: (key: string, value: string) => void;
+    /** The current route. */
     route: () => Route;
 };
+/**
+ * Handles one `keydown` for the viewer. Keys: Cmd/Ctrl+K palette; `?` help; Escape closes help or the palette,
+ * else stops playback and returns to the list. On a test page: Left/Right/Home/End scrub frames, Space plays,
+ * Up/Down jump between steps, `n`/`N` between failures, `[`/`]` to the previous/next test (keeping the list's
+ * params), `1`-`9` pick a client, and, when the frame has a UI snapshot, `m` single/multi view, `a` aside, `p`
+ * press targets, `f` cycles zoom (fit, 50, 75, 100).
+ *
+ * Cmd/Ctrl+K and Escape-closing-the-palette work anywhere. Every other key is ignored while the palette is open and
+ * while focus is in an input, textarea, select, button, link or editable element; the test-page keys also need the
+ * route to be a test that is in `data`.
+ */
 export declare function onReportKeyDown(e: KeyboardEvent, data: ReportData, h: KeyNavHandlers): void;

package/dist/reports/src/keyboard.js

@@ -85,6 +85,17 @@ function viewKeys(e, ctx) {
             ctx.h.goFrame(ctx.sel, ids[n - 1] ?? '');
     }
 }
+/**
+ * Handles one `keydown` for the viewer. Keys: Cmd/Ctrl+K palette; `?` help; Escape closes help or the palette,
+ * else stops playback and returns to the list. On a test page: Left/Right/Home/End scrub frames, Space plays,
+ * Up/Down jump between steps, `n`/`N` between failures, `[`/`]` to the previous/next test (keeping the list's
+ * params), `1`-`9` pick a client, and, when the frame has a UI snapshot, `m` single/multi view, `a` aside, `p`
+ * press targets, `f` cycles zoom (fit, 50, 75, 100).
+ *
+ * Cmd/Ctrl+K and Escape-closing-the-palette work anywhere. Every other key is ignored while the palette is open and
+ * while focus is in an input, textarea, select, button, link or editable element; the test-page keys also need the
+ * route to be a test that is in `data`.
+ */
 export function onReportKeyDown(e, data, h) {
     if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
         e.preventDefault();