@aywengo/mercury-fleet 0.0.1-bootstrap

package/dist/cli.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+/**
+ * Fleet CLI: host registry, probe and credential inspection.
+ *
+ * Dispatch, routing, event aggregation, interaction and the metrics rollup are NOT here. They live on the
+ * service (docs/fleet-design.md section 12, phases 1-6), because a Run binding has to survive the process
+ * that created it: a CLI that submitted work would have to stay alive to reconcile it, which is the
+ * durability property Fleet exists to provide.
+ *
+ * Usage:
+ *   fleet hosts add <id> --url <base> --credential <ref> [--label k=v] [--path <abs>] [--disabled]
+ *   fleet hosts list [--json] [--live]
+ *   fleet hosts enable|disable <id>
+ *   fleet hosts rm <id>
+ *   fleet hosts probe [<id>] [--json]
+ *   fleet probe --watch            run the sweep on FLEET_PROBE_INTERVAL_MS until interrupted
+  fleet serve                    run the service; binds 127.0.0.1:3100 by default
+ *   fleet credentials list         credential NAMES only; values are never printed
+ *
+ * No command accepts a child credential as an argument. argv is world-readable through ps, so the secret
+ * lives in the credential file and only its name travels (design section 9).
+ */
+import { loadConfig } from "./config.js";
+import { openFleetDb } from "./db.js";
+import { HostRegistry, RegistryError } from "./registry.js";
+import { loadCredentials, CredentialError } from "./credentials.js";
+import { createProber } from "./prober.js";
+import { probeAndRecord } from "./probe.js";
+import { createFleetServer } from "./server.js";
+import { assertServeable } from "./config.js";
+import { createServiceRedactor } from "./redact.js";
+import { createLogger } from "./logger.js";
+import { parseCallerTokens } from "./auth.js";
+import { FLEET_VERSION } from "./version.js";
+const USAGE = `fleet -- manage multiple Mercury instances
+
+  fleet hosts add <id> --url <base> --credential <ref> [--label k=v] [--path <abs>] [--disabled]
+  fleet hosts list [--json] [--live]
+  fleet hosts enable|disable <id>
+  fleet hosts rm <id>
+  fleet hosts probe [<id>] [--json]
+  fleet probe --watch
+  fleet serve                      run the service (binds FLEET_BIND_HOST:FLEET_PORT)
+  fleet credentials list
+  fleet --version                  print mercury-fleet <version>
+`;
+/** Human label per outcome. Kept distinct because each one sends the operator somewhere different. */
+const STATE_LABEL = {
+    ok: 'up',
+    unreachable: 'down',
+    unauthorized: 'auth-fail',
+    not_mercury: 'not-mercury',
+    not_serving: 'no-worker',
+    http_error: 'http-error',
+    timeout: 'timeout',
+};
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = new Map();
+    const multi = new Map();
+    const repeatable = new Set(['label', 'path']);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--')) {
+            positionals.push(a);
+            continue;
+        }
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        const takesValue = next !== undefined && !next.startsWith('--');
+        if (!takesValue) {
+            flags.set(key, true);
+            continue;
+        }
+        i++;
+        if (repeatable.has(key)) {
+            const list = multi.get(key) ?? [];
+            list.push(next);
+            multi.set(key, list);
+        }
+        else {
+            flags.set(key, next);
+        }
+    }
+    return { positionals, flags, multi };
+}
+function ago(iso) {
+    if (!iso)
+        return 'never';
+    const ms = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ms))
+        return 'never';
+    if (ms < 0)
+        return 'now';
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    if (s < 86400)
+        return `${Math.floor(s / 3600)}h`;
+    return `${Math.floor(s / 86400)}d`;
+}
+function stateOf(view) {
+    if (!view.enabled)
+        return 'disabled';
+    if (!view.probe)
+        return 'never-probed';
+    return STATE_LABEL[view.probe.outcome] ?? view.probe.outcome;
+}
+function renderTable(rows) {
+    const header = ['ID', 'STATE', 'SEEN', 'WORKERS', 'RUNS', 'QUEUE', 'AGENTS', 'URL'];
+    const body = rows.map((r) => {
+        const p = r.probe;
+        return [
+            r.id,
+            stateOf(r),
+            ago(p?.probedAt ?? r.lastSeenAt),
+            p?.workerCount === null || p?.workerCount === undefined ? '-' : String(p.workerCount),
+            p?.activeRuns === null || p?.activeRuns === undefined ? '-' : String(p.activeRuns),
+            p?.queueDepth === null || p?.queueDepth === undefined ? '-' : String(p.queueDepth),
+            p?.agents?.length ? String(p.agents.length) : r.agentsCache.length ? String(r.agentsCache.length) : '-',
+            r.baseUrl,
+        ];
+    });
+    const widths = header.map((h, i) => Math.max(h.length, ...body.map((row) => (row[i] ?? '').length)));
+    const line = (cells) => cells.map((c, i) => (c ?? '').padEnd(widths[i])).join('  ').trimEnd();
+    const out = [line(header)];
+    // Detail lines carry the diagnosis, which is the part a fixed-width table cannot hold.
+    for (let i = 0; i < rows.length; i++) {
+        out.push(line(body[i]));
+        const p = rows[i].probe;
+        if (p?.detail && p.outcome !== 'ok')
+            out.push(`    ${rows[i].id}: ${p.detail}`);
+    }
+    return out.join('\n');
+}
+function parseLabels(pairs) {
+    const labels = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            throw new RegistryError(`--label expects key=value, got ${JSON.stringify(pair)}`);
+        labels[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return labels;
+}
+function openStore(config) {
+    return loadCredentials(config.credentialsFile, config.allowInsecureCredentials);
+}
+export async function main(argv) {
+    if (argv[0] === '--version' || argv[0] === '-V') {
+        process.stdout.write(`mercury-fleet ${FLEET_VERSION}\n`);
+        return 0;
+    }
+    if (argv.length === 0 || argv[0] === 'help' || argv[0] === '--help') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    const config = loadConfig();
+    const { positionals, flags, multi } = parseArgs(argv);
+    const [group, action] = positionals;
+    const asJson = flags.get('json') === true;
+    const withRegistry = async (fn) => {
+        const { db } = openFleetDb(config.dbPath);
+        try {
+            return await fn(new HostRegistry(db), db);
+        }
+        finally {
+            db.close();
+        }
+    };
+    if (group === 'credentials') {
+        if (action !== 'list') {
+            process.stderr.write('usage: fleet credentials list\n');
+            return 2;
+        }
+        // Names only. Printing values here would put every child credential in terminal scrollback and any
+        // captured log, which is the exposure the file's 0600 mode exists to prevent.
+        const store = openStore(config);
+        const names = store.names();
+        process.stdout.write(asJson ? JSON.stringify({ credentialsFile: config.credentialsFile, refs: names }, null, 2) + '\n'
+            : names.length ? names.join('\n') + '\n' : `(no credentials in ${config.credentialsFile})\n`);
+        return 0;
+    }
+    if (group === 'serve') {
+        // Startup order from design section 15.6: configuration, then credentials, then the database, then the
+        // server binds. Binding last means a client never reaches an endpoint whose registry is still loading.
+        assertServeable(config);
+        return await withRegistry(async (_registry, db) => {
+            const store = openStore(config);
+            // Seeded from all three secret classes: child credentials, caller tokens, and the admin token. A
+            // pattern pass cannot recognise a bare token it has no label for, and a caller or admin token in a
+            // log is the credential that reaches a whole fleet.
+            const callers = parseCallerTokens(config.apiTokens);
+            const redactor = createServiceRedactor({
+                childSecrets: store.secrets(),
+                callerTokens: callers.secrets(),
+                adminToken: config.adminToken,
+            });
+            const logger = createLogger(redactor, config.logLevel);
+            const server = createFleetServer({ db, config, credentials: store, logger });
+            const addr = await server.listen();
+            logger.info('fleet api listening', {
+                host: addr.host, port: addr.port, tls: addr.tls,
+                callers: callers.size, unrestricted: callers.unrestrictedOwners(),
+                seededSecrets: redactor.seededCount,
+            });
+            const unrestricted = callers.unrestrictedOwners();
+            if (unrestricted.length) {
+                logger.warn('caller tokens grant access to every host', { owners: unrestricted,
+                    hint: 'scope with token:owner:host1+host2 to limit blast radius' });
+            }
+            await new Promise((resolve) => {
+                const done = () => { void server.close().then(resolve); };
+                process.once('SIGINT', done);
+                process.once('SIGTERM', done);
+            });
+            logger.info('fleet stopped');
+            return 0;
+        });
+    }
+    if (group === 'probe') {
+        return withRegistry(async (registry) => {
+            const store = openStore(config);
+            const prober = createProber({
+                registry,
+                resolveToken: (ref) => store.secret(ref),
+                intervalMs: config.probeIntervalMs,
+                timeoutMs: config.probeTimeoutMs,
+            });
+            if (flags.get('once') === true || flags.get('watch') !== true) {
+                const results = await prober.sweepOnce();
+                process.stdout.write(`probed ${results.length} enabled host(s)\n`);
+                process.stdout.write(renderTable(registry.listWithProbe()) + '\n');
+                return 0;
+            }
+            // --watch: sweep immediately so the operator sees state, then keep sweeping on the timer.
+            await prober.sweepOnce();
+            prober.start();
+            process.stdout.write(`sweeping every ${Math.round(config.probeIntervalMs / 1000)}s; Ctrl-C to stop\n`);
+            await new Promise((resolve) => {
+                const done = () => {
+                    prober.stop();
+                    resolve();
+                };
+                process.once('SIGINT', done);
+                process.once('SIGTERM', done);
+            });
+            return 0;
+        });
+    }
+    if (group !== 'hosts') {
+        process.stderr.write(`unknown command group ${JSON.stringify(group ?? '')}\n\n${USAGE}`);
+        return 2;
+    }
+    return withRegistry((registry) => {
+        if (action === 'add') {
+            const id = positionals[2];
+            const url = flags.get('url');
+            const cred = flags.get('credential');
+            if (!id || typeof url !== 'string' || typeof cred !== 'string') {
+                process.stderr.write('usage: fleet hosts add <id> --url <base> --credential <ref> [--label k=v] [--path <abs>]\n' +
+                    '  --credential names a ref in the credential file; the secret itself is never an argument.\n');
+                return 2;
+            }
+            // Validate the ref resolves NOW. Accepting a typo here would defer the failure to a probe that
+            // reports the host as auth-fail, pointing at the host when the mistake is in this command.
+            const store = openStore(config);
+            store.secret(cred);
+            registry.add({
+                id,
+                baseUrl: url,
+                credentialRef: cred,
+                labels: parseLabels(multi.get('label') ?? []),
+                localPaths: multi.get('path') ?? [],
+                enabled: flags.get('disabled') !== true,
+            });
+            process.stdout.write(`added ${id}\n`);
+            return 0;
+        }
+        if (action === 'list') {
+            return (async () => {
+                if (flags.get('live') === true) {
+                    const store = openStore(config);
+                    const prober = createProber({
+                        registry,
+                        resolveToken: (ref) => store.secret(ref),
+                        intervalMs: config.probeIntervalMs,
+                        timeoutMs: config.probeTimeoutMs,
+                    });
+                    await prober.sweepOnce();
+                }
+                const rows = registry.listWithProbe();
+                if (asJson) {
+                    process.stdout.write(JSON.stringify({ hosts: rows }, null, 2) + '\n');
+                    return 0;
+                }
+                process.stdout.write((rows.length ? renderTable(rows) : '(no hosts; add one with `fleet hosts add`)') + '\n');
+                return 0;
+            })();
+        }
+        if (action === 'enable' || action === 'disable') {
+            const id = positionals[2];
+            if (!id) {
+                process.stderr.write(`usage: fleet hosts ${action} <id>\n`);
+                return 2;
+            }
+            registry.setEnabled(id, action === 'enable');
+            process.stdout.write(`${id} ${action}d\n`);
+            return 0;
+        }
+        if (action === 'rm' || action === 'remove') {
+            const id = positionals[2];
+            if (!id) {
+                process.stderr.write('usage: fleet hosts rm <id>\n');
+                return 2;
+            }
+            const removed = registry.remove(id);
+            process.stdout.write(removed ? `removed ${id}\n` : `no such host: ${id}\n`);
+            return removed ? 0 : 1;
+        }
+        if (action === 'probe') {
+            return (async () => {
+                const store = openStore(config);
+                const only = positionals[2];
+                const prober = createProber({
+                    registry,
+                    resolveToken: (ref) => store.secret(ref),
+                    intervalMs: config.probeIntervalMs,
+                    timeoutMs: config.probeTimeoutMs,
+                });
+                if (!only) {
+                    await prober.sweepOnce();
+                    const rows = registry.listWithProbe();
+                    process.stdout.write(asJson ? JSON.stringify({ hosts: rows }, null, 2) + '\n' : renderTable(rows) + '\n');
+                    return 0;
+                }
+                const host = registry.get(only);
+                if (!host) {
+                    process.stderr.write(`no such host: ${only}\n`);
+                    return 1;
+                }
+                const rec = await probeAndRecord({
+                    hostId: host.id, baseUrl: host.baseUrl, token: store.secret(host.credentialRef),
+                    timeoutMs: config.probeTimeoutMs,
+                });
+                registry.recordProbe(rec);
+                process.stdout.write(asJson ? JSON.stringify(rec, null, 2) + '\n' : renderTable(registry.listWithProbe()) + '\n');
+                // Exit non-zero when the host is not usable, so this composes in a readiness check.
+                return rec.outcome === 'ok' ? 0 : 1;
+            })();
+        }
+        process.stderr.write(`unknown hosts subcommand ${JSON.stringify(action ?? '')}\n\n${USAGE}`);
+        return 2;
+    });
+}
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    const e = err;
+    if (e instanceof RegistryError || e instanceof CredentialError) {
+        process.stderr.write(`fleet: ${e.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    process.stderr.write(`fleet: unexpected error: ${e.stack ?? e.message}\n`);
+    process.exitCode = 1;
+});

package/dist/config.js

@@ -0,0 +1,80 @@
+/**
+ * Fleet configuration. Fleet is a federation layer over independent Mercury instances and must never
+ * import from Mercury's src/ (docs/fleet-design.md section 11), so everything Fleet needs is parsed here
+ * from its own environment. Node builtins and declared dependencies only.
+ */
+function num(raw, fallback) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number(raw);
+    // Reject NaN, negatives and zero explicitly: a zero probe interval would spin the event loop hot.
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return n;
+}
+/**
+ * Parse a TCP port. Unlike an interval or a timeout, 0 is meaningful here -- it asks the OS for an
+ * ephemeral port -- so it must not fall back the way `num` does. Silently turning 0 into 3100 made every
+ * test instance fight over one fixed port.
+ */
+function port(raw, fallback) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0 || n > 65535)
+        return fallback;
+    return n;
+}
+/** Default credential location is outside the working tree so it cannot be committed by accident. */
+function defaultCredentialsFile() {
+    const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.';
+    return home + '/.fleet/credentials.json';
+}
+export function loadConfig(env = process.env) {
+    return {
+        dbPath: env['FLEET_DB'] ?? 'fleet.db',
+        credentialsFile: env['FLEET_CREDENTIALS_FILE'] ?? defaultCredentialsFile(),
+        probeIntervalMs: num(env['FLEET_PROBE_INTERVAL_MS'], 15_000),
+        probeTimeoutMs: num(env['FLEET_PROBE_TIMEOUT_MS'], 5_000),
+        sweepIntervalMs: num(env['FLEET_SWEEP_INTERVAL_MS'], 10_000),
+        streamPollMs: num(env['FLEET_STREAM_POLL_MS'], 1000),
+        repoUrlsFile: env.FLEET_REPO_URLS_FILE ?? null,
+        allowInsecureCredentials: env['FLEET_ALLOW_INSECURE_CREDENTIALS'] === '1',
+        bindHost: env['FLEET_BIND_HOST'] ?? '127.0.0.1',
+        port: port(env['FLEET_PORT'], 3100),
+        apiTokens: env['FLEET_API_TOKENS'],
+        adminToken: env['FLEET_ADMIN_TOKEN'] || null,
+        tlsCert: env['FLEET_TLS_CERT'] || null,
+        tlsKey: env['FLEET_TLS_KEY'] || null,
+        logLevel: level(env['FLEET_LOG_LEVEL']),
+    };
+}
+function level(raw) {
+    const v = (raw ?? 'info').toLowerCase();
+    return v === 'debug' || v === 'warn' || v === 'error' ? v : 'info';
+}
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
+/**
+ * Refuse to start in a configuration that would leak caller credentials.
+ *
+ * Binding beyond loopback without TLS puts every caller's bearer token on the wire in plaintext, and Fleet
+ * tokens are the ones that reach a whole fleet. The safe default is to fail at startup with an explanation
+ * rather than serve insecurely and leave discovery to an audit.
+ */
+export function assertServeable(config) {
+    // Half a TLS configuration is checked first: telling someone to "set FLEET_TLS_CERT and FLEET_TLS_KEY"
+    // when they set exactly one of them is a message that cannot be acted on.
+    if (Boolean(config.tlsCert) !== Boolean(config.tlsKey)) {
+        throw new Error('FLEET_TLS_CERT and FLEET_TLS_KEY must both be set or both unset');
+    }
+    const tls = Boolean(config.tlsCert && config.tlsKey);
+    if (!LOOPBACK.has(config.bindHost) && !tls) {
+        throw new Error(`refusing to bind ${config.bindHost}:${config.port} without TLS. Caller bearer tokens would cross ` +
+            `the network in plaintext, and a Fleet token reaches every Mercury it manages. Set FLEET_TLS_CERT ` +
+            `and FLEET_TLS_KEY, or bind 127.0.0.1 and terminate TLS in a reverse proxy.`);
+    }
+    if (!config.apiTokens && !config.adminToken) {
+        throw new Error('no caller tokens configured: set FLEET_API_TOKENS (token:owner[:hosts]) or FLEET_ADMIN_TOKEN, ' +
+            'otherwise every request would be rejected and the service would look broken.');
+    }
+}

package/dist/credentials.js

@@ -0,0 +1,93 @@
+/**
+ * Child credentials, read from a file and referenced by name (docs/fleet-design.md section 9).
+ *
+ * Two rules drive this whole module. A credential is never a command-line argument, because argv is
+ * world-readable through ps. And the file must not be readable by anyone but its owner, because Fleet
+ * holds a credential for every Mercury it can reach -- one exposed file compromises the whole fleet.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+export class CredentialError extends Error {
+}
+/**
+ * Reject any file whose mode grants access to group or other.
+ *
+ * Only the low nine permission bits are examined: the file mode also carries type bits (a socket or
+ * symlink target would report them), and masking to 0o777 keeps the check about access rather than
+ * file type.
+ */
+function assertPrivateMode(path, mode, allowInsecure) {
+    const access = mode & 0o777;
+    if ((access & 0o077) === 0)
+        return;
+    const octal = access.toString(8).padStart(3, '0');
+    const message = `credential file ${path} is mode ${octal}; group or other can read it. ` +
+        `Fleet holds a credential for every Mercury it manages, so this file must be owner-only. ` +
+        `Fix with: chmod 600 ${path}`;
+    if (!allowInsecure)
+        throw new CredentialError(message);
+}
+/**
+ * Load the credential file.
+ *
+ * Shape is a flat JSON object of name -> secret. Anything else is refused rather than coerced: a nested
+ * object would silently yield "[object Object]" as a bearer token and every probe would fail with 401,
+ * which reads like a credential problem rather than the file-format problem it is.
+ */
+export function loadCredentials(path, allowInsecure = false) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        throw new CredentialError(`credential file ${path} not found. Create it as a JSON object of {"ref": "secret"} ` +
+            `and chmod 600 it, or set FLEET_CREDENTIALS_FILE.`);
+    }
+    assertPrivateMode(path, stat.mode, allowInsecure);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new CredentialError(`cannot read credential file ${path}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new CredentialError(`credential file ${path} is not valid JSON: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CredentialError(`credential file ${path} must contain a JSON object of {"ref": "secret"}; ` +
+            `got ${Array.isArray(parsed) ? 'an array' : typeof parsed}`);
+    }
+    const map = new Map();
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== 'string') {
+            throw new CredentialError(`credential "${key}" in ${basename(path)} is ${value === null ? 'null' : typeof value}, ` +
+                `not a string. A non-string would be sent as a bearer token and rejected with 401.`);
+        }
+        if (value.length === 0) {
+            throw new CredentialError(`credential "${key}" in ${basename(path)} is empty`);
+        }
+        map.set(key, value);
+    }
+    return {
+        secret(ref) {
+            const found = map.get(ref);
+            if (found === undefined) {
+                // Names only in the message. Listing values would put secrets in logs and terminal scrollback.
+                const known = [...map.keys()].sort().join(', ') || '(none)';
+                throw new CredentialError(`unknown credential ref "${ref}"; known refs: ${known}`);
+            }
+            return found;
+        },
+        names() {
+            return [...map.keys()].sort();
+        },
+        secrets() {
+            return [...map.values()];
+        },
+    };
+}