@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -1,11 +1,28 @@
+/**
+ * @module Choosing between the shared and the local reports store
+ *
+ * Decides which store answers for a commit or a source when a project has both a shared store and this machine's own,
+ * and merges their source records. The local store wins for what it holds, so a remote outage cannot hide a local run.
+ */
 import type { SourceRecord } from './protocol.js';
 import type { ObjectStore } from './object-store.js';
+/** The stores a reports host reads. */
 export type ReportsStores = {
+    /** The shared reports store, or `null` when this deployment has no credential for one. */
     readonly store: ObjectStore | null;
+    /** This machine's own store, where collected local runs are written. */
     readonly localStore?: ObjectStore;
 };
-/** Collected local runs own their timelines; a remote outage cannot hide them. */
+/**
+ * The store to read a commit from: the local store when it has that commit's record, else the shared store (`null`
+ * when there is none). Collected local runs own their timelines; a remote outage cannot hide them.
+ */
 export declare function reportsStoreForCommit(deps: ReportsStores, sha: string): Promise<ObjectStore | null>;
+/** The store to read one source of a commit from: the local store when it holds that source, else the shared store (`null` when there is none). */
 export declare function reportsStoreForSource(deps: ReportsStores, sha: string, source: string): Promise<ObjectStore | null>;
-/** Merge independent producers; local output overrides only its own source. */
+/**
+ * Lists the source records of a commit from the shared and the local store, one per source name. A local source
+ * replaces the shared one of the same name only; others from both are kept. A store that fails is skipped, and the
+ * error is thrown only when no source was found at all and a store failed.
+ */
 export declare function reportsSources(deps: ReportsStores, sha: string): Promise<readonly SourceRecord[]>;

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

@@ -1,18 +1,26 @@
 import { listSourceRecords, readCommit, } from './read.js';
 import { readStoredSource } from './source-content.js';
-/** Collected local runs own their timelines; a remote outage cannot hide them. */
+/**
+ * The store to read a commit from: the local store when it has that commit's record, else the shared store (`null`
+ * when there is none). Collected local runs own their timelines; a remote outage cannot hide them.
+ */
 export async function reportsStoreForCommit(deps, sha) {
     if (deps.localStore && (await readCommit(deps.localStore, sha)) !== null)
         return deps.localStore;
     return deps.store;
 }
+/** The store to read one source of a commit from: the local store when it holds that source, else the shared store (`null` when there is none). */
 export async function reportsStoreForSource(deps, sha, source) {
     if (deps.localStore &&
         (await readStoredSource(deps.localStore, sha, source)) !== null)
         return deps.localStore;
     return deps.store;
 }
-/** Merge independent producers; local output overrides only its own source. */
+/**
+ * Lists the source records of a commit from the shared and the local store, one per source name. A local source
+ * replaces the shared one of the same name only; others from both are kept. A store that fails is skipped, and the
+ * error is thrown only when no source was found at all and a store failed.
+ */
 export async function reportsSources(deps, sha) {
     const stores = [deps.store, deps.localStore].filter((store) => store != null);
     const results = await Promise.allSettled(stores.map((store) => listSourceRecords(store, sha)));

package/dist/reports/src/resilient-cache.d.ts

@@ -1,3 +1,16 @@
+/**
+ * @module Resilient report cache
+ *
+ * Wraps a persistent `ReportCache` (IndexedDB, which a browser may deny or corrupt) so a failure of the cache never
+ * blocks reports: everything is also kept in memory and every storage error is swallowed.
+ */
 import type { ReportCache } from './fetcher.js';
-/** Storage is an optimization. A denied or corrupt persistent cache cannot block reports. */
+/**
+ * Returns a cache that reads and writes `cache` and also keeps every value in memory. Storage is an optimization. A
+ * denied or corrupt persistent cache cannot block reports.
+ *
+ * `get` answers from `cache`, falling back to memory when it has no value or throws. `set` and `remove` always apply
+ * to memory first, then try `cache` and ignore its errors, so a value written while storage is failing is still
+ * readable for the life of this wrapper (but not after a reload).
+ */
 export declare function resilientReportCache(cache: ReportCache): ReportCache;

package/dist/reports/src/resilient-cache.js

@@ -1,5 +1,12 @@
 import { memoryReportCache } from './fetcher.js';
-/** Storage is an optimization. A denied or corrupt persistent cache cannot block reports. */
+/**
+ * Returns a cache that reads and writes `cache` and also keeps every value in memory. Storage is an optimization. A
+ * denied or corrupt persistent cache cannot block reports.
+ *
+ * `get` answers from `cache`, falling back to memory when it has no value or throws. `set` and `remove` always apply
+ * to memory first, then try `cache` and ignore its errors, so a value written while storage is failing is still
+ * readable for the life of this wrapper (but not after a reload).
+ */
 export function resilientReportCache(cache) {
     const fallback = memoryReportCache();
     return {

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

@@ -1,9 +1,25 @@
+/**
+ * @module Report retention
+ *
+ * The plan for what cleanup may remove from a store. There is none: Atlas never deletes a layer or a commit's evidence
+ * by itself (the contract is deletion-free), so the plan always retains everything and lists no key to delete.
+ * Retention is the operator's choice, made outside Atlas.
+ *
+ * @see docs/report-contract.md#guarantees
+ */
 import type { ObjectStore } from './object-store.js';
 import type { CommitRecord } from './protocol.js';
+/** What a retention pass would keep and delete. */
 export type ReportRetentionPlan = {
+    /** The commit records found, all of them. */
     readonly retained: readonly CommitRecord[];
+    /** Keys to delete. Always empty: automatic cleanup never discards evidence. */
     readonly deleteKeys: readonly string[];
 };
-/** Report evidence outlives branch heads. Automatic cleanup never discards a layer. */
+/**
+ * Lists the commits recorded in `index/` with their records, and no key to delete. Report evidence outlives branch
+ * heads: automatic cleanup never discards a layer. A listed commit with no readable record is left out of `retained`.
+ */
 export declare function planReportRetention(store: ObjectStore): Promise<ReportRetentionPlan>;
+/** Same as `planReportRetention`. Despite the name it deletes nothing, and `deleteKeys` is always empty. */
 export declare function pruneReports(store: ObjectStore): Promise<ReportRetentionPlan>;

package/dist/reports/src/retention.js

@@ -1,5 +1,8 @@
 import { readCommit } from './read.js';
-/** Report evidence outlives branch heads. Automatic cleanup never discards a layer. */
+/**
+ * Lists the commits recorded in `index/` with their records, and no key to delete. Report evidence outlives branch
+ * heads: automatic cleanup never discards a layer. A listed commit with no readable record is left out of `retained`.
+ */
 export async function planReportRetention(store) {
     const keys = await store.listKeys('index/');
     const shas = new Set(keys.flatMap(key => /([0-9a-f]{40})\.json$/.exec(key)?.[1] ?? []));
@@ -11,6 +14,7 @@ export async function planReportRetention(store) {
     }
     return { retained, deleteKeys: [] };
 }
+/** Same as `planReportRetention`. Despite the name it deletes nothing, and `deleteKeys` is always empty. */
 export async function pruneReports(store) {
     return planReportRetention(store);
 }

package/dist/reports/src/run-bundle.d.ts

@@ -0,0 +1,63 @@
+import { type ObjectStore, type StoredObject } from './object-store.js';
+type Count = {
+    total: number;
+    passed: number;
+    failed: number;
+    flaky: number;
+    notReached: number;
+};
+/**
+ * Builds the row the viewer lists for a finished run (a `RunSummary`) from its `manifest.json`, which may be any JSON:
+ * every field is read defensively and a missing one takes a default.
+ *
+ * `startedAt` is `run.startedAt`, else the time in the run id (`2026-10-09T12-00-00-000Z-...`), else the epoch;
+ * `mode` is `run.mode`, else `showcase` for an id ending in `showcase`, else `fast`. `journeys` counts the manifest's
+ * `journeys` (or the `paths` of kind `journey`) by status `passed`, `failed`, `flaky`, with any other status counted
+ * as `notReached`. `progress` is always `complete`.
+ */
+export declare function summarizeManifest(id: string, manifest: unknown): {
+    journeys: Count;
+    coverage?: {
+        transitions?: Count | undefined;
+        states?: Count | undefined;
+    } | undefined;
+    progress: "complete";
+    hasManifest: boolean;
+    specVersion?: string | undefined;
+    durationMs?: number | undefined;
+    id: string;
+    startedAt: string;
+    mode: string;
+    commit: string | null;
+    branch: string | null;
+};
+/** Thrown by `publishRunBundle` when a run's privacy scan did not pass (or never ran), so the run is not uploaded. The same rule the static viewer applies. */
+export declare class RunNotShareableError extends Error {
+}
+/**
+ * Uploads a finished run directory so the viewer can browse it from the store. Files go first and
+ * `manifest.json` after them, then the catalog entry, so a half-uploaded run is never listed. Running it
+ * again after a failure finishes the job; a run that is already complete is left alone.
+ *
+ * The run id is the directory's name (letters, digits, `_`, `.`, `-`; not starting with a dot). Files are written to
+ * `layers/runs/<id>/<relative path>` with a media type from their extension; dot-files, dot-folders and symbolic links
+ * are skipped. Resolves to the file and byte counts uploaded (both 0 with `alreadyPublished: true` when the manifest
+ * was already in the store; a missing catalog entry is then written). Throws `RunNotShareableError` when
+ * `manifest.privacy.passed` is not `true`, and an `Error` for a badly named directory or a missing or unreadable
+ * `manifest.json`.
+ */
+export declare function publishRunBundle(store: ObjectStore, directory: string): Promise<{
+    readonly id: string;
+    readonly files: number;
+    readonly bytes: number;
+    readonly alreadyPublished: boolean;
+}>;
+/**
+ * Lists the newest `limit` (default 100) runs in the store, newest first by `startedAt` (ties by id). The catalog is
+ * newest first, so one page of it is enough; entries never change, so `cache` (catalog key to summary) lets a
+ * long-lived reader open each only once. A catalog entry that is empty or not JSON is skipped.
+ */
+export declare function listRunSummaries(store: ObjectStore, limit?: number, cache?: Map<string, ReturnType<typeof summarizeManifest>>): Promise<ReturnType<typeof summarizeManifest>[]>;
+/** Reads one file of a run, or `null` when it is missing. Also `null`, without reading, for an `id` that is not a plain run name or a `relative` path with an empty, `.`, `..` or backslash segment, so a path can never leave the run. */
+export declare function readRunFile(store: ObjectStore, id: string, relative: string): Promise<StoredObject | null>;
+export {};

package/dist/reports/src/run-bundle.js

@@ -0,0 +1,159 @@
+/**
+ * @module Run bundles
+ *
+ * Uploads a finished statechart run directory (manifest, screenshots, clips) to a store under `layers/runs/<run>/` and
+ * lists and reads them back for the viewer. A run is shared only once its privacy scan passed. The manifest is written
+ * after its files and the catalog entry (`layers/runs/index/<inverted-time>-<run>.json`) after the manifest, so a
+ * half-uploaded run is never listed, and uploading again finishes the job. Uses Node's `fs`, so it is not for
+ * browsers.
+ *
+ * @see docs/report-contract.md#where-bytes-go
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { eachLimited } from './completion-order.js';
+import { contentTypeOf } from './media-types.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+import { isPaged } from './object-store.js';
+const RUN_PREFIX = 'layers/runs/';
+const INDEX_PREFIX = 'layers/runs/index/';
+const object = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {});
+const count = (value) => {
+    const found = object(value);
+    if (!Object.keys(found).length)
+        return undefined;
+    const n = (key) => (typeof found[key] === 'number' ? found[key] : 0);
+    return { total: n('total'), passed: n('passed'), failed: n('failed'), flaky: n('flaky'), notReached: n('notReached') };
+};
+/**
+ * Builds the row the viewer lists for a finished run (a `RunSummary`) from its `manifest.json`, which may be any JSON:
+ * every field is read defensively and a missing one takes a default.
+ *
+ * `startedAt` is `run.startedAt`, else the time in the run id (`2026-10-09T12-00-00-000Z-...`), else the epoch;
+ * `mode` is `run.mode`, else `showcase` for an id ending in `showcase`, else `fast`. `journeys` counts the manifest's
+ * `journeys` (or the `paths` of kind `journey`) by status `passed`, `failed`, `flaky`, with any other status counted
+ * as `notReached`. `progress` is always `complete`.
+ */
+export function summarizeManifest(id, manifest) {
+    const root = object(manifest);
+    const run = object(root.run);
+    const coverage = object(object(root.coverage).overall);
+    const paths = (Array.isArray(root.journeys) ? root.journeys : Array.isArray(root.paths) ? root.paths.filter(item => object(item).kind === 'journey') : []).map(object);
+    const journeys = { total: paths.length, passed: 0, failed: 0, flaky: 0, notReached: 0 };
+    for (const item of paths) {
+        if (item.status === 'passed')
+            journeys.passed++;
+        else if (item.status === 'failed')
+            journeys.failed++;
+        else if (item.status === 'flaky')
+            journeys.flaky++;
+        else
+            journeys.notReached++;
+    }
+    const fromId = id.match(/^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/);
+    return {
+        id,
+        startedAt: typeof run.startedAt === 'string' ? run.startedAt : fromId ? `${fromId[1]}T${fromId[2]}:${fromId[3]}:${fromId[4]}.${fromId[5]}Z` : new Date(0).toISOString(),
+        mode: typeof run.mode === 'string' ? run.mode : id.endsWith('showcase') ? 'showcase' : 'fast',
+        commit: typeof run.commit === 'string' ? run.commit : null,
+        branch: typeof run.branch === 'string' ? run.branch : null,
+        ...(typeof run.durationMs === 'number' ? { durationMs: run.durationMs } : {}),
+        ...(typeof run.specVersion === 'string' ? { specVersion: run.specVersion } : {}),
+        progress: 'complete',
+        hasManifest: true,
+        ...(Object.keys(coverage).length ? { coverage: { ...(count(coverage.states) ? { states: count(coverage.states) } : {}), ...(count(coverage.transitions) ? { transitions: count(coverage.transitions) } : {}) } } : {}),
+        journeys
+    };
+}
+async function walk(dir, root = dir) {
+    const nested = await Promise.all((await readdir(dir, { withFileTypes: true })).map(async (entry) => {
+        if (entry.name.startsWith('.'))
+            return [];
+        const full = path.join(dir, entry.name);
+        return entry.isDirectory() ? walk(full, root) : entry.isFile() ? [path.relative(root, full).split(path.sep).join('/')] : [];
+    }));
+    return nested.flat();
+}
+/** Thrown by `publishRunBundle` when a run's privacy scan did not pass (or never ran), so the run is not uploaded. The same rule the static viewer applies. */
+export class RunNotShareableError extends Error {
+}
+/**
+ * Uploads a finished run directory so the viewer can browse it from the store. Files go first and
+ * `manifest.json` after them, then the catalog entry, so a half-uploaded run is never listed. Running it
+ * again after a failure finishes the job; a run that is already complete is left alone.
+ *
+ * The run id is the directory's name (letters, digits, `_`, `.`, `-`; not starting with a dot). Files are written to
+ * `layers/runs/<id>/<relative path>` with a media type from their extension; dot-files, dot-folders and symbolic links
+ * are skipped. Resolves to the file and byte counts uploaded (both 0 with `alreadyPublished: true` when the manifest
+ * was already in the store; a missing catalog entry is then written). Throws `RunNotShareableError` when
+ * `manifest.privacy.passed` is not `true`, and an `Error` for a badly named directory or a missing or unreadable
+ * `manifest.json`.
+ */
+export async function publishRunBundle(store, directory) {
+    const id = path.basename(path.resolve(directory));
+    if (!/^[\w.-]+$/.test(id) || id.startsWith('.'))
+        throw new Error(`A run directory is named like 2026-10-09T12-00-00-000Z-fast; "${id}" is not.`);
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path.join(directory, 'manifest.json'), 'utf8'));
+    }
+    catch {
+        throw new Error(`${directory} has no readable manifest.json: is the run finished?`);
+    }
+    if (object(object(manifest).privacy).passed !== true)
+        throw new RunNotShareableError(`Run ${id} is not shared: its privacy scan did not pass (or never ran). Fix what it found and run it again.`);
+    const summary = summarizeManifest(id, manifest);
+    const inverse = String(Number.MAX_SAFE_INTEGER - Math.max(0, Date.parse(summary.startedAt) || 0)).padStart(16, '0');
+    const catalog = `${INDEX_PREFIX}${inverse}-${id}.json`;
+    if (await store.head(`${RUN_PREFIX}${id}/manifest.json`)) {
+        // The manifest is written before the catalog entry: an upload that died in between is finished here.
+        if (!(await store.head(catalog)))
+            await writeUtf8(store, catalog, JSON.stringify(summary), 'application/json');
+        return { id, files: 0, bytes: 0, alreadyPublished: true };
+    }
+    const files = await walk(directory);
+    let bytes = 0;
+    await eachLimited(files.filter(file => file !== 'manifest.json'), 16, async (file) => {
+        const body = new Uint8Array(await readFile(path.join(directory, file)));
+        bytes += body.length;
+        await store.put(`${RUN_PREFIX}${id}/${file}`, body, contentTypeOf(file));
+    });
+    const text = await readFile(path.join(directory, 'manifest.json'), 'utf8');
+    bytes += text.length;
+    await writeUtf8(store, `${RUN_PREFIX}${id}/manifest.json`, text, 'application/json');
+    await writeUtf8(store, catalog, JSON.stringify(summary), 'application/json');
+    return { id, files: files.length, bytes, alreadyPublished: false };
+}
+/**
+ * Lists the newest `limit` (default 100) runs in the store, newest first by `startedAt` (ties by id). The catalog is
+ * newest first, so one page of it is enough; entries never change, so `cache` (catalog key to summary) lets a
+ * long-lived reader open each only once. A catalog entry that is empty or not JSON is skipped.
+ */
+export async function listRunSummaries(store, limit = 100, cache = new Map()) {
+    const keys = isPaged(store) ? (await store.listPage(INDEX_PREFIX, { limit })).keys : (await store.listKeys(INDEX_PREFIX)).slice(0, limit);
+    const rows = [];
+    await eachLimited(keys, 16, async (key) => {
+        const known = cache.get(key);
+        if (known) {
+            rows.push(known);
+            return;
+        }
+        const raw = await readUtf8(store, key);
+        if (!raw)
+            return;
+        try {
+            const row = JSON.parse(raw);
+            cache.set(key, row);
+            rows.push(row);
+        }
+        catch { /* an unreadable marker is skipped */ }
+    });
+    return rows.sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt) || (a.id < b.id ? -1 : 1));
+}
+/** Reads one file of a run, or `null` when it is missing. Also `null`, without reading, for an `id` that is not a plain run name or a `relative` path with an empty, `.`, `..` or backslash segment, so a path can never leave the run. */
+export async function readRunFile(store, id, relative) {
+    const parts = relative.split('/');
+    if (!/^[\w.-]+$/.test(id) || id.startsWith('.') || parts.some(part => !part || part === '.' || part === '..' || part.includes('\\')))
+        return null;
+    return store.get(`${RUN_PREFIX}${id}/${relative}`);
+}

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

@@ -0,0 +1,79 @@
+import { type CredentialProvider } from './aws-credentials.js';
+import type { ObjectStore, PagedListing } from './object-store.js';
+import { type Credentials } from './sigv4.js';
+/** How to reach a bucket. Only `bucket` is required. */
+export type S3StoreOptions = {
+    /** The bucket name. A name containing `.` is addressed path-style. */
+    readonly bucket: string;
+    /** A folder inside the bucket that holds everything: `atlas/my-project`. */
+    readonly prefix?: string;
+    /** Default `AWS_REGION`, then `us-east-1`. Cloudflare R2 uses `auto`. */
+    readonly region?: string;
+    /** For anything that is not AWS: `https://<account>.r2.cloudflarestorage.com`, `http://localhost:9000`. */
+    readonly endpoint?: string;
+    /** `endpoint/bucket/key` instead of `bucket.endpoint/key`. Default: yes for a custom endpoint, no for AWS. */
+    readonly forcePathStyle?: boolean;
+    /** Keys, or a provider. Default: the same lookup an AWS SDK does ({@link credentialChain}). */
+    readonly credentials?: Credentials | CredentialProvider;
+    /** The environment variables to read (`AWS_REGION`, `AWS_ENDPOINT_URL_S3`, credentials, ...). Default: `process.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The `fetch` to send requests with. Default: the global one; inject a fake in tests. */
+    readonly fetch?: typeof fetch;
+    /** Attempts after the first for a request that failed in a way worth retrying. Default 4. */
+    readonly retries?: number;
+    /** For the service to start answering, per attempt, in milliseconds. A large body may take longer. Default 30 000. */
+    readonly timeoutMs?: number;
+    /** Requests in flight at once. Default 64: S3 answers in tens of milliseconds, so parallelism is what makes a cold start fast. */
+    readonly concurrency?: number;
+    /** The clock used to sign requests. Default: the system clock; inject in tests. */
+    readonly now?: () => Date;
+    /** The wait between retries, in milliseconds. Default: a real timer; inject in tests. */
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * An error from the store. The message names the bucket and what to do about it (for example the missing IAM
+ * permission); `status` and `code` are what the service answered, `null` when it was never reached.
+ * `retryable` says whether trying again can help; the store already retried before throwing.
+ */
+export declare class S3Error extends Error {
+    readonly status: number | null;
+    readonly code: string | null;
+    readonly retryable: boolean;
+    constructor(message: string, status: number | null, code: string | null, retryable?: boolean);
+}
+/** An `ObjectStore` on S3 with paged listing, a secret-free label, and diagnostics. */
+export type S3Store = ObjectStore & PagedListing & {
+    /** A description with no secrets: `s3://bucket/prefix (us-east-1)`. */
+    readonly label: string;
+    /** Where the credentials came from, once a request has been made. */
+    credentialSource(): string | null;
+    /** One cheap round trip: can this store be listed? Used by readiness checks and `atlas report doctor`. */
+    ping(): Promise<{
+        readonly ok: boolean;
+        readonly ms: number;
+        readonly error?: string;
+    }>;
+};
+/**
+ * An {@link ObjectStore} on S3, or anything that speaks its protocol: Cloudflare R2, MinIO, Google
+ * Cloud Storage (interoperability), Backblaze B2, Wasabi, SeaweedFS. No SDK: requests are signed with
+ * Signature Version 4 and sent with `fetch`, so it runs on Bun and Node and adds nothing
+ * to the install.
+ *
+ * Made for many writers and a long-lived reader: connections are reused, requests in flight are
+ * capped, throttling and server errors are retried with jittered backoff, a bucket in another region
+ * is followed, and expired credentials are refreshed once.
+ *
+ * Behaviour to know: a missing key reads as `null`/`false` only when S3 answers 404. For an account without
+ * `s3:ListBucket`, S3 answers 403 for a missing key, which throws `S3Error` with a hint: the publishing credentials
+ * need `s3:GetObject`, `s3:PutObject` and `s3:ListBucket` (`atlas report policy` prints a least-privilege policy).
+ * `getUri` returns a presigned URL valid for one hour. `deleteMany` sends one request per key, 16 at a time.
+ * `listKeys` pages through the whole listing and sorts it; use `listPage` to read part of a large catalog. Nothing is
+ * checked or created at construction: the first request is the first contact.
+ *
+ * @example
+ * const store = s3Store({ bucket: 'my-evidence', prefix: 'atlas/my-project', region: 'eu-west-1' });
+ * await store.put('layers/manifests/x.json', bytes, 'application/json');
+ * const { ok, error } = await store.ping();
+ */
+export declare function s3Store(options: S3StoreOptions): S3Store;