@crvouga/atlas 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog: @crvouga/atlas
 
-## 1.19.0 (2026-10-29)
+## 1.21.0 (2026-10-29)
+
+### Features
+
+- add an atlas ui-catalog command group, a single-file export and comparison of commits and profiles ([3159315](https://github.com/crvouga/atlas/commit/3159315e9a1b057309b5b1eb2d745426885adfa8))
+
+## 1.20.0 (2026-10-28)
+
+### Features
+
+- mark stored-then-unavailable recordings in the Runs tab from a server read-back ([8c9370a](https://github.com/crvouga/atlas/commit/8c9370aecf67e2b2e690ba25ed512be36a137875))
+
+## 1.19.0 (2026-10-28)
 
 ### Features
 

package/dist/core/src/cli.d.ts

@@ -9,6 +9,6 @@
  * @see docs/reference/cli.md
  */
 /** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
-export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas server [--port 8080]                                     one Atlas node: API, projects and client; needs ATLAS_S3_* (atlas serve --help)\n  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client\n  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
+export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas server [--port 8080]                                     one Atlas node: API, projects and client; needs ATLAS_S3_* (atlas serve --help)\n  atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client\n  atlas dev    [--port 5180]                                     develop the Atlas server and client on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n  atlas ui-catalog plan|publish|status|diff|export \u2026              the UI catalog of captured states (atlas ui-catalog --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
 /** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
 export declare function main(argv?: string[]): Promise<number>;

package/dist/core/src/cli.js

@@ -33,6 +33,7 @@ export const USAGE = `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
@@ -105,6 +106,8 @@ export async function main(argv = process.argv.slice(2)) {
         return (await import('../../reports/src/init.js')).initMain(argv.slice(1), { out: text => process.stdout.write(text) });
     if (command === 'report')
         return (await import('../../reports/src/report-cli.js')).runReportCommand(argv.slice(1));
+    if (command === 'ui-catalog')
+        return (await import('../../reports/src/ui-catalog-cli.js')).runUiCatalogCommand(argv.slice(1));
     const configFile = flag(argv, 'config') ?? 'atlas.config.ts';
     const specs = flag(argv, 'specs');
     const output = flag(argv, 'output');

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

@@ -1,4 +1,5 @@
-import type { BackendInfo, LayerHeader, StatusCounts } from './evidence-types.js';
+import type { BackendInfo, LayerEvidence, LayerHeader, StatusCounts } from './evidence-types.js';
+import type { SpecEntry } from './explorer-types.js';
 import { type CombinedEvidence, type EvidenceResult } from './layer-merge.js';
 import type { ReportOutline } from './layer-types.js';
 import type { ObjectStore } from './object-store.js';
@@ -58,6 +59,27 @@ export declare function countResults(all: readonly EvidenceResult[]): StatusCoun
 };
 /** Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all. */
 export declare function summarize(combined: CombinedEvidence): ReportSummary;
+/** Every layer of some backends, read but not yet composed. */
+export type BackendLayers = {
+    /** Each layer that could be read, with the specs it recorded. A layer several backends hold appears once per backend. */
+    readonly loaded: readonly {
+        readonly evidence: LayerEvidence;
+        readonly specs: readonly SpecEntry[];
+    }[];
+    /** Every backend given, sorted by id, with whether it could be listed. */
+    readonly backends: readonly BackendInfo[];
+    /** What could not be read, sorted and without repeats. */
+    readonly notices: readonly string[];
+};
+/**
+ * Reads every layer of every backend, superseded ones included, without composing them. This is what {@link combineBackends}
+ * starts from; a caller that needs layers a newer layer has replaced (to compare two commits, for example) reads them here.
+ * A backend that cannot be listed, or a layer that cannot be understood, is a notice, never an omission that looks like a pass.
+ * Throws for an invalid or repeated backend `id`, before anything is read.
+ */
+export declare function readBackendLayers(backends: readonly BackendInput[], options?: {
+    readonly concurrency?: number;
+}): Promise<BackendLayers>;
 /**
  * Reads every layer of every backend and lays them over the specs. Layers are the only input:
  * a report is a function of the set of layers, so the order of backends and layers, and how they

package/dist/reports/src/compose.js

@@ -45,25 +45,12 @@ export function summarize(combined) {
     };
 }
 /**
- * Reads every layer of every backend and lays them over the specs. Layers are the only input:
- * a report is a function of the set of layers, so the order of backends and layers, and how they
- * were split across machines, branches and runs, does not change it.
- *
- * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
- * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
- * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
- * repeated) throws, before anything is read. Backends are only read from.
- *
- * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
- * recording of each spec path wins), with no commit sha.
- *
- * @example
- * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
- * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
- * report.summary.checks.failed; // number of slots whose winner failed
- * report.notices; // non-empty means something could not be read
+ * Reads every layer of every backend, superseded ones included, without composing them. This is what {@link combineBackends}
+ * starts from; a caller that needs layers a newer layer has replaced (to compare two commits, for example) reads them here.
+ * A backend that cannot be listed, or a layer that cannot be understood, is a notice, never an omission that looks like a pass.
+ * Throws for an invalid or repeated backend `id`, before anything is read.
  */
-export async function combineBackends(backends, options = {}) {
+export async function readBackendLayers(backends, options = {}) {
     const seen = new Set();
     for (const backend of backends) {
         if (!BACKEND_ID.test(backend.id) || seen.has(backend.id))
@@ -96,6 +83,29 @@ export async function combineBackends(backends, options = {}) {
             notices.push(`${backend.label ?? backend.id}: a layer could not be read, so its outcome is unknown (${error instanceof Error ? error.message : String(error)})`);
         }
     });
+    return { loaded, backends: info.sort((a, b) => (a.id < b.id ? -1 : 1)), notices: [...new Set(notices)].sort() };
+}
+/**
+ * Reads every layer of every backend and lays them over the specs. Layers are the only input:
+ * a report is a function of the set of layers, so the order of backends and layers, and how they
+ * were split across machines, branches and runs, does not change it.
+ *
+ * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
+ * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
+ * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
+ * repeated) throws, before anything is read. Backends are only read from.
+ *
+ * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
+ * recording of each spec path wins), with no commit sha.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
+ * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
+ * report.summary.checks.failed; // number of slots whose winner failed
+ * report.notices; // non-empty means something could not be read
+ */
+export async function combineBackends(backends, options = {}) {
+    const { loaded, backends: info, notices } = await readBackendLayers(backends, options.concurrency === undefined ? {} : { concurrency: options.concurrency });
     const include = options.include;
     const kept = include ? loaded.filter(item => include(item.evidence.layer)) : loaded;
     const layers = kept.map(item => item.evidence);
@@ -107,5 +117,5 @@ export async function combineBackends(backends, options = {}) {
     const outline = options.outline ?? { specs: recorded.entries(), sha: null, changedFiles: [] };
     const combined = combineEvidence(outline, layers);
     const headers = distinctHeaders(layers.map(evidence => evidence.layer)).sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-    return { combined, layers: headers, backends: info.sort((a, b) => (a.id < b.id ? -1 : 1)), notices: [...new Set(notices)].sort(), summary: summarize(combined) };
+    return { combined, layers: headers, backends: info, notices, summary: summarize(combined) };
 }

package/dist/reports/src/report-cli.d.ts

@@ -12,6 +12,7 @@
  * @see docs/integrating.md
  * @see docs/agents.md
  */
+import { type LayerRun } from '../../schema/src/layer.js';
 /** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
 export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n                       [--require-recordings]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--run-id <id>] [--run-title <t>]\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report verify-recordings [--store <dir|s3://\u2026|id=url>]... [--backends <module>] [--layer <id>]...\n                       [--limit <n>] [--branch <name>]... [--ignore-modified] [--format text|json]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).\n                            Layers that share an id are one run, however many shards or batches uploaded them;\n                            another invocation at the same commit gets another id. Never part of what a check is\n            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at\n                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            --require-recordings   exit 1 when a check that declared recordingExpectation \"required\" has no\n                              uploaded video (absent, left out as too large or not allowed, or refused). The layer is\n                              still written and the checks keep their results; only this command fails. The receipt of\n                              what was uploaded (counts, sizes, checksums) is in the JSON result under layer.recordings.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  verify-recordings   Read back the videos the layers published and check they are still there as published: the\n            layer still lists the file, its blob is still stored, its size and SHA-256 are the recorded ones, and it\n            begins like the container its media type names. Exit 1 when any video is missing, unreadable, corrupt or\n            not that container, naming the layer and check; test results are never changed. This checks stored bytes,\n            not playback in a browser. Videos given only by address are counted, not checked.\n            --layer <id>   only the layer whose id starts with this (repeatable; at least 7 digits)\n            --limit <n>    only the newest n layers\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor, status and verify-recordings print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status, verify-recordings-result). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
 type Env = Readonly<Record<string, string | undefined>>;
@@ -41,11 +42,23 @@ export declare function detectFreshness(origin: {
     sha: string | null;
     ci: boolean;
 }, git?: Git): 'modified' | 'unknown' | undefined;
+/** Splits `key=value` (the form of `--param` and `--label`), or throws a message naming `flag`. */
+export declare function keyValue(pair: string, flag: string): [string, string];
+/** An ISO date or epoch milliseconds from a flag, `null` when the flag was not given. Throws a message naming `flag` for anything else. */
+export declare function parseTime(text: string | undefined, flag?: string): number | null;
+/**
+ * The execution the producer named, from `--run-id`, `--run-title`, `--run-started-at`, `--run-ended-at` and then
+ * `ATLAS_RUN_ID` / `ATLAS_RUN_TITLE`, laid over a `run` the checks file gave. `undefined` when nothing names one, so the
+ * documented grouping (CI run URL, else branch@sha) applies. A title or time without an id is refused: it would have nothing to belong to.
+ */
+export declare function executionOf(rest: readonly string[], env: Env, given?: unknown): LayerRun | undefined;
 /**
  * `atlas report …` for a terminal: a mistake in the command or a path is a message on stderr and exit
  * code 2, so a CI job can tell a broken invocation (2) from a report that does not pass (1).
  */
 export declare function runReportCommand(argv: readonly string[]): Promise<number>;
+/** Does the command ask for a JSON document (`--format json` or `--json`) instead of prose? */
+export declare function wantsJson(argv: readonly string[]): boolean;
 /** `atlas report …`. Returns the exit code: 0 passes, 1 does not. Throws on a mistake in the command (see {@link runReportCommand}). */
 export declare function reportMain(argv: readonly string[], io?: ReportIo): Promise<number>;
 export {};

package/dist/reports/src/report-cli.js

@@ -149,7 +149,8 @@ export function detectFreshness(origin, git = gitOutput) {
     // `git diff` is empty (so null) when clean; untracked files (test output, build products) do not count.
     return git(['status', '--porcelain', '--untracked-files=no']) ? 'modified' : undefined;
 }
-function keyValue(pair, flag) {
+/** Splits `key=value` (the form of `--param` and `--label`), or throws a message naming `flag`. */
+export function keyValue(pair, flag) {
     const at = pair.indexOf('=');
     if (at < 1)
         throw new Error(`${flag} takes key=value (got "${pair}")`);
@@ -173,7 +174,8 @@ function linkSpec(spec) {
     const named = /^([^=/:]+)=(.+)$/.exec(spec);
     return named ? { name: named[1], url: named[2] } : { url: spec };
 }
-function parseTime(text, flag = '--recorded-at') {
+/** An ISO date or epoch milliseconds from a flag, `null` when the flag was not given. Throws a message naming `flag` for anything else. */
+export function parseTime(text, flag = '--recorded-at') {
     if (text === undefined)
         return null;
     const numeric = Number(text);
@@ -187,7 +189,7 @@ function parseTime(text, flag = '--recorded-at') {
  * `ATLAS_RUN_ID` / `ATLAS_RUN_TITLE`, laid over a `run` the checks file gave. `undefined` when nothing names one, so the
  * documented grouping (CI run URL, else branch@sha) applies. A title or time without an id is refused: it would have nothing to belong to.
  */
-function executionOf(rest, env, given) {
+export function executionOf(rest, env, given) {
     const file = typeof given === 'object' && given !== null && !Array.isArray(given) ? given : {};
     const id = value(rest, 'run-id') ?? env.ATLAS_RUN_ID ?? (typeof file.id === 'string' ? file.id : undefined);
     const title = value(rest, 'run-title') ?? env.ATLAS_RUN_TITLE;
@@ -235,7 +237,7 @@ export async function runReportCommand(argv) {
     }
 }
 /** Does the command ask for a JSON document (`--format json` or `--json`) instead of prose? */
-function wantsJson(argv) {
+export function wantsJson(argv) {
     return value(argv, 'format') === 'json' || argv.includes('--json');
 }
 function printChecks(out, label, checks) {

package/dist/reports/src/ui-catalog-cli.d.ts

@@ -0,0 +1,10 @@
+import { type ReportIo } from './report-cli.js';
+/** The text `atlas ui-catalog --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of its entry in `docs/reference/cli.md`. */
+export declare const UI_CATALOG_USAGE = "atlas ui-catalog \u2014 a browsable inventory of captured UI states, from any collector\n\n  atlas ui-catalog plan    --states <file.json> --producer <name> [--store <dir|s3://bucket/prefix|https://\u2026>]\n                           [--environment <name>] [--param key=value]... [--shard <label>]\n                           [--branch <b>] [--sha <s>] [--run-url <u>] [--run-id <id>] [--run-title <t>] [--recorded-at <iso|ms>]\n  atlas ui-catalog publish --captures <file.json> --producer <name> [the same flags as plan]\n                           [--attach-root <dir>]... [--max-picture-mb <n>]\n  atlas ui-catalog status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>] [filters] [--branch <name>]...\n                           [--ignore-modified] [--format text|json|markdown]\n  atlas ui-catalog diff    --from <commit> --to <commit> [--store \u2026]... [--backends <module>] [filters]\n                           [--fail-on-change] [--format text|json|markdown]\n  atlas ui-catalog export  --out <file.html> [--store \u2026]... [--backends <module>] [filters]\n                           [--images inline|none] [--max-mb <n>] [--manifest <file.json>] [--title <t>]\n\n  filters (status, diff, export): --q <words> --coverage a,b --profile <key|label>... --area a --route r --cohort c\n                           --flag f --surface s --producer p\n\n  plan      Write one layer of kind ui-plan: the states (and with \"inventory\": true, the surfaces) that should exist under\n            this profile. Every entry is not-run, so a plan never counts as a pass. The file is {\"states\":[{\"id\":\u2026,\n            \"title\"?,\"route\"?,\"fixture\"?,\"cohort\"?,\"area\"?,\"flags\"?,\"covers\"?,\"inventory\"?}]} or just that list.\n  publish   Write one layer of kind ui-state: the states one collector or shard captured under this profile. The file is\n            {\"states\":[{\"id\":\u2026,\"title\"?,\"status\"?:\"passed|failed|running|not-run\",\"detail\"?,\"route\"?,\"fixture\"?,\"cohort\"?,\n            \"area\"?,\"flags\"?,\"covers\"?,\"labels\"?,\"tags\"?,\"durationMs\"?,\"screenshot\"?:\"file.png\"|{\"path\"|\"uri\",\n            \"width\"?,\"height\"?,\"contentType\"?}}]}. A picture file is read from beside the file and each --attach-root, never\n            from a hidden file or a link out. A passed state whose picture cannot be read is published as failed, with the\n            reason: a state without its picture is not shown as captured.\n            --environment and each --param key=value are the profile (a viewport, a color scheme, a device): another\n            profile is another result side by side. --shard only describes the layer; it never splits a result.\n            --recorded-at defaults to the modification time of the file, so publishing the same file twice is one layer.\n  status    Read every store and print the catalog's summary. Exit 1 unless the catalog holds a state and there is nothing\n            to attend to: a failed capture, a state a plan expects with nothing captured, a capture still in progress, a\n            backend or layer that could not be read. Without a plan nothing is expected, so nothing is missing.\n            --profile takes a profile's key or its label, as printed by status.\n  diff      Set the catalog recorded at one commit (--from) against another (--to): each state in each profile is paired\n            with itself and is unchanged, changed in coverage, changed in picture (the stored bytes differ), unverified (a\n            side has no content hash), only in --to (added) or only in --from (removed). A commit is the whole id or at\n            least 7 digits of it. Exit 0 unless a store could not be read, or, with --fail-on-change, anything differs.\n  export    Write the catalog as one HTML file with its pictures embedded and its manifest in it: no server, no network.\n            It is the catalog at the moment it was made. --images none leaves the pictures out. --max-mb (default 32) limits\n            the embedded pictures; those past it are listed in the page as left out, and the manifest stays complete.\n            --manifest writes the catalog's JSON manifest too.\n\n  --format json (alias --json)   every subcommand prints one JSON document instead of prose\n                       (schemas: ui-catalog-publish-result, ui-catalog-status, ui-catalog-diff-result, ui-catalog-export-result).\n                       A command that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store is a directory, s3://bucket/prefix or an Atlas server (https://\u2026), exactly as for atlas report; select a project\n  with --project <slug> or ATLAS_PROJECT. When no --store is given, ATLAS_STORE is used.\n\n  Exit codes: 0 ok, 1 the answer is no (see each command), 2 the command was wrong.\n";
+/** `atlas ui-catalog …`. Returns the exit code. Throws on a mistake in the command (see {@link runUiCatalogCommand}). */
+export declare function uiCatalogMain(argv: readonly string[], io?: ReportIo): Promise<number>;
+/**
+ * `atlas ui-catalog …` for a terminal: a mistake in the command or a path is a message on stderr and exit code 2, so a CI job can
+ * tell a broken invocation (2) from a catalog that needs attention (1). With `--format json` the mistake is a JSON document.
+ */
+export declare function runUiCatalogCommand(argv: readonly string[]): Promise<number>;