@crvouga/atlas 0.3.0 → 0.5.0

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 viewer, 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 {};

package/dist/server/src/main.js

@@ -0,0 +1,112 @@
+/**
+ * @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 viewer, 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 { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { openStore } from '../../reports/src/store-url.js';
+import { createAtlasServer } from './app.js';
+import { ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
+import { listen } from './host.js';
+import { findSite } from './site.js';
+/** Open every backend of a configuration. The data folder is made if it is not there. */
+export function openConfiguredBackends(config, env, cwd) {
+    return config.backends.map((spec, i) => {
+        if (i === 0)
+            mkdirSync(spec.url, { recursive: true });
+        const opened = openStore(spec.url, { base: cwd, env });
+        return { id: spec.id, label: spec.label, store: opened.store, writable: spec.id === config.writeId };
+    });
+}
+/** Can the server put things in the place uploads go? Said at the start, not at the first upload. */
+async function probeWritable(backend) {
+    const key = `layers/doctor-${Math.random().toString(36).slice(2, 10)}/probe`;
+    try {
+        await backend.store.put(key, new TextEncoder().encode('atlas'), 'text/plain');
+        if (!(await backend.store.head(key)))
+            return 'an object was written but could not be found again';
+        await backend.store.delete(key).catch(() => { });
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+/** What `createAtlasServer` is given for a configuration: `atlas serve` and `atlas dev` run the same server. */
+export function serverOptionsOf(config, backends, log) {
+    const branches = config.include.branches;
+    const include = branches?.length || config.include.ignoreModified
+        ? (layer) => (!branches?.length || (layer.branch !== null && branches.includes(layer.branch))) && (!config.include.ignoreModified || layer.freshness === undefined)
+        : undefined;
+    return {
+        backends, write: config.writeId, tokens: config.tokens, anonymousRead: config.anonymousRead,
+        ...(config.outlineBranch ? { outlineBranch: config.outlineBranch } : {}), ...(include ? { include } : {}),
+        refreshMs: config.refreshSeconds * 1000, limits: config.limits, heartbeatMs: config.heartbeatSeconds * 1000,
+        ...(config.log && log ? { log } : {})
+    };
+}
+/** `atlas serve`. Runs until it is told to stop; returns the exit code. */
+export async function serveMain(argv, io) {
+    const cwd = io.cwd ?? process.cwd();
+    const env = io.env ?? process.env;
+    if (argv.includes('--help') || argv.includes('-h')) {
+        io.out(SERVER_USAGE);
+        return 0;
+    }
+    let config;
+    try {
+        config = loadServerConfig(argv, env, cwd);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            io.out(`atlas serve: ${error.message}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    const backends = openConfiguredBackends(config, env, cwd);
+    const writeBackend = backends.find(backend => backend.writable);
+    io.out(`${config.configFile ? `Configuration ${path.relative(cwd, config.configFile) || config.configFile}. ` : ''}Backends: ${backends.map(backend => `${backend.id}${backend.writable ? ' (uploads)' : ''}`).join(', ')}\n`);
+    const problem = await probeWritable(writeBackend);
+    if (problem) {
+        io.out(`atlas serve: uploads would go to "${writeBackend.id}" and it cannot be written to: ${problem}\n`);
+        return 2;
+    }
+    const site = await findSite(config.site, cwd, io.out);
+    if (!site)
+        io.out('No viewer to serve: build one with `atlas-visualizer build --no-data --out atlas-site`. The API is served meanwhile.\n');
+    const server = createAtlasServer({ ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), ...(site ? { site } : {}) });
+    // Listen at once: the first pass over a large backend can take a while, and a liveness probe must find the
+    // process meanwhile. /readyz is 503 until there is a report to show.
+    const running = await listen(server.fetch, { port: config.port, host: config.host, maxBodyBytes: Math.max(config.limits.maxObjectMiB, config.limits.maxJsonMiB) * 1024 * 1024 });
+    io.out(`Listening on ${running.url}; reading the backends (/readyz is 503 until it is done)\n`);
+    await server.ready;
+    const snapshot = server.index.snapshot();
+    for (const notice of snapshot.notices)
+        io.out(`! ${notice}\n`);
+    const stats = server.index.stats();
+    const reachable = snapshot.backends.some(backend => backend.available);
+    const access = config.tokens.length ? `, ${config.tokens.length} token${config.tokens.length === 1 ? '' : 's'}${config.anonymousRead ? ', anyone may look' : ''}` : ', NO tokens: anyone who can reach it may upload';
+    io.out(reachable
+        ? `Atlas ready on ${running.url}: ${stats.layers} layers, ${stats.slots} checks${access}\n`
+        : `Atlas listening on ${running.url} but no backend can be read yet (see above); /readyz stays 503 and it keeps trying${access}\n`);
+    await new Promise(resolve => {
+        const stop = () => resolve();
+        io.signal?.addEventListener('abort', stop, { once: true });
+        if (!io.signal) {
+            process.once('SIGTERM', stop);
+            process.once('SIGINT', stop);
+        }
+    });
+    io.out('Stopping…\n');
+    // End the live streams first: they never finish on their own and would hold the server open.
+    server.close();
+    await running.close();
+    return 0;
+}

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

@@ -0,0 +1,59 @@
+/** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
+export declare const API_VERSION = "1.0.0";
+/** Who may call an operation: `none` (anyone), or the least role that may (`read` < `publish` < `admin`). */
+export type Role = 'none' | 'read' | 'publish' | 'admin';
+type JsonSchema = Record<string, unknown>;
+type Param = {
+    readonly name: string;
+    readonly in: 'path' | 'query' | 'header';
+    readonly description: string;
+    readonly required?: boolean;
+    readonly schema?: JsonSchema;
+    readonly example?: unknown;
+};
+type Body = {
+    readonly description: string;
+    readonly contentType: string;
+    readonly schema: JsonSchema;
+    readonly required?: boolean;
+};
+type Response = {
+    readonly description: string;
+    readonly contentType?: string;
+    readonly schema?: JsonSchema;
+    readonly headers?: Record<string, {
+        description: string;
+        schema: JsonSchema;
+    }>;
+};
+/** One operation of the API, and the route the server registers for it. */
+export type Operation = {
+    /** The route as Hono registers it, `METHOD /path` (`:name` for a parameter, `*` for the rest of the path). */
+    readonly route: string;
+    /** The same route as OpenAPI writes it, `/path/{name}`. */
+    readonly path: string;
+    readonly operationId: string;
+    readonly tag: string;
+    readonly summary: string;
+    /** What it does and how to use it, written for a client that has read nothing else (Markdown). */
+    readonly description: string;
+    readonly role: Role;
+    readonly parameters?: readonly Param[];
+    readonly body?: Body;
+    readonly responses: Readonly<Record<string, Response>>;
+};
+/**
+ * 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.
+ */
+export declare const OPERATIONS: readonly Operation[];
+/**
+ * Routes the server registers that are not operations of this API, each with the reason. The coverage test skips
+ * these and only these.
+ */
+export declare const NOT_OPERATIONS: ReadonlyMap<string, string>;
+/** The OpenAPI 3.1 document of the API. `serverUrl` (such as `https://atlas.example.com`) is written into `servers` when given. */
+export declare function openApiDocument(options?: {
+    readonly serverUrl?: string;
+}): Record<string, unknown>;
+export {};