@crvouga/atlas 0.4.0 → 0.6.0

package/dist/playwright/src/media.js

@@ -1,8 +1,19 @@
+/**
+ * @module Playwright screenshots, clips and paced actions
+ *
+ * The media side of the Playwright driver: `UserActions` taps and types like a person (pausing, and drawing a touch
+ * indicator in showcase videos) while logging each action to the step's timeline; `captureScreen` takes a settled,
+ * deterministic screenshot at device resolution plus a WebP thumbnail; `ScreencastRecorder` records an H.264 clip at
+ * device resolution; `ffmpeg` runs the `ffmpeg` binary, which must be on the PATH for thumbnails and clips.
+ *
+ * @see docs/statecharts.md
+ */
 import { spawn } from 'node:child_process';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { locate } from './signals.js';
 const isLocator = (target) => 'waitFor' in target;
+/** The default pacing of showcase mode: a visible glide and pauses, so a person can follow the clip. */
 export const SHOWCASE_PACING = {
     moveMs: 600,
     pauseBeforeTapMs: 300,
@@ -10,6 +21,7 @@ export const SHOWCASE_PACING = {
     holdAfterMs: 1000,
     holdBeforeMs: 500
 };
+/** No pauses at all; the pacing of fast mode. */
 export const FAST_PACING = {
     moveMs: 0,
     pauseBeforeTapMs: 0,
@@ -17,6 +29,10 @@ export const FAST_PACING = {
     holdAfterMs: 0,
     holdBeforeMs: 0
 };
+/**
+ * The default `device` of `playwrightDriver`: a 390 by 844 CSS pixel viewport at device scale factor 3 (screenshots
+ * are 1170 by 2532 pixels), a mobile user agent and touch.
+ */
 export const PHONE = {
     viewport: { width: 390, height: 844 },
     deviceScaleFactor: 3,
@@ -66,7 +82,10 @@ const TOUCH_OVERLAY = `(() => {
   };
   if (document.documentElement) install(); else document.addEventListener('DOMContentLoaded', install);
 })();`;
-/** Taps and typing a person would do, paced for showcase videos and logged to the step timeline. */
+/**
+ * Taps and typing a person would do, paced for showcase videos and logged to the step timeline. Provided to event
+ * implementations as `user` on the `PlaywrightContext`. `showTouches` turns on the touch indicator (showcase mode).
+ */
 export class UserActions {
     page;
     pacing;
@@ -78,6 +97,10 @@ export class UserActions {
         this.timeline = timeline;
         this.showTouches = showTouches;
     }
+    /**
+     * Registers the touch indicator overlay to be added to every page load, so it exists before the app's scripts run.
+     * Call it once per page, before navigating.
+     */
     static async install(page) {
         await page.addInitScript(TOUCH_OVERLAY);
     }
@@ -91,7 +114,13 @@ export class UserActions {
         }, { fn, args })
             .catch(() => undefined);
     }
-    /** Tap a locator or a signal (resolved with `locate`). */
+    /**
+     * Taps the centre of a locator or a signal (resolved with `locate`). Waits up to 15 s for it to be visible, scrolls
+     * it
+     * into view, logs a `tap` entry labelled `label` to the timeline, then clicks (10 s timeout). In showcase mode the
+     * touch
+     * indicator glides there first. Throws when the target has no position on screen.
+     */
     async tap(target, label) {
         const locator = isLocator(target) ? target : locate(this.page, target);
         await locator.waitFor({ state: 'visible', timeout: 15_000 });
@@ -113,6 +142,10 @@ export class UserActions {
             await this.overlay('press', false);
         }
     }
+    /**
+     * Taps `target`, clears it, then types `text` one character at a time, `pacing.typeDelayMs` apart. Logs a `tap` and
+     * a `type` entry labelled `label` to the timeline.
+     */
     async type(target, text, label) {
         const locator = isLocator(target) ? target : locate(this.page, target);
         await this.tap(locator, label);
@@ -120,18 +153,26 @@ export class UserActions {
         await locator.fill('');
         await locator.pressSequentially(text, { delay: this.pacing.typeDelayMs });
     }
+    /** Waits `ms` milliseconds; does nothing when `ms` is zero or less. */
     async hold(ms) {
         if (ms > 0)
             await this.page.waitForTimeout(ms);
     }
+    /** Hides the touch indicator, so a screenshot does not show it. */
     async hideTouches() {
         await this.overlay('visible', false);
     }
+    /** Shows the touch indicator again after `hideTouches`. */
     async showTouchLayer() {
         await this.overlay('visible', true);
     }
 }
-/** A settled, deterministic capture at device resolution, with the touch layer hidden. */
+/**
+ * Takes a settled, deterministic screenshot at device resolution, with the touch layer hidden: waits for the network to
+ * go quiet (up to 5 s) and for fonts, disables animations and hides the caret. Writes the PNG to `file` (creating its
+ * folder) and a 400 px wide WebP thumbnail beside it with FFmpeg. `mask` lists locators to paint over. Rejects when
+ * FFmpeg is missing or fails.
+ */
 export async function captureScreen(page, driver, file, mask = []) {
     mkdirSync(path.dirname(file), { recursive: true });
     await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => undefined);
@@ -160,6 +201,10 @@ export async function captureScreen(page, driver, file, mask = []) {
     ]);
     return { png: file, webp };
 }
+/**
+ * Runs `ffmpeg` with `args` and resolves when it exits with code 0. Rejects with the spawn error when `ffmpeg` is not
+ * on the PATH, or with `ffmpeg <code>: <stderr>` when it fails.
+ */
 export function ffmpeg(args) {
     return new Promise((resolve, reject) => {
         const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
@@ -170,7 +215,7 @@ export function ffmpeg(args) {
     });
 }
 /**
- * Records a clip at the phone's physical resolution (1170×2532). Chrome's screencast, and
+ * Records a clip of a page at its physical resolution (1170×2532 for the default `PHONE`). Chrome's screencast, and
  * Playwright's built-in video that rides on it, only deliver CSS-pixel frames (390×844) and
  * upscale them, so text goes soft. Instead this loops device-scale JPEG captures (about 20 fps
  * here), keeps each frame's own timestamp, and encodes H.264 at 30 fps, holding each frame for as
@@ -189,6 +234,7 @@ export class ScreencastRecorder {
         this.page = page;
         this.scale = scale;
     }
+    /** Begins capturing frames of the page into `workDirectory`, which is emptied first. Call `stop` to encode them. */
     async start(workDirectory) {
         this.directory = workDirectory;
         rmSync(workDirectory, { recursive: true, force: true });
@@ -220,6 +266,11 @@ export class ScreencastRecorder {
             }
         })();
     }
+    /**
+     * Stops capturing and encodes the frames to the MP4 file `output` (the poster is written beside it, with `.mp4`
+     * replaced by `.poster.webp`), then deletes the work directory. Resolves to `{ video, poster, durationMs }`, or
+     * `null` when no frame was captured.
+     */
     async stop(output) {
         this.stoppedAt = Date.now();
         this.running = false;

package/dist/playwright/src/signals.d.ts

@@ -1,24 +1,63 @@
+/**
+ * @module Playwright signal helpers
+ *
+ * Maps the driver-neutral `Signal` values (test ID, role, label, text, CSS) to Playwright locators, and builds state
+ * recognisers from them: `recognize` evaluates a UI signature, `checkSignals` verifies quoted spec text is on screen,
+ * and `screen` wraps both into a `StateImplementation` for any context that exposes `page`. Also re-exports the
+ * signal constructors so an implementation imports everything from `@crvouga/atlas/playwright`. Visibility always
+ * means the first visible match.
+ *
+ * @see docs/statecharts.md
+ */
 import type { CheckResult, RecognizerResult, StateImplementation } from '../../core/src/index.js';
 import type { Signal } from '../../core/src/signals.js';
 import type { Locator, Page } from 'playwright';
 export { css, describeSignal, label, role, testId, text, type Signal } from '../../core/src/signals.js';
-/** A signal as a Playwright locator: the first visible match, with Playwright's own role and text rules. */
+/**
+ * Resolves a `Signal` to a Playwright locator for the first visible match, using Playwright's own role, label and
+ * text rules (text matches are substrings unless `exact`).
+ */
 export declare function locate(page: Page, signal: Signal): Locator;
+/**
+ * A state's UI signature: every `all` signal visible, at least one `any` signal visible (when `any` is given), and no
+ * `none` signal visible.
+ */
 export type SignatureSpec = {
     all?: Signal[];
     any?: Signal[];
     none?: Signal[];
 };
-/** Recognise a state from its UI signature: every `all` visible, one `any` visible, no `none`. */
+/**
+ * Recognises a state from its UI signature on `page`: every `all` signal visible, one `any` signal visible (when `any`
+ * is given), no `none` signal visible. Returns `matched` plus one entry per signal with what was expected and whether
+ * it
+ * was visible, which the report shows when the state is not recognised. A signal that cannot be evaluated counts as not
+ * visible.
+ */
 export declare function recognize(page: Page, spec: SignatureSpec): Promise<RecognizerResult>;
-/** Checks that a quoted piece of the spec is on screen; records expected and actual on failure. */
+/**
+ * Checks that each quoted piece of the spec (`check`) is visible on screen; returns one result per check, with
+ * `expected` and `actual` filled in.
+ */
 export declare function checkSignals(page: Page, checks: {
     check: string;
     signal: Signal;
 }[]): Promise<CheckResult[]>;
 /**
- * A state implementation from a UI signature, for a context that exposes `page`. Extra fields
- * (`lookIn`, `settle`, `transient`, `sameAs`, `checks`) pass through.
+ * Builds a state implementation from a UI signature, for a context that exposes `page` (the `PlaywrightContext`). The
+ * state is recognised as `recognize` describes; `checks` become the state's `meta.checks` results. The other fields
+ * (`lookIn`, `settle`, `transient`, `sameAs`) pass through to the `StateImplementation`.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { role, screen, text } from '@crvouga/atlas/playwright';
+ *
+ * const states = {
+ *   'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] })
+ * };
+ * ```
  */
 export declare function screen<C extends {
     page: Page;

package/dist/playwright/src/signals.js

@@ -1,6 +1,9 @@
 import { describeSignal } from '../../core/src/signals.js';
 export { css, describeSignal, label, role, testId, text } from '../../core/src/signals.js';
-/** A signal as a Playwright locator: the first visible match, with Playwright's own role and text rules. */
+/**
+ * Resolves a `Signal` to a Playwright locator for the first visible match, using Playwright's own role, label and
+ * text rules (text matches are substrings unless `exact`).
+ */
 export function locate(page, signal) {
     if ('testId' in signal)
         return page.getByTestId(signal.testId).filter({ visible: true }).first();
@@ -15,7 +18,13 @@ export function locate(page, signal) {
     return page.getByText(signal.text, signal.exact ? { exact: true } : {}).filter({ visible: true }).first();
 }
 const isVisible = (page, signal) => locate(page, signal).isVisible().catch(() => false);
-/** Recognise a state from its UI signature: every `all` visible, one `any` visible, no `none`. */
+/**
+ * Recognises a state from its UI signature on `page`: every `all` signal visible, one `any` signal visible (when `any`
+ * is given), no `none` signal visible. Returns `matched` plus one entry per signal with what was expected and whether
+ * it
+ * was visible, which the report shows when the state is not recognised. A signal that cannot be evaluated counts as not
+ * visible.
+ */
 export async function recognize(page, spec) {
     const signals = [];
     for (const s of spec.all ?? [])
@@ -31,7 +40,10 @@ export async function recognize(page, spec) {
         signals.push({ signal: describeSignal(s), expected: 'hidden', visible: await isVisible(page, s) });
     return { matched: signals.every((x) => (x.expected === 'visible' ? x.visible : !x.visible)), signals };
 }
-/** Checks that a quoted piece of the spec is on screen; records expected and actual on failure. */
+/**
+ * Checks that each quoted piece of the spec (`check`) is visible on screen; returns one result per check, with
+ * `expected` and `actual` filled in.
+ */
 export async function checkSignals(page, checks) {
     const results = [];
     for (const { check, signal } of checks) {
@@ -41,8 +53,20 @@ export async function checkSignals(page, checks) {
     return results;
 }
 /**
- * A state implementation from a UI signature, for a context that exposes `page`. Extra fields
- * (`lookIn`, `settle`, `transient`, `sameAs`, `checks`) pass through.
+ * Builds a state implementation from a UI signature, for a context that exposes `page` (the `PlaywrightContext`). The
+ * state is recognised as `recognize` describes; `checks` become the state's `meta.checks` results. The other fields
+ * (`lookIn`, `settle`, `transient`, `sameAs`) pass through to the `StateImplementation`.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { role, screen, text } from '@crvouga/atlas/playwright';
+ *
+ * const states = {
+ *   'No todos': screen({ all: [text('Nothing to do yet')], none: [role('listitem')] })
+ * };
+ * ```
  */
 export function screen(spec) {
     return {

package/dist/reports/src/attachment-files.d.ts

@@ -0,0 +1,44 @@
+type Loose = Record<string, unknown>;
+/** What {@link readAttachmentFiles} found. */
+export type AttachmentFileResult = {
+    /** A copy of the holder in which every readable `path` attachment became a `data` attachment (and `path` is gone). The input is not mutated. */
+    readonly value: Loose;
+    /** How many files were read. */
+    readonly attached: number;
+    /** The total size of those files, in bytes. */
+    readonly bytes: number;
+    /** One line per attachment that was left out (missing, not allowed, too large, over budget), prefixed with its name. */
+    readonly warnings: readonly string[];
+};
+/** A budget shared by every call of one publish, so many files cannot add up to more than can be held. */
+export type AttachmentBudget = {
+    /** Bytes still available; each file read subtracts its size. A file larger than this is left out, not truncated. */
+    remaining: number;
+};
+/** Options of {@link readAttachmentFiles}. */
+export type ReadOptions = {
+    /** Largest single file, in bytes. Default 512 MiB. */
+    readonly maxBytes?: number;
+    /** Shared total-size budget; mutated as files are read. Omit for no total limit. */
+    readonly budget?: AttachmentBudget;
+    /**
+     * A path the person running the command typed (`--attach`) is theirs to choose. A path inside a *report* is
+     * data from a test run, which is not: it may name only files inside `roots`, never a hidden file, and never a
+     * link that leads out.
+     */
+    readonly trusted?: boolean;
+};
+/**
+ * Reads the files that attachments name (`path`), at every level (the holder, its `steps` and its `attempts`,
+ * recursively), and hands their bytes over as `data` with a `contentType` guessed from the file name when the
+ * attachment gave none.
+ *
+ * A file that is missing, not allowed or too large is left out with a warning: evidence that could not be
+ * found never stops the results from being published. Attachments without a `path` are kept untouched.
+ *
+ * @param holder A check, step, attempt or any object that may have `attachments`, `steps` and `attempts`.
+ * @param roots Folders a relative path is resolved against (in order), and the only folders an untrusted path may name.
+ * @returns The rewritten copy, counts and warnings; never throws for a bad file.
+ */
+export declare function readAttachmentFiles(holder: Loose, roots: readonly string[], options?: ReadOptions): Promise<AttachmentFileResult>;
+export {};

package/dist/reports/src/attachment-files.js

@@ -0,0 +1,121 @@
+/**
+ * @module Reading the files attachments name
+ *
+ * Turns an attachment that names a file on disk (`path`) into one that carries its bytes (`data`), just before a
+ * layer is published. It owns the safety rules for doing so: a path that came from a test report may only name
+ * files inside the allowed roots, never a hidden file, and never a link that leads out; a path the person running
+ * the command typed is trusted. It does not upload anything. Node-only (reads the file system).
+ *
+ * @see docs/report-contract.md (evidence rule 7: paths inside a report are data from a test run)
+ */
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { contentTypeOf } from './media-types.js';
+/**
+ * Reads the files that attachments name (`path`), at every level (the holder, its `steps` and its `attempts`,
+ * recursively), and hands their bytes over as `data` with a `contentType` guessed from the file name when the
+ * attachment gave none.
+ *
+ * A file that is missing, not allowed or too large is left out with a warning: evidence that could not be
+ * found never stops the results from being published. Attachments without a `path` are kept untouched.
+ *
+ * @param holder A check, step, attempt or any object that may have `attachments`, `steps` and `attempts`.
+ * @param roots Folders a relative path is resolved against (in order), and the only folders an untrusted path may name.
+ * @returns The rewritten copy, counts and warnings; never throws for a bad file.
+ */
+export async function readAttachmentFiles(holder, roots, options = {}) {
+    const warnings = [];
+    const maxBytes = options.maxBytes ?? 512 * 1024 * 1024;
+    let attached = 0, bytes = 0;
+    async function walk(value) {
+        const out = { ...value };
+        if (Array.isArray(out.attachments)) {
+            const kept = [];
+            for (const given of out.attachments) {
+                const file = typeof given.path === 'string' ? given.path : undefined;
+                if (file === undefined) {
+                    kept.push(given);
+                    continue;
+                }
+                const name = String(given.name ?? file);
+                const { path: _path, ...rest } = given;
+                const found = await locate(file, roots, options.trusted === true);
+                if (found.problem) {
+                    warnings.push(`${name}: ${found.problem}`);
+                    continue;
+                }
+                const size = (await stat(found.file)).size;
+                if (size > maxBytes) {
+                    warnings.push(`${name}: ${(size / 1024 / 1024).toFixed(0)} MiB is over the limit of ${Math.round(maxBytes / 1024 / 1024)} MiB`);
+                    continue;
+                }
+                if (options.budget && size > options.budget.remaining) {
+                    warnings.push(`${name}: the total size of attachments would pass the budget (raise --max-total-attachment-mb, or attach a uri)`);
+                    continue;
+                }
+                if (options.budget)
+                    options.budget.remaining -= size;
+                attached += 1;
+                bytes += size;
+                kept.push({ ...rest, data: new Uint8Array(await readFile(found.file)), ...(rest.contentType ? {} : { contentType: contentTypeOf(found.file) }) });
+            }
+            out.attachments = kept;
+        }
+        if (Array.isArray(out.steps)) {
+            const steps = [];
+            for (const step of out.steps)
+                steps.push(await walk(step));
+            out.steps = steps;
+        }
+        if (Array.isArray(out.attempts)) {
+            const attempts = [];
+            for (const attempt of out.attempts)
+                attempts.push(await walk(attempt));
+            out.attempts = attempts;
+        }
+        return out;
+    }
+    return { value: await walk(holder), attached, bytes, warnings };
+}
+/** Is `file` inside `root`, once both are real paths (so a link cannot lead out)? */
+function inside(file, root) {
+    const relative = path.relative(root, file);
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+// Resolves a named file to a real path, or says why not. A trusted path may also be relative to the working
+// directory; an untrusted one must land, after resolving links, inside a root and under no dot-named part.
+async function locate(file, roots, trusted) {
+    const candidates = path.isAbsolute(file) ? [file] : [...roots.map(root => path.resolve(root, file)), ...(trusted ? [path.resolve(file)] : [])];
+    let outside = false;
+    for (const candidate of candidates) {
+        let real;
+        try {
+            real = await realpath(candidate);
+            if (!(await stat(real)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (trusted)
+            return { file: real };
+        const root = await firstRootHolding(real, roots);
+        // A hidden file or folder (.env, .aws, .git, .ssh) is never attached on a report's say-so.
+        if (!root || path.relative(root, real).split(path.sep).some(part => part.startsWith('.'))) {
+            outside = true;
+            continue;
+        }
+        return { file: real };
+    }
+    return { problem: outside ? `${file} is outside the folders reports may attach from (the report's own folder and each --attach-root), or is a hidden file: pass --attach-root <dir> to allow a folder` : `file not found (${file})` };
+}
+async function firstRootHolding(real, roots) {
+    for (const root of roots) {
+        try {
+            if (inside(real, await realpath(root)))
+                return await realpath(root);
+        }
+        catch { /* a root that is not there holds nothing */ }
+    }
+    return null;
+}

package/dist/reports/src/attachment-response.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module Serving attachment bytes safely
+ *
+ * Builds the HTTP response for an attachment's bytes. A producer chose the media type, and the bytes come from a
+ * test run, so they are treated as untrusted: never sniffed, never allowed to run scripts, never embedded by
+ * another site. Videos can be sought (HTTP range requests). Every route that serves attachment bytes must go
+ * through here (or add {@link UNTRUSTED_HEADERS}); it never reads from a store itself.
+ *
+ * @see docs/report-contract.md (evidence rule 8)
+ */
+/**
+ * Headers for bytes that came from a test run: never sniffed (`nosniff`), a sandboxing content-security policy so a
+ * page navigated to at this address runs locked down, and `cross-origin-resource-policy: same-origin` so
+ * another site cannot embed it. Spread these into every response that serves attachment or recorded bytes.
+ */
+export declare const UNTRUSTED_HEADERS: Readonly<Record<string, string>>;
+/**
+ * Answers a request for one attachment's bytes with the untrusted-bytes headers, long-lived immutable caching
+ * and range support.
+ *
+ * The producer's `contentType` is used only when it is a well-formed media type (`type/subtype` with simple
+ * parameters); anything else is served as `application/octet-stream`. A matching `if-none-match` answers 304.
+ * A single `bytes=a-b`, `bytes=a-` or `bytes=-n` range answers 206, an unsatisfiable one 416; multiple ranges are
+ * not understood and get the whole body (200).
+ *
+ * @param etag A strong validator the caller derives from content identity (it is sent as given, so include the quotes).
+ */
+export declare function attachmentResponse(request: Request, entry: {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}, etag: string): Response;

package/dist/reports/src/attachment-response.js

@@ -0,0 +1,55 @@
+/**
+ * @module Serving attachment bytes safely
+ *
+ * Builds the HTTP response for an attachment's bytes. A producer chose the media type, and the bytes come from a
+ * test run, so they are treated as untrusted: never sniffed, never allowed to run scripts, never embedded by
+ * another site. Videos can be sought (HTTP range requests). Every route that serves attachment bytes must go
+ * through here (or add {@link UNTRUSTED_HEADERS}); it never reads from a store itself.
+ *
+ * @see docs/report-contract.md (evidence rule 8)
+ */
+/**
+ * Headers for bytes that came from a test run: never sniffed (`nosniff`), a sandboxing content-security policy so a
+ * page navigated to at this address runs locked down, and `cross-origin-resource-policy: same-origin` so
+ * another site cannot embed it. Spread these into every response that serves attachment or recorded bytes.
+ */
+export const UNTRUSTED_HEADERS = {
+    'x-content-type-options': 'nosniff',
+    // If a page is ever navigated to or framed from this address, it runs as a locked-down document.
+    'content-security-policy': "sandbox; default-src 'none'; img-src data:; media-src 'self'; style-src 'unsafe-inline'",
+    'cross-origin-resource-policy': 'same-origin'
+};
+/**
+ * Answers a request for one attachment's bytes with the untrusted-bytes headers, long-lived immutable caching
+ * and range support.
+ *
+ * The producer's `contentType` is used only when it is a well-formed media type (`type/subtype` with simple
+ * parameters); anything else is served as `application/octet-stream`. A matching `if-none-match` answers 304.
+ * A single `bytes=a-b`, `bytes=a-` or `bytes=-n` range answers 206, an unsatisfiable one 416; multiple ranges are
+ * not understood and get the whole body (200).
+ *
+ * @param etag A strong validator the caller derives from content identity (it is sent as given, so include the quotes).
+ */
+export function attachmentResponse(request, entry, etag) {
+    // A media type is a short token list; anything with line breaks or odd characters is not one.
+    const type = /^[\w.+-]+\/[\w.+-]+(?:\s*;\s*[\w.-]+=[\w.\-"]+)*$/.test(entry.contentType) ? entry.contentType : 'application/octet-stream';
+    const headers = {
+        'content-type': type,
+        ...UNTRUSTED_HEADERS,
+        'cache-control': 'public, max-age=31536000, immutable',
+        'accept-ranges': 'bytes',
+        etag
+    };
+    if (request.headers.get('if-none-match') === etag)
+        return new Response(null, { status: 304, headers });
+    const size = entry.bytes.length;
+    const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get('range') ?? '');
+    if (!range || (range[1] === '' && range[2] === ''))
+        return new Response(entry.bytes, { headers: { ...headers, 'content-length': String(size) } });
+    // `bytes=-500` is the last 500 bytes; `bytes=500-` is from 500 on.
+    const start = range[1] === '' ? Math.max(0, size - Number(range[2])) : Number(range[1]);
+    const end = range[1] === '' || range[2] === '' ? size - 1 : Math.min(Number(range[2]), size - 1);
+    if (start >= size || start > end)
+        return new Response(null, { status: 416, headers: { ...headers, 'content-range': `bytes */${size}` } });
+    return new Response(entry.bytes.slice(start, end + 1), { status: 206, headers: { ...headers, 'content-range': `bytes ${start}-${end}/${size}`, 'content-length': String(end - start + 1) } });
+}

package/dist/reports/src/aws-credentials.d.ts

@@ -0,0 +1,48 @@
+import type { Credentials } from './sigv4.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/**
+ * An async function returning currently valid credentials, with cache control. Concurrent calls share one lookup;
+ * cached credentials are reused until shortly before they expire (never, when they carry no expiry).
+ */
+export type CredentialProvider = (() => Promise<Credentials>) & {
+    /** Drop what is cached, so the next call asks again. Used when a store says the credentials expired. */
+    invalidate(): void;
+    /** Where the credentials came from, once known: "environment", "web identity (IRSA)", "profile prod", … */
+    source(): string | null;
+};
+/** Options of {@link credentialChain}; every one exists so a test can replace a piece of the machine. */
+export type ChainOptions = {
+    /** The environment variables to read. Default `process.env`. */
+    readonly env?: Env;
+    /** The HTTP client for STS, container and instance-metadata calls. Default global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Reads a UTF-8 file. Default `fs.readFile`. */
+    readonly readFile?: (file: string) => Promise<string>;
+    /** Run a command and return its stdout, or null when it is not installed or fails. Default spawns it with a 20 s timeout. */
+    readonly run?: (command: string, args: readonly string[]) => Promise<string | null>;
+    /** The clock, epoch milliseconds. Default `Date.now`. */
+    readonly now?: () => number;
+    /** The home directory that holds `.aws/credentials`. Default `$HOME`, then the OS home. */
+    readonly home?: string;
+    /** Refresh this long before credentials expire, in milliseconds. Default 5 minutes. */
+    readonly skewMs?: number;
+};
+/**
+ * Creates a provider for the credentials an AWS SDK would find, in the same order, with no SDK: environment, web
+ * identity (EKS), container (ECS), shared credentials file, the AWS CLI (which covers SSO and assumed roles),
+ * and EC2 instance metadata. `ATLAS_S3_ACCESS_KEY_ID` / `ATLAS_S3_SECRET_ACCESS_KEY` (and `ATLAS_S3_SESSION_TOKEN`)
+ * come first so one store can use keys that are not the machine's AWS keys, such as Cloudflare R2 tokens.
+ *
+ * Nothing is looked up until the provider is first called. The first source that yields credentials wins and
+ * is cached; a source that throws (for example an STS error) is skipped and reported if no later source works.
+ * When none works the provider rejects with an error that lists every source tried and how to fix it. Set
+ * `ATLAS_NO_AWS_CLI` to skip the `aws` CLI step and `AWS_EC2_METADATA_DISABLED=true` to skip instance metadata.
+ *
+ * @example
+ * const credentials = await credentialChain()();
+ * credentials.accessKeyId;
+ */
+export declare function credentialChain(options?: ChainOptions): CredentialProvider;
+/** Wraps keys that are already known in a {@link CredentialProvider} that never refreshes (its `invalidate` does nothing). */
+export declare function staticCredentials(credentials: Credentials): CredentialProvider;
+export {};