@crvouga/atlas 0.3.0 → 0.5.0

package/dist/schema/src/api.js

@@ -0,0 +1,201 @@
+/**
+ * @module Atlas server API documents
+ *
+ * The JSON bodies the Atlas server speaks, as Zod schemas: the problem document every error uses (RFC 9457), what
+ * `/api/server` and `/readyz` say about the server, the report a viewer reads (`/api/reports/evidence/effective`) and
+ * what changed since a version of it, the store protocol's listings and acknowledgements, and the events on the
+ * stream. The server's OpenAPI document (`@crvouga/atlas/openapi.json`) is generated from these, and each is also
+ * published as a JSON Schema, so a client in any language can validate what it receives.
+ *
+ * Every object is open (unknown keys are kept, not refused) because the API only grows: within a version a response
+ * may gain optional fields, never lose or change one (see AGENTS.md, "The server is a living application"). A client
+ * must ignore what it does not know.
+ *
+ * @see docs/server.md
+ */
+import { z } from 'zod/v4';
+import { CheckSchema } from './layer.js';
+/** One of the statuses a check has in a report: `passed`, `failed`, `running` (not finished) or `not-run`. Closed. */
+export const EvidenceStatusSchema = z.enum(['passed', 'failed', 'running', 'not-run']);
+/**
+ * The body of every error the server answers, a Problem Details document (RFC 9457, `application/problem+json`).
+ * `error` repeats `detail` for clients written before the standard was adopted; read `detail`.
+ */
+export const ProblemSchema = z.looseObject({
+    type: z.string().default('about:blank').describe('A URI naming the kind of problem. `about:blank` means the status code says it all'),
+    title: z.string().describe('The status in words, such as "Unauthorized"'),
+    status: z.number().int().describe('The HTTP status code'),
+    detail: z.string().describe('What went wrong and what to do about it, in a sentence an agent or a person can act on'),
+    error: z.string().describe('The same as `detail`. Kept for clients that read `error`')
+});
+/** What `GET /healthz` answers: the process is up. */
+export const HealthSchema = z.looseObject({ ok: z.literal(true) });
+/** What `GET /readyz` answers: whether the backends were read, and counts for logs. `ready` false comes with status 503. */
+export const ReadySchema = z.looseObject({
+    ready: z.boolean().describe('True once the first pass over the backends is done and at least one backend answers'),
+    layers: z.number().int().nonnegative().describe('Distinct layers read'),
+    slots: z.number().int().nonnegative().describe('Distinct checks (slots) the report holds a winner for'),
+    holding: z.number().int().nonnegative().describe('Layers that still hold at least one winner'),
+    failed: z.number().int().nonnegative().describe('Layers or backends that could not be read right now'),
+    refreshedAt: z.number().describe('When a pass over the backends last finished, epoch milliseconds; 0 before the first'),
+    backends: z.array(z.looseObject({ id: z.string(), available: z.boolean() }))
+});
+/** What `GET /api/server` answers: what the server is, who is asking, and what it can do. */
+export const ServerInfoSchema = z.looseObject({
+    name: z.literal('atlas'),
+    version: z.string().nullable().describe('The @crvouga/atlas version the server runs, or null when it does not know'),
+    role: z.enum(['read', 'publish', 'admin']).describe('What the token of this request may do. A server with no tokens treats everyone as admin'),
+    open: z.boolean().describe('True when the server has no tokens at all'),
+    write: z.string().describe('The id of the backend uploads go to'),
+    ready: z.boolean(),
+    viewers: z.number().int().nonnegative().describe('Viewers connected to /api/events right now'),
+    time: z.number().describe('The server clock, epoch milliseconds'),
+    backends: z.array(z.looseObject({ id: z.string(), label: z.string(), available: z.boolean(), write: z.boolean() })),
+    layers: z.number().int().nonnegative(),
+    slots: z.number().int().nonnegative(),
+    capabilities: z.record(z.string(), z.boolean()).describe('Features this server has, by name: `events`, `ingest`, `store`, `checks`, `status`, `effective`. A client checks a name before using what it names')
+});
+/** A backend as the report shows it: where results came from, and whether it could be read. */
+export const BackendInfoSchema = z.looseObject({
+    id: z.string(),
+    label: z.string(),
+    live: z.boolean().describe('Always false on a server'),
+    available: z.boolean().describe('False when the backend could not be read; its results are then unknown, never passed')
+});
+/** What a result carries beyond its outcome, as counts and short facts. Present only when there is something. */
+export const EvidenceSummarySchema = z.looseObject({
+    attachments: z.number().int().nonnegative(),
+    steps: z.number().int().nonnegative(),
+    annotations: z.number().int().nonnegative(),
+    attempts: z.number().int().nonnegative(),
+    links: z.number().int().nonnegative(),
+    tags: z.array(z.string()),
+    labels: z.record(z.string(), z.string()),
+    roles: z.array(z.string())
+});
+/** A layer as the report shows it: its origin and its checks by status. */
+export const LayerHeaderSchema = z.looseObject({
+    id: z.string().describe('The layer id: 64 lowercase hex digits, the SHA-256 of its content'),
+    backend: z.string().describe('The backend it was read from; the one that sorts first when several hold it'),
+    producer: z.string().describe('The suite or tool that made it. Part of the slot'),
+    packageDir: z.string().nullable(),
+    recordedAtMs: z.number().describe('When the checks ran, epoch milliseconds. The newest completed result wins its slot'),
+    sha: z.string().nullable().describe('The commit it was recorded at. Provenance only'),
+    branch: z.string().nullable().describe('The branch it was recorded on. Provenance only'),
+    environment: z.string().nullable().describe('The client it checked, such as `ios`. Part of the slot'),
+    runUrl: z.string().nullable(),
+    parameters: z.record(z.string(), z.string()).describe('Other choices that make a result its own slot'),
+    freshness: z.enum(['unknown', 'modified']).optional().describe('`modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent: clean'),
+    recording: z.unknown().nullable().describe('Where recorded timelines are read from, or null'),
+    live: z.boolean(),
+    counts: z.record(EvidenceStatusSchema, z.number().int().nonnegative()),
+    execution: z.string(),
+    evidence: EvidenceSummarySchema.optional()
+});
+/** One check of a layer as the report shows it. */
+export const LayerRowSchema = z.looseObject({
+    kind: z.string().describe('The kind of the part holding the check. Part of the slot'),
+    id: z.string().describe('The check id. Part of the slot'),
+    title: z.string(),
+    status: EvidenceStatusSchema,
+    specPath: z.string().nullable().describe('The spec the check belongs to, `specs/<path>`, or null'),
+    detail: z.string().describe('Why it has this status; empty when there is nothing to add'),
+    measurements: z.array(z.looseObject({ name: z.string(), value: z.number(), unit: z.string(), limit: z.number().optional() })),
+    testId: z.string().nullable(),
+    variant: z.record(z.string(), z.string()),
+    durationMs: z.number().nullable(),
+    evidence: EvidenceSummarySchema.optional()
+});
+/** A layer with its checks: the rows of one layer, read apart from its header. */
+export const LayerRowsSchema = z.looseObject({
+    id: z.string(),
+    rows: z.array(LayerRowSchema),
+    fingerprints: z.record(z.string(), z.string()).describe('Spec path to the fingerprint the layer recorded for it')
+});
+/** A layer that holds winners, with only the rows that win. */
+export const LayerEvidenceSchema = LayerRowsSchema.extend({ layer: LayerHeaderSchema });
+/**
+ * The report as it stands: `GET /api/reports/evidence/effective`. Only the layers that win at least one check are
+ * listed, each with only the rows that win, newest first. `version` is a hash of the report: equal exactly when the
+ * report is, on every replica, so it works as an ETag and as the `since` of a delta.
+ */
+export const EffectiveEvidenceSchema = z.looseObject({
+    version: z.string().describe('Changes exactly when the report does'),
+    layers: z.array(LayerEvidenceSchema),
+    backends: z.array(BackendInfoSchema),
+    notices: z.array(z.string()).describe('What could not be read. A gate treats any notice as unknown, never as passed'),
+    totalLayers: z.number().int().nonnegative().describe('Every layer read, whether or not it still wins anything'),
+    active: z.array(z.unknown()).describe('Always empty on a server; kept for viewers written for live spec runs')
+});
+/**
+ * What `GET /api/reports/evidence/effective?since=<version>` answers when the server remembers that version: only
+ * what changed. Replace the layers of the same id, drop `removed`, take the rest whole; the result equals the full
+ * report. When the server does not remember the version it answers with the whole report instead (no `delta` key).
+ */
+export const EffectiveDeltaSchema = EffectiveEvidenceSchema.extend({
+    delta: z.literal(true),
+    base: z.string().describe('The version this applies to'),
+    layers: z.array(LayerEvidenceSchema).describe('Layers that are new or changed since `base`, whole'),
+    removed: z.array(z.string()).describe('Ids of layers that no longer hold a winner')
+});
+/** A spec of the outline a report is laid over. */
+export const OutlineSpecSchema = z.looseObject({
+    path: z.string().describe('`specs/<path>`'),
+    domain: z.string(),
+    kind: z.string().describe('The kind of spec: `gherkin`, `quint`, `dmn`, …'),
+    title: z.string(),
+    fingerprint: z.string().optional().describe('Identity of the spec text, so a result recorded against other text is flagged as possibly outdated')
+});
+/** `GET /api/reports/outline`: the specs a report is laid over, from the newest committed spec set. */
+export const OutlineSchema = z.looseObject({
+    specs: z.array(OutlineSpecSchema),
+    sha: z.string().nullable(),
+    changedFiles: z.array(z.string())
+});
+/** `GET /api/reports/evidence`: one page of layer headers, newest first. Used by clients that read the whole history. */
+export const EvidencePageSchema = z.looseObject({
+    layers: z.array(LayerHeaderSchema),
+    cursor: z.string().nullable().describe('Pass as `?cursor=` for the next page; null at the end'),
+    notices: z.array(z.string()),
+    backends: z.array(BackendInfoSchema),
+    active: z.array(z.unknown())
+});
+/** `GET /api/reports/evidence/detail/{backend}/{id}`: everything one check carries, and what its run carries. */
+export const CheckDetailSchema = z.looseObject({
+    layer: z.string(),
+    kind: z.string(),
+    check: CheckSchema,
+    run: z.looseObject({}).describe('What the run as a whole carries: its logs, links, labels, annotations and extensions')
+});
+/** `GET /api/store?prefix=…`: one page of keys under `layers/`, in code-unit order. */
+export const StoreListingSchema = z.looseObject({
+    keys: z.array(z.string()),
+    next: z.string().nullable().describe('Pass as `?after=` for the next page; null when there are no more')
+});
+/** `PUT /api/store/{key}` answered: the key was taken (`created`) or was already there with the same bytes. */
+export const StoreWriteResultSchema = z.looseObject({
+    ok: z.literal(true),
+    key: z.string(),
+    kind: z.string().describe('What the server recognised the key as: `layer`, `layer-catalog`, `blob`, `spec-body`, `spec-set`, `spec-catalog`, `run-manifest`, `run-catalog`, `run-file` or `scratch`'),
+    created: z.boolean()
+});
+/** `POST /api/checks` answered: the layer that was written. */
+export const ChecksResultSchema = z.looseObject({
+    ok: z.literal(true),
+    id: z.string().describe('The layer id'),
+    checks: z.number().int().nonnegative()
+});
+/** The data of the `hello` event: sent first on `/api/events`. */
+export const HelloEventSchema = z.looseObject({ version: z.string(), ready: z.boolean(), time: z.number() });
+/** The data of the `report` event: layers arrived. Enough to say who sent what, without asking. */
+export const ReportEventSchema = z.looseObject({
+    version: z.string().describe('The report version after these layers'),
+    totalLayers: z.number().int().nonnegative(),
+    added: z.array(z.looseObject({
+        id: z.string(), producer: z.string(), environment: z.string().nullable().optional(), branch: z.string().nullable().optional(),
+        sha: z.string().nullable().optional(), recordedAtMs: z.number(), counts: z.record(EvidenceStatusSchema, z.number().int().nonnegative()).optional()
+    })).describe('At most the 20 newest of the layers that arrived'),
+    addedTotal: z.number().int().nonnegative().describe('How many layers arrived, including those not listed')
+});
+/** The data of the `ping` event: sent every `heartbeatSeconds`, so a quiet server is told apart from a dead connection. */
+export const PingEventSchema = z.looseObject({});

package/dist/schema/src/cli-results.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @module Command results (`--format json`)
+ *
+ * What `atlas report publish`, `stream`, `merge` and `doctor` print on standard output with `--format json` (alias
+ * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
+ * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
+ * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
+ *
+ * Exit codes are the same with and without `--format json`: `0` it worked, `1` it ran and the answer is no (a
+ * report that does not pass, a store that needs attention, checks that could not be sent), `2` the command itself
+ * was wrong (a missing flag, a path that does not exist). Within a version these only gain optional fields.
+ *
+ * @see docs/agents.md
+ */
+import { z } from 'zod/v4';
+/** What was written for one layer by `atlas report publish`. */
+export declare const PublishedLayerSchema: z.ZodObject<{
+    id: z.ZodString;
+    producer: z.ZodString;
+    environment: z.ZodNullable<z.ZodString>;
+    checks: z.ZodNumber;
+    passed: z.ZodNumber;
+    failed: z.ZodNumber;
+    notRun: z.ZodNumber;
+    linkedToSpec: z.ZodNumber;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        modified: "modified";
+    }>>;
+    attachmentFiles: z.ZodNumber;
+    attachmentBytes: z.ZodNumber;
+}, z.core.$loose>;
+/** What `atlas report publish --format json` prints. */
+export declare const PublishResultSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    store: z.ZodString;
+    layer: z.ZodObject<{
+        id: z.ZodString;
+        producer: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
+        checks: z.ZodNumber;
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+        notRun: z.ZodNumber;
+        linkedToSpec: z.ZodNumber;
+        freshness: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            modified: "modified";
+        }>>;
+        attachmentFiles: z.ZodNumber;
+        attachmentBytes: z.ZodNumber;
+    }, z.core.$loose>;
+    specSet: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        files: z.ZodNumber;
+        branch: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>>;
+    run: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        files: z.ZodNumber;
+        bytes: z.ZodNumber;
+        alreadyPublished: z.ZodBoolean;
+    }, z.core.$loose>>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+/** What `atlas report stream --format json` prints when its input ends. */
+export declare const StreamResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    producer: z.ZodString;
+    environment: z.ZodNullable<z.ZodString>;
+    layers: z.ZodNumber;
+    checks: z.ZodNumber;
+    lost: z.ZodNumber;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+/** What `atlas report merge --format json` prints. */
+export declare const MergeResultSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    into: z.ZodString;
+    copied: z.ZodNumber;
+    skipped: z.ZodNumber;
+    ignored: z.ZodNumber;
+}, z.core.$loose>;
+/** One thing `atlas report doctor` checked about a store. */
+export declare const DoctorCheckSchema: z.ZodObject<{
+    name: z.ZodString;
+    ok: z.ZodBoolean;
+    detail: z.ZodString;
+    fix: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** What `atlas report doctor --format json` prints. */
+export declare const DoctorResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    stores: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        checks: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            ok: z.ZodBoolean;
+            detail: z.ZodString;
+            fix: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** What any `atlas` command prints on standard error, with `--format json`, when the command itself was wrong (exit code 2). */
+export declare const CommandErrorSchema: z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        message: z.ZodString;
+        code: z.ZodLiteral<"usage">;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/** A test suite `atlas init` found, and the commands that run it and send its results. */
+export declare const InitSuiteSchema: z.ZodObject<{
+    id: z.ZodString;
+    runner: z.ZodString;
+    evidence: z.ZodString;
+    run: z.ZodString;
+    output: z.ZodString;
+    format: z.ZodEnum<{
+        junit: "junit";
+        ctrf: "ctrf";
+        manifest: "manifest";
+    }>;
+    environment: z.ZodNullable<z.ZodString>;
+    publish: z.ZodString;
+    stream: z.ZodNullable<z.ZodString>;
+    prerequisites: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+/** A file `atlas init` creates or updates. */
+export declare const InitFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    action: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        unchanged: "unchanged";
+    }>;
+    purpose: z.ZodString;
+    content: z.ZodString;
+}, z.core.$loose>;
+/**
+ * What `atlas init --format json` prints: everything found about the project, and everything it would change.
+ * Without `--write` nothing is changed. With `--write`, the files are written and `written` says which.
+ */
+export declare const InitPlanSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    directory: z.ZodString;
+    project: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        packageManager: z.ZodNullable<z.ZodEnum<{
+            bun: "bun";
+            pnpm: "pnpm";
+            yarn: "yarn";
+            npm: "npm";
+        }>>;
+        languages: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    git: z.ZodObject<{
+        branch: z.ZodNullable<z.ZodString>;
+        defaultBranch: z.ZodString;
+    }, z.core.$loose>;
+    ci: z.ZodEnum<{
+        none: "none";
+        "github-actions": "github-actions";
+        "gitlab-ci": "gitlab-ci";
+        circleci: "circleci";
+    }>;
+    server: z.ZodObject<{
+        url: z.ZodNullable<z.ZodString>;
+        tokenEnv: z.ZodLiteral<"ATLAS_TOKEN">;
+    }, z.core.$loose>;
+    specs: z.ZodObject<{
+        directory: z.ZodNullable<z.ZodString>;
+        kinds: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$loose>;
+    suites: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        runner: z.ZodString;
+        evidence: z.ZodString;
+        run: z.ZodString;
+        output: z.ZodString;
+        format: z.ZodEnum<{
+            junit: "junit";
+            ctrf: "ctrf";
+            manifest: "manifest";
+        }>;
+        environment: z.ZodNullable<z.ZodString>;
+        publish: z.ZodString;
+        stream: z.ZodNullable<z.ZodString>;
+        prerequisites: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        action: z.ZodEnum<{
+            create: "create";
+            update: "update";
+            unchanged: "unchanged";
+        }>;
+        purpose: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$loose>>;
+    written: z.ZodArray<z.ZodString>;
+    verification: z.ZodNullable<z.ZodObject<{
+        reachable: z.ZodBoolean;
+        role: z.ZodNullable<z.ZodString>;
+        canPublish: z.ZodBoolean;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>>;
+    nextSteps: z.ZodArray<z.ZodString>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;

package/dist/schema/src/cli-results.js

@@ -0,0 +1,124 @@
+/**
+ * @module Command results (`--format json`)
+ *
+ * What `atlas report publish`, `stream`, `merge` and `doctor` print on standard output with `--format json` (alias
+ * `--json`), and what any `atlas` command prints on standard error for a command that was wrong: one JSON document,
+ * so an agent or a script never has to parse prose. (`status` and `policy` already print documents:
+ * `ReportStatusSchema`, and an IAM policy.) Each is also published as a JSON Schema.
+ *
+ * Exit codes are the same with and without `--format json`: `0` it worked, `1` it ran and the answer is no (a
+ * report that does not pass, a store that needs attention, checks that could not be sent), `2` the command itself
+ * was wrong (a missing flag, a path that does not exist). Within a version these only gain optional fields.
+ *
+ * @see docs/agents.md
+ */
+import { z } from 'zod/v4';
+/** What was written for one layer by `atlas report publish`. */
+export const PublishedLayerSchema = z.looseObject({
+    id: z.string().describe('The layer id: 64 hex digits, the SHA-256 of its content. Publishing the same input again gives the same id'),
+    producer: z.string(),
+    environment: z.string().nullable(),
+    checks: z.number().int().nonnegative(),
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    notRun: z.number().int().nonnegative().describe('Skipped, pending or otherwise not run'),
+    linkedToSpec: z.number().int().nonnegative().describe('Checks that were matched to a spec file. The rest still count, but belong to no spec'),
+    freshness: z.enum(['modified', 'unknown']).optional().describe('Set when the checkout had uncommitted changes (`modified`) or no git origin (`unknown`)'),
+    attachmentFiles: z.number().int().nonnegative(),
+    attachmentBytes: z.number().int().nonnegative()
+});
+/** What `atlas report publish --format json` prints. */
+export const PublishResultSchema = z.looseObject({
+    ok: z.literal(true),
+    store: z.string().describe('Where it was written: a folder, `s3://…` or a server URL'),
+    layer: PublishedLayerSchema,
+    specSet: z.looseObject({ id: z.string(), files: z.number().int().nonnegative(), branch: z.string().nullable() }).optional().describe('Present when `--specs` was given'),
+    run: z.looseObject({ id: z.string(), files: z.number().int().nonnegative(), bytes: z.number().int().nonnegative(), alreadyPublished: z.boolean() }).optional().describe('Present with `--upload-run`'),
+    warnings: z.array(z.string()).describe('What was skipped and why, such as an attachment file that could not be read. Never fatal')
+});
+/** What `atlas report stream --format json` prints when its input ends. */
+export const StreamResultSchema = z.looseObject({
+    ok: z.boolean().describe('False when any check could not be sent (the exit code is then 1)'),
+    producer: z.string(),
+    environment: z.string().nullable(),
+    layers: z.number().int().nonnegative().describe('Layers that arrived'),
+    checks: z.number().int().nonnegative().describe('Checks that arrived'),
+    lost: z.number().int().nonnegative().describe('Checks that never arrived'),
+    warnings: z.array(z.string()).describe('Input lines that were skipped, and sends that failed')
+});
+/** What `atlas report merge --format json` prints. */
+export const MergeResultSchema = z.looseObject({
+    ok: z.literal(true),
+    into: z.string(),
+    copied: z.number().int().nonnegative().describe('Objects that were missing in the destination and were copied'),
+    skipped: z.number().int().nonnegative().describe('Objects the destination already had'),
+    ignored: z.number().int().nonnegative().describe('Objects outside `layers/`, which are never merged')
+});
+/** One thing `atlas report doctor` checked about a store. */
+export const DoctorCheckSchema = z.looseObject({
+    name: z.string().describe('`store`, `list`, `contents`, `write`, …'),
+    ok: z.boolean(),
+    detail: z.string(),
+    fix: z.string().optional().describe('What to change, when `ok` is false')
+});
+/** What `atlas report doctor --format json` prints. */
+export const DoctorResultSchema = z.looseObject({
+    ok: z.boolean().describe('True when every check of every store passed (otherwise the exit code is 1)'),
+    stores: z.array(z.looseObject({ id: z.string(), checks: z.array(DoctorCheckSchema) }))
+});
+/** What any `atlas` command prints on standard error, with `--format json`, when the command itself was wrong (exit code 2). */
+export const CommandErrorSchema = z.looseObject({
+    ok: z.literal(false),
+    error: z.looseObject({
+        message: z.string().describe('What is wrong, and usually what to do about it'),
+        code: z.literal('usage').describe('`usage`: the command or its inputs were wrong. Nothing was written')
+    })
+});
+/** A test suite `atlas init` found, and the commands that run it and send its results. */
+export const InitSuiteSchema = z.looseObject({
+    id: z.string().describe('A stable name for the suite, lowercase: `vitest`, `playwright`, `pytest`, … Used as the default `--producer`'),
+    runner: z.string().describe('What runs it: `vitest`, `jest`, `playwright`, `bun-test`, `mocha`, `cypress`, `cucumber`, `pytest`, `go-test`, `atlas-statecharts`'),
+    evidence: z.string().describe('Where the detection came from, such as `package.json devDependencies: vitest`'),
+    run: z.string().describe('A command that runs the suite and writes its results to `output`. Its exit code is the suite\'s; publish regardless'),
+    output: z.string().describe('The file the results are written to'),
+    format: z.enum(['junit', 'ctrf', 'manifest']).describe('How `publish` should read `output`: `--junit`, `--ctrf` or `--manifest`'),
+    environment: z.string().nullable().describe('The client the suite checks (`desktop-web`, `ios`, …) when that is known; null when it should be chosen'),
+    publish: z.string().describe('The command that sends `output` to the server'),
+    stream: z.string().nullable().describe('The command that streams checks as they finish, when the runner can print them as JSON lines; else null'),
+    prerequisites: z.array(z.string()).describe('What must be installed or configured first, as commands (`bun add -d jest-junit`)')
+});
+/** A file `atlas init` creates or updates. */
+export const InitFileSchema = z.looseObject({
+    path: z.string().describe('Relative to the project directory'),
+    action: z.enum(['create', 'update', 'unchanged']).describe('`unchanged`: already what it would write, so applying changes nothing'),
+    purpose: z.string(),
+    content: z.string().describe('The whole file as it would be written')
+});
+/**
+ * What `atlas init --format json` prints: everything found about the project, and everything it would change.
+ * Without `--write` nothing is changed. With `--write`, the files are written and `written` says which.
+ */
+export const InitPlanSchema = z.looseObject({
+    ok: z.boolean().describe('False when `verification` was asked for and failed (the exit code is then 1)'),
+    directory: z.string(),
+    project: z.looseObject({
+        name: z.string().nullable(),
+        packageManager: z.enum(['bun', 'pnpm', 'yarn', 'npm']).nullable(),
+        languages: z.array(z.string())
+    }),
+    git: z.looseObject({ branch: z.string().nullable(), defaultBranch: z.string().describe('`main` unless the repository says otherwise') }),
+    ci: z.enum(['github-actions', 'gitlab-ci', 'circleci', 'none']),
+    server: z.looseObject({ url: z.string().nullable(), tokenEnv: z.literal('ATLAS_TOKEN') }),
+    specs: z.looseObject({
+        directory: z.string().nullable().describe('The folder to pass as `--specs`, relative to the project; null when no spec files were found'),
+        kinds: z.record(z.string(), z.number().int().nonnegative()).describe('Spec files by kind: `gherkin`, `quint`, `dmn`, `alloy`, `openslo`, `scxml`, …')
+    }),
+    suites: z.array(InitSuiteSchema),
+    files: z.array(InitFileSchema),
+    written: z.array(z.string()).describe('The files `--write` wrote; empty without it'),
+    verification: z.looseObject({
+        reachable: z.boolean(), role: z.string().nullable(), canPublish: z.boolean(), error: z.string().nullable()
+    }).nullable().describe('Present with `--verify` (and a server): whether the server answers, and what the token in `ATLAS_TOKEN` may do'),
+    nextSteps: z.array(z.string()).describe('What to do next, in order, as plain instructions an agent can follow'),
+    warnings: z.array(z.string())
+});

package/dist/schema/src/common.d.ts

@@ -1,11 +1,27 @@
+/**
+ * @module Shared statechart vocabulary
+ *
+ * Small schemas and types used by both the run manifest (`manifest.ts`) and the spec formats (`spec.ts`): the status
+ * of a run result, who sends an event, how sure a spec is, screenshot references, status tallies, the shape of a
+ * reading problem, and the transition id convention. The statuses and kinds are written by `atlas run` and read by
+ * the visualizer.
+ *
+ * @see docs/statecharts.md
+ */
 import { z } from 'zod/v4';
+/**
+ * Outcome of a state, transition, path or journey in a statechart run: `passed`, `failed`, `flaky` (failed on the
+ * first attempt and passed on the retry) or `not-reached` (no path got there, or the path was blocked before it).
+ */
 export declare const RUN_STATUSES: readonly ["passed", "failed", "flaky", "not-reached"];
+/** Zod enum over `RUN_STATUSES`. */
 export declare const RunStatusSchema: z.ZodEnum<{
     passed: "passed";
     failed: "failed";
     flaky: "flaky";
     "not-reached": "not-reached";
 }>;
+/** One of `RUN_STATUSES`. */
 export type RunStatus = z.infer<typeof RunStatusSchema>;
 /**
  * Who or what sends an event: a person using the product (`user`), another system (`system`), the
@@ -13,19 +29,35 @@ export type RunStatus = z.infer<typeof RunStatusSchema>;
  * `member` is read as `user`, for specs written before the kinds were renamed.
  */
 export declare const EVENT_KINDS: readonly ["user", "system", "time", "hand-off"];
+/**
+ * Zod schema for an `EVENT_KINDS` value that first rewrites the legacy value `member` to `user`, so specs written
+ * before the kinds were renamed still parse.
+ */
 export declare const EventKindSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
     time: "time";
     user: "user";
     system: "system";
     "hand-off": "hand-off";
 }>>;
+/** One of `EVENT_KINDS`. */
 export type EventKind = z.infer<typeof EventKindSchema>;
+/**
+ * How sure a spec is about a state's description (`meta.confidence`): `confirmed` or `assumed`. A run records
+ * `assumed` for a state whose spec does not say.
+ */
 export declare const CONFIDENCES: readonly ["confirmed", "assumed"];
+/** Zod enum over `CONFIDENCES`. */
 export declare const ConfidenceSchema: z.ZodEnum<{
     confirmed: "confirmed";
     assumed: "assumed";
 }>;
+/** One of `CONFIDENCES`. */
 export type Confidence = z.infer<typeof ConfidenceSchema>;
+/**
+ * A screenshot of a state in a run manifest: `png` and an optional `webp` thumbnail, as paths relative to the run
+ * directory (the folder holding `manifest.json`), plus the other clients' screens at the same moment in a
+ * multi-client run.
+ */
 export declare const ImageSchema: z.ZodObject<{
     png: z.ZodString;
     webp: z.ZodOptional<z.ZodString>;
@@ -36,7 +68,12 @@ export declare const ImageSchema: z.ZodObject<{
         client: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+/** A parsed `ImageSchema` value. */
 export type Image = z.infer<typeof ImageSchema>;
+/**
+ * Tally of states or transitions by status: `total` and one count per `RUN_STATUSES` value (`notReached` for
+ * `not-reached`). Used by manifest coverage and run summaries.
+ */
 export declare const CountSchema: z.ZodObject<{
     total: z.ZodNumber;
     passed: z.ZodNumber;
@@ -44,14 +81,30 @@ export declare const CountSchema: z.ZodObject<{
     flaky: z.ZodNumber;
     notReached: z.ZodNumber;
 }, z.core.$strip>;
+/** A parsed `CountSchema` value. */
 export type Count = z.infer<typeof CountSchema>;
+/** Severities of a `DataIssue`, most serious first: `error`, `warning`, `info`. */
 export declare const ISSUE_SEVERITIES: readonly ["error", "warning", "info"];
+/** One of `ISSUE_SEVERITIES`. */
 export type IssueSeverity = (typeof ISSUE_SEVERITIES)[number];
+/**
+ * A problem found while reading a spec or manifest file, in words a non-engineer can read: how serious it is, which
+ * file, where in the file (path segments joined with ` › `), and what is wrong. The visualizer shows these instead of
+ * failing to load.
+ */
 export type DataIssue = {
     severity: IssueSeverity;
     file: string;
     path: string;
     message: string;
 };
+/**
+ * Separator inside a transition id (`<source state> :: <event>`). Ids are not escaped, so a state name containing it
+ * makes an id ambiguous. The same value as core's `TRANSITION_SEPARATOR`.
+ */
 export declare const TRANSITION_ID_SEPARATOR = " :: ";
+/**
+ * Builds the id of a transition, the key of `transitions` in a manifest: the source state's name,
+ * `TRANSITION_ID_SEPARATOR`, then the event name.
+ */
 export declare function transitionId(source: string, event: string): string;