@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/spec-set.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module Spec sets
+ *
+ * Publishes and finds spec sets: the specs of one commit, stored in the store itself so a viewer needs no checkout. Bodies
+ * are content-addressed in `layers/specs/blobs/<sha256>.txt`, the set is `layers/specs/sets/<id>.json`, and the catalog
+ * entry `layers/specs/index/<inverted-time>-<branch>-<flag>-<id>.json` is written last. `latestSpecSet` picks the outline
+ * a report is laid over: the newest set of `main` (then `master`, then any branch), preferring a set from a clean
+ * commit over one from a modified checkout.
+ *
+ * @see docs/report-contract.md#where-bytes-go
+ */
+import { type SpecSet } from '../../schema/src/layer.js';
+import { collectSpecFiles, isSpecFile, type SpecFileText } from './directory-outline.js';
+import { type ObjectStore } from './object-store.js';
+export { collectSpecFiles, isSpecFile, type SpecFileText };
+/** What to publish as one spec set. */
+export type PublishSpecSetInput = {
+    /** The spec files and their text; see `collectSpecFiles`. */
+    readonly files: readonly SpecFileText[];
+    /** The branch the specs are from, or `null`. Part of the set's identity and of its catalog key. */
+    readonly branch: string | null;
+    /** The commit the specs are from, or `null`. Part of the set's identity. */
+    readonly sha: string | null;
+    /** When the specs were recorded, epoch milliseconds; orders the catalog (newest first). */
+    readonly recordedAtMs: number;
+    /** `modified` for a checkout with uncommitted edits, `unknown` outside git; absent for a clean checkout. Part of the set's identity. */
+    readonly freshness?: 'unknown' | 'modified';
+    /** The group shown in the viewer for every file. Default `product`. */
+    readonly domain?: string;
+};
+/**
+ * Publishes the specs of one version and returns the set. Bodies are stored by content, so a spec that did not change
+ * costs nothing, and the set is named by what it holds: publishing the same specs from the same commit twice
+ * writes the same set. The catalog entry is written last.
+ *
+ * The set's `id` is the SHA-256 of the branch, sha, freshness and each file's path and digest, so the same specs from a
+ * developer's edited worktree and from CI are different sets. Store errors reject; a failure part-way leaves bodies
+ * no set names, never a set whose bodies are missing.
+ */
+export declare function publishSpecSet(store: ObjectStore, input: PublishSpecSetInput): Promise<SpecSet>;
+/** Reads and validates a spec set by id, or `null` when it is missing. Throws `Spec set <id> is not valid: ...` when it fails the schema, and a `SyntaxError` when it is not JSON. */
+export declare function readSpecSet(store: ObjectStore, id: string): Promise<SpecSet | null>;
+/** Reads the text of a spec body by its SHA-256 digest, or `null` when it is missing or `digest` is not 64 lowercase hex digits. */
+export declare function readSpecBody(store: ObjectStore, digest: string): Promise<string | null>;
+type Found = {
+    readonly set: SpecSet;
+    readonly store: ObjectStore;
+};
+/**
+ * The spec set the report is laid over: the newest one of `branch` in any of the stores. Without a
+ * branch, the newest of `main` or `master`, and failing that the newest of all, so a project that
+ * only ever publishes from other branches still has an outline.
+ *
+ * A set from a modified checkout (a developer's uncommitted edits) is used only when no set from a
+ * commit exists: the shared view does not follow anyone's work in progress. The branch and cleanliness
+ * are read from the catalog's keys, so choosing costs a listing and a read or two, however many sets
+ * other branches have published. `cache` keeps sets already read: they never change.
+ *
+ * Resolves to the set and the store it was found in, or `null` when no store has a fitting set (with an explicit
+ * `branch`, only that branch counts). A store that fails is skipped; the first error is thrown only when every store
+ * failed. A set that cannot be read is skipped.
+ */
+export declare function latestSpecSet(stores: readonly ObjectStore[], branch?: string, cache?: Map<string, SpecSet>): Promise<Found | null>;

package/dist/reports/src/spec-set.js

@@ -0,0 +1,177 @@
+/**
+ * @module Spec sets
+ *
+ * Publishes and finds spec sets: the specs of one commit, stored in the store itself so a viewer needs no checkout. Bodies
+ * are content-addressed in `layers/specs/blobs/<sha256>.txt`, the set is `layers/specs/sets/<id>.json`, and the catalog
+ * entry `layers/specs/index/<inverted-time>-<branch>-<flag>-<id>.json` is written last. `latestSpecSet` picks the outline
+ * a report is laid over: the newest set of `main` (then `master`, then any branch), preferring a set from a clean
+ * commit over one from a modified checkout.
+ *
+ * @see docs/report-contract.md#where-bytes-go
+ */
+import { SpecSetSchema } from '../../schema/src/layer.js';
+import { eachLimited } from './completion-order.js';
+import { collectSpecFiles, isSpecFile, specKindOf, specTitleOf } from './directory-outline.js';
+import { textFingerprint } from './layer-merge.js';
+import { readUtf8, writeUtf8 } from './object-io.js';
+import { isPaged } from './object-store.js';
+import { sha256Hex } from './sigv4.js';
+export { collectSpecFiles, isSpecFile };
+const SET_PREFIX = 'layers/specs/sets/';
+const INDEX_PREFIX = 'layers/specs/index/';
+const BLOB_PREFIX = 'layers/specs/blobs/';
+/** A branch as it appears in a catalog key: lowercase letters and digits. `_` for none. */
+const branchSlug = (branch) => branch?.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || '_';
+const flagOf = (freshness) => (freshness === undefined ? 'c' : freshness === 'modified' ? 'm' : 'u');
+/**
+ * Publishes the specs of one version and returns the set. Bodies are stored by content, so a spec that did not change
+ * costs nothing, and the set is named by what it holds: publishing the same specs from the same commit twice
+ * writes the same set. The catalog entry is written last.
+ *
+ * The set's `id` is the SHA-256 of the branch, sha, freshness and each file's path and digest, so the same specs from a
+ * developer's edited worktree and from CI are different sets. Store errors reject; a failure part-way leaves bodies
+ * no set names, never a set whose bodies are missing.
+ */
+export async function publishSpecSet(store, input) {
+    const files = await Promise.all([...input.files].sort((a, b) => (a.path < b.path ? -1 : 1)).map(async (file) => {
+        const bytes = new TextEncoder().encode(file.text);
+        return { path: file.path, digest: await sha256Hex(bytes), fingerprint: textFingerprint(file.text), kind: specKindOf(file.path), title: specTitleOf(file.path, file.text), domain: input.domain ?? 'product', bytes: bytes.length, text: file.text };
+    }));
+    await eachLimited(files, 16, async (file) => {
+        const key = `${BLOB_PREFIX}${file.digest}.txt`;
+        if (!(await store.head(key)))
+            await writeUtf8(store, key, file.text, 'text/plain; charset=utf-8');
+    });
+    // Freshness is part of the identity: the same specs from a developer's edited worktree and from CI are different sets.
+    const id = await sha256Hex(JSON.stringify([input.branch, input.sha, input.freshness ?? null, files.map(file => [file.path, file.digest])]));
+    const set = {
+        schemaVersion: 1, id, branch: input.branch, sha: input.sha, recordedAtMs: input.recordedAtMs,
+        ...(input.freshness ? { freshness: input.freshness } : {}),
+        files: files.map(({ text: _text, ...file }) => file)
+    };
+    if (!(await store.head(`${SET_PREFIX}${id}.json`)))
+        await writeUtf8(store, `${SET_PREFIX}${id}.json`, JSON.stringify(set), 'application/json');
+    const inverse = String(Number.MAX_SAFE_INTEGER - Math.max(0, Math.floor(input.recordedAtMs))).padStart(16, '0');
+    // The branch and whether the checkout was clean are in the key, so the outline is found without opening every set.
+    await writeUtf8(store, `${INDEX_PREFIX}${inverse}-${branchSlug(input.branch)}-${flagOf(input.freshness)}-${id}.json`, JSON.stringify({ id }), 'application/json');
+    return set;
+}
+/** Reads and validates a spec set by id, or `null` when it is missing. Throws `Spec set <id> is not valid: ...` when it fails the schema, and a `SyntaxError` when it is not JSON. */
+export async function readSpecSet(store, id) {
+    const raw = await readUtf8(store, `${SET_PREFIX}${id}.json`);
+    if (raw === null)
+        return null;
+    const parsed = SpecSetSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success)
+        throw new Error(`Spec set ${id.slice(0, 12)} is not valid: ${parsed.error.issues[0]?.message ?? 'unknown'}`);
+    return parsed.data;
+}
+/** Reads the text of a spec body by its SHA-256 digest, or `null` when it is missing or `digest` is not 64 lowercase hex digits. */
+export async function readSpecBody(store, digest) {
+    return /^[0-9a-f]{64}$/.test(digest) ? readUtf8(store, `${BLOB_PREFIX}${digest}.txt`) : null;
+}
+const DEFAULT_BRANCHES = ['main', 'master'];
+const MAX_PAGES = 20;
+const newer = (a, b) => b.set.recordedAtMs - a.set.recordedAtMs || (a.set.id < b.set.id ? -1 : 1);
+const clean = (found) => found.set.freshness === undefined;
+const ENTRY = /(?:^|\/)(\d{16})-(.+)-([cmu])-([0-9a-f]{64})\.json$/;
+/** The catalog, newest first, a page at a time where the store can. */
+async function* catalog(store) {
+    const parse = (key) => { const match = ENTRY.exec(key); return match ? { slug: match[2], flag: match[3], id: match[4] } : null; };
+    if (!isPaged(store)) {
+        for (const key of await store.listKeys(INDEX_PREFIX)) {
+            const entry = parse(key);
+            if (entry)
+                yield entry;
+        }
+        return;
+    }
+    let after;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const result = await store.listPage(INDEX_PREFIX, { ...(after === undefined ? {} : { after }), limit: 1000 });
+        for (const key of result.keys) {
+            const entry = parse(key);
+            if (entry)
+                yield entry;
+        }
+        if (result.next === null)
+            return;
+        after = result.next;
+    }
+}
+/**
+ * The spec set the report is laid over: the newest one of `branch` in any of the stores. Without a
+ * branch, the newest of `main` or `master`, and failing that the newest of all, so a project that
+ * only ever publishes from other branches still has an outline.
+ *
+ * A set from a modified checkout (a developer's uncommitted edits) is used only when no set from a
+ * commit exists: the shared view does not follow anyone's work in progress. The branch and cleanliness
+ * are read from the catalog's keys, so choosing costs a listing and a read or two, however many sets
+ * other branches have published. `cache` keeps sets already read: they never change.
+ *
+ * Resolves to the set and the store it was found in, or `null` when no store has a fitting set (with an explicit
+ * `branch`, only that branch counts). A store that fails is skipped; the first error is thrown only when every store
+ * failed. A set that cannot be read is skipped.
+ */
+export async function latestSpecSet(stores, branch, cache = new Map()) {
+    const wanted = new Set((branch ? [branch] : DEFAULT_BRANCHES).map(name => branchSlug(name)));
+    const read = async (store, id) => {
+        const known = cache.get(id);
+        if (known)
+            return known;
+        const set = await readSpecSet(store, id).catch(() => null);
+        if (set)
+            cache.set(id, set);
+        return set;
+    };
+    const preferred = [];
+    const newest = [];
+    const failures = [];
+    for (const store of stores) {
+        let firstAccepted = null;
+        let firstOverall = null;
+        let firstCleanOverall = null;
+        try {
+            for await (const entry of catalog(store)) {
+                // Entries are newest first. Stop at the first clean set of the branch; remember the others for the fallbacks.
+                if (!wanted.has(entry.slug)) {
+                    if (!branch && entry.flag === 'c' && !firstCleanOverall) {
+                        const set = await read(store, entry.id);
+                        if (set)
+                            firstCleanOverall = { set, store };
+                    }
+                    else if (!branch && !firstOverall && !firstCleanOverall) {
+                        const set = await read(store, entry.id);
+                        if (set)
+                            firstOverall = { set, store };
+                    }
+                    continue;
+                }
+                const set = await read(store, entry.id);
+                if (!set || (branch && set.branch !== branch))
+                    continue;
+                const found = { set, store };
+                firstAccepted ??= found;
+                if (entry.flag === 'c') {
+                    firstAccepted = found;
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            // One store that is down does not take the outline with it.
+            failures.push(error);
+            continue;
+        }
+        if (firstAccepted)
+            preferred.push(firstAccepted);
+        const fallback = firstCleanOverall ?? firstOverall;
+        if (fallback)
+            newest.push(fallback);
+    }
+    if (failures.length === stores.length && stores.length > 0)
+        throw failures[0];
+    const pool = preferred.length || branch ? preferred : newest;
+    const cleaned = pool.filter(clean);
+    return [...(cleaned.length ? cleaned : pool)].sort(newer)[0] ?? null;
+}

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

@@ -1,4 +1,14 @@
+/**
+ * @module Suite status
+ *
+ * The one rule for rolling test outcomes up into a suite or commit outcome, used wherever a recorded run is summarised.
+ */
 import type { ReportTestStatus } from './report-types.js';
+/**
+ * The worst outcome of a set of tests or sources: `failed` if any failed, `skipped` if there is at least one and all
+ * were skipped, otherwise `passed`. An empty list is `passed`: callers that need "no evidence" to mean something else
+ * (for example `closeCommit`) check for emptiness themselves.
+ */
 export declare function suiteStatus(tests: readonly {
     readonly status: ReportTestStatus;
 }[]): ReportTestStatus;

package/dist/reports/src/status.js

@@ -1,3 +1,8 @@
+/**
+ * The worst outcome of a set of tests or sources: `failed` if any failed, `skipped` if there is at least one and all
+ * were skipped, otherwise `passed`. An empty list is `passed`: callers that need "no evidence" to mean something else
+ * (for example `closeCommit`) check for emptiness themselves.
+ */
 export function suiteStatus(tests) {
     if (tests.some((t) => t.status === 'failed'))
         return 'failed';

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

@@ -1,21 +1,49 @@
+/**
+ * @module Prefix-scoped object store
+ *
+ * A decorator that makes a store look like it starts at a key prefix: callers use short keys, the shared bucket stays
+ * partitioned by prefix, and prefixes compose. It guards the keys it is given (no leading `/`, no `..`) so a scoped
+ * store cannot reach outside its prefix by key.
+ */
 import type { ObjectStore, StoredObject } from './object-store.js';
+/** Returns `prefix` with exactly one trailing `/` added when missing. Throws `ObjectStoreWithPrefix: prefix must be non-empty` for an empty prefix. */
 export declare function normalizeObjectStorePrefix(prefix: string): string;
 /**
  * Decorator that scopes every {@link ObjectStore} operation to a fixed key
  * prefix. Used at composition roots (e.g. API bindings) so feature code uses
  * logical keys while a shared bucket stays partitioned by prefix.
+ *
+ * Keys passed to `get`, `put`, `head`, `delete`, `deleteMany`, `getUri` are checked (`assertLogicalObjectKey`: not
+ * empty, no leading `/`, no `..`) and throw otherwise. The `prefix` argument of `listKeys` and `listPage` is not
+ * checked here; the store underneath is responsible for it. Returned keys have the prefix removed.
  */
 export declare class ObjectStoreWithPrefix implements ObjectStore {
     private readonly inner;
     private readonly prefix;
     constructor(inner: ObjectStore, prefix: string);
     private scopedKey;
+    /** Reads `prefix + key` from the underlying store; `null` when missing. Throws for an invalid key. */
     get(key: string): Promise<StoredObject | null>;
+    /** Writes `prefix + key` in the underlying store. Throws for an invalid key. */
     put(key: string, bytes: Uint8Array, contentType: string): Promise<void>;
+    /** Whether `prefix + key` exists in the underlying store. Throws for an invalid key. */
     head(key: string): Promise<boolean>;
+    /** Removes `prefix + key`; a no-op when missing. Throws for an invalid key. */
     delete(key: string): Promise<void>;
+    /** Removes every `prefix + key`. Throws for an invalid key, before deleting any. */
     deleteMany(keys: readonly string[]): Promise<void>;
+    /** The underlying store's URL for `prefix + key`, or `null`. Throws for an invalid key. */
     getUri(key: string): Promise<string | null>;
+    /** Lists keys under `prefix` (relative to this store's prefix) in the underlying store's order, with this store's prefix removed. */
     listKeys(prefix?: string): Promise<readonly string[]>;
+    /** Paged listing with this store's prefix removed from keys and from `next`; present only when the store underneath has `listPage`. */
+    listPage?: (prefix: string, options?: {
+        readonly after?: string;
+        readonly limit?: number;
+    }) => Promise<{
+        readonly keys: readonly string[];
+        readonly next: string | null;
+    }>;
+    /** A store scoped to this prefix followed by `subPrefix`, over the same underlying store (`a/` then `b/` is `a/b/`). */
     withPrefix(subPrefix: string): ObjectStore;
 }

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

@@ -1,4 +1,5 @@
 import { assertLogicalObjectKey } from './namespace-guard.js';
+/** Returns `prefix` with exactly one trailing `/` added when missing. Throws `ObjectStoreWithPrefix: prefix must be non-empty` for an empty prefix. */
 export function normalizeObjectStorePrefix(prefix) {
     if (prefix.length === 0) {
         throw new Error('ObjectStoreWithPrefix: prefix must be non-empty');
@@ -12,6 +13,10 @@ function joinObjectStorePrefixes(left, right) {
  * Decorator that scopes every {@link ObjectStore} operation to a fixed key
  * prefix. Used at composition roots (e.g. API bindings) so feature code uses
  * logical keys while a shared bucket stays partitioned by prefix.
+ *
+ * Keys passed to `get`, `put`, `head`, `delete`, `deleteMany`, `getUri` are checked (`assertLogicalObjectKey`: not
+ * empty, no leading `/`, no `..`) and throw otherwise. The `prefix` argument of `listKeys` and `listPage` is not
+ * checked here; the store underneath is responsible for it. Returned keys have the prefix removed.
  */
 export class ObjectStoreWithPrefix {
     inner;
@@ -19,34 +24,51 @@ export class ObjectStoreWithPrefix {
     constructor(inner, prefix) {
         this.inner = inner;
         this.prefix = normalizeObjectStorePrefix(prefix);
+        const paged = inner.listPage;
+        if (paged) {
+            this.listPage = async (listPrefix, options = {}) => {
+                const page = await paged.call(inner, `${this.prefix}${listPrefix}`, { ...options, ...(options.after === undefined ? {} : { after: `${this.prefix}${options.after}` }) });
+                return { keys: page.keys.map(key => key.slice(this.prefix.length)), next: page.next === null ? null : page.next.slice(this.prefix.length) };
+            };
+        }
     }
     scopedKey(key) {
         assertLogicalObjectKey(key);
         return `${this.prefix}${key}`;
     }
+    /** Reads `prefix + key` from the underlying store; `null` when missing. Throws for an invalid key. */
     get(key) {
         return this.inner.get(this.scopedKey(key));
     }
+    /** Writes `prefix + key` in the underlying store. Throws for an invalid key. */
     put(key, bytes, contentType) {
         return this.inner.put(this.scopedKey(key), bytes, contentType);
     }
+    /** Whether `prefix + key` exists in the underlying store. Throws for an invalid key. */
     head(key) {
         return this.inner.head(this.scopedKey(key));
     }
+    /** Removes `prefix + key`; a no-op when missing. Throws for an invalid key. */
     delete(key) {
         return this.inner.delete(this.scopedKey(key));
     }
+    /** Removes every `prefix + key`. Throws for an invalid key, before deleting any. */
     deleteMany(keys) {
         return this.inner.deleteMany(keys.map((key) => this.scopedKey(key)));
     }
+    /** The underlying store's URL for `prefix + key`, or `null`. Throws for an invalid key. */
     getUri(key) {
         return this.inner.getUri(this.scopedKey(key));
     }
+    /** Lists keys under `prefix` (relative to this store's prefix) in the underlying store's order, with this store's prefix removed. */
     async listKeys(prefix = '') {
         const scopedPrefix = `${this.prefix}${prefix}`;
         const keys = await this.inner.listKeys(scopedPrefix);
         return keys.map((k) => k.slice(this.prefix.length));
     }
+    /** Paged listing with this store's prefix removed from keys and from `next`; present only when the store underneath has `listPage`. */
+    listPage;
+    /** A store scoped to this prefix followed by `subPrefix`, over the same underlying store (`a/` then `b/` is `a/b/`). */
     withPrefix(subPrefix) {
         return new ObjectStoreWithPrefix(this.inner, joinObjectStorePrefixes(this.prefix, subPrefix));
     }

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

@@ -0,0 +1,89 @@
+/**
+ * @module Stores named by URL
+ *
+ * Turns a store name (`./folder`, `s3://bucket/prefix`, `r2://…`, `gs://…`, `https://atlas.example.com`) into an opened
+ * `ObjectStore`, and a list of names (`ATLAS_STORE`, `--store`) into backends with unique ids. Secrets never travel in a
+ * URL: S3 credentials come from the environment, an Atlas server's token from `ATLAS_TOKEN` (or `ATLAS_TOKEN_<ID>` for a
+ * named store when several servers are used), and a token is never sent to a server over plain `http://` beyond this machine.
+ *
+ * @see docs/deploying.md#1-where-results-are-kept
+ */
+import type { BackendInput } from './compose.js';
+import type { ObjectStore } from './object-store.js';
+import { type HttpStore } from './http-store.js';
+import { type S3Store } from './s3-store.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/** Where a store is, parsed: a `directory`, an S3-compatible `s3` bucket and prefix (with region, endpoint and addressing), or an Atlas `server` URL. */
+export type StoreLocation = {
+    readonly kind: 'directory';
+    readonly directory: string;
+} | {
+    readonly kind: 's3';
+    readonly bucket: string;
+    readonly prefix: string;
+    readonly region?: string;
+    readonly endpoint?: string;
+    readonly pathStyle?: boolean;
+}
+/** An Atlas server: uploads go to it, and it shows everyone the combined report. */
+ | {
+    readonly kind: 'server';
+    readonly url: string;
+};
+/** A store opened from a location: the `ObjectStore`, a `label` for people, the parsed `location`, and, by kind, the `s3` or `server` store with its extra methods. */
+export type OpenedStore = {
+    readonly store: ObjectStore;
+    /** What to show people: no credentials, ever. */
+    readonly label: string;
+    readonly location: StoreLocation;
+    /** The S3 handle, for credential source and ping. */
+    readonly s3?: S3Store;
+    /** The server handle, for ping. */
+    readonly server?: HttpStore;
+};
+/**
+ * Where a store is, from one string:
+ *
+ * - `./atlas-reports`, `/srv/atlas`, `file:///srv/atlas`: a directory.
+ * - `s3://bucket/prefix`: S3. Add `?region=eu-west-1`, `?endpoint=https://…` for R2, MinIO and the
+ *   rest, `?pathStyle=1`. Keys are never in the URL: they come from the environment (see
+ *   `credentialChain`).
+ * - `r2://bucket/prefix?account=<id>` (Cloudflare R2) and `gs://bucket/prefix` (Google Cloud Storage with
+ *   HMAC keys): the same store with the endpoint filled in. Atlas does not test against these two.
+ */
+export declare function parseStoreLocation(spec: string, base: string, env?: Env): StoreLocation;
+/** Which store this is among those opened together, so a token goes only to the server it is for. */
+export type StoreRole = {
+    readonly id: string; /** The only Atlas server among them: the one `ATLAS_TOKEN` is for. */
+    readonly soleServer: boolean;
+};
+/**
+ * Opens one store from its name. A directory is not created here (commands that write create it). Throws for a name it cannot make sense of, and for a token that would be sent over plain `http://` beyond this machine.
+ *
+ * @example
+ * const { store } = openStore('s3://my-bucket/atlas/my-project?region=us-east-1', { base: process.cwd(), env: process.env });
+ */
+export declare function openStore(spec: string, options: {
+    readonly base: string;
+    readonly env?: Env;
+    readonly fetch?: typeof fetch;
+    readonly role?: StoreRole;
+}): OpenedStore;
+/**
+ * The token a client sends to one Atlas server. `ATLAS_TOKEN_<ID>` (or the first line of the file `ATLAS_TOKEN_FILE_<ID>`
+ * names) is for the store called `<ID>`; `ATLAS_TOKEN` / `ATLAS_TOKEN_FILE` is for the only server there is. With
+ * several servers, `ATLAS_TOKEN` is for none of them: a token is a secret of one server, never sent to another.
+ */
+export declare function serverToken(env: Env, role?: StoreRole, readFile?: (file: string) => string | null): string | null;
+/** A short id for a store, unique among the given ones: `my-bucket-ci`, `reports`. */
+export declare function storeId(location: StoreLocation, taken: ReadonlySet<string>): string;
+/** `--store` values, or `ATLAS_STORE` when there are none: one store, or several separated by commas or new lines (a folder may have spaces in its name). */
+export declare function storeSpecs(flags: readonly string[], env: Env): string[];
+/** `id=url` or a bare url, opened and given a unique id. */
+export declare function openBackends(specs: readonly string[], options: {
+    readonly base: string;
+    readonly env?: Env;
+    readonly fetch?: typeof fetch;
+    readonly mustExist?: boolean;
+}): (BackendInput & OpenedStore)[];
+export {};

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

@@ -0,0 +1,160 @@
+/**
+ * @module Stores named by URL
+ *
+ * Turns a store name (`./folder`, `s3://bucket/prefix`, `r2://…`, `gs://…`, `https://atlas.example.com`) into an opened
+ * `ObjectStore`, and a list of names (`ATLAS_STORE`, `--store`) into backends with unique ids. Secrets never travel in a
+ * URL: S3 credentials come from the environment, an Atlas server's token from `ATLAS_TOKEN` (or `ATLAS_TOKEN_<ID>` for a
+ * named store when several servers are used), and a token is never sent to a server over plain `http://` beyond this machine.
+ *
+ * @see docs/deploying.md#1-where-results-are-kept
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { directoryStore } from './directory-store.js';
+import { httpStore } from './http-store.js';
+import { s3Store } from './s3-store.js';
+/**
+ * Where a store is, from one string:
+ *
+ * - `./atlas-reports`, `/srv/atlas`, `file:///srv/atlas`: a directory.
+ * - `s3://bucket/prefix`: S3. Add `?region=eu-west-1`, `?endpoint=https://…` for R2, MinIO and the
+ *   rest, `?pathStyle=1`. Keys are never in the URL: they come from the environment (see
+ *   `credentialChain`).
+ * - `r2://bucket/prefix?account=<id>` (Cloudflare R2) and `gs://bucket/prefix` (Google Cloud Storage with
+ *   HMAC keys): the same store with the endpoint filled in. Atlas does not test against these two.
+ */
+export function parseStoreLocation(spec, base, env = {}) {
+    // Shorthands for two services that speak S3's protocol, so there is no endpoint to look up.
+    const shorthand = /^(r2|gs):\/\/(.*)$/i.exec(spec);
+    if (shorthand) {
+        const kind = shorthand[1].toLowerCase();
+        const url = new URL(`s3://${shorthand[2]}`);
+        const account = url.searchParams.get('account') ?? env.R2_ACCOUNT_ID ?? env.CLOUDFLARE_ACCOUNT_ID;
+        if (kind === 'r2' && !account)
+            throw new Error('An r2:// store needs the Cloudflare account id: r2://bucket/folder?account=<id>, or set R2_ACCOUNT_ID');
+        url.searchParams.delete('account');
+        url.searchParams.set('endpoint', kind === 'r2' ? `https://${account}.r2.cloudflarestorage.com` : 'https://storage.googleapis.com');
+        if (!url.searchParams.has('region'))
+            url.searchParams.set('region', 'auto');
+        return parseStoreLocation(url.toString(), base, env);
+    }
+    if (/^s3:\/\//i.test(spec)) {
+        const url = new URL(spec);
+        const bucket = decodeURIComponent(url.hostname);
+        if (!bucket)
+            throw new Error(`"${spec}" names no bucket. Write s3://<bucket>/<folder>`);
+        if (url.username || url.password)
+            throw new Error('Keys do not belong in a store URL: put them in AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (or ATLAS_S3_*), or sign in with `aws sso login`.');
+        const prefix = decodeURIComponent(url.pathname).replace(/^\/+|\/+$/g, '');
+        const region = url.searchParams.get('region') ?? undefined;
+        const endpoint = url.searchParams.get('endpoint') ?? undefined;
+        const pathStyle = url.searchParams.get('pathStyle');
+        return { kind: 's3', bucket, prefix, ...(region ? { region } : {}), ...(endpoint ? { endpoint } : {}), ...(pathStyle ? { pathStyle: pathStyle !== '0' && pathStyle !== 'false' } : {}) };
+    }
+    if (/^https?:\/\//i.test(spec)) {
+        const url = new URL(spec);
+        if (url.username || url.password)
+            throw new Error('A token does not belong in a server URL: set ATLAS_TOKEN.');
+        return { kind: 'server', url: `${url.origin}${url.pathname.replace(/\/+$/, '')}` };
+    }
+    if (/^[a-z][a-z0-9+.-]+:\/\//i.test(spec) && !/^file:\/\//i.test(spec))
+        throw new Error(`Unsupported store "${spec}". Use a directory, an Atlas server (https://…), s3://bucket/prefix, r2://bucket/prefix?account=<id> or gs://bucket/prefix`);
+    return { kind: 'directory', directory: /^file:\/\//i.test(spec) ? fileURLToPath(spec) : path.resolve(base, spec) };
+}
+/**
+ * Opens one store from its name. A directory is not created here (commands that write create it). Throws for a name it cannot make sense of, and for a token that would be sent over plain `http://` beyond this machine.
+ *
+ * @example
+ * const { store } = openStore('s3://my-bucket/atlas/my-project?region=us-east-1', { base: process.cwd(), env: process.env });
+ */
+export function openStore(spec, options) {
+    const location = parseStoreLocation(spec, options.base, options.env ?? {});
+    if (location.kind === 'directory')
+        return { store: directoryStore(location.directory), label: location.directory, location };
+    if (location.kind === 'server') {
+        const env = options.env ?? {};
+        const token = serverToken(env, options.role ?? { id: '', soleServer: true });
+        if (token)
+            refuseClearToken(location.url, env);
+        const server = httpStore({ url: location.url, ...(env.ATLAS_PROJECT ? { project: env.ATLAS_PROJECT } : {}), ...(token ? { token } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) });
+        return { store: server, label: server.label, location, server };
+    }
+    const s3 = s3Store({
+        bucket: location.bucket,
+        prefix: location.prefix,
+        ...(location.region ? { region: location.region } : {}),
+        ...(location.endpoint ? { endpoint: location.endpoint } : {}),
+        ...(location.pathStyle !== undefined ? { forcePathStyle: location.pathStyle } : {}),
+        ...(options.env ? { env: options.env } : {}),
+        ...(options.fetch ? { fetch: options.fetch } : {})
+    });
+    return { store: s3, label: s3.label, location, s3 };
+}
+/**
+ * The token a client sends to one Atlas server. `ATLAS_TOKEN_<ID>` (or the first line of the file `ATLAS_TOKEN_FILE_<ID>`
+ * names) is for the store called `<ID>`; `ATLAS_TOKEN` / `ATLAS_TOKEN_FILE` is for the only server there is. With
+ * several servers, `ATLAS_TOKEN` is for none of them: a token is a secret of one server, never sent to another.
+ */
+export function serverToken(env, role = { id: '', soleServer: true }, readFile = file => { try {
+    return readFileSync(file, 'utf8');
+}
+catch {
+    return null;
+} }) {
+    const suffix = role.id ? `_${role.id.toUpperCase().replace(/[^A-Z0-9]/g, '_')}` : null;
+    const named = suffix ? env[`ATLAS_TOKEN${suffix}`] : undefined;
+    if (named)
+        return named.trim();
+    const namedFile = suffix ? env[`ATLAS_TOKEN_FILE${suffix}`] : undefined;
+    if (namedFile)
+        return readFile(namedFile)?.split('\n')[0]?.trim() || null;
+    if (!role.soleServer)
+        return null;
+    if (env.ATLAS_TOKEN)
+        return env.ATLAS_TOKEN.trim();
+    if (env.ATLAS_TOKEN_FILE)
+        return readFile(env.ATLAS_TOKEN_FILE)?.split('\n')[0]?.trim() || null;
+    return null;
+}
+/** A token over plain `http` crosses the network readable by anyone on it: only to this machine, unless the network is said to be trusted. */
+function refuseClearToken(url, env) {
+    const { protocol, hostname } = new URL(url);
+    if (protocol === 'https:' || ['localhost', '127.0.0.1', '[::1]', '::1'].includes(hostname) || env.ATLAS_TRUST_NETWORK === '1')
+        return;
+    throw new Error(`Not sending a token to ${hostname} over plain http: anyone on the network could read it. Use https://, or set ATLAS_TRUST_NETWORK=1 if this network is yours.`);
+}
+/** A short id for a store, unique among the given ones: `my-bucket-ci`, `reports`. */
+export function storeId(location, taken) {
+    const raw = location.kind === 's3' ? [location.bucket, location.prefix].filter(Boolean).join('-') : location.kind === 'server' ? new URL(location.url).host : path.basename(location.directory);
+    const base = raw.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'store';
+    let id = base;
+    for (let n = 2; taken.has(id); n++)
+        id = `${base}-${n}`;
+    return id;
+}
+/** `--store` values, or `ATLAS_STORE` when there are none: one store, or several separated by commas or new lines (a folder may have spaces in its name). */
+export function storeSpecs(flags, env) {
+    if (flags.length)
+        return [...flags];
+    return (env.ATLAS_STORE ?? '').split(/[\n,]+/).map(spec => spec.trim()).filter(Boolean);
+}
+/** `id=url` or a bare url, opened and given a unique id. */
+export function openBackends(specs, options) {
+    const taken = new Set();
+    const named = specs.map(spec => /^([a-z0-9-]+)=(.+)$/.exec(spec)).flatMap(match => (match ? [match[1]] : []));
+    for (const id of named) {
+        if (taken.has(id))
+            throw new Error(`Two stores are named "${id}"`);
+        taken.add(id);
+    }
+    const servers = specs.filter(spec => /^https?:\/\//i.test(spec.replace(/^[a-z0-9-]+=/, ''))).length;
+    return specs.map(spec => {
+        const match = /^([a-z0-9-]+)=(.+)$/.exec(spec);
+        const target = match ? match[2] : spec;
+        const id = match ? match[1] : storeId(parseStoreLocation(target, options.base, options.env ?? {}), taken);
+        const opened = openStore(target, { ...options, role: { id, soleServer: servers === 1 } });
+        taken.add(id);
+        return { ...opened, id, label: match ? id : opened.location.kind === 'directory' ? path.basename(opened.location.directory) : opened.label };
+    });
+}

package/dist/reports/src/test-catalog-entity.d.ts

@@ -1,3 +1,14 @@
+/**
+ * @module Test as a catalog row
+ *
+ * Maps a recorded test to the flat row the viewer's searchable, groupable list draws.
+ */
 import type { HtmlReportTest } from './recording-bundle.js';
 import type { CatalogEntity } from './catalog.js';
+/**
+ * Flattens a recorded test into a `CatalogEntity`: its id, title, status and duration; the base name of its source
+ * file; the package (the part of the viewer test id's source before `--`, or `report`); its runtime; and the first
+ * line of its error as the detail. `search` joins the title, ids, paths, system, runtime, package and error for text
+ * matching. `href` is `null`; the caller sets where a row links to.
+ */
 export declare function testCatalogEntity(test: HtmlReportTest): CatalogEntity;