@crvouga/atlas 0.5.0 → 0.6.1

package/dist/runners/src/mocha.js

@@ -0,0 +1,39 @@
+import { testFile, runnerLive, finishRunner } from './publish.js';
+/**
+ * Mocha reporter; use `--reporter @crvouga/atlas/mocha` or CodeceptJS `--reporter @crvouga/atlas/codecept`.
+ * Reporter options go in `reporterOptions`; environment variables are supported by every runner.
+ * A failed upload adds a runner failure through Mocha's completion callback.
+ * @example
+ * // mocha configuration
+ * export default { reporter: '@crvouga/atlas/mocha', reporterOptions: { url: 'https://atlas.example.com' } };
+ */
+export default class AtlasMochaReporter {
+    checks = new Map();
+    options;
+    runnerName;
+    live;
+    constructor(runner, options = {}, runnerName = 'mocha') {
+        this.options = options.reporterOptions ?? {};
+        this.runnerName = runnerName;
+        this.live = runnerLive(runnerName, this.options, runner.total);
+        const add = (test, status, error) => {
+            const file = testFile(test.file, this.options.rootDir);
+            const retry = test.currentRetry?.() ?? 0;
+            this.checks.set(test, { id: [file, test.fullTitle()].filter(Boolean).join(' > '), title: test.title, status,
+                detail: error?.stack ?? error?.message ?? (status === 'failed' ? test.err?.stack ?? test.err?.message ?? 'failed' : ''), measurements: [],
+                ...(typeof test.duration === 'number' && Number.isFinite(test.duration) && test.duration >= 0 ? { durationMs: test.duration } : {}),
+                ...(retry ? { labels: { retries: String(retry), ...(status === 'passed' ? { flaky: 'true' } : {}) } } : {}),
+                ...(test.steps?.length ? { steps: test.steps.map(step => ({ name: step.name ?? 'step', ...(step.status ? { status: step.status } : {}) })) } : {}) });
+            const check = this.checks.get(test);
+            this.live.check({ ...check, steps: check.steps?.map(step => ({ name: step.name, status: step.status })) });
+        };
+        runner.on('test', test => add(test, 'running'));
+        runner.on('pass', test => add(test, 'passed'));
+        runner.on('fail', (test, error) => add(test, 'failed', error));
+        runner.on('pending', test => add(test, 'not-run'));
+    }
+    /** Mocha waits for this callback before exiting. Publishing errors fail the invocation. */
+    done(failures, callback) {
+        void finishRunner(this.live, this.runnerName, [...this.checks.values()], this.options).then(() => callback(failures), error => { console.error(error instanceof Error ? error.message : String(error)); callback(failures + 1); });
+    }
+}

package/dist/runners/src/node-test.d.ts

@@ -0,0 +1,28 @@
+type Event = {
+    type: string;
+    data: {
+        name?: string;
+        file?: string;
+        nesting?: number;
+        type?: string;
+        skip?: boolean | string;
+        todo?: boolean | string;
+        details?: {
+            type?: string;
+            duration_ms?: number;
+            error?: {
+                stack?: string;
+                message?: string;
+                failureType?: string;
+            };
+        };
+    };
+};
+/**
+ * Async generator reporter. Use alongside Node's spec reporter to keep normal output.
+ * Upload errors reject the stream; skips and TODOs never count as passed. Successful suite containers are excluded; hook failures are retained.
+ * @example
+ * // node --test --test-reporter=spec --test-reporter=@crvouga/atlas/node-test
+ */
+export default function atlasNodeReporter(source: AsyncIterable<Event>): AsyncGenerator<string>;
+export {};

package/dist/runners/src/node-test.js

@@ -0,0 +1,44 @@
+import { testFile, runnerLive, finishRunner } from './publish.js';
+/**
+ * Async generator reporter. Use alongside Node's spec reporter to keep normal output.
+ * Upload errors reject the stream; skips and TODOs never count as passed. Successful suite containers are excluded; hook failures are retained.
+ * @example
+ * // node --test --test-reporter=spec --test-reporter=@crvouga/atlas/node-test
+ */
+export default async function* atlasNodeReporter(source) {
+    const checks = [];
+    const live = runnerLive('node-test');
+    const kinds = new Map();
+    try {
+        const parents = [];
+        for await (const { type, data } of source) {
+            const nesting = data.nesting ?? 0;
+            const identity = `${data.file ?? ''}|${nesting}|${data.name ?? ''}`;
+            if (type === 'test:enqueue' && data.type)
+                kinds.set(identity, data.type);
+            if (type === 'test:start') {
+                parents[nesting] = data.name ?? '';
+                parents.length = nesting + 1;
+                if (kinds.get(identity) === 'test')
+                    live.check({ id: [testFile(data.file), ...parents.slice(0, nesting), data.name].filter(Boolean).join(' > '), title: data.name ?? 'test', status: 'running' });
+            }
+            if (type !== 'test:pass' && type !== 'test:fail')
+                continue;
+            if (data.details?.type === 'suite' && (type === 'test:pass' || data.details.error?.failureType === 'subtestsFailed'))
+                continue;
+            const file = testFile(data.file);
+            const status = data.skip || data.todo ? 'not-run' : type === 'test:pass' ? 'passed' : 'failed';
+            checks.push({ id: [file, ...parents.slice(0, nesting), data.name].filter(Boolean).join(' > '), title: data.name ?? 'test', status,
+                detail: data.details?.error?.stack ?? data.details?.error?.message ?? '', measurements: [],
+                ...(typeof data.details?.duration_ms === 'number' && Number.isFinite(data.details.duration_ms) && data.details.duration_ms >= 0 ? { durationMs: data.details.duration_ms } : {}) });
+            live.check(checks.at(-1));
+        }
+        checks.forEach(check => live.check(check));
+        await finishRunner(live, 'node-test', checks);
+        yield `Atlas: uploaded ${checks.length} checks\n`;
+    }
+    catch (error) {
+        await live.finish('interrupted', 'The test event stream ended unexpectedly.').catch(() => { });
+        throw error;
+    }
+}

package/dist/runners/src/publish.d.ts

@@ -0,0 +1,30 @@
+import type { EvidenceCheck } from '../../reports/src/explorer-types.js';
+/** Reporter options; explicit values override ATLAS_SERVER_URL, ATLAS_PUBLISH_TOKEN, ATLAS_ENVIRONMENT, ATLAS_BRANCH and ATLAS_SHA. */
+export type ReporterOptions = {
+    /** Project namespace; defaults to ATLAS_PROJECT. */
+    readonly project?: string;
+    readonly url?: string;
+    readonly token?: string;
+    readonly producer?: string;
+    readonly environment?: string;
+    readonly branch?: string;
+    readonly sha?: string;
+    readonly timeoutMs?: number;
+    readonly rootDir?: string;
+    /** Explicit final evidence time; normally generated when publication finishes. */
+    readonly recordedAtMs?: number;
+};
+/** A portable check identity: paths relative to the project, using forward slashes on every OS. */
+export declare function testFile(file: string | undefined, root?: string): string;
+/**
+ * Upload one completed runner invocation. Unknown outcomes stay not-run, repeated identities are numbered.
+ * Throws on missing configuration, timeouts or refused uploads so CI cannot silently lose its evidence.
+ * No storage credentials or backend URL are needed by the runner.
+ * @example
+ * await uploadChecks('mocha', checks, { url: 'https://atlas.example.com', token: process.env.ATLAS_PUBLISH_TOKEN });
+ */
+export declare function uploadChecks(runner: string, checks: readonly EvidenceCheck[], options?: ReporterOptions): Promise<void>;
+/** Start the native runner's live feed with the same endpoint and identity as its final report. */
+export declare function runnerLive(runner: string, options?: ReporterOptions, plannedChecks?: number): import('../../reports/src/live-reporter.js').LiveReporter;
+/** Flush live progress, then publish the full final evidence even if the lease was interrupted. Reject either failure. */
+export declare function finishRunner(live: import('../../reports/src/live-reporter.js').LiveReporter, runner: string, checks: readonly EvidenceCheck[], options?: ReporterOptions): Promise<void>;

package/dist/runners/src/publish.js

@@ -0,0 +1,68 @@
+/** @module Publishing native runner results
+ * Native reporters send checks to the project's Atlas server. Only the server knows its storage backend.
+ */
+import path from 'node:path';
+import { createLiveReporter } from '../../reports/src/live-reporter.js';
+import { uniqueChecks } from '../../reports/src/ingest.js';
+/** A portable check identity: paths relative to the project, using forward slashes on every OS. */
+export function testFile(file, root = process.cwd()) {
+    return file ? path.relative(root, path.resolve(root, file)).replaceAll('\\', '/') : '';
+}
+/**
+ * Upload one completed runner invocation. Unknown outcomes stay not-run, repeated identities are numbered.
+ * Throws on missing configuration, timeouts or refused uploads so CI cannot silently lose its evidence.
+ * No storage credentials or backend URL are needed by the runner.
+ * @example
+ * await uploadChecks('mocha', checks, { url: 'https://atlas.example.com', token: process.env.ATLAS_PUBLISH_TOKEN });
+ */
+export async function uploadChecks(runner, checks, options = {}) {
+    const url = options.url ?? process.env.ATLAS_SERVER_URL;
+    if (!url)
+        throw new Error('Atlas reporter: set ATLAS_SERVER_URL to the project Atlas server');
+    const target = new URL(url);
+    if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.search || target.hash)
+        throw new Error('Atlas reporter: use an HTTP(S) server URL without credentials, query or fragment');
+    target.pathname = `${target.pathname.replace(/\/$/, '')}/api/checks`;
+    const token = options.token ?? process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN;
+    const response = await fetch(target, {
+        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+        headers: { 'content-type': 'application/json', ...((options.project ?? process.env.ATLAS_PROJECT) ? { 'x-atlas-project': options.project ?? process.env.ATLAS_PROJECT } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify({ producer: options.producer ?? runner, recordedAtMs: options.recordedAtMs ?? Date.now(),
+            environment: options.environment ?? process.env.ATLAS_ENVIRONMENT,
+            branch: options.branch ?? process.env.ATLAS_BRANCH, sha: options.sha ?? process.env.ATLAS_SHA,
+            checks: uniqueChecks(checks) })
+    });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`Atlas reporter: upload refused (HTTP ${response.status})`);
+    }
+    await response.body?.cancel();
+}
+/** Start the native runner's live feed with the same endpoint and identity as its final report. */
+export function runnerLive(runner, options = {}, plannedChecks) {
+    const url = options.url ?? process.env.ATLAS_SERVER_URL;
+    if (!url)
+        throw new Error('Atlas reporter: set ATLAS_SERVER_URL to the project Atlas server');
+    return createLiveReporter({ producer: options.producer ?? runner, plannedChecks, title: `${runner} tests`, environment: options.environment ?? process.env.ATLAS_ENVIRONMENT,
+        branch: options.branch ?? process.env.ATLAS_BRANCH, sha: options.sha ?? process.env.ATLAS_SHA }, { url, project: options.project ?? process.env.ATLAS_PROJECT, token: options.token ?? process.env.ATLAS_PUBLISH_TOKEN ?? process.env.ATLAS_TOKEN, timeoutMs: options.timeoutMs });
+}
+/** Flush live progress, then publish the full final evidence even if the lease was interrupted. Reject either failure. */
+export async function finishRunner(live, runner, checks, options = {}) {
+    let error;
+    const finalChecks = uniqueChecks(checks);
+    finalChecks.forEach(check => live.check(check));
+    try {
+        await live.finish();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    try {
+        await uploadChecks(runner, finalChecks, { ...options, recordedAtMs: Math.max(Date.now(), (live.finishedAtMs ?? 0) + 1) });
+    }
+    catch (caught) {
+        error ??= caught;
+    }
+    if (error)
+        throw error;
+}

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

@@ -774,6 +774,7 @@ export declare const HelloEventSchema: z.ZodObject<{
     version: z.ZodString;
     ready: z.ZodBoolean;
     time: z.ZodNumber;
+    heartbeatMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** The data of the `report` event: layers arrived. Enough to say who sent what, without asking. */
 export declare const ReportEventSchema: z.ZodObject<{

package/dist/schema/src/api.js

@@ -186,7 +186,7 @@ export const ChecksResultSchema = z.looseObject({
     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() });
+export const HelloEventSchema = z.looseObject({ version: z.string(), ready: z.boolean(), time: z.number(), heartbeatMs: z.number().positive().optional() });
 /** 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'),

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

@@ -147,10 +147,10 @@ export declare const InitPlanSchema: z.ZodObject<{
     project: z.ZodObject<{
         name: z.ZodNullable<z.ZodString>;
         packageManager: z.ZodNullable<z.ZodEnum<{
-            bun: "bun";
+            npm: "npm";
             pnpm: "pnpm";
+            bun: "bun";
             yarn: "yarn";
-            npm: "npm";
         }>>;
         languages: z.ZodArray<z.ZodString>;
     }, z.core.$loose>;
@@ -208,3 +208,234 @@ export declare const InitPlanSchema: z.ZodObject<{
     nextSteps: z.ZodArray<z.ZodString>;
     warnings: z.ZodArray<z.ZodString>;
 }, z.core.$loose>;
+/**
+ * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
+ * A new result needs an entry here and a runtime scenario in the documentation contract tests.
+ */
+export declare const CLI_RESULTS: {
+    readonly init: {
+        readonly command: "atlas init";
+        readonly schemaName: "init-plan";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            directory: z.ZodString;
+            project: z.ZodObject<{
+                name: z.ZodNullable<z.ZodString>;
+                packageManager: z.ZodNullable<z.ZodEnum<{
+                    npm: "npm";
+                    pnpm: "pnpm";
+                    bun: "bun";
+                    yarn: "yarn";
+                }>>;
+                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>;
+    };
+    readonly publish: {
+        readonly command: "atlas report publish";
+        readonly schemaName: "publish-result";
+        readonly schema: 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>;
+    };
+    readonly stream: {
+        readonly command: "atlas report stream";
+        readonly schemaName: "stream-result";
+        readonly schema: 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>;
+    };
+    readonly merge: {
+        readonly command: "atlas report merge";
+        readonly schemaName: "merge-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            into: z.ZodString;
+            copied: z.ZodNumber;
+            skipped: z.ZodNumber;
+            ignored: z.ZodNumber;
+        }, z.core.$loose>;
+    };
+    readonly doctor: {
+        readonly command: "atlas report doctor";
+        readonly schemaName: "doctor-result";
+        readonly schema: 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>;
+    };
+    readonly status: {
+        readonly command: "atlas report status";
+        readonly schemaName: "report-status";
+        readonly schema: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            ok: z.ZodBoolean;
+            reasons: z.ZodArray<z.ZodString>;
+            checks: z.ZodObject<{
+                passed: z.ZodNumber;
+                failed: z.ZodNumber;
+                running: z.ZodNumber;
+                'not-run': z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            byEnvironment: z.ZodRecord<z.ZodString, z.ZodObject<{
+                passed: z.ZodNumber;
+                failed: z.ZodNumber;
+                running: z.ZodNumber;
+                'not-run': z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>>;
+            layers: z.ZodNumber;
+            backends: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                available: z.ZodBoolean;
+            }, z.core.$strip>>;
+            notices: z.ZodArray<z.ZodString>;
+            specsWithoutEvidence: z.ZodArray<z.ZodString>;
+            specs: z.ZodArray<z.ZodObject<{
+                path: z.ZodNullable<z.ZodString>;
+                title: z.ZodString;
+                kind: z.ZodString;
+                checks: z.ZodObject<{
+                    passed: z.ZodNumber;
+                    failed: z.ZodNumber;
+                    running: z.ZodNumber;
+                    'not-run': z.ZodNumber;
+                    total: z.ZodNumber;
+                }, z.core.$strip>;
+                byEnvironment: z.ZodRecord<z.ZodString, z.ZodObject<{
+                    passed: z.ZodNumber;
+                    failed: z.ZodNumber;
+                    running: z.ZodNumber;
+                    'not-run': z.ZodNumber;
+                    total: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$loose>>;
+            failing: z.ZodArray<z.ZodObject<{
+                spec: z.ZodNullable<z.ZodString>;
+                check: z.ZodString;
+                title: z.ZodString;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    running: "running";
+                }>;
+                environment: z.ZodNullable<z.ZodString>;
+                producer: z.ZodString;
+                branch: z.ZodNullable<z.ZodString>;
+                sha: z.ZodNullable<z.ZodString>;
+                layer: z.ZodString;
+                backend: z.ZodString;
+                runUrl: z.ZodNullable<z.ZodString>;
+                detail: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>;
+    };
+    readonly error: {
+        readonly command: "a command that was wrong (standard error)";
+        readonly schemaName: "command-error";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<false>;
+            error: z.ZodObject<{
+                message: z.ZodString;
+                code: z.ZodLiteral<"usage">;
+            }, z.core.$loose>;
+        }, z.core.$loose>;
+    };
+};

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

@@ -13,6 +13,7 @@
  * @see docs/agents.md
  */
 import { z } from 'zod/v4';
+import { ReportStatusSchema } from './layer.js';
 /** 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'),
@@ -122,3 +123,16 @@ export const InitPlanSchema = z.looseObject({
     nextSteps: z.array(z.string()).describe('What to do next, in order, as plain instructions an agent can follow'),
     warnings: z.array(z.string())
 });
+/**
+ * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
+ * A new result needs an entry here and a runtime scenario in the documentation contract tests.
+ */
+export const CLI_RESULTS = {
+    init: { command: 'atlas init', schemaName: 'init-plan', schema: InitPlanSchema },
+    publish: { command: 'atlas report publish', schemaName: 'publish-result', schema: PublishResultSchema },
+    stream: { command: 'atlas report stream', schemaName: 'stream-result', schema: StreamResultSchema },
+    merge: { command: 'atlas report merge', schemaName: 'merge-result', schema: MergeResultSchema },
+    doctor: { command: 'atlas report doctor', schemaName: 'doctor-result', schema: DoctorResultSchema },
+    status: { command: 'atlas report status', schemaName: 'report-status', schema: ReportStatusSchema },
+    error: { command: 'a command that was wrong (standard error)', schemaName: 'command-error', schema: CommandErrorSchema }
+};

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

@@ -17,3 +17,5 @@ export * from './layer.js';
 export * from './server-config.js';
 export * from './api.js';
 export * from './cli-results.js';
+export * from './live-run.js';
+export * from './project.js';

package/dist/schema/src/index.js

@@ -17,3 +17,5 @@ export * from './layer.js';
 export * from './server-config.js';
 export * from './api.js';
 export * from './cli-results.js';
+export * from './live-run.js';
+export * from './project.js';

package/dist/schema/src/live-run.d.ts

@@ -0,0 +1,123 @@
+/** @module Live run protocol
+ * A live run is a producer lease, separate from immutable report layers. Server receipt times determine liveness.
+ * Expiration means interrupted, never passed; completed check results retain the stable layer contract.
+ */
+import { z } from 'zod/v4';
+/** Small progress messages: no attachment bytes, bounded step history and text. */
+export declare const LiveCheckSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        running: "running";
+        "not-run": "not-run";
+    }>;
+    detail: z.ZodDefault<z.ZodString>;
+    specPath: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** The producer starts one UUID-named run. Identity stays fixed for its lifetime. */
+export declare const LiveRunStartSchema: z.ZodObject<{
+    id: z.ZodString;
+    producer: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    sha: z.ZodOptional<z.ZodString>;
+    plannedChecks: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Ordered deltas. A retried sequence must have identical content; terminal runs never accept more progress. */
+export declare const LiveRunUpdateSchema: z.ZodObject<{
+    sequence: z.ZodNumber;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodDefault<z.ZodString>;
+        specPath: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    finish: z.ZodOptional<z.ZodEnum<{
+        completed: "completed";
+        interrupted: "interrupted";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The bounded live feed response; completed and interrupted runs remain visible as recent history. */
+export declare const LiveRunSchema: z.ZodObject<{
+    id: z.ZodString;
+    producer: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    sha: z.ZodOptional<z.ZodString>;
+    plannedChecks: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodEnum<{
+        running: "running";
+        completed: "completed";
+        interrupted: "interrupted";
+    }>;
+    startedAtMs: z.ZodNumber;
+    lastHeartbeatAtMs: z.ZodNumber;
+    lastProgressAtMs: z.ZodNumber;
+    finishedAtMs: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+    sequence: z.ZodNumber;
+    completed: z.ZodNumber;
+    passed: z.ZodNumber;
+    failed: z.ZodNumber;
+    notRun: z.ZodNumber;
+    running: z.ZodNumber;
+    current: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodDefault<z.ZodString>;
+        specPath: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    recent: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            running: "running";
+            "not-run": "not-run";
+        }>;
+        detail: z.ZodDefault<z.ZodString>;
+        specPath: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The shape a producer uses for a progress check. */
+export type LiveCheck = z.input<typeof LiveCheckSchema>;
+/** A server's live run snapshot. */
+export type LiveRun = z.output<typeof LiveRunSchema>;