@crvouga/atlas 1.19.0 → 1.21.0

package/dist/server/src/recording-verification.js

@@ -0,0 +1,118 @@
+import { RecordingVerifyRequestSchema } from '../../schema/src/api.js';
+import { eachLimited } from '../../reports/src/completion-order.js';
+import { layerKey } from '../../reports/src/layer-store.js';
+import { verifyStoreRecordings } from '../../reports/src/recording-verify.js';
+import { runKey } from '../../reports/src/test-catalog.js';
+import { problemResponse } from './problem.js';
+import { readLimited } from './store-api.js';
+import { Refusal } from './validate.js';
+const NO_STORE = { 'cache-control': 'no-store' };
+const HELD_MS = 30_000;
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 200;
+/**
+ * Registers `GET` and `POST /api/reports/recordings/verification` on `app`. The result of the last read-back of each
+ * layer is held in memory, replaced by a newer one, and served only for layers a store still holds. A layer held by
+ * two backends keeps the reading with more gaps, so a copy that lost its blobs is never hidden by one that did not.
+ */
+export function mountRecordingVerification(app, deps) {
+    const { stores, auth, index, now } = deps;
+    const held = new Map();
+    let notices = [];
+    let running = false;
+    // Whether a layer's manifest is still in some store (garbage collection removes superseded layers), asked at most every
+    // HELD_MS. Only a `head` of the manifest: no recording is read.
+    const present = new Map();
+    const holds = async (ids) => {
+        const out = new Set();
+        await eachLimited(ids, 8, async (id) => {
+            const known = present.get(id);
+            let value = known !== undefined && now() - known.at < HELD_MS ? known.value : undefined;
+            if (value === undefined) {
+                value = false;
+                for (const store of stores) {
+                    if (await store.head(layerKey(id)).catch(() => false)) {
+                        value = true;
+                        break;
+                    }
+                }
+                present.set(id, { at: now(), value });
+            }
+            if (value)
+                out.add(id);
+        });
+        return out;
+    };
+    const document = async (request, extra = {}) => {
+        const search = new URL(request.url).searchParams;
+        const run = search.get('run');
+        const prefixes = search.getAll('layer').flatMap(value => value.split(',')).map(value => value.trim().toLowerCase()).filter(Boolean);
+        const wanted = [...held.values()].filter(entry => (!run || entry.run === run) && (!prefixes.length || prefixes.some(prefix => entry.layer.startsWith(prefix))));
+        const still = await holds(wanted.map(entry => entry.layer));
+        const layers = wanted.filter(entry => still.has(entry.layer))
+            .sort((a, b) => b.verifiedAtMs - a.verifiedAtMs || (a.layer < b.layer ? -1 : 1));
+        return { schemaVersion: 1, layers, notices, ...extra };
+    };
+    app.get('/api/reports/recordings/verification', async (c) => c.json(await document(c.req.raw), 200, NO_STORE));
+    app.post('/api/reports/recordings/verification', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return deps.unauthorized(verdict);
+        if (!index.ready)
+            return problemResponse(503, 'The report is still loading. Try again in a moment.', { 'retry-after': '2' });
+        let input = {};
+        try {
+            const bytes = await readLimited(c.req.raw, 16 * 1024);
+            if (bytes.length) {
+                try {
+                    input = JSON.parse(new TextDecoder().decode(bytes));
+                }
+                catch {
+                    return problemResponse(422, 'The body is not JSON.');
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Refusal)
+                return problemResponse(error.status, error.message);
+            throw error;
+        }
+        const parsed = RecordingVerifyRequestSchema.safeParse(input);
+        if (!parsed.success)
+            return problemResponse(422, `Not a verification request: ${parsed.error.issues[0]?.message ?? 'invalid'}.`);
+        if (running)
+            return problemResponse(409, 'A read-back is already running. Read the result with GET when it finishes.', { 'retry-after': '5' });
+        running = true;
+        try {
+            const limit = Math.min(MAX_LIMIT, parsed.data.limit ?? DEFAULT_LIMIT);
+            const runs = new Map();
+            const found = [];
+            const lost = [];
+            const at = now();
+            for (const store of stores) {
+                const result = await verifyStoreRecordings(store, {
+                    ...(parsed.data.layers?.length ? { ids: parsed.data.layers } : {}), limit,
+                    include: layer => { runs.set(layer.id, runKey(layer)); return true; }
+                });
+                lost.push(...result.notices);
+                for (const layer of result.layers)
+                    found.push({ ...layer, run: runs.get(layer.layer) ?? '', verifiedAtMs: at });
+            }
+            // A layer held by two backends keeps the copy with more gaps; a newer pass replaces an older one.
+            const fresh = new Map();
+            for (const entry of found)
+                if ((fresh.get(entry.layer)?.gaps.length ?? -1) < entry.gaps.length || !fresh.has(entry.layer))
+                    fresh.set(entry.layer, entry);
+            for (const [layer, entry] of fresh)
+                held.set(layer, entry);
+            notices = [...new Set(lost)];
+            return c.json(await document(c.req.raw, { verified: fresh.size }), 200, NO_STORE);
+        }
+        catch (error) {
+            return problemResponse(502, `The store could not be read: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        }
+        finally {
+            running = false;
+        }
+    });
+}

package/docs/agents.md

@@ -164,6 +164,11 @@ JSON Schema (`@crvouga/atlas/schemas/<name>.schema.json`, draft 2020-12):
 | `atlas report doctor` | `doctor-result` |
 | `atlas report status` | `report-status` |
 | `atlas report verify-recordings` | `verify-recordings-result` |
+| `atlas ui-catalog plan` | `ui-catalog-publish-result` |
+| `atlas ui-catalog publish` | `ui-catalog-publish-result` |
+| `atlas ui-catalog status` | `ui-catalog-status` |
+| `atlas ui-catalog diff` | `ui-catalog-diff-result` |
+| `atlas ui-catalog export` | `ui-catalog-export-result` |
 | `a command that was wrong (standard error)` | `command-error` |
 <!-- /generated:json-command-schemas -->
 

package/docs/reference/cli.md

@@ -2,7 +2,7 @@
 
 > Generated from the usage text each command prints (`atlas <command> --help`) by `bun run docs`. Do not edit.
 
-Add `--format json` (alias `--json`) to `init`, `report publish`, `stream`, `merge`, `doctor` and `status` for a JSON document on standard output (schemas in `@crvouga/atlas/schemas`). Exit codes: `0` it worked, `1` it ran and the answer is no, `2` the command was wrong.
+Add `--format json` (alias `--json`) to `init`, `report publish`, `stream`, `merge`, `doctor`, `status` and every `ui-catalog` command for a JSON document on standard output (schemas in `@crvouga/atlas/schemas`). Exit codes: `0` it worked, `1` it ran and the answer is no, `2` the command was wrong.
 
 ## atlas
 
@@ -21,6 +21,7 @@ atlas — executable statecharts
   atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
   atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
   atlas report publish|stream|status|merge|doctor|policy …       layered evidence for any kind of spec (atlas report --help)
+  atlas ui-catalog plan|publish|status|diff|export …              the UI catalog of captured states (atlas ui-catalog --help)
 
   --workers       path attempts that run at once (default: one per CPU, capped by the driver)
   --seed          only paths that start from this seed ("start" for paths setup starts); repeatable
@@ -172,3 +173,57 @@ atlas report — layered evidence for any kind of spec
 
   Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.
 ```
+
+## atlas ui-catalog
+
+```text
+atlas ui-catalog — a browsable inventory of captured UI states, from any collector
+
+  atlas ui-catalog plan    --states <file.json> --producer <name> [--store <dir|s3://bucket/prefix|https://…>]
+                           [--environment <name>] [--param key=value]... [--shard <label>]
+                           [--branch <b>] [--sha <s>] [--run-url <u>] [--run-id <id>] [--run-title <t>] [--recorded-at <iso|ms>]
+  atlas ui-catalog publish --captures <file.json> --producer <name> [the same flags as plan]
+                           [--attach-root <dir>]... [--max-picture-mb <n>]
+  atlas ui-catalog status  [--store <dir|s3://…|id=url>]... [--backends <module>] [filters] [--branch <name>]...
+                           [--ignore-modified] [--format text|json|markdown]
+  atlas ui-catalog diff    --from <commit> --to <commit> [--store …]... [--backends <module>] [filters]
+                           [--fail-on-change] [--format text|json|markdown]
+  atlas ui-catalog export  --out <file.html> [--store …]... [--backends <module>] [filters]
+                           [--images inline|none] [--max-mb <n>] [--manifest <file.json>] [--title <t>]
+
+  filters (status, diff, export): --q <words> --coverage a,b --profile <key|label>... --area a --route r --cohort c
+                           --flag f --surface s --producer p
+
+  plan      Write one layer of kind ui-plan: the states (and with "inventory": true, the surfaces) that should exist under
+            this profile. Every entry is not-run, so a plan never counts as a pass. The file is {"states":[{"id":…,
+            "title"?,"route"?,"fixture"?,"cohort"?,"area"?,"flags"?,"covers"?,"inventory"?}]} or just that list.
+  publish   Write one layer of kind ui-state: the states one collector or shard captured under this profile. The file is
+            {"states":[{"id":…,"title"?,"status"?:"passed|failed|running|not-run","detail"?,"route"?,"fixture"?,"cohort"?,
+            "area"?,"flags"?,"covers"?,"labels"?,"tags"?,"durationMs"?,"screenshot"?:"file.png"|{"path"|"uri",
+            "width"?,"height"?,"contentType"?}}]}. A picture file is read from beside the file and each --attach-root, never
+            from a hidden file or a link out. A passed state whose picture cannot be read is published as failed, with the
+            reason: a state without its picture is not shown as captured.
+            --environment and each --param key=value are the profile (a viewport, a color scheme, a device): another
+            profile is another result side by side. --shard only describes the layer; it never splits a result.
+            --recorded-at defaults to the modification time of the file, so publishing the same file twice is one layer.
+  status    Read every store and print the catalog's summary. Exit 1 unless the catalog holds a state and there is nothing
+            to attend to: a failed capture, a state a plan expects with nothing captured, a capture still in progress, a
+            backend or layer that could not be read. Without a plan nothing is expected, so nothing is missing.
+            --profile takes a profile's key or its label, as printed by status.
+  diff      Set the catalog recorded at one commit (--from) against another (--to): each state in each profile is paired
+            with itself and is unchanged, changed in coverage, changed in picture (the stored bytes differ), unverified (a
+            side has no content hash), only in --to (added) or only in --from (removed). A commit is the whole id or at
+            least 7 digits of it. Exit 0 unless a store could not be read, or, with --fail-on-change, anything differs.
+  export    Write the catalog as one HTML file with its pictures embedded and its manifest in it: no server, no network.
+            It is the catalog at the moment it was made. --images none leaves the pictures out. --max-mb (default 32) limits
+            the embedded pictures; those past it are listed in the page as left out, and the manifest stays complete.
+            --manifest writes the catalog's JSON manifest too.
+
+  --format json (alias --json)   every subcommand prints one JSON document instead of prose
+                       (schemas: ui-catalog-publish-result, ui-catalog-status, ui-catalog-diff-result, ui-catalog-export-result).
+                       A command that is wrong is {"ok":false,"error":{"message":…,"code":"usage"}} on standard error.
+  A store is a directory, s3://bucket/prefix or an Atlas server (https://…), exactly as for atlas report; select a project
+  with --project <slug> or ATLAS_PROJECT. When no --store is given, ATLAS_STORE is used.
+
+  Exit codes: 0 ok, 1 the answer is no (see each command), 2 the command was wrong.
+```

package/docs/reference/http-api.md

@@ -694,6 +694,58 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `201` The recorded entry.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `413` Request too large.; `422` Not a tag edit: a bad target, an empty or over-long tag, or nothing to change.
 
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Which stored recordings the server last read back, and which were gone or damaged
+
+`GET /api/projects/{project}/reports/recordings/verification` · role: read
+
+The newest read-back the server did of stored videos, per layer: how many it checked, how many passed and the `gaps` (a blob that is gone, bytes of another size or hash than were published, or a file that does not begin like its container), each naming the check that holds the video. `run` is the key of the run the layer belongs to (a `RunSummary.key`), so a viewer can mark that run's recordings as stored-then-unavailable beside its test results.
+
+This route never reads a blob: it returns what a publish token's `POST` found earlier. A layer that was never read back is absent, which means "not verified", not "fine"; the result is kept in the server's memory only, so a restart empties it. Only layers a store still holds are listed (one removed by garbage collection drops out). No status, slot or winner depends on it. It checks stored bytes, not browser playback. Narrow with `?run=` (a run key) and `?layer=` (an id prefix of at least 7 hex digits, repeatable).
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `run` (query): Only layers of this run (a key from `GET /api/reports/runs`).
+- `layer` (query): Only layers whose id starts with this prefix. Repeatable or comma-separated.
+
+Responses: `200` The held read-backs.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Read stored recordings back and check them (publish token)
+
+`POST /api/projects/{project}/reports/recordings/verification` · role: publish
+
+Reads the videos of the newest layers (`limit`, default 20, at most 200; or the layers `layers` names) back from storage and checks that each is still stored, still has the size and SHA-256 published, and still begins like its media type's container. This reads blobs, so it needs a publish (or admin) token in a Bearer header; a reader-only token, a browser sign-in box and an anonymous reader are refused. One read-back runs at a time (`409` otherwise). It writes nothing to storage and changes no status. The answer is the same document `GET` returns, with `verified`: how many layers this pass read back.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The read-backs now held.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` A read-back is already running.; `413` Request too large.; `422` Not a verification request.; `502` A store could not be read.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### Review collections: curated sets of recordings, newest first
 
 `GET /api/reports/review-collections` · role: read