@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/http-store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module Atlas server as an ObjectStore
+ *
+ * `httpStore` speaks the server's store protocol (`/api/store`) as an `ObjectStore`, so everything that publishes to a store
+ * (`publishChecks`, spec sets, run uploads, `copyStore`, `createReporter`) publishes to a server unchanged. It retries what a
+ * retry can fix (network errors, 5xx, 429, 408) with jittered backoff, never what it cannot (401, 403, 409, 413, 422), and
+ * every refusal says what to do about it.
+ *
+ * @see docs/server.md#the-store-protocol
+ */
+import type { ObjectStore, PagedListing } from './object-store.js';
+/** How to reach a server: its `url`, the `token` to send (never in the URL), and, for tests and special runtimes, `fetch`, the retry count, the per-attempt timeout and `sleep`. */
+export type HttpStoreOptions = {
+    /** Project namespace on a shared Atlas node. Omit for the legacy default project. */
+    readonly project?: string;
+    /** The Atlas server, such as `https://atlas.example.com`. A path on it (`/atlas`) is kept. */
+    readonly url: string;
+    /** A publish or admin token to write with, a read token to read with. Never put it in the URL. */
+    readonly token?: string;
+    readonly fetch?: typeof fetch;
+    /** Retries after the first attempt, for network errors and server errors. Default 4. */
+    readonly retries?: number;
+    /** Per attempt, to start answering, in milliseconds. Default 30 000. */
+    readonly timeoutMs?: number;
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+/** What an Atlas server said no to, with what to do about it. */
+export declare class AtlasHttpError extends Error {
+    readonly status: number | null;
+    readonly retryable: boolean;
+    constructor(message: string, status: number | null, retryable?: boolean);
+}
+/** An `ObjectStore` (with paged listing) over an Atlas server, plus what only a server can answer: `ping` (is it there, and what may this token do) and `status` (the gate, worked out by the server). */
+export type HttpStore = ObjectStore & PagedListing & {
+    /** The same authenticated node connection, scoped to another project. */
+    forProject(project: string): HttpStore;
+    /** `https://atlas.example.com`, with no secrets. */
+    readonly label: string;
+    readonly url: string;
+    /** Is the server there, and does it know this token? */
+    ping(): Promise<{
+        readonly ok: boolean;
+        readonly ms: number;
+        readonly role?: string;
+        readonly error?: string;
+    }>;
+    /** The gate, worked out by the server from the layers it holds: the `atlas report status --format json` document. Needs a token that may read. */
+    status(query?: URLSearchParams): Promise<unknown>;
+};
+/**
+ * An {@link ObjectStore} on an Atlas server, over its store protocol (`/api/store`). The server holds the
+ * layers (on its own disk, or in whatever backends it was given), checks what is uploaded, and shows
+ * everyone the combined report at once. Anything that publishes to a store, `publishChecks`, spec sets,
+ * run uploads, `copyStore`, works against it unchanged.
+ */
+export declare function httpStore(options: HttpStoreOptions): HttpStore;

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

@@ -0,0 +1,148 @@
+/**
+ * @module Atlas server as an ObjectStore
+ *
+ * `httpStore` speaks the server's store protocol (`/api/store`) as an `ObjectStore`, so everything that publishes to a store
+ * (`publishChecks`, spec sets, run uploads, `copyStore`, `createReporter`) publishes to a server unchanged. It retries what a
+ * retry can fix (network errors, 5xx, 429, 408) with jittered backoff, never what it cannot (401, 403, 409, 413, 422), and
+ * every refusal says what to do about it.
+ *
+ * @see docs/server.md#the-store-protocol
+ */
+import { ObjectStoreWithPrefix } from './store-prefix.js';
+import { ProjectSlugSchema } from '../../schema/src/project.js';
+/** What an Atlas server said no to, with what to do about it. */
+export class AtlasHttpError extends Error {
+    status;
+    retryable;
+    constructor(message, status, retryable = false) {
+        super(message);
+        this.status = status;
+        this.retryable = retryable;
+        this.name = 'AtlasHttpError';
+    }
+}
+const encode = (key) => key.split('/').map(encodeURIComponent).join('/');
+function explain(status, base, message) {
+    const said = message ? `: ${message}` : '';
+    switch (status) {
+        case 401: return `${base} wants a token${said}. Set ATLAS_TOKEN (a publish token to upload, a read token to read).`;
+        case 403: return `${base} knows this token but it may not do that${said}. Uploading needs a publish or admin token.`;
+        case 409: return `${base} refused a change to something that already exists${said}`;
+        case 413: return `${base} refused an object that large${said}. Attach big files by uri, or raise the server's limits.maxObjectMiB.`;
+        case 422: return `${base} did not accept it${said}`;
+        default: return `${base} answered ${status}${said}`;
+    }
+}
+/**
+ * An {@link ObjectStore} on an Atlas server, over its store protocol (`/api/store`). The server holds the
+ * layers (on its own disk, or in whatever backends it was given), checks what is uploaded, and shows
+ * everyone the combined report at once. Anything that publishes to a store, `publishChecks`, spec sets,
+ * run uploads, `copyStore`, works against it unchanged.
+ */
+export function httpStore(options) {
+    const base = options.url.replace(/\/+$/, '');
+    const api = options.project ? `${base}/api/projects/${ProjectSlugSchema.parse(options.project)}` : `${base}/api`;
+    const root = `${api}/store`;
+    const doFetch = options.fetch ?? fetch;
+    const retries = options.retries ?? 4;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const authorization = options.token ? { authorization: `Bearer ${options.token}` } : {};
+    async function request(method, url, init = {}) {
+        for (let attempt = 0;; attempt++) {
+            let failure;
+            try {
+                // The clock is for the server to start answering; a large body may take longer to arrive.
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), timeoutMs);
+                let response;
+                try {
+                    response = await doFetch(url, { method, headers: init.contentType ? { ...authorization, 'content-type': init.contentType } : authorization, ...(init.body ? { body: init.body } : {}), signal: controller.signal });
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+                if (response.ok)
+                    return response;
+                if (response.status === 404 && init.allow404) {
+                    await response.body?.cancel();
+                    return null;
+                }
+                const said = await response.json().then((body) => body && typeof body === 'object' && 'error' in body && typeof body.error === 'string' ? body.error : null, () => null);
+                failure = new AtlasHttpError(explain(response.status, base, said), response.status, response.status >= 500 || response.status === 429 || response.status === 408);
+            }
+            catch (error) {
+                failure = new AtlasHttpError(`cannot reach ${base} (${error instanceof Error ? (error.name === 'AbortError' ? `no answer in ${timeoutMs} ms` : error.message) : String(error)})`, null, true);
+            }
+            if (!failure.retryable || attempt >= retries)
+                throw failure;
+            await sleep(Math.random() * Math.min(8_000, 100 * 2 ** attempt));
+        }
+    }
+    const store = {
+        forProject: project => httpStore({ ...options, project }),
+        label: base,
+        url: base,
+        async get(key) {
+            const response = await request('GET', `${root}/${encode(key)}`, { allow404: true });
+            if (!response)
+                return null;
+            return { body: response.body ?? new Blob([]).stream(), contentType: response.headers.get('content-type') ?? 'application/octet-stream', size: Number(response.headers.get('content-length') ?? 0) };
+        },
+        async put(key, bytes, contentType) {
+            await (await request('PUT', `${root}/${encode(key)}`, { body: bytes, contentType }))?.arrayBuffer();
+        },
+        async head(key) {
+            return (await request('HEAD', `${root}/${encode(key)}`, { allow404: true })) !== null;
+        },
+        async delete(key) {
+            await (await request('DELETE', `${root}/${encode(key)}`, { allow404: true }))?.arrayBuffer();
+        },
+        async deleteMany(keys) {
+            for (const key of keys)
+                await store.delete(key);
+        },
+        async getUri() {
+            return null;
+        },
+        async listPage(prefix = '', page = {}) {
+            const query = new URLSearchParams({ prefix, limit: String(page.limit ?? 1000) });
+            if (page.after !== undefined)
+                query.set('after', page.after);
+            const response = (await request('GET', `${root}?${query}`));
+            const body = await response.json();
+            if (!Array.isArray(body.keys))
+                throw new AtlasHttpError(`${base} did not answer a listing`, response.status);
+            return { keys: body.keys, next: body.next ?? null };
+        },
+        async listKeys(prefix = '') {
+            const keys = [];
+            for (let after;;) {
+                const page = await store.listPage(prefix, after === undefined ? {} : { after });
+                keys.push(...page.keys);
+                if (page.next === null)
+                    return keys;
+                after = page.next;
+            }
+        },
+        withPrefix(prefix) {
+            return new ObjectStoreWithPrefix(store, prefix);
+        },
+        async status(query = new URLSearchParams()) {
+            const suffix = query.size ? `?${query}` : '';
+            return (await request('GET', `${api}/status${suffix}`)).json();
+        },
+        async ping() {
+            const started = performance.now();
+            try {
+                const response = (await request('GET', `${base}/api/server`));
+                const info = await response.json();
+                return { ok: true, ms: Math.round(performance.now() - started), ...(info.role ? { role: info.role } : {}) };
+            }
+            catch (error) {
+                return { ok: false, ms: Math.round(performance.now() - started), error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+    };
+    return store;
+}

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

@@ -1,3 +1,10 @@
+/**
+ * @module HTTP client port
+ *
+ * The one thing the reports readers need from the network, as a type, so a host can supply `fetch`, an
+ * authenticating wrapper or a test double.
+ */
+/** Anything with a `fetch` of the standard signature. The readers only call it; they do not retry or add credentials. */
 export type HttpClient = {
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 };

package/dist/reports/src/http.js

@@ -0,0 +1,6 @@
+/**
+ * @module HTTP client port
+ *
+ * The one thing the reports readers need from the network, as a type, so a host can supply `fetch`, an
+ * authenticating wrapper or a test double.
+ */

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

@@ -0,0 +1,54 @@
+import type { EvidenceCheck } from './explorer-types.js';
+/** The checks an existing test report holds, and when it was recorded when the report says. */
+export type IngestedChecks = {
+    /** One per test, with ids made unique. Attachments that name a file carry a `path` for the publisher to read; see `attachment-files.ts`. */
+    readonly checks: readonly EvidenceCheck[];
+    /**
+     * For each check, in order, the names the report gave its container (suite, class, file), which
+     * can name the spec it checks when the report has no path for it.
+     */
+    readonly hints?: readonly (readonly string[])[];
+    /** When the report says the run ended (or started), epoch milliseconds; null when it does not say. */
+    readonly recordedAtMs: number | null;
+    /** The tool that wrote the report, when it says. */
+    readonly tool: string | null;
+    /** What the report says about the run as a whole: the tool, the build, the platform. */
+    readonly labels?: Readonly<Record<string, string>>;
+};
+/** 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 declare function uniqueChecks(checks: readonly EvidenceCheck[]): EvidenceCheck[];
+/**
+ * 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 declare function checksFromCtrf(report: unknown): IngestedChecks;
+/**
+ * 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 declare function checksFromJunit(xml: string): IngestedChecks;
+/**
+ * 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 declare function checksFromManifest(manifest: unknown): IngestedChecks;

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>;