@crvouga/atlas 0.5.0 → 0.6.0

package/docs/reference/reports.md

@@ -895,7 +895,7 @@ One thing `inspectStore` checked: its `name` (`store`, `list`, `contents`, `writ
 export function iamPolicy(location: { bucket: string; prefix: string }, role: 'publisher' | 'reader' | 'both'): object
 ```
 
-The least an account needs, as an AWS IAM policy. R2, MinIO and the rest have their own policy languages: grant the same actions.
+The least an account needs, as an AWS IAM policy. The combined server role also stores operational leases under server/live/. R2, MinIO and the rest have their own policy languages: grant the same actions.
 
 #### `Role`
 
@@ -2453,6 +2453,8 @@ See docs/server.md#the-store-protocol
 
 ```ts
 export type HttpStoreOptions = {
+  /** Project namespace on a shared Atlas node. Omit for the legacy default project. */
+  readonly project?: string;
   /** The Atlas server, such as `https://atlas.example.com`. A path on it (`/atlas`) is kept. */
   readonly url: string;
   /** A publish or admin token to write with, a read token to read with. Never put it in the URL. */
@@ -2480,6 +2482,8 @@ What an Atlas server said no to, with what to do about it.
 
 ```ts
 export type HttpStore = ObjectStore & PagedListing & {
+  /** The same authenticated node connection, scoped to another project. */
+  forProject(project: string): HttpStore;
   /** `https://atlas.example.com`, with no secrets. */
   readonly label: string;
   readonly url: string;
@@ -3619,6 +3623,56 @@ Routes, relative to where it is mounted:
 Directory listings are cached for 30 s (1.5 s for the local store). A listing that fails keeps the previous keys and
 marks the backend unavailable; the page then carries a notice.
 
+### live-reporter.ts
+
+Source: `packages/reports/src/live-reporter.ts`. Import: `@crvouga/atlas/reports/live-reporter`
+
+@module Reporting a live run to Atlas
+Streams bounded check deltas while tests execute. Heartbeats are independent of progress; finished results are
+published by the server as ordinary immutable layers. A final flush is awaited before a runner exits.
+
+#### `LiveIdentity`
+
+```ts
+export type LiveIdentity = Omit<z.input<typeof LiveRunStartSchema>, 'id'> & { id?: string };
+```
+
+Fixed identity of a live invocation; a UUID is generated when omitted.
+
+#### `LiveReporterOptions`
+
+```ts
+export type LiveReporterOptions = { url: string; project?: string; token?: string; flushMs?: number; heartbeatMs?: number; timeoutMs?: number; onError?: (error: Error) => void };
+```
+
+Transport and batching configuration. Defaults: 250 ms batches, 5 s heartbeats and 10 s request timeouts.
+
+#### `LiveReporter`
+
+```ts
+export type LiveReporter = { readonly id: string; readonly finishedAtMs?: number; check(check: LiveCheck): void; flush(): Promise<void>; finish(status?: 'completed' | 'interrupted', reason?: string): Promise<void> };
+```
+
+Producer handle. check never throws transport errors into a test; finish flushes and rejects if publication failed.
+
+#### `createLiveReporter`
+
+```ts
+export function createLiveReporter(identity: LiveIdentity, options: LiveReporterOptions): LiveReporter
+```
+
+Start publishing immediately, batch changing checks, and send independent heartbeats while the producer is alive.
+The same failed batch is retried with the same sequence and content; never silently replace a lost update.
+
+**Example**
+
+```ts
+const run = createLiveReporter({ producer: 'unit', plannedChecks: 10 }, { url: 'http://localhost:5180' });
+run.check({ id: 'a', title: 'Adds a todo', status: 'running' });
+run.check({ id: 'a', title: 'Adds a todo', status: 'passed' });
+await run.finish();
+```
+
 ### Media types by file extension
 
 Source: `packages/reports/src/media-types.ts`. Import: `@crvouga/atlas/reports/media-types`

package/docs/reference/runners.md

@@ -0,0 +1,169 @@
+# Reference: runners
+
+Native reporters that upload to the project server. Import paths `@crvouga/atlas/codecept`, `@crvouga/atlas/mocha`, `@crvouga/atlas/jest`, `@crvouga/atlas/node-test`.
+
+> Generated from the doc comments of `packages/runners/src` by `bun run docs`. Do not edit: change the comment next to the code.
+
+### codecept.ts
+
+Source: `packages/runners/src/codecept.ts`. Import: `@crvouga/atlas/codecept`
+
+@module CodeceptJS reporter
+CodeceptJS's Mocha reporter interface carries scenario outcomes and steps to the singleton Atlas server.
+
+#### `AtlasCodeceptReporter`
+
+```ts
+export default class AtlasCodeceptReporter extends AtlasMochaReporter
+```
+
+Use `codeceptjs run --reporter
+
+**Example**
+
+```ts
+// codecept.conf.js
+export const config = { tests: './tests/*_test.js', reporter: '@crvouga/atlas/codecept' };
+```
+
+### jest.ts
+
+Source: `packages/runners/src/jest.ts`. Import: `@crvouga/atlas/jest`
+
+@module Jest reporter
+Uploads the aggregated results after Jest has finished, with suite crashes represented as failed checks.
+
+#### `AtlasJestReporter`
+
+```ts
+export default class AtlasJestReporter
+```
+
+Jest's native reporter; retain `default` in the reporter list for console output. Upload errors fail Jest.
+
+**Example**
+
+```ts
+export default { reporters: ['default', ['@crvouga/atlas/jest', { url: 'https://atlas.example.com' }]] };
+```
+
+- `onRunStart(result?: { numTotalTests?: number }): void` — Reset publishing errors for each watch-mode invocation.
+- `onTestCaseStart(test: { path: string }, info: { fullName: string; title: string }): void` — Publish the test as running before its body executes in a worker.
+- `onTestCaseResult(test: { path: string }, result: Result['testResults'][number]): void` — Stream each test outcome immediately, without waiting for other files to finish.
+- `async onRunComplete(_contexts: unknown, result: { testResults: Result[] }): Promise<void>` — Await uploading every final result, including test-file failures before any test ran.
+- `getLastError(): Error | undefined` — Jest uses this to turn a publishing error into a failed invocation.
+
+### mocha.ts
+
+Source: `packages/runners/src/mocha.ts`. Import: `@crvouga/atlas/mocha`
+
+@module Mocha and CodeceptJS reporter
+Receives Mocha's final test outcomes, including CodeceptJS scenarios, and waits for the server upload in `done`.
+No runner package is imported, so consumers use their own installed version.
+
+#### `AtlasMochaReporter`
+
+```ts
+export default class AtlasMochaReporter
+```
+
+Mocha reporter; use `--reporter
+
+**Example**
+
+```ts
+// mocha configuration
+export default { reporter: '@crvouga/atlas/mocha', reporterOptions: { url: 'https://atlas.example.com' } };
+```
+
+- `done(failures: number, callback: (failures: number) => void): void` — Mocha waits for this callback before exiting. Publishing errors fail the invocation.
+
+### node-test.ts
+
+Source: `packages/runners/src/node-test.ts`. Import: `@crvouga/atlas/node-test`
+
+@module Node test runner reporter
+Consumes Node's test event stream and publishes final leaf outcomes to the project Atlas server.
+
+#### `atlasNodeReporter`
+
+```ts
+export default async function* atlasNodeReporter(source: AsyncIterable<Event>): AsyncGenerator<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**
+
+```ts
+// node --test --test-reporter=spec --test-reporter=@crvouga/atlas/node-test
+```
+
+### publish.ts
+
+Source: `packages/runners/src/publish.ts`
+
+@module Publishing native runner results
+Native reporters send checks to the project's Atlas server. Only the server knows its storage backend.
+
+#### `ReporterOptions`
+
+```ts
+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;
+};
+```
+
+Reporter options; explicit values override ATLAS_SERVER_URL, ATLAS_PUBLISH_TOKEN, ATLAS_ENVIRONMENT, ATLAS_BRANCH and ATLAS_SHA.
+
+#### `testFile`
+
+```ts
+export function testFile(file: string | undefined, root = process.cwd()): string
+```
+
+A portable check identity: paths relative to the project, using forward slashes on every OS.
+
+#### `uploadChecks`
+
+```ts
+export async function uploadChecks(runner: string, checks: readonly EvidenceCheck[], options: ReporterOptions = {}): Promise<void>
+```
+
+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**
+
+```ts
+await uploadChecks('mocha', checks, { url: 'https://atlas.example.com', token: process.env.ATLAS_PUBLISH_TOKEN });
+```
+
+#### `runnerLive`
+
+```ts
+export function runnerLive(runner: string, options: ReporterOptions = {}, plannedChecks?: number): import('../../reports/src/live-reporter').LiveReporter
+```
+
+Start the native runner's live feed with the same endpoint and identity as its final report.
+
+#### `finishRunner`
+
+```ts
+export async function finishRunner(live: import('../../reports/src/live-reporter').LiveReporter, runner: string, checks: readonly EvidenceCheck[], options: ReporterOptions = {}): Promise<void>
+```
+
+Flush live progress, then publish the full final evidence even if the lease was interrupted. Reject either failure.

package/docs/reference/schema.md

@@ -863,6 +863,62 @@ export type SpecSet = z.output<typeof SpecSetSchema>;
 
 A parsed `SpecSetSchema` value.
 
+### live-run.ts
+
+Source: `packages/schema/src/live-run.ts`
+
+@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.
+
+#### `LiveCheckSchema`
+
+```ts
+export const LiveCheckSchema = …
+```
+
+Small progress messages: no attachment bytes, bounded step history and text.
+
+#### `LiveRunStartSchema`
+
+```ts
+export const LiveRunStartSchema = …
+```
+
+The producer starts one UUID-named run. Identity stays fixed for its lifetime.
+
+#### `LiveRunUpdateSchema`
+
+```ts
+export const LiveRunUpdateSchema = …
+```
+
+Ordered deltas. A retried sequence must have identical content; terminal runs never accept more progress.
+
+#### `LiveRunSchema`
+
+```ts
+export const LiveRunSchema = …
+```
+
+The bounded live feed response; completed and interrupted runs remain visible as recent history.
+
+#### `LiveCheck`
+
+```ts
+export type LiveCheck = z.input<typeof LiveCheckSchema>;
+```
+
+The shape a producer uses for a progress check.
+
+#### `LiveRun`
+
+```ts
+export type LiveRun = z.output<typeof LiveRunSchema>;
+```
+
+A server's live run snapshot.
+
 ### Statechart run manifest schemas
 
 Source: `packages/schema/src/manifest.ts`
@@ -1205,6 +1261,45 @@ The top level of `runs/<run-id>/manifest.json`. Sections are `unknown` here so a
 validate each record on its own and keep the valid ones; the record schemas above are the
 contract for each entry.
 
+### project.ts
+
+Source: `packages/schema/src/project.ts`
+
+@module Project identity
+Project slugs partition every report, spec, recording and live run on an Atlas node.
+
+#### `ProjectSlugSchema`
+
+```ts
+export const ProjectSlugSchema = …
+```
+
+A portable project namespace: 1–64 lowercase letters, digits or hyphens, starting and ending with a letter or digit.
+
+#### `ProjectSchema`
+
+```ts
+export const ProjectSchema = …
+```
+
+One project advertised by a node. The default project contains uploads from older clients.
+
+#### `ProjectsSchema`
+
+```ts
+export const ProjectsSchema = …
+```
+
+Project discovery response.
+
+#### `Project`
+
+```ts
+export type Project = z.output<typeof ProjectSchema>;
+```
+
+A project's public identity.
+
 ### Report sources and change notices
 
 Source: `packages/schema/src/report-sources.ts`
@@ -1399,6 +1494,22 @@ export type ServerConfigInput = z.input<typeof ServerConfigSchema>;
 
 A server configuration as written, before defaults are applied.
 
+#### `ServerEditableSettingsSchema`
+
+```ts
+export const ServerEditableSettingsSchema = …
+```
+
+Storage and report settings editable by an admin. Authentication, listeners and the served site stay deployment-owned. Replaces the editable portion of the file; omitted fields use defaults after restart.
+
+#### `ServerSettingsSnapshotSchema`
+
+```ts
+export const ServerSettingsSnapshotSchema = …
+```
+
+The settings API response: persisted editable configuration, active values, concurrency revision and restart/precedence guidance. Authentication token settings are excluded.
+
 ### Statechart spec schemas
 
 Source: `packages/schema/src/spec.ts`

package/docs/reference/server.md

@@ -24,6 +24,8 @@ export type AtlasServerOptions = {
   readonly backends: readonly BackendInput[];
   /** The id of the backend uploads go to. */
   readonly write: string;
+  /** Operational lease storage. Defaults to the write backend; HTTP relays use their own local store. */
+  readonly liveStore?: ObjectStore;
   readonly tokens?: readonly ResolvedToken[];
   readonly anonymousRead?: boolean;
   /** The built viewer. Without it, only the API is served. */
@@ -33,9 +35,15 @@ export type AtlasServerOptions = {
   readonly refreshMs?: number;
   readonly limits?: { readonly maxObjectMiB?: number; readonly maxJsonMiB?: number; readonly maxStreams?: number };
   readonly heartbeatMs?: number;
+  /** Producer lease timeout; default 30 seconds. */
+  readonly runTimeoutMs?: number;
+  /** Maximum time without progress; default 15 minutes, 0 disables. */
+  readonly runStallMs?: number;
   readonly log?: (line: Record<string, unknown>) => void;
   readonly now?: () => number;
   readonly version?: string;
+  /** Admin configuration persistence, supplied by atlas serve. Changes apply on restart. */
+  readonly settings?: ServerSettings;
   /** Extra runtime configuration written into the page. */
   readonly page?: Record<string, unknown>;
 };
@@ -252,9 +260,9 @@ A server that anyone on the network can upload to must say who may.
 
 Source: `packages/server/src/dev.ts`
 
-Runs the same server as `atlas serve` on a port of its own, with the viewer's Vite dev server in front of it. Vite proxies
+Runs the same server as `atlas serve` on a port of its own, with the client's Vite dev server in front of it. Vite proxies
 `/api` (server-sent events included) to the server and writes the same address book into the page, so the browser, the
-uploaders and the viewer all use one host, exactly as in production, and a change to the viewer shows at once.
+uploaders and the client all use one host, exactly as in production, and a change to the client shows at once.
 
 #### `DEV_USAGE`
 
@@ -277,7 +285,7 @@ export async function devMain(argv: readonly string[], io: ServeIo): Promise<num
 Source: `packages/server/src/events.ts`
 
 What the server tells every connected viewer the moment it happens. A viewer that misses some (a dropped connection, a
-laptop that slept) loses nothing: events say "something changed", the state is always fetched, and a viewer reads again
+laptop that slept) loses nothing: report events announce changes, run events carry bounded progress snapshots, and a viewer reads authoritative state again
 when it reconnects. `EventHub` encodes each event once for all viewers, sends a named `ping` every heartbeat so proxies
 keep the connection and a quiet server is told apart from a dead one, refuses past a maximum number of viewers (they poll
 instead), and lets go of a viewer that has stopped reading rather than hold its backlog.
@@ -287,10 +295,10 @@ See docs/server.md#streaming
 #### `EventName`
 
 ```ts
-export type EventName = 'hello' | 'report' | 'atlas:change';
+export type EventName = 'hello' | 'report' | 'atlas:change' | 'run' | 'projects';
 ```
 
-The events the server publishes: `hello` (sent first to a new viewer), `report` (layers arrived) and `atlas:change` (specs or runs changed). `ping` is the heartbeat, sent by the hub itself.
+The events the server publishes: `hello` (sent first to a new viewer), `report` (layers arrived) `atlas:change` (specs or runs changed), `run` (a bounded live lease snapshot), and `projects` (project discovery changed). `ping` is the heartbeat, sent by the hub itself.
 
 #### `EventHub`
 
@@ -360,6 +368,44 @@ as one checked configuration), `serveMain` (what `atlas serve` runs), `EventHub`
 
 See docs/server.md
 
+### live-runs.ts
+
+Source: `packages/server/src/live-runs.ts`
+
+@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.
+
+#### `LiveRunError`
+
+```ts
+export class LiveRunError extends Error
+```
+
+A refused run update: 403 another publisher, 404 unknown run, 409 stale/terminal run, or 429 capacity.
+
+#### `LiveRuns`
+
+```ts
+export class LiveRuns
+```
+
+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**
+
+```ts
+const live = new LiveRuns({ store, timeoutMs: 30_000, stalledMs: 900_000, onChange: () => {}, onLayer: async () => {} });
+```
+
+- `readonly ready: Promise<void>;` — Resolves after restoring summaries and interrupting leases left by a previous server process.
+- `async list(): Promise<LiveRun[]>` — Read the most recent 50 summaries. Progress detail and counters are already bounded and cached.
+- `async start(input: Start, owner: string): Promise<LiveRun>` — Register one producer lease. Retrying an identical start is idempotent.
+- `async heartbeat(id: string, owner: string): Promise<void>` — Renew liveness by server receipt time, independently of whether a test made progress.
+- `async update(id: string, input: Update, owner: string): Promise<LiveRun>` — Apply one ordered progress batch and publish its completed checks before acknowledging it.
+- `async sweep(): Promise<void>` — Expire silent producers and optional progress stalls. Heartbeats cannot revive an expired run.
+
 ### llms.txt of a running server
 
 Source: `packages/server/src/llms.ts`
@@ -397,7 +443,7 @@ The guide for one server, Markdown. Stable in structure: an agent may read it by
 Source: `packages/server/src/main.ts`
 
 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 viewer, listens at once (so a liveness probe finds the
+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.
 
@@ -494,8 +540,7 @@ One operation of the API, and the route the server registers for it.
 export const OPERATIONS: readonly Operation[]
 ```
 
-Every operation of the API. The order is the order of the document. The descriptions are the documentation an
-agent reads, so they say what to send, what comes back, and what to do when it does not work.
+Every node operation and the same stable report protocol inside each project namespace.
 
 #### `NOT_OPERATIONS`
 
@@ -541,21 +586,116 @@ The response made into a problem document when it is an error (status 400 or mor
 `error`. Headers (`WWW-Authenticate`, `Retry-After`, `Allow`) and any other body fields are kept. Anything else,
 including every success, is returned as it is.
 
-### Finding the viewer
+### projects.ts
+
+Source: `packages/server/src/projects.ts`
+
+@module Project routing
+One node serves isolated project stores through the same authenticated API. Legacy unqualified requests address
+the default project; named projects use scoped stores without rewriting uploaded report documents.
+
+#### `projectServer`
+
+```ts
+export function projectServer(options: AtlasServerOptions, create: (options: AtlasServerOptions) => AtlasServer): AtlasServer
+```
+
+Wrap the single-project protocol in project selection. Auth, upload validation and composition stay identical.
+
+### settings-page.ts
+
+Source: `packages/server/src/settings-page.ts`
+
+@module Settings page
+A standalone administrator form, styled with the Atlas client's shared design tokens.
+Credentials remain in page memory; the settings API owns authorization and validation.
+
+#### `SETTINGS_PAGE`
+
+```ts
+export const SETTINGS_PAGE = …
+```
+
+The settings form and its browser controller, also usable without a built client.
+
+#### `renderSettingsPage`
+
+```ts
+export function renderSettingsPage(): Promise<string>
+```
+
+Render Settings using the exact design tokens shipped with the Atlas client. Loads and caches the stylesheet
+on first request, never at import time. Minimal neutral tokens keep embedded API-only servers usable too.
+
+**Example**
+
+```ts
+const html = await renderSettingsPage();
+```
+
+### settings.ts
+
+Source: `packages/server/src/settings.ts`
+
+@module Persisted server settings
+The admin UI edits storage and report configuration in atlas.server.json. Changes take effect on restart;
+environment variables and flags keep their documented precedence. Authentication is managed outside this UI.
+
+#### `SettingsSnapshot`
+
+```ts
+export type SettingsSnapshot = { readonly revision: string; readonly settings: Record<string, unknown>; readonly active: Record<string, unknown>; readonly restartRequired: boolean; readonly precedence: string };
+```
+
+The persisted editable settings, active settings and a revision for optimistic concurrency. Authentication token settings are excluded.
+
+#### `ServerSettings`
+
+```ts
+export type ServerSettings = { read(): Promise<SettingsSnapshot>; save(settings: unknown, revision: string): Promise<SettingsSnapshot> };
+```
+
+Storage for the admin API; saving is serialized and refuses a stale revision.
+
+#### `fileServerSettings`
+
+```ts
+export function fileServerSettings(config: ResolvedServerConfig, argv: readonly string[], env: Readonly<Record<string, string | undefined>>, cwd: string): ServerSettings
+```
+
+Manage the server's configuration file with atomic replacement, preserving authentication and unrelated fields.
+Validates both the file alone and the effective configuration before saving. Never migrates or deletes report data.
+Changes need a server restart; deployment environment variables and flags override the file.
+
+**Example**
+
+```ts
+const settings = fileServerSettings(config, argv, process.env, process.cwd());
+```
+
+### Finding the client
 
 Source: `packages/server/src/site.ts`
 
-Locates the built viewer a server serves: the folder named by `--site`, `./atlas-site`, or one built once into the user's
-cache from the viewer source shipped in the package (`atlas-visualizer build --no-data`). The build is the same for every
+Locates the built client a server serves: the folder named by `--site`, `./atlas-site`, or one built once into the user's
+cache from the client source shipped in the package (`atlas client build --no-data`). The build is the same for every
 project because the server writes its own address book into the page, so it is built at most once per installed version.
 
+#### `clientMain`
+
+```ts
+export async function clientMain(argv: readonly string[]): Promise<number>
+```
+
+Run the Atlas client build tools. Returns the child's exit code; throws when the client is missing.
+
 #### `visualizerRoot`
 
 ```ts
 export function visualizerRoot(): string | null
 ```
 
-Where the viewer's source is, in this repository and in an installed package.
+Where the client's source is, in this repository and in an installed package.
 
 #### `buildSite`
 
@@ -563,7 +703,7 @@ Where the viewer's source is, in this repository and in an installed package.
 export async function buildSite(out: string, log: (text: string) => void): Promise<boolean>
 ```
 
-Build the viewer once into a folder, for a server that was not given a prebuilt one.
+Build the client once into a folder, for a server that was not given a prebuilt one.
 
 #### `findSite`
 
@@ -571,7 +711,7 @@ Build the viewer once into a folder, for a server that was not given a prebuilt
 export async function findSite(named: string | undefined, cwd: string, log: (text: string) => void): Promise<string | null>
 ```
 
-The viewer to serve: the one named, a build beside the project, or one built into the user's cache.
+The client to serve: the one named, a build beside the project, or one built into the user's cache.
 
 ### Store protocol routes