@crvouga/atlas 0.4.0 → 0.6.0

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

@@ -0,0 +1,83 @@
+/**
+ * @module Server configuration
+ *
+ * Loads how the server runs: `atlas.server.json`, then environment variables, then flags, each overriding the last, checked
+ * against `ServerConfigSchema` and resolved (paths made absolute, backends named, tokens read). Every mistake is a
+ * `ConfigError` that says what to change, and a server that would listen beyond this machine with no tokens refuses to
+ * start. `SERVER_SETTINGS` documents every setting once; the table in docs/server.md is generated from it and a test proves
+ * each row.
+ *
+ * @see docs/server.md#configuration
+ */
+import { type ServerConfig, type ServerRole } from '../../schema/src/server-config.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/** A token as the server holds it: the `name` it is shown under in logs, its `role`, and the secret `token`. */
+export type ResolvedToken = {
+    readonly name: string;
+    readonly role: ServerRole;
+    readonly token: string;
+};
+/** A backend as configured: its `id`, the `label` people see, and the `url` (a folder, `s3://…`, or another server) to open. */
+export type BackendSpec = {
+    readonly id: string;
+    readonly label: string;
+    readonly url: string;
+};
+/** The configuration the server runs with: the file, then the environment, then the flags, checked and resolved. */
+export type ResolvedServerConfig = Omit<ServerConfig, 'backends' | 'auth' | 'write'> & {
+    /** The folder that is the default backend, absolute. */
+    readonly data: string;
+    /** Every backend, the data folder first. All are read; uploads go to `writeId`. */
+    readonly backends: readonly BackendSpec[];
+    readonly writeId: string;
+    readonly tokens: readonly ResolvedToken[];
+    readonly anonymousRead: boolean;
+    readonly insecure: boolean;
+    /** Where the config came from, for the first line of the log. */
+    readonly configFile: string | null;
+};
+/** A configuration that cannot be used. The message says what to change; `atlas serve` prints it and exits 2. */
+export declare class ConfigError extends Error {
+}
+/** Every flag `atlas serve` accepts, with its `--`. */
+export declare const SERVER_FLAGS: readonly string[];
+/** One setting of the server as an operator meets it: the config key, the flag, the environment variables, and what it does. */
+export type ServerSetting = {
+    /** What it sets, in words. */
+    readonly summary: string;
+    /** The key in `atlas.server.json` (dotted for nested keys). */
+    readonly key: string;
+    /** The command-line flag, with its value placeholder, or null when there is none. */
+    readonly flag: string | null;
+    /** The environment variables, the first that is set wins; empty when there are none. */
+    readonly env: readonly string[];
+    /** What it is when nothing sets it. */
+    readonly default: string;
+    /**
+     * How the documentation is held to the code: giving `value` through the environment variable (or the flag) must make
+     * `read` of the resolved configuration equal `expected`. A test runs every setting's example both ways.
+     */
+    readonly example: {
+        readonly value: string;
+        readonly read: (config: ResolvedServerConfig) => unknown;
+        readonly expected: unknown;
+    };
+};
+/**
+ * Every setting that can be given by flag or environment, documented once. `docs/server.md` renders its table from
+ * this list, and a test proves each row: its example, through the flag and through the environment, changes the
+ * configuration as the row says. A setting added to the loader without a row here is therefore not documented in the
+ * table; one documented here that the loader ignores fails the test.
+ */
+export declare const SERVER_SETTINGS: readonly ServerSetting[];
+/** The text `atlas serve --help` prints. Also the source of the `atlas serve` section of `docs/reference/cli.md`. */
+export declare const SERVER_USAGE = "atlas serve: the Atlas server\n\n  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]\n              [--store <url|id=url>]... [--write <id>] [--site <dir>]\n              [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]\n              [--anonymous-read] [--insecure] [--no-log]\n\n  One process serves the client and the API. Test results are uploaded to it from anywhere (laptops, CI) and it\n  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more\n  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.\n\n  Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or \"auth.tokens\" in the config) are required\n  to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).\n";
+/**
+ * Read the file named by `--config`/`ATLAS_CONFIG`, or `atlas.server.json` in the folder if there is one, lay the
+ * environment and then the flags over it, and check the result. Every problem is a {@link ConfigError} that says
+ * what to change.
+ */
+export declare function loadServerConfig(argv: readonly string[], env: Env, cwd: string, read?: (file: string) => string): ResolvedServerConfig;
+/** A server that anyone on the network can upload to must say who may. */
+export declare function assertSafeToListen(config: Pick<ResolvedServerConfig, 'host' | 'tokens' | 'insecure'>): void;
+export {};

package/dist/server/src/config.js

@@ -0,0 +1,204 @@
+/**
+ * @module Server configuration
+ *
+ * Loads how the server runs: `atlas.server.json`, then environment variables, then flags, each overriding the last, checked
+ * against `ServerConfigSchema` and resolved (paths made absolute, backends named, tokens read). Every mistake is a
+ * `ConfigError` that says what to change, and a server that would listen beyond this machine with no tokens refuses to
+ * start. `SERVER_SETTINGS` documents every setting once; the table in docs/server.md is generated from it and a test proves
+ * each row.
+ *
+ * @see docs/server.md#configuration
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { ServerConfigSchema } from '../../schema/src/server-config.js';
+/** A configuration that cannot be used. The message says what to change; `atlas serve` prints it and exits 2. */
+export class ConfigError extends Error {
+}
+const DEFAULT_FILE = 'atlas.server.json';
+const MIN_TOKEN = 12;
+const OPTIONS = {
+    config: { type: 'string' }, data: { type: 'string' }, store: { type: 'string', multiple: true }, write: { type: 'string' },
+    host: { type: 'string' }, port: { type: 'string' }, site: { type: 'string' }, 'outline-branch': { type: 'string' },
+    branch: { type: 'string', multiple: true }, 'ignore-modified': { type: 'boolean' }, refresh: { type: 'string' },
+    insecure: { type: 'boolean' }, 'no-log': { type: 'boolean' }, 'anonymous-read': { type: 'boolean' }
+};
+/** Every flag `atlas serve` accepts, with its `--`. */
+export const SERVER_FLAGS = Object.keys(OPTIONS).map(name => `--${name}`);
+/**
+ * Every setting that can be given by flag or environment, documented once. `docs/server.md` renders its table from
+ * this list, and a test proves each row: its example, through the flag and through the environment, changes the
+ * configuration as the row says. A setting added to the loader without a row here is therefore not documented in the
+ * table; one documented here that the loader ignores fails the test.
+ */
+export const SERVER_SETTINGS = [
+    { summary: 'Address to listen on', key: 'host', flag: '--host <address>', env: ['ATLAS_HOST', 'HOST'], default: '`127.0.0.1`', example: { value: '0.0.0.0', read: c => c.host, expected: '0.0.0.0' } },
+    { summary: 'Port (`0` picks a free one)', key: 'port', flag: '--port <n>', env: ['ATLAS_PORT', 'PORT'], default: '`8080`', example: { value: '9191', read: c => c.port, expected: 9191 } },
+    { summary: 'The server\'s own folder: the default backend and write target', key: 'data', flag: '--data <dir>', env: ['ATLAS_DATA'], default: '`./atlas-data`', example: { value: 'results', read: c => path.basename(c.data), expected: 'results' } },
+    { summary: 'More backends, read together with the data folder', key: 'backends', flag: '--store <[id=]url>` (repeatable)', env: ['ATLAS_STORE'], default: 'none', example: { value: 'lab=https://lab.example.com', read: c => c.backends.map(backend => backend.id), expected: ['data', 'lab'] } },
+    { summary: 'The backend uploads go to', key: 'write', flag: '--write <id>', env: ['ATLAS_WRITE'], default: '`data`', example: { value: 'data', read: c => c.writeId, expected: 'data' } },
+    { summary: 'The built client', key: 'site', flag: '--site <dir>', env: ['ATLAS_SITE'], default: '`./atlas-site`, else built once', example: { value: 'client', read: c => path.basename(c.site ?? ''), expected: 'client' } },
+    { summary: 'Whose specs the report is laid over', key: 'outlineBranch', flag: '--outline-branch <branch>', env: ['ATLAS_OUTLINE_BRANCH'], default: '`main`, then `master`, then the newest', example: { value: 'trunk', read: c => c.outlineBranch, expected: 'trunk' } },
+    { summary: 'Only layers recorded on these branches take part', key: 'include.branches', flag: '--branch <name>` (repeatable)', env: ['ATLAS_ONLY_BRANCH'], default: 'all', example: { value: 'main', read: c => c.include.branches, expected: ['main'] } },
+    { summary: 'Leave out layers from modified checkouts and unknown origins', key: 'include.ignoreModified', flag: '--ignore-modified', env: ['ATLAS_IGNORE_MODIFIED'], default: 'no', example: { value: '1', read: c => c.include.ignoreModified, expected: true } },
+    { summary: 'How often (seconds) the backends are looked at for layers written by something else', key: 'refreshSeconds', flag: '--refresh <seconds>', env: ['ATLAS_REFRESH_SECONDS'], default: '`10`', example: { value: '30', read: c => c.refreshSeconds, expected: 30 } },
+    { summary: 'Let anyone look, not upload', key: 'auth.anonymousRead', flag: '--anonymous-read', env: ['ATLAS_ANONYMOUS_READ'], default: 'no', example: { value: '1', read: c => c.anonymousRead, expected: true } },
+    { summary: 'Listen publicly with no tokens (something in front signs people in)', key: 'auth.insecure', flag: '--insecure', env: ['ATLAS_INSECURE'], default: 'no', example: { value: '1', read: c => c.insecure, expected: true } },
+    { summary: 'The admin token (also `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for the other roles, or `auth.tokens` in the file)', key: 'auth.tokens', flag: null, env: ['ATLAS_TOKEN'], default: 'none: the server is open and listens on this machine only', example: { value: 'admin-token-123456', read: c => c.tokens.map(token => token.role), expected: ['admin'] } },
+    { summary: 'The configuration file', key: '(the file itself)', flag: '--config <file>', env: ['ATLAS_CONFIG'], default: '`./atlas.server.json` when it exists', example: { value: 'custom.json', read: c => path.basename(c.configFile ?? ''), expected: 'custom.json' } },
+    { summary: 'Largest uploaded object in MiB', key: 'limits.maxObjectMiB', flag: null, env: ['ATLAS_MAX_OBJECT_MIB'], default: '`256`', example: { value: '64', read: c => c.limits.maxObjectMiB, expected: 64 } },
+    { summary: 'Largest JSON upload in MiB', key: 'limits.maxJsonMiB', flag: null, env: ['ATLAS_MAX_JSON_MIB'], default: '`32`', example: { value: '8', read: c => c.limits.maxJsonMiB, expected: 8 } },
+    { summary: 'Maximum simultaneous live viewers', key: 'limits.maxStreams', flag: null, env: ['ATLAS_MAX_STREAMS'], default: '`500`', example: { value: '100', read: c => c.limits.maxStreams, expected: 100 } },
+    { summary: 'Live connection heartbeat in seconds', key: 'heartbeatSeconds', flag: null, env: ['ATLAS_HEARTBEAT_SECONDS'], default: '`15`', example: { value: '20', read: c => c.heartbeatSeconds, expected: 20 } },
+    { summary: 'Live producer heartbeat timeout in seconds', key: 'runTimeoutSeconds', flag: null, env: ['ATLAS_RUN_TIMEOUT_SECONDS'], default: '`30`', example: { value: '60', read: c => c.runTimeoutSeconds, expected: 60 } },
+    { summary: 'Live run progress stall timeout in seconds (0 disables)', key: 'runStallSeconds', flag: null, env: ['ATLAS_RUN_STALL_SECONDS'], default: '`900`', example: { value: '0', read: c => c.runStallSeconds, expected: 0 } },
+    { summary: 'No request log', key: 'log', flag: '--no-log', env: ['ATLAS_LOG'], default: 'one JSON line per request', example: { value: 'false', read: c => c.log, expected: false } }
+];
+/** The text `atlas serve --help` prints. Also the source of the `atlas serve` section of `docs/reference/cli.md`. */
+export const SERVER_USAGE = `atlas serve: the Atlas server
+
+  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]
+              [--store <url|id=url>]... [--write <id>] [--site <dir>]
+              [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]
+              [--anonymous-read] [--insecure] [--no-log]
+
+  One process serves the client and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
+  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more
+  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.
+
+  Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or "auth.tokens" in the config) are required
+  to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).
+`;
+function parseFlags(argv) {
+    try {
+        return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: false, strict: true }).values;
+    }
+    catch (error) {
+        throw new ConfigError(error instanceof Error ? error.message : String(error));
+    }
+}
+const list = (text) => (text ?? '').split(/[\n,]+/).map(item => item.trim()).filter(Boolean);
+const truthy = (value) => value === '1' || value === 'true';
+/** `id=url`, or a bare url with an id made from it. */
+function backendOf(spec, taken) {
+    const named = /^([a-z0-9-]+)=(.+)$/.exec(spec);
+    if (named)
+        return { id: named[1], url: named[2] };
+    const base = spec.replace(/^[a-z0-9+.-]+:\/\//i, '').replace(/[?#].*$/, '').replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 40) || 'store';
+    let id = base;
+    for (let n = 2; taken.has(id); n++)
+        id = `${base}-${n}`;
+    return { id, url: spec };
+}
+/**
+ * Read the file named by `--config`/`ATLAS_CONFIG`, or `atlas.server.json` in the folder if there is one, lay the
+ * environment and then the flags over it, and check the result. Every problem is a {@link ConfigError} that says
+ * what to change.
+ */
+export function loadServerConfig(argv, env, cwd, read = file => readFileSync(file, 'utf8')) {
+    const flags = parseFlags(argv);
+    const named = flags.config ?? env.ATLAS_CONFIG;
+    const file = named ? path.resolve(cwd, named) : existsSync(path.join(cwd, DEFAULT_FILE)) ? path.join(cwd, DEFAULT_FILE) : null;
+    let raw = {};
+    if (file) {
+        try {
+            raw = JSON.parse(read(file));
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const base = file ? path.dirname(file) : cwd;
+    const auth = { ...raw.auth };
+    const include = { ...raw.include };
+    const merged = { ...raw, auth, include };
+    const set = (key, value) => { if (value !== undefined)
+        merged[key] = value; };
+    // ATLAS_HOST and ATLAS_PORT first: HOST is often the machine's own name, and PORT belongs to whatever else is running here.
+    set('host', flags.host ?? env.ATLAS_HOST ?? env.HOST);
+    const port = env.ATLAS_PORT ?? env.PORT;
+    set('port', flags.port !== undefined ? Number(flags.port) : port !== undefined ? Number(port) : undefined);
+    set('data', flags.data ?? env.ATLAS_DATA);
+    set('write', flags.write ?? env.ATLAS_WRITE);
+    set('site', flags.site ?? env.ATLAS_SITE);
+    set('outlineBranch', flags['outline-branch'] ?? env.ATLAS_OUTLINE_BRANCH);
+    set('refreshSeconds', flags.refresh !== undefined ? Number(flags.refresh) : env.ATLAS_REFRESH_SECONDS !== undefined ? Number(env.ATLAS_REFRESH_SECONDS) : undefined);
+    if (env.ATLAS_LOG !== undefined)
+        merged.log = truthy(env.ATLAS_LOG);
+    if (flags['no-log'])
+        merged.log = false;
+    set('runTimeoutSeconds', env.ATLAS_RUN_TIMEOUT_SECONDS === undefined ? undefined : Number(env.ATLAS_RUN_TIMEOUT_SECONDS));
+    set('runStallSeconds', env.ATLAS_RUN_STALL_SECONDS === undefined ? undefined : Number(env.ATLAS_RUN_STALL_SECONDS));
+    set('heartbeatSeconds', env.ATLAS_HEARTBEAT_SECONDS === undefined ? undefined : Number(env.ATLAS_HEARTBEAT_SECONDS));
+    const limits = { ...raw.limits };
+    for (const [key, variable] of [['maxObjectMiB', 'ATLAS_MAX_OBJECT_MIB'], ['maxJsonMiB', 'ATLAS_MAX_JSON_MIB'], ['maxStreams', 'ATLAS_MAX_STREAMS']]) {
+        if (env[variable] !== undefined)
+            limits[key] = Number(env[variable]);
+    }
+    merged.limits = limits;
+    if (flags.insecure || truthy(env.ATLAS_INSECURE))
+        auth.insecure = true;
+    if (flags['anonymous-read'] || truthy(env.ATLAS_ANONYMOUS_READ))
+        auth.anonymousRead = true;
+    const branches = [...(flags.branch ?? []), ...list(env.ATLAS_ONLY_BRANCH)];
+    if (branches.length)
+        include.branches = branches;
+    if (flags['ignore-modified'] || truthy(env.ATLAS_IGNORE_MODIFIED))
+        include.ignoreModified = true;
+    const parsed = ServerConfigSchema.safeParse(merged);
+    if (!parsed.success)
+        throw new ConfigError(`${file ? `${file}: ` : 'Configuration: '}${parsed.error.issues.map(issue => `${issue.path.join('.') || '(config)'}: ${issue.message}`).join('; ')}`);
+    const config = parsed.data;
+    // Backends: the data folder, then those in the file, then --store and ATLAS_STORE.
+    const taken = new Set(['data']);
+    const backends = [{ id: 'data', label: 'Server data', url: path.resolve(base, config.data) }];
+    const extra = config.backends.map(item => ({ id: item.id, label: item.label ?? item.id, url: item.url, write: item.write === true }));
+    for (const item of extra) {
+        if (taken.has(item.id))
+            throw new ConfigError(`Two backends are called "${item.id}" ("data" is the data folder)`);
+        taken.add(item.id);
+        backends.push({ id: item.id, label: item.label, url: item.url });
+    }
+    for (const spec of [...(flags.store ?? []), ...(flags.store ? [] : list(env.ATLAS_STORE))]) {
+        const item = backendOf(spec, taken);
+        if (taken.has(item.id))
+            throw new ConfigError(`Two backends are called "${item.id}"`);
+        taken.add(item.id);
+        backends.push({ id: item.id, label: item.id, url: item.url });
+    }
+    const marked = extra.filter(item => item.write).map(item => item.id);
+    if (marked.length > 1)
+        throw new ConfigError(`Only one backend can take uploads; ${marked.join(', ')} are all marked write`);
+    const writeId = config.write ?? marked[0] ?? 'data';
+    if (!backends.some(item => item.id === writeId))
+        throw new ConfigError(`write names "${writeId}", which is not a backend (${backends.map(item => item.id).join(', ')})`);
+    // Tokens: the file's, then the environment's.
+    const tokens = [];
+    for (const item of config.auth.tokens) {
+        const token = item.token ?? env[item.tokenEnv];
+        if (!token)
+            throw new ConfigError(`Token "${item.name}" reads ${item.tokenEnv} and it is not set`);
+        tokens.push({ name: item.name, role: item.role, token });
+    }
+    for (const [variable, role, name] of [['ATLAS_TOKEN', 'admin', 'admin'], ['ATLAS_PUBLISH_TOKEN', 'publish', 'publish'], ['ATLAS_READ_TOKEN', 'read', 'read']]) {
+        if (env[variable])
+            tokens.push({ name, role, token: env[variable].trim() });
+    }
+    for (const item of tokens)
+        if (item.token.length < MIN_TOKEN)
+            throw new ConfigError(`Token "${item.name}" is shorter than ${MIN_TOKEN} characters: use a long random one (openssl rand -hex 24)`);
+    if (new Set(tokens.map(item => item.token)).size !== tokens.length)
+        throw new ConfigError('Two tokens are the same: each token must say who it is');
+    const { backends: _backends, auth: _auth, write: _write, ...rest } = config;
+    const resolved = { ...rest, data: backends[0].url, backends, writeId, tokens, anonymousRead: config.auth.anonymousRead, insecure: config.auth.insecure, configFile: file, ...(config.site ? { site: path.resolve(base, config.site) } : {}) };
+    assertSafeToListen(resolved);
+    return resolved;
+}
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+/** A server that anyone on the network can upload to must say who may. */
+export function assertSafeToListen(config) {
+    if (config.tokens.length || config.insecure || LOOPBACK.has(config.host))
+        return;
+    throw new ConfigError(`Listening on ${config.host} with no tokens would let anyone on the network upload results. Set ATLAS_TOKEN (and ATLAS_PUBLISH_TOKEN / ATLAS_READ_TOKEN), or listen on 127.0.0.1, or pass --insecure if something else in front of it does the signing in.`);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @module `atlas dev`
+ *
+ * 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 client all use one host, exactly as in production, and a change to the client shows at once.
+ */
+import { type ServeIo } from './main.js';
+/** The text `atlas dev --help` prints. Also the source of the `atlas dev` section of `docs/reference/cli.md`. */
+export declare const DEV_USAGE = "atlas dev: the Atlas server and the client, for working on either\n\n  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]\n\n  Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the\n  browser talks to one host and a change to the client shows at once. In production `atlas serve` does both from\n  one process.\n";
+/** `atlas dev`. */
+export declare function devMain(argv: readonly string[], io: ServeIo): Promise<number>;

package/dist/server/src/dev.js

@@ -0,0 +1,89 @@
+/**
+ * @module `atlas dev`
+ *
+ * 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 client all use one host, exactly as in production, and a change to the client shows at once.
+ */
+import path from 'node:path';
+import { openConfiguredBackends, serverOptionsOf } from './main.js';
+import { createAtlasServer } from './app.js';
+import { ConfigError, loadServerConfig, SERVER_USAGE } from './config.js';
+import { listen } from './host.js';
+import { fileServerSettings } from './settings.js';
+import { visualizerRoot } from './site.js';
+/** The text `atlas dev --help` prints. Also the source of the `atlas dev` section of `docs/reference/cli.md`. */
+export const DEV_USAGE = `atlas dev: the Atlas server and the client, for working on either
+
+  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
+
+  Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the
+  browser talks to one host and a change to the client shows at once. In production \`atlas serve\` does both from
+  one process.
+`;
+/** `atlas dev`. */
+export async function devMain(argv, io) {
+    const cwd = io.cwd ?? process.cwd();
+    const env = io.env ?? process.env;
+    if (argv.includes('--help') || argv.includes('-h')) {
+        io.out(DEV_USAGE);
+        return 0;
+    }
+    const root = visualizerRoot();
+    if (!root) {
+        io.out('atlas dev: the client is not installed alongside the server.\n');
+        return 2;
+    }
+    // --port is the one the browser uses (the client's); the API takes another that nobody needs to know.
+    const flagged = argv.findIndex(item => item === '--port');
+    const publicPort = flagged >= 0 ? Number(argv[flagged + 1]) : Number(env.ATLAS_PORT ?? env.PORT ?? 5180);
+    const forServer = argv.filter((_, i) => i !== flagged && i !== flagged + 1 || flagged < 0);
+    let config;
+    try {
+        // The API itself listens on a port of its own on this machine; what the user said about --host is for the client, the one door.
+        config = loadServerConfig([...forServer, '--port', '0'], { ...env, PORT: undefined, ATLAS_PORT: undefined }, cwd);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            io.out(`atlas dev: ${error.message}\n${SERVER_USAGE.split('\n')[0]}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    const backends = openConfiguredBackends(config, env, cwd);
+    const api = createAtlasServer({ ...serverOptionsOf(config, backends, line => io.out(`${JSON.stringify(line)}\n`)), settings: fileServerSettings(config, forServer, env, cwd) });
+    const running = await listen(api.fetch, { port: 0, host: '127.0.0.1', maxBodyBytes: Math.max(config.limits.maxObjectMiB, config.limits.maxJsonMiB) * 1024 * 1024 });
+    await api.ready;
+    // The client's config reads this to proxy /api, and to write the same page config a server would.
+    process.env.ATLAS_API_URL = running.url.replace('localhost', '127.0.0.1');
+    process.env.INIT_CWD = cwd;
+    const { createServer } = await import('vite');
+    const vite = await createServer({
+        configFile: path.join(root, 'vite.config.ts'),
+        configLoader: 'runner',
+        root,
+        server: { port: publicPort, host: config.host, strictPort: true }
+    });
+    try {
+        await vite.listen();
+    }
+    catch (error) {
+        api.close();
+        await vite.close();
+        await running.close(2_000);
+        throw error;
+    }
+    vite.printUrls();
+    io.out(`Data in ${path.relative(cwd, config.data) || config.data}. Publish with: ATLAS_STORE=${vite.resolvedUrls?.local[0] ?? `http://localhost:${publicPort}`} atlas report publish …\n`);
+    await new Promise(resolve => {
+        io.signal?.addEventListener('abort', () => resolve(), { once: true });
+        if (!io.signal) {
+            process.once('SIGTERM', () => resolve());
+            process.once('SIGINT', () => resolve());
+        }
+    });
+    api.close();
+    await vite.close();
+    await running.close(2_000);
+    return 0;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @module Server-sent events
+ *
+ * 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: 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.
+ *
+ * @see docs/server.md#streaming
+ */
+/** 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. */
+export type EventName = 'hello' | 'report' | 'atlas:change' | 'run' | 'projects';
+/** The viewers connected to `/api/events` and how to reach them all. One hub per server. */
+export declare class EventHub {
+    #private;
+    constructor(options?: {
+        readonly maxSubscribers?: number;
+        readonly heartbeatMs?: number;
+    });
+    /** How many viewers are connected right now. */
+    get count(): number;
+    /** Tell every viewer. `data` is JSON. */
+    publish(name: EventName, data: unknown): void;
+    /** A stream for one viewer, starting with `hello` (what `greeting` returns). It ends when the viewer goes. */
+    stream(request: Request, greeting: () => unknown): Response;
+    /** End every stream, for shutting down. */
+    close(): void;
+}

package/dist/server/src/events.js

@@ -0,0 +1,101 @@
+/**
+ * @module Server-sent events
+ *
+ * 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: 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.
+ *
+ * @see docs/server.md#streaming
+ */
+/** Events a viewer may be behind by before it is let go. */
+const MAX_BACKLOG = 256;
+/** The viewers connected to `/api/events` and how to reach them all. One hub per server. */
+export class EventHub {
+    #subscribers = new Set();
+    #max;
+    #heartbeatMs;
+    #encoder = new TextEncoder();
+    #id = 0;
+    #timer = null;
+    constructor(options = {}) {
+        this.#max = options.maxSubscribers ?? 500;
+        this.#heartbeatMs = options.heartbeatMs ?? 15_000;
+    }
+    /** How many viewers are connected right now. */
+    get count() {
+        return this.#subscribers.size;
+    }
+    /** Tell every viewer. `data` is JSON. */
+    publish(name, data) {
+        this.#id += 1;
+        // Written once, however many are listening.
+        const frame = this.#encoder.encode(`id: ${this.#id}\nevent: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+        for (const subscriber of [...this.#subscribers])
+            subscriber.send(frame);
+    }
+    /** A stream for one viewer, starting with `hello` (what `greeting` returns). It ends when the viewer goes. */
+    stream(request, greeting) {
+        if (this.#subscribers.size >= this.#max)
+            return Response.json({ error: 'Too many viewers are connected for live updates; they will poll instead.' }, { status: 503, headers: { 'retry-after': '30' } });
+        let subscriber = null;
+        const body = new ReadableStream({
+            start: (controller) => {
+                const send = (chunk) => {
+                    try {
+                        // A viewer that has stopped reading (a laptop asleep, a dead connection) must not make the server hold its backlog: it reconnects and reads everything again.
+                        if ((controller.desiredSize ?? 1) < -MAX_BACKLOG) {
+                            drop();
+                            controller.close();
+                            return;
+                        }
+                        controller.enqueue(chunk);
+                    }
+                    catch {
+                        drop();
+                    }
+                };
+                const drop = () => { if (subscriber)
+                    this.#subscribers.delete(subscriber); subscriber = null; if (!this.#subscribers.size)
+                    this.#stopTimer(); };
+                subscriber = { send, close: () => { drop(); try {
+                        controller.close();
+                    }
+                    catch { /* already closed */ } } };
+                this.#subscribers.add(subscriber);
+                this.#startTimer();
+                // `retry` is how long the browser waits before reconnecting by itself.
+                send(this.#encoder.encode(`retry: 3000\n\n`));
+                this.#id += 1;
+                send(this.#encoder.encode(`id: ${this.#id}\nevent: hello\ndata: ${JSON.stringify(greeting())}\n\n`));
+                request.signal.addEventListener('abort', drop, { once: true });
+            },
+            cancel: () => { if (subscriber)
+                this.#subscribers.delete(subscriber); subscriber = null; if (!this.#subscribers.size)
+                this.#stopTimer(); }
+        });
+        return new Response(body, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache, no-transform', connection: 'keep-alive', 'x-accel-buffering': 'no' } });
+    }
+    #startTimer() {
+        if (this.#timer)
+            return;
+        // A named event, not a comment: proxies see traffic, and the viewer (which a browser does not tell about comments) can tell a quiet
+        // server from a dead connection.
+        const ping = this.#encoder.encode('event: ping\ndata: {}\n\n');
+        this.#timer = setInterval(() => { for (const subscriber of [...this.#subscribers])
+            subscriber.send(ping); }, this.#heartbeatMs);
+        this.#timer.unref?.();
+    }
+    #stopTimer() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = null;
+    }
+    /** End every stream, for shutting down. */
+    close() {
+        for (const subscriber of [...this.#subscribers])
+            subscriber.close();
+        this.#stopTimer();
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * @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.
+ */
+/** A server that is listening: the `port` it got (useful when asked for `0`), its `url`, and `close`. */
+export type RunningServer = {
+    readonly port: number;
+    readonly url: string;
+    /** Stop accepting, let requests in flight finish for up to `graceMs`, then end what is left. */
+    close(graceMs?: number): Promise<void>;
+};
+/** Where to listen (`port`, `host`) and the largest request body the runtime will accept. */
+export type ListenOptions = {
+    readonly port: number;
+    readonly host: string;
+    /** The largest request body to read, in bytes. */
+    readonly maxBodyBytes: number;
+};
+type Handler = (request: Request) => Promise<Response> | Response;
+/**
+ * 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 declare function listen(handler: Handler, options: ListenOptions): Promise<RunningServer>;
+export {};