@crvouga/atlas 0.4.0 → 0.6.0

package/dist/server/src/host.js

@@ -0,0 +1,115 @@
+/**
+ * @module HTTP host for a fetch handler
+ *
+ * `listen` serves any `(Request) => Promise<Response>` over HTTP: with `Bun.serve` when running on Bun, with a `node:http`
+ * bridge (streaming bodies in and out, so server-sent events work) everywhere else. The server's behaviour is the same on
+ * both; `bun run release:smoke` proves it under each. Bodies over `maxBodyBytes` are refused by the runtime before the
+ * handler sees them.
+ */
+import { createServer } from 'node:http';
+import { Readable } from 'node:stream';
+const display = (host, port) => `http://${host === '0.0.0.0' || host === '::' ? 'localhost' : host}:${port}`;
+/**
+ * Serve a fetch handler. On Bun, which is what Atlas is made for, that is `Bun.serve`: one native server for the
+ * API, the live streams and the page. On Node it is the same handler behind `node:http`, so the package still runs
+ * where Bun is not installed.
+ */
+export async function listen(handler, options) {
+    const bun = getBun();
+    if (bun)
+        return listenBun(bun, handler, options);
+    return listenNode(handler, options);
+}
+const getBun = () => globalThis.Bun;
+async function listenBun(bun, handler, options) {
+    const server = bun.serve({
+        port: options.port,
+        hostname: options.host,
+        // Live streams are quiet between heartbeats; the longest idle time Bun allows keeps them open.
+        idleTimeout: 120,
+        maxRequestBodySize: options.maxBodyBytes + 1024 * 1024,
+        fetch: handler,
+        error: (error) => Response.json({ error: error.message }, { status: 500 })
+    });
+    return {
+        port: server.port,
+        url: display(options.host, server.port),
+        close: async (graceMs = 10_000) => {
+            // Stop taking new connections and let requests in flight finish; end the rest after the grace period.
+            const closing = Promise.resolve(server.stop(false));
+            const timer = setTimeout(() => { void server.stop(true); }, graceMs);
+            timer.unref?.();
+            await closing;
+            clearTimeout(timer);
+        }
+    };
+}
+function toRequest(req, host, maxBodyBytes) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers))
+        if (value !== undefined)
+            headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+    const method = req.method ?? 'GET';
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    let size = 0;
+    const body = hasBody ? Readable.toWeb(req).pipeThrough(new TransformStream({ transform(chunk, controller) { size += chunk.byteLength; if (size > maxBodyBytes)
+            controller.error(new Error('The request body is too large'));
+        else
+            controller.enqueue(chunk); } })) : null;
+    return new Request(`http://${req.headers.host ?? host}${req.url ?? '/'}`, { method, headers, ...(body ? { body, duplex: 'half' } : {}) });
+}
+async function send(response, res, head) {
+    const headers = {};
+    response.headers.forEach((value, name) => { headers[name] = value; });
+    const cookies = response.headers.getSetCookie?.();
+    if (cookies?.length)
+        headers['set-cookie'] = cookies;
+    res.writeHead(response.status, headers);
+    if (head || !response.body) {
+        res.end();
+        return;
+    }
+    const reader = response.body.getReader();
+    res.on('close', () => { void reader.cancel().catch(() => { }); });
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!res.write(value))
+            await new Promise(resolve => res.once('drain', resolve));
+    }
+    res.end();
+}
+async function listenNode(handler, options) {
+    const server = createServer((req, res) => {
+        void (async () => {
+            const controller = new AbortController();
+            res.on('close', () => controller.abort());
+            try {
+                const request = toRequest(req, options.host, options.maxBodyBytes);
+                const abortable = new Request(request, { signal: controller.signal });
+                await send(await handler(abortable), res, req.method === 'HEAD');
+            }
+            catch (error) {
+                if (!res.headersSent)
+                    await send(Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 }), res, false).catch(() => { });
+                else
+                    res.destroy();
+            }
+        })();
+    });
+    server.keepAliveTimeout = 65_000;
+    server.requestTimeout = 0;
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port, options.host, resolve); });
+    const port = server.address().port;
+    return {
+        port,
+        url: display(options.host, port),
+        close: (graceMs = 10_000) => new Promise(resolve => {
+            server.close(() => resolve());
+            server.closeIdleConnections?.();
+            const timer = setTimeout(() => { server.closeAllConnections?.(); }, graceMs);
+            timer.unref?.();
+        })
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @module Server package entry point (`@crvouga/atlas/server`)
+ *
+ * Everything needed to run the Atlas server from code: `createAtlasServer` (a `fetch` handler with the live report, uploads
+ * and the viewer), `listen` (serve it over HTTP on Bun or Node), `loadServerConfig` (the file, the environment and the flags
+ * as one checked configuration), `serveMain` (what `atlas serve` runs), `EventHub`, `createAuth`, and the upload checks.
+ *
+ * @see docs/server.md
+ */
+export { createAtlasServer, type AtlasServer, type AtlasServerOptions } from './app.js';
+export { createAuth, type Auth, type Identity } from './auth.js';
+export { assertSafeToListen, ConfigError, loadServerConfig, SERVER_USAGE, type ResolvedServerConfig, type ResolvedToken } from './config.js';
+export { EventHub, type EventName } from './events.js';
+export { listen, type RunningServer } from './host.js';
+export { serveMain } from './main.js';
+export { classify, validateUpload, validKey, Refusal } from './validate.js';
+export { fileServerSettings, type ServerSettings, type SettingsSnapshot } from './settings.js';
+export { LiveRuns, LiveRunError } from './live-runs.js';

package/dist/server/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * @module Server package entry point (`@crvouga/atlas/server`)
+ *
+ * Everything needed to run the Atlas server from code: `createAtlasServer` (a `fetch` handler with the live report, uploads
+ * and the viewer), `listen` (serve it over HTTP on Bun or Node), `loadServerConfig` (the file, the environment and the flags
+ * as one checked configuration), `serveMain` (what `atlas serve` runs), `EventHub`, `createAuth`, and the upload checks.
+ *
+ * @see docs/server.md
+ */
+export { createAtlasServer } from './app.js';
+export { createAuth } from './auth.js';
+export { assertSafeToListen, ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
+export { EventHub } from './events.js';
+export { listen } from './host.js';
+export { serveMain } from './main.js';
+export { classify, validateUpload, validKey, Refusal } from './validate.js';
+export { fileServerSettings } from './settings.js';
+export { LiveRuns, LiveRunError } from './live-runs.js';

package/dist/server/src/live-runs.d.ts

@@ -0,0 +1,52 @@
+import type { z } from 'zod/v4';
+import { type LiveRun, type LiveRunStartSchema, type LiveRunUpdateSchema } from '../../schema/src/live-run.js';
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import type { ReportLayer } from '../../reports/src/layer-types.js';
+type Start = z.output<typeof LiveRunStartSchema>;
+type Update = z.output<typeof LiveRunUpdateSchema>;
+/** A refused run update: 403 another publisher, 404 unknown run, 409 stale/terminal run, or 429 capacity. */
+export declare class LiveRunError extends Error {
+    readonly status: 403 | 404 | 409 | 429;
+    constructor(status: 403 | 404 | 409 | 429, message: string);
+}
+/**
+ * One server's live feed. Heartbeats never create result layers. Persisted summaries contain at most 20 recent
+ * checks and 10 active checks; completed results live in ordinary immutable layers. Leases expire by server time.
+ * @example
+ * const live = new LiveRuns({ store, timeoutMs: 30_000, stalledMs: 900_000, onChange: () => {}, onLayer: async () => {} });
+ */
+export declare class LiveRuns {
+    private readonly options;
+    private readonly held;
+    private readonly attempts;
+    private readonly queues;
+    /** Resolves after restoring summaries and interrupting leases left by a previous server process. */
+    readonly ready: Promise<void>;
+    private readonly now;
+    constructor(options: {
+        store: ObjectStore;
+        timeoutMs: number;
+        stalledMs: number;
+        now?: () => number;
+        onChange: (run: LiveRun) => void;
+        onLayer: (key: string, layer: ReportLayer) => Promise<void>;
+    });
+    private restore;
+    private save;
+    private locked;
+    private state;
+    private interrupt;
+    private expired;
+    private requireLive;
+    /** Read the most recent 50 summaries. Progress detail and counters are already bounded and cached. */
+    list(): Promise<LiveRun[]>;
+    /** Register one producer lease. Retrying an identical start is idempotent. */
+    start(input: Start, owner: string): Promise<LiveRun>;
+    /** Renew liveness by server receipt time, independently of whether a test made progress. */
+    heartbeat(id: string, owner: string): Promise<void>;
+    /** Apply one ordered progress batch and publish its completed checks before acknowledging it. */
+    update(id: string, input: Update, owner: string): Promise<LiveRun>;
+    /** Expire silent producers and optional progress stalls. Heartbeats cannot revive an expired run. */
+    sweep(): Promise<void>;
+}
+export {};

package/dist/server/src/live-runs.js

@@ -0,0 +1,229 @@
+/** @module Live run leases
+ * Tracks producer heartbeats independently of progress, publishes completed checks incrementally, and persists
+ * bounded run summaries. A server restart interrupts outstanding leases rather than inventing continued progress.
+ */
+import { createHash } from 'node:crypto';
+import { LiveRunSchema } from '../../schema/src/live-run.js';
+import { readUtf8, writeUtf8 } from '../../reports/src/object-io.js';
+import { publishChecks } from '../../reports/src/publish-checks.js';
+import { layerCatalogKey } from '../../reports/src/layer-store.js';
+const PREFIX = 'server/live/';
+const keyOf = (run) => `${PREFIX}${String(Number.MAX_SAFE_INTEGER - run.startedAtMs).padStart(16, '0')}-${run.id}.json`;
+/** A refused run update: 403 another publisher, 404 unknown run, 409 stale/terminal run, or 429 capacity. */
+export class LiveRunError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * One server's live feed. Heartbeats never create result layers. Persisted summaries contain at most 20 recent
+ * checks and 10 active checks; completed results live in ordinary immutable layers. Leases expire by server time.
+ * @example
+ * const live = new LiveRuns({ store, timeoutMs: 30_000, stalledMs: 900_000, onChange: () => {}, onLayer: async () => {} });
+ */
+export class LiveRuns {
+    options;
+    held = new Map();
+    attempts = new Map();
+    queues = new Map();
+    /** Resolves after restoring summaries and interrupting leases left by a previous server process. */
+    ready;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.ready = this.restore();
+        // Requests await ready and surface failures; no unhandled rejection while a backend is unavailable.
+        void this.ready.catch(() => undefined);
+    }
+    async restore() {
+        const keys = (await this.options.store.listKeys(PREFIX)).slice(0, 200);
+        for (const key of keys) {
+            const text = await readUtf8(this.options.store, key);
+            if (text === null)
+                continue;
+            const stored = JSON.parse(text);
+            const run = LiveRunSchema.parse(stored.run);
+            const state = { run, owner: stored.owner, digest: stored.digest, states: new Map() };
+            this.held.set(run.id, state);
+            if (run.status === 'running')
+                await this.interrupt(state, 'The Atlas server restarted before the run completed.');
+        }
+    }
+    async save(state) {
+        await writeUtf8(this.options.store, keyOf(state.run), JSON.stringify({ run: state.run, owner: state.owner, digest: state.digest }), 'application/json');
+    }
+    locked(id, action) {
+        const next = (this.queues.get(id) ?? Promise.resolve()).catch(() => { }).then(action);
+        this.queues.set(id, next);
+        return next.finally(() => { if (this.queues.get(id) === next)
+            this.queues.delete(id); });
+    }
+    state(id, owner) {
+        const held = this.held.get(id);
+        if (!held)
+            throw new LiveRunError(404, 'Unknown run.');
+        if (held.owner !== owner)
+            throw new LiveRunError(403, 'This run belongs to another publisher.');
+        return held;
+    }
+    async interrupt(state, reason) {
+        const next = { ...state, states: new Map(), run: { ...state.run, status: 'interrupted', reason, finishedAtMs: this.now(), running: 0,
+                current: state.run.current.map(check => ({ ...check, status: 'not-run', detail: reason })) } };
+        await this.save(next);
+        this.held.set(next.run.id, next);
+        this.options.onChange(next.run);
+    }
+    expired(run) {
+        if (this.now() - run.lastHeartbeatAtMs >= this.options.timeoutMs)
+            return 'Producer heartbeat timed out. The run may have exited or lost its connection.';
+        if (this.options.stalledMs > 0 && this.now() - run.lastProgressAtMs >= this.options.stalledMs)
+            return 'No test progress arrived before the configured stall timeout.';
+        return undefined;
+    }
+    async requireLive(state) {
+        if (state.run.status !== 'running')
+            throw new LiveRunError(409, 'This run has ended.');
+        const reason = this.expired(state.run);
+        if (reason) {
+            await this.interrupt(state, reason);
+            throw new LiveRunError(409, reason);
+        }
+    }
+    /** Read the most recent 50 summaries. Progress detail and counters are already bounded and cached. */
+    async list() {
+        await this.ready;
+        return [...this.held.values()].map(state => state.run).sort((a, b) => b.startedAtMs - a.startedAtMs || a.id.localeCompare(b.id)).slice(0, 50);
+    }
+    /** Register one producer lease. Retrying an identical start is idempotent. */
+    async start(input, owner) {
+        await this.ready;
+        return this.locked(input.id, async () => {
+            const prior = this.held.get(input.id);
+            if (prior) {
+                const found = this.state(input.id, owner);
+                if (Object.entries(input).some(([key, value]) => found.run[key] !== value))
+                    throw new LiveRunError(409, 'A run id cannot be reused with another identity.');
+                return found.run;
+            }
+            if ([...this.held.values()].filter(state => state.run.status === 'running').length >= 100)
+                throw new LiveRunError(429, 'Too many live runs.');
+            const now = this.now();
+            const state = { owner, digest: '', states: new Map(), run: { ...input, status: 'running', sequence: 0, startedAtMs: now, lastHeartbeatAtMs: now, lastProgressAtMs: now, completed: 0, passed: 0, failed: 0, notRun: 0, running: 0, current: [], recent: [] } };
+            await this.save(state);
+            this.held.set(input.id, state);
+            // Retain bounded terminal history in memory; durable summaries remain in the configured backend.
+            if (this.held.size > 200) {
+                const old = [...this.held.values()].filter(value => value.run.status !== 'running').sort((a, b) => a.run.startedAtMs - b.run.startedAtMs)[0];
+                if (old)
+                    this.held.delete(old.run.id);
+            }
+            this.options.onChange(state.run);
+            return state.run;
+        });
+    }
+    /** Renew liveness by server receipt time, independently of whether a test made progress. */
+    async heartbeat(id, owner) {
+        await this.ready;
+        await this.locked(id, async () => {
+            const state = this.state(id, owner);
+            await this.requireLive(state);
+            const next = { ...state, run: { ...state.run, lastHeartbeatAtMs: this.now() } };
+            await this.save(next);
+            this.held.set(id, next);
+            this.options.onChange(next.run);
+        });
+    }
+    /** Apply one ordered progress batch and publish its completed checks before acknowledging it. */
+    async update(id, input, owner) {
+        await this.ready;
+        return this.locked(id, async () => {
+            const state = this.state(id, owner);
+            const digest = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+            if (input.sequence === state.run.sequence && digest === state.digest)
+                return state.run;
+            await this.requireLive(state);
+            if (input.sequence !== state.run.sequence + 1)
+                throw new LiveRunError(409, 'This run ended or its progress sequence is stale.');
+            if (state.states.size + input.checks.filter(check => !state.states.has(check.id)).length > 100_000)
+                throw new LiveRunError(429, 'A live run may track at most 100000 check identities.');
+            const priorAttempt = this.attempts.get(id);
+            if (priorAttempt && (priorAttempt.sequence !== input.sequence || priorAttempt.digest !== digest))
+                throw new LiveRunError(409, 'Retry the pending sequence with identical content.');
+            const now = priorAttempt?.at ?? Math.max(this.now(), state.run.lastProgressAtMs + 1);
+            const states = new Map(state.states);
+            const run = { ...state.run, sequence: input.sequence, lastHeartbeatAtMs: now, ...(input.checks.length ? { lastProgressAtMs: now } : {}) };
+            const current = new Map(run.current.map(check => [check.id, check]));
+            for (const check of input.checks) {
+                const prior = states.get(check.id);
+                if (prior === 'running')
+                    run.running--;
+                else if (prior) {
+                    run.completed--;
+                    if (prior === 'passed')
+                        run.passed--;
+                    else if (prior === 'failed')
+                        run.failed--;
+                    else
+                        run.notRun--;
+                }
+                states.set(check.id, check.status);
+                if (check.status === 'running') {
+                    run.running++;
+                    current.set(check.id, check);
+                }
+                else {
+                    run.completed++;
+                    if (check.status === 'passed')
+                        run.passed++;
+                    else if (check.status === 'failed')
+                        run.failed++;
+                    else
+                        run.notRun++;
+                    current.delete(check.id);
+                }
+            }
+            run.current = [...current.values()].slice(-10);
+            run.recent = [...input.checks].reverse().concat(run.recent.filter(check => !input.checks.some(next => next.id === check.id))).slice(0, 20);
+            if (input.finish) {
+                if (input.finish === 'completed' && run.running)
+                    throw new LiveRunError(409, 'Finish running checks before completing the run.');
+                run.status = input.finish;
+                run.finishedAtMs = now;
+                run.reason = input.reason;
+                if (input.finish === 'interrupted') {
+                    run.running = 0;
+                    run.current = run.current.map(check => ({ ...check, status: 'not-run', detail: input.reason ?? 'Run interrupted.' }));
+                }
+                states.clear();
+            }
+            const finished = input.checks.filter(check => check.status !== 'running');
+            this.attempts.set(id, { sequence: input.sequence, digest, at: now });
+            if (finished.length) {
+                const layer = await publishChecks(this.options.store, { producer: state.run.producer, environment: state.run.environment, branch: state.run.branch, sha: state.run.sha, recordedAtMs: now,
+                    labels: { 'atlas.run': id }, checks: finished });
+                await this.options.onLayer(layerCatalogKey(layer.recordedAtMs, layer.id), layer);
+            }
+            const next = { ...state, states, run, digest };
+            await this.save(next);
+            this.held.set(id, next);
+            this.attempts.delete(id);
+            this.options.onChange(run);
+            return run;
+        });
+    }
+    /** Expire silent producers and optional progress stalls. Heartbeats cannot revive an expired run. */
+    async sweep() {
+        await this.ready;
+        await Promise.all([...this.held.keys()].map(id => this.locked(id, async () => {
+            const state = this.held.get(id);
+            if (state.run.status !== 'running')
+                return;
+            const reason = this.expired(state.run);
+            if (reason)
+                await this.interrupt(state, reason);
+        })));
+    }
+}

package/dist/server/src/llms.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module llms.txt of a running server
+ *
+ * The plain-text guide ([llms.txt](https://llmstxt.org)) a server serves about itself at `GET /llms.txt`, for an AI
+ * agent that was handed nothing but the server's address. It is written from this server's own settings (its
+ * address, whether it needs a token), so what it says is true of the server that says it, and it points at the
+ * machine-readable description (`/api/openapi.json`) rather than repeating it.
+ */
+/** What the guide says about the server that serves it. */
+export type LlmsContext = {
+    /** The address clients use, such as `https://atlas.example.com`, no trailing slash. */
+    readonly url: string;
+    /** True when the server has no tokens: anyone who can reach it may upload. */
+    readonly open: boolean;
+    /** The id of the backend uploads go to. */
+    readonly write: string;
+};
+/** The guide for one server, Markdown. Stable in structure: an agent may read it by its headings. */
+export declare function llmsTxt(context: LlmsContext): string;

package/dist/server/src/llms.js

@@ -0,0 +1,63 @@
+/**
+ * @module llms.txt of a running server
+ *
+ * The plain-text guide ([llms.txt](https://llmstxt.org)) a server serves about itself at `GET /llms.txt`, for an AI
+ * agent that was handed nothing but the server's address. It is written from this server's own settings (its
+ * address, whether it needs a token), so what it says is true of the server that says it, and it points at the
+ * machine-readable description (`/api/openapi.json`) rather than repeating it.
+ */
+/** The guide for one server, Markdown. Stable in structure: an agent may read it by its headings. */
+export function llmsTxt(context) {
+    const { url } = context;
+    return `# Atlas server at ${url}
+
+> Atlas shows whether a product still does what it was specified to do. Every environment (laptops, CI, device labs) sends its test results here as immutable "layers"; this server keeps them and shows everyone one combined report, live. The newest completed result of every check wins its slot, whoever sent it.
+
+## Machine-readable description
+
+- [OpenAPI 3.1](${url}/api/openapi.json): every endpoint, parameter, body, response and error. Generate a client or a test suite from it.
+- [JSON Schemas](https://unpkg.com/@crvouga/atlas/packages/schema/schemas/): the layer format, the checks file, the report status and the server's responses.
+- Errors are RFC 9457 problem documents (\`application/problem+json\`); \`detail\` says what to do.
+- Live updates: \`GET ${url}/api/events\` (server-sent events: \`hello\`, \`report\`, \`atlas:change\`, \`ping\`).
+
+## Authenticate
+
+${context.open
+        ? 'This server has **no tokens**: anyone who can reach it may upload. Nothing to configure.'
+        : `This server needs a token. Ask the operator for a \`publish\` token (to upload) and a \`read\` token (to look). Send \`Authorization: Bearer <token>\`; the CLI reads \`ATLAS_TOKEN\`. Uploading needs the Bearer header. A token is a secret of this one server: never put it in a URL or send it to another host.`}
+
+## Integrate a project (run in the project's repository)
+
+\`\`\`sh
+export ATLAS_STORE=${url}${context.open ? '' : '\nexport ATLAS_TOKEN=<a publish token>'}
+bunx @crvouga/atlas init --server ${url}          # detects test runners and specs, prints a plan (add --json for a machine-readable one)
+bunx @crvouga/atlas init --server ${url} --write  # writes the CI workflow and the AGENTS.md section the plan names
+bunx @crvouga/atlas report doctor                 # proves the server can be written to and read
+\`\`\`
+
+After each suite, send its results (a JUnit or CTRF file, or JSON lines as checks finish):
+
+\`\`\`sh
+bunx @crvouga/atlas report publish --producer <suite> --junit out.xml --specs ./specs --environment <env>
+my-suite --json | bunx @crvouga/atlas report stream --producer <suite> --environment <env>
+\`\`\`
+
+Or with no tooling at all: \`POST ${url}/api/checks\` with \`{"producer":"smoke","checks":[{"id":"login","title":"can log in","status":"passed"}]}\`.
+
+## Ask whether it passes
+
+\`\`\`sh
+bunx @crvouga/atlas report status --format json --branch main --ignore-modified   # exit 0 pass, 1 does not, 2 wrong command
+curl ${context.open ? '' : '-H "authorization: Bearer $ATLAS_TOKEN" '}${url}/api/status                      # the same verdict; header X-Atlas-Ok: true|false
+\`\`\`
+
+## Rules worth knowing
+
+- **Layered, never partitioned.** A check is identified by its \`id\` (keep it stable across runs) plus producer, kind, spec, environment and parameters. A layer that re-ran one check leaves every other check as the last layer that ran it.
+- **Unknown is never a pass.** A check still \`running\`, a layer that could not be read, a backend that is down, or a required environment with no results all fail the gate.
+- **Failures are evidence: publish them.** Run the suite, ignore its exit code, publish, then gate.
+- **Layers are immutable** and named by their content: re-publishing is safe, and a retry never makes a duplicate.
+- Uploads go to the backend \`${context.write}\`. Read \`${url}/api/server\` for the backends and what this server can do (\`capabilities\`).
+- Evidence (screenshots, videos, traces, logs, steps, annotations, your own data) rides on checks: see https://github.com/crvouga/atlas/blob/main/docs/extending.md
+`;
+}

package/dist/server/src/main.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module `atlas serve`
+ *
+ * Starts the Atlas server from its configuration: opens every backend (creating the data folder), proves the upload
+ * backend can be written to before listening, finds or builds the client, listens at once (so a liveness probe finds the
+ * process while a large backend is still being read), and stops cleanly on SIGTERM or SIGINT. `serverOptionsOf` is shared
+ * with `atlas dev`, so the two run the same server.
+ *
+ * @see docs/server.md#run-it
+ */
+import type { BackendInput } from '../../reports/src/compose.js';
+import { type AtlasServerOptions } from './app.js';
+import { type ResolvedServerConfig } from './config.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/** What `serveMain` and `devMain` are given besides arguments: where output goes, and, for tests and embedding, the environment, working directory and an `AbortSignal` that stops the server (otherwise SIGTERM and SIGINT do). */
+export type ServeIo = {
+    readonly out: (text: string) => void;
+    readonly env?: Env;
+    readonly cwd?: string;
+    readonly signal?: AbortSignal;
+};
+/** Open every backend of a configuration. The data folder is made if it is not there. */
+export declare function openConfiguredBackends(config: ResolvedServerConfig, env: Env, cwd: string): (BackendInput & {
+    readonly writable: boolean;
+})[];
+/** What `createAtlasServer` is given for a configuration: `atlas serve` and `atlas dev` run the same server. */
+export declare function serverOptionsOf(config: ResolvedServerConfig, backends: ReturnType<typeof openConfiguredBackends>, log?: (line: Record<string, unknown>) => void): AtlasServerOptions;
+/** `atlas serve`. Runs until it is told to stop; returns the exit code. */
+export declare function serveMain(argv: readonly string[], io: ServeIo): Promise<number>;
+export {};