@datumos/datum-cli 0.0.0 → 0.589.0

package/cli/datum.js

@@ -0,0 +1,814 @@
+#!/usr/bin/env node
+/**
+ * `datum` — the official CLI of the Datum API (docs/cli.md).
+ *
+ * Every API command here is DERIVED: the tree, the flags and every help
+ * page come from the OpenAPI contract (server/src/openapi/spec.ts), which
+ * CLAUDE.md requires to change in the same commit as any API change — so
+ * the CLI and its --help update themselves with the API. The ONLY
+ * hand-written commands are the ones that are not API operations: the
+ * CLI's own (`help`, `spec`, `commands`), the person sign-in
+ * (`login`, `logout`, `whoami`, `mcp serve` — docs/developer-access.md),
+ * which talk to the identity provider and to Claude Code, not to the API,
+ * and `artifacts publish <dir>` (#589), which is an API command spanning a
+ * directory walk and several calls, so no single derived one could be it,
+ * and `outputs download <id>` (#2680) — metadata from /api, the bytes from
+ * the origin's /outputs route.
+ *
+ * Auth model: an API key (DATUM_API_KEY / --api-key; panel: Settings →
+ * API keys) rides the public surface (/public/api) — the key pins the
+ * actor server-side; /api/secrets, /api/config and /api/api-keys stay
+ * blocked (docs/public-api.md). Without a key, the sign-in from
+ * `datum login` (a person's Entra access token) rides /api with the
+ * person's own role (the panel's — #1817). --env pins the target deployment
+ * variant on the Ring Accelerator via x-oa-variant.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { openApiSpec } from "../openapi/spec.js";
+import { CREDENTIAL_PROCESS_ENV, CredentialProcessError, readCredentialProcess } from "./credentialProcess.js";
+/** The 409 code of a write that waits for the person's approval — the
+ * server's `APPROVAL_REQUIRED_CODE` (personAgent.interfaces.ts; the package
+ * ships only cli/ and openapi/, a test pins the two equal). */
+export const APPROVAL_REQUIRED_CODE = "approval_required";
+/** Exit code of a write that waits for the person's approval (409
+ * `approval_required`, #2719) — the same number datum-tool gives a
+ * pending approval. */
+export const EXIT_APPROVAL_REQUIRED = 4;
+import { buildCommandTree, matchCommand, } from "./commandTree.js";
+import { BUILTIN_COMMANDS, createStyle, renderBuiltinHelp, renderCommandHelp, renderCommandList, renderGroupHelp, renderRootHelp, } from "./help.js";
+import { buildRequest, executeRequest, MAX_PRINTED_RESPONSE_BYTES, spillNotice, spillResponse, toCurl, UsageError, } from "./invoke.js";
+import { runArtifactsPublish } from "./artifactsPublish.js";
+import { runOutputsDownload } from "./outputsDownload.js";
+import { interruptedBySignal, runPreviewDown, runPreviewTrace, runPreviewUp, runPreviewsList } from "./previewCommand.js";
+import { daemonReadsPairTokenEnv, maskedTitle, pairTokenOutOfArgs, SATELLITE_PAIR_TOKEN_ENV, SATELLITE_PAIR_TOKEN_ENV_SINCE } from "./satellitePairToken.js";
+import { runA2a } from "./a2aCommand.js";
+import { runLogin, runLogout, runWhoami } from "./authCommands.js";
+import { CredentialStore } from "./credentials.js";
+import { LoginFlowError, NotLoggedInError, ensureAccessToken, spaceBaseUrl } from "./entraLogin.js";
+import { runMcpServe } from "./mcpServe.js";
+import { runSpaceManifestInit, runSpaceManifestPull, runSpaceManifestPush, runSpaceManifestSchema, runSpaceManifestValidate, } from "./spaceManifestCommand.js";
+import { ENV_DELEGATED, ENV_LAUNCHER_VERSION, preflight, runProcess, updatePaths, } from "./selfUpdate.js";
+import { runUpdate } from "./updateCommand.js";
+const spec = openApiSpec;
+/** Global flags and their arity; everything else belongs to the command. */
+const GLOBAL_VALUE_FLAGS = new Set([
+    "base-url",
+    "api-key",
+    "env",
+    "data",
+    "fields",
+    "space",
+]);
+const GLOBAL_BOOL_FLAGS = new Set(["curl", "raw", "full", "help", "version"]);
+/** First pass: pull global flags out of argv, keep the rest in order. */
+function extractGlobals(argv) {
+    const values = new Map();
+    const bools = new Set();
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "-h") {
+            bools.add("help");
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const eq = token.indexOf("=");
+            const name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+            if (GLOBAL_BOOL_FLAGS.has(name)) {
+                bools.add(name);
+                continue;
+            }
+            if (GLOBAL_VALUE_FLAGS.has(name)) {
+                const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+                if (value === undefined) {
+                    throw new UsageError(`--${name} needs a value`);
+                }
+                values.set(name, value);
+                continue;
+            }
+        }
+        rest.push(token);
+    }
+    return { globals: { values, bools }, rest };
+}
+/**
+ * Second pass, with the command known: command flags consume a value
+ * unless their schema says boolean; bare tokens are positionals.
+ */
+function parseCommandArgs(tokens, boolFlags) {
+    const flags = new Map();
+    const positionals = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (!token.startsWith("--")) {
+            positionals.push(token);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+        let value;
+        if (eq !== -1) {
+            value = token.slice(eq + 1);
+        }
+        else if (boolFlags.has(name)) {
+            value = "";
+        }
+        else {
+            const next = tokens[++i];
+            if (next === undefined) {
+                throw new UsageError(`--${name} needs a value`);
+            }
+            value = next;
+        }
+        const list = flags.get(name) ?? [];
+        list.push(value);
+        flags.set(name, list);
+    }
+    return { positionals, flags };
+}
+/** PROD/STAGE/TEST are canonical uppercase; personal variants pass verbatim. */
+function normalizeVariant(value) {
+    if (!value)
+        return undefined;
+    return /^(prod|stage|test)$/i.test(value) ? value.toUpperCase() : value;
+}
+/**
+ * `datum satellite …` (#504): hands the arguments to the installed
+ * `@datum/datum-satellite` binary (`satellite`) with inherited stdio, so the
+ * one command Account → Computers prints works as printed. The daemon is
+ * deliberately NOT bundled here — it runs on machines the panel never
+ * touches and carries its own version and contract (satellite/CHANGELOG.md).
+ */
+/** The hand-written verbs of `space-manifest` (#1809, #1824) — `list`/`set` stay derived. */
+const SPACE_MANIFEST_DIR_VERBS = new Set(["pull", "push", "init", "validate", "schema"]);
+/** `datum preview <verb>` (#2928) — `datum previews` lists. */
+const PREVIEW_VERBS = new Set(["up", "down", "trace"]);
+const SPACE_MANIFEST_DIR_FLAGS = {
+    pull: { bools: [], values: [] },
+    push: { bools: ["dry-run", "prune", "expect-empty"], values: ["markdown"] },
+    init: { bools: ["refresh"], values: [] },
+    validate: { bools: [], values: [] },
+    schema: { bools: [], values: [] },
+};
+/**
+ * `datum space-manifest pull|push|init|validate <dir>` and `schema [kind]`:
+ * one positional (the directory; the kind, optional, for schema) and the
+ * verb's own flags; `--space` / `DATUM_SPACE` (a global) picks the space
+ * host for the calls and names the space for init, `--raw` prints the
+ * server's answer of `push` as JSON instead of the Markdown plan.
+ */
+async function runSpaceManifestDir(verb, tokens, space, raw, resolveConfig) {
+    const io = { out: process.stdout, err: process.stderr };
+    const known = SPACE_MANIFEST_DIR_FLAGS[verb];
+    let args;
+    try {
+        args = parseCommandArgs(tokens, new Set(known.bools));
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            console.error(`datum: ${err.message}`);
+            return 2;
+        }
+        throw err;
+    }
+    const allowed = [...known.bools, ...known.values];
+    const unknown = [...args.flags.keys()].find((f) => !allowed.includes(f));
+    if (unknown !== undefined) {
+        console.error(`datum: unknown flag --${unknown}${allowed.length ? `. Known flags: ${allowed.map((f) => `--${f}`).join(", ")}.` : " — this command takes none."}`);
+        return 2;
+    }
+    if (verb === "schema") {
+        if (args.positionals.length > 1) {
+            console.error("datum: expected at most 1 argument ([kind]) — see: datum space-manifest schema --help");
+            return 2;
+        }
+        const config = await resolveConfig();
+        if (!config)
+            return 2;
+        const kind = args.positionals[0];
+        return runSpaceManifestSchema(kind !== undefined ? { kind } : {}, config, io);
+    }
+    if (args.positionals.length !== 1) {
+        console.error(`datum: expected 1 argument (<dir>) — see: datum space-manifest ${verb} --help`);
+        return 2;
+    }
+    const dir = args.positionals[0];
+    if (verb === "init")
+        return runSpaceManifestInit({ dir, space, refresh: args.flags.has("refresh") }, io);
+    const config = await resolveConfig();
+    if (!config)
+        return 2;
+    if (verb === "pull")
+        return runSpaceManifestPull({ dir }, config, io);
+    if (verb === "validate")
+        return runSpaceManifestValidate({ dir }, config, io);
+    const markdown = args.flags.get("markdown")?.at(-1);
+    return runSpaceManifestPush({
+        dir,
+        dryRun: args.flags.has("dry-run"),
+        prune: args.flags.has("prune"),
+        expectEmpty: args.flags.has("expect-empty"),
+        ...(markdown !== undefined ? { markdown } : {}),
+        json: raw,
+    }, config, io);
+}
+async function runSatellitePassthrough(given) {
+    const { spawn, spawnSync } = await import("node:child_process");
+    // The one-time pairing token travels in the daemon's environment, never on a command line (#2948) —
+    // when the installed daemon reads it (0.21.2+); an older one still gets the flag, and is told to upgrade.
+    const out = pairTokenOutOfArgs(given);
+    let args = given;
+    let env = process.env;
+    if (out.token) {
+        process.title = maskedTitle(process.argv, out.token);
+        const probe = spawnSync("satellite", ["--version"], { encoding: "utf8", timeout: 10_000 });
+        if (daemonReadsPairTokenEnv(probe.stdout ?? "")) {
+            args = out.args;
+            env = { ...process.env, [SATELLITE_PAIR_TOKEN_ENV]: out.token };
+        }
+        else if (!probe.error) {
+            console.error(`datum: this satellite daemon is older than ${SATELLITE_PAIR_TOKEN_ENV_SINCE} — the pairing token goes on its command line (visible in ps until it pairs). Upgrade: npm i -g @datum/datum-satellite`);
+        }
+    }
+    return new Promise((resolve) => {
+        const child = spawn("satellite", args, { stdio: "inherit", env });
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                console.error("datum: the satellite daemon is not installed on this machine — install it first:\n" +
+                    "  npm i -g @datum/datum-satellite   (from your organisation's npm registry)\n" +
+                    "then re-run the command.");
+                resolve(2);
+                return;
+            }
+            console.error(`datum: cannot start the satellite daemon: ${err.message}`);
+            resolve(1);
+        });
+        child.on("close", (code, signal) => resolve(code ?? (signal ? 130 : 1)));
+    });
+}
+function appVersion() {
+    const componentDir = path.dirname(fileURLToPath(import.meta.url));
+    // ../package.json: the published npm package; ../../../package.json: the
+    // repo root when running from server/src or server/dist.
+    for (const rel of ["../package.json", "../../../package.json"]) {
+        try {
+            const pkg = JSON.parse(readFileSync(path.resolve(componentDir, rel), "utf8"));
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return "unknown";
+}
+function updateDeps() {
+    return { fetch, run: runProcess, nodePath: process.execPath, now: Date.now };
+}
+/**
+ * The server the launcher's update check asks: the same resolution as the
+ * commands (flag, env, the sign-in's default) — but NO localhost fallback,
+ * a machine that configured no server has nothing to ask.
+ */
+function configuredBaseUrl(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === "--base-url")
+            return argv[i + 1] ?? null;
+        if (t.startsWith("--base-url="))
+            return t.slice("--base-url=".length);
+    }
+    return (process.env.DATUM_BASE_URL ??
+        process.env.MCA_BASE_URL ??
+        new CredentialStore().defaultBaseUrl() ??
+        null);
+}
+/**
+ * The binary's entry: the self-update preflight (selfUpdate.ts) may hand the
+ * process over to a newer installed version — same argv, inherited stdio,
+ * its exit code — before main() runs here at all.
+ */
+export async function runBin(argv) {
+    const entryFile = fileURLToPath(import.meta.url);
+    const pre = await preflight({
+        argv,
+        env: process.env,
+        entryDir: path.dirname(entryFile),
+        entryFile,
+        ownVersion: appVersion(),
+        baseUrl: configuredBaseUrl(argv),
+        paths: updatePaths(),
+        deps: updateDeps(),
+        err: process.stderr,
+    });
+    if (pre.delegate) {
+        const { spawnSync } = await import("node:child_process");
+        const run = spawnSync(process.execPath, [pre.delegate, ...argv], {
+            stdio: "inherit",
+            env: { ...process.env, [ENV_DELEGATED]: "1", [ENV_LAUNCHER_VERSION]: appVersion() },
+        });
+        if (run.error) {
+            console.error(`datum: cannot start ${pre.delegate} (${run.error.message}) — running the installed package instead`);
+            return main(argv);
+        }
+        return run.status ?? (run.signal ? 130 : 1);
+    }
+    return main(argv);
+}
+export async function main(argv) {
+    const style = createStyle(process.stdout.isTTY === true);
+    const commands = buildCommandTree(spec);
+    let globals;
+    let rest;
+    try {
+        ({ globals, rest } = extractGlobals(argv));
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            console.error(`datum: ${err.message}`);
+            return 2;
+        }
+        throw err;
+    }
+    if (globals.bools.has("version")) {
+        console.log(`datum ${appVersion()} (API contract ${spec.info.version})`);
+        return 0;
+    }
+    // Built-ins that are about the CLI itself, not an API operation.
+    if (rest[0] === "help") {
+        rest = rest.slice(1);
+        globals.bools.add("help");
+    }
+    if (rest[0] === "spec") {
+        // The largest fixed dump this CLI owns (over a megabyte), so it obeys
+        // the same rule as an oversized response: parked in a file unless the
+        // caller asked for it on stdout (#646).
+        const rendered = JSON.stringify(spec, null, 2);
+        const bytes = Buffer.byteLength(rendered);
+        if (!globals.bools.has("full") && bytes > MAX_PRINTED_RESPONSE_BYTES) {
+            const file = await spillResponse(rendered);
+            process.stdout.write(spillNotice(bytes, file, spec, {
+                what: "the OpenAPI spec",
+                hint: "re-run with --full",
+            }));
+            return 0;
+        }
+        process.stdout.write(`${rendered}\n`);
+        return 0;
+    }
+    if (rest[0] === "commands") {
+        console.log(renderCommandList(commands, style));
+        return 0;
+    }
+    // The person sign-in (docs/developer-access.md) — the CLI's own, not API
+    // operations. Base URL resolution here also honours the stored default
+    // (`datum login` remembers where it signed in).
+    const store = new CredentialStore();
+    const orgBaseUrl = globals.values.get("base-url") ??
+        process.env.DATUM_BASE_URL ??
+        process.env.MCA_BASE_URL ??
+        store.defaultBaseUrl() ??
+        "http://localhost:3001";
+    const space = globals.values.get("space") ?? process.env.DATUM_SPACE;
+    // MCA_* fallbacks: pre-rename shells keep working; DATUM_* always wins.
+    // Resolved here, before the sign-in commands, because `whoami`/`login` must
+    // tell the person which credential API commands would actually use (#343):
+    // a key ALWAYS wins over the stored sign-in (docs/cli.md "Auth").
+    // A credential PROCESS (#2719) sits between the flag and the env key:
+    // on a personal agent's machine it hands out the person's own short-lived
+    // token. Run lazily — only once a command needs a credential.
+    const credentialProcess = globals.values.has("api-key") ? "" : (process.env[CREDENTIAL_PROCESS_ENV]?.trim() ?? "");
+    let apiKeySource = globals.values.has("api-key")
+        ? "--api-key"
+        : credentialProcess
+            ? CREDENTIAL_PROCESS_ENV
+            : process.env.DATUM_API_KEY
+                ? "DATUM_API_KEY"
+                : process.env.MCA_API_KEY
+                    ? "MCA_API_KEY"
+                    : undefined;
+    let apiKey = globals.values.get("api-key") ??
+        (credentialProcess ? undefined : (process.env.DATUM_API_KEY ?? process.env.MCA_API_KEY));
+    const authIo = { out: process.stdout, err: process.stderr, store, apiKeySource, apiKey };
+    /** Runs the credential process once (null = reported, exit 2). */
+    const loadProcessCredential = () => {
+        if (!credentialProcess || apiKey)
+            return true;
+        try {
+            apiKey = readCredentialProcess(credentialProcess).token;
+            authIo.apiKey = apiKey;
+            return true;
+        }
+        catch (err) {
+            if (!(err instanceof CredentialProcessError))
+                throw err;
+            console.error(`datum: ${err.message}`);
+            apiKeySource = undefined;
+            return false;
+        }
+    };
+    /**
+     * The credential and the surface every API call rides — shared by the
+     * derived commands and by the hand-written `artifacts publish`, which is
+     * an API command too (it just spans several calls). Resolved lazily,
+     * because group help and the sign-in commands must not demand a
+     * credential. Returns null after reporting a usage problem.
+     */
+    const resolveConfig = async () => {
+        // --curl renders a placeholder: no reason to ask for a real token.
+        if (!globals.bools.has("curl") && !loadProcessCredential())
+            return null;
+        const variant = normalizeVariant(globals.values.get("env") ?? process.env.DATUM_ENV ?? process.env.MCA_ENV);
+        // No key → the person's sign-in, refreshed when about to expire. A
+        // missing/expired sign-in is reported as usage (2), like a missing key.
+        let bearerToken;
+        if (!apiKey) {
+            try {
+                bearerToken = await ensureAccessToken(orgBaseUrl, store);
+            }
+            catch (err) {
+                if (err instanceof NotLoggedInError || err instanceof LoginFlowError) {
+                    // --curl renders a placeholder anyway — no sign-in needed for that.
+                    if (!globals.bools.has("curl")) {
+                        console.error(`datum: ${err.message}`);
+                        return null;
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        let baseUrl = orgBaseUrl;
+        if (space) {
+            try {
+                // --space addresses the space's own host (tenant by host, like the panel).
+                baseUrl = spaceBaseUrl(orgBaseUrl, space);
+            }
+            catch (err) {
+                if (err instanceof UsageError) {
+                    console.error(`datum: ${err.message}`);
+                    return null;
+                }
+                throw err;
+            }
+        }
+        return {
+            baseUrl,
+            ...(apiKey ? { apiKey } : {}),
+            ...(bearerToken ? { bearerToken } : {}),
+            ...(variant ? { variant } : {}),
+            // --curl only renders the request (with a placeholder credential).
+            ...(globals.bools.has("curl") ? { allowMissingKey: true } : {}),
+        };
+    };
+    /**
+     * `datum artifacts publish <dir>` is hand-written (#589), but the spec
+     * also DERIVES `artifacts publish plan` and `artifacts publish commit`
+     * from the two-step transport endpoints. A third word that names one of
+     * those derived commands therefore belongs to the tree; anything else is
+     * the directory to publish. (A directory literally called `plan` needs
+     * `./plan`.)
+     */
+    const derivedUnderArtifactsPublish = (words) => words[0] === "artifacts" &&
+        words[1] === "publish" &&
+        commands.some((c) => c.name === `artifacts publish ${words[2] ?? ""}`);
+    // A directory that happens to be called `plan` or `commit` loses to the
+    // derived command — say how to reach it instead of leaving the person
+    // with "missing required flag --files" (#589 e2e).
+    if (derivedUnderArtifactsPublish(rest) && rest[2] && existsSync(rest[2]) && statSync(rest[2]).isDirectory()) {
+        console.error(`datum: \`${rest[2]}\` is also the derived command \`artifacts publish ${rest[2]}\` — to publish the directory, write \`./${rest[2]}\``);
+    }
+    // The hand-written commands' --help (and `datum help <cmd>`) must print
+    // usage — never start a device-code flow or block on stdio waiting for MCP
+    // frames, which is what falling through into the handler did.
+    const builtin = derivedUnderArtifactsPublish(rest)
+        ? undefined
+        : BUILTIN_COMMANDS.find((c) => c.tokens.every((t, i) => rest[i] === t));
+    if (builtin && globals.bools.has("help")) {
+        process.stdout.write(`${renderBuiltinHelp(builtin, style)}\n`);
+        return 0;
+    }
+    if (rest[0] === "update") {
+        // Self-update (#1512, selfUpdate.ts): the CLI's own, not an API operation.
+        return runUpdate({
+            args: rest.slice(1),
+            baseUrl: orgBaseUrl,
+            ownVersion: appVersion(),
+            entryDir: path.dirname(fileURLToPath(import.meta.url)),
+            env: process.env,
+            paths: updatePaths(),
+            deps: updateDeps(),
+        }, { out: process.stdout, err: process.stderr });
+    }
+    if (rest[0] === "login")
+        return runLogin(orgBaseUrl, authIo);
+    if (rest[0] === "logout")
+        return runLogout(orgBaseUrl, authIo);
+    if (rest[0] === "whoami")
+        return loadProcessCredential() ? runWhoami(orgBaseUrl, space, authIo) : 2;
+    if (rest[0] === "a2a")
+        return loadProcessCredential() ? runA2a(orgBaseUrl, space, rest.slice(1), authIo) : 2;
+    if (rest[0] === "mcp" && rest[1] === "serve") {
+        return runMcpServe({ baseUrl: orgBaseUrl, space, store, version: appVersion() });
+    }
+    if (rest[0] === "mcp") {
+        // `datum mcp` / `datum mcp --help` / `datum mcp start`: the only verb is
+        // `serve` — say so instead of the API tree's "Unknown command: mcp".
+        const serve = BUILTIN_COMMANDS.find((c) => c.tokens[1] === "serve");
+        console.error(`datum: did you mean \`datum mcp serve\`? (the stdio MCP server for Claude Code)`);
+        process.stdout.write(`${renderBuiltinHelp(serve, style)}\n`);
+        return globals.bools.has("help") ? 0 : 2;
+    }
+    if (rest[0] === "satellite") {
+        // `datum satellite …` (#504): the daemon lives in its own package (it
+        // runs on machines the panel never touches); this CLI only hands the
+        // arguments to the installed binary so the one command the Account page
+        // shows works as printed.
+        return runSatellitePassthrough(rest.slice(1));
+    }
+    if (rest[0] === "artifacts" && rest[1] === "publish" && !derivedUnderArtifactsPublish(rest)) {
+        // Publishing a page from outside a run (#589): one command, but a walk
+        // and up to N+2 HTTP calls — the derived tree cannot express it, so
+        // POST /api/artifacts/publish is `x-cli: hidden` and this owns the name.
+        const config = await resolveConfig();
+        if (!config)
+            return 2;
+        let args;
+        try {
+            args = parseCommandArgs(rest.slice(2), new Set());
+        }
+        catch (err) {
+            if (err instanceof UsageError) {
+                console.error(`datum: ${err.message}`);
+                return 2;
+            }
+            throw err;
+        }
+        const flag = (name) => args.flags.get(name)?.at(-1);
+        const unknown = [...args.flags.keys()].filter((f) => !["key", "title", "description", "entry"].includes(f));
+        if (unknown.length > 0) {
+            console.error(`datum: unknown flag --${unknown[0]}. Known flags: --key, --title, --description, --entry.`);
+            return 2;
+        }
+        if (args.positionals.length !== 1) {
+            console.error("datum: expected 1 argument (<dir>) — see: datum artifacts publish --help");
+            return 2;
+        }
+        return runArtifactsPublish({
+            dir: args.positionals[0],
+            ...(flag("key") !== undefined ? { key: flag("key") } : {}),
+            ...(flag("title") !== undefined ? { title: flag("title") } : {}),
+            ...(flag("description") !== undefined ? { description: flag("description") } : {}),
+            ...(flag("entry") !== undefined ? { entry: flag("entry") } : {}),
+        }, config, { out: process.stdout, err: process.stderr });
+    }
+    if (rest[0] === "previews" || (rest[0] === "preview" && PREVIEW_VERBS.has(rest[1] ?? ""))) {
+        // The preview gateway from a terminal (#2928): a foreground loop and a
+        // follow over /api/acc-previews — nothing the derived tree can express.
+        const config = await resolveConfig();
+        if (!config)
+            return 2;
+        const verb = rest[0] === "previews" ? "list" : rest[1];
+        let args;
+        try {
+            args = parseCommandArgs(rest.slice(rest[0] === "previews" ? 1 : 2), new Set(["follow", "json"]));
+        }
+        catch (err) {
+            if (err instanceof UsageError) {
+                console.error(`datum: ${err.message}`);
+                return 2;
+            }
+            throw err;
+        }
+        const flag = (name) => args.flags.get(name)?.at(-1);
+        const known = { list: ["json"], up: ["port", "vhost", "machine"], down: [], trace: ["follow", "limit"] };
+        const unknown = [...args.flags.keys()].find((f) => !known[verb].includes(f));
+        if (unknown) {
+            console.error(`datum: unknown flag --${unknown} — see: datum ${rest[0] === "previews" ? "previews" : `preview ${verb}`} --help`);
+            return 2;
+        }
+        // Ctrl+C ends the foreground verbs cleanly (up closes its preview); the others keep the default.
+        const foreground = verb === "up" || (verb === "trace" && args.flags.has("follow"));
+        const io = {
+            out: process.stdout,
+            err: process.stderr,
+            // A foreground verb outlives one access token: refresh before each call.
+            freshToken: () => ensureAccessToken(orgBaseUrl, store),
+            ...(foreground ? { interrupted: interruptedBySignal() } : {}),
+        };
+        if (verb === "list")
+            return runPreviewsList({ json: args.flags.has("json") }, config, io);
+        if (verb === "up") {
+            const port = Number(flag("port"));
+            if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+                console.error("datum: --port <1-65535> is required — the port your app listens on (127.0.0.1)");
+                return 2;
+            }
+            return runPreviewUp({ port, ...(flag("vhost") ? { vhost: flag("vhost") } : {}), ...(flag("machine") ? { machine: flag("machine") } : {}) }, config, io);
+        }
+        if (args.positionals.length !== 1) {
+            console.error(`datum: expected 1 argument (<id>, from datum previews) — see: datum preview ${verb} --help`);
+            return 2;
+        }
+        const id = args.positionals[0];
+        if (verb === "down")
+            return runPreviewDown({ id }, config, io);
+        const limit = flag("limit") !== undefined ? Number(flag("limit")) : undefined;
+        return runPreviewTrace({ id, follow: args.flags.has("follow"), ...(limit !== undefined && Number.isInteger(limit) ? { limit } : {}) }, config, io);
+    }
+    if (rest[0] === "outputs" && rest[1] === "download") {
+        // An output's bytes (#2680): metadata from /api, the file from the
+        // origin's /outputs route — two calls the derived tree cannot express.
+        const config = await resolveConfig();
+        if (!config)
+            return 2;
+        let args;
+        try {
+            args = parseCommandArgs(rest.slice(2), new Set());
+        }
+        catch (err) {
+            if (err instanceof UsageError) {
+                console.error(`datum: ${err.message}`);
+                return 2;
+            }
+            throw err;
+        }
+        const unknown = [...args.flags.keys()].filter((f) => f !== "out");
+        if (unknown.length > 0) {
+            console.error(`datum: unknown flag --${unknown[0]}. Known flags: --out.`);
+            return 2;
+        }
+        if (args.positionals.length !== 1) {
+            console.error("datum: expected 1 argument (<id>) — see: datum outputs download --help");
+            return 2;
+        }
+        const out = args.flags.get("out")?.at(-1);
+        return runOutputsDownload({ id: args.positionals[0], ...(out !== undefined ? { out } : {}) }, config, { out: process.stdout, err: process.stderr });
+    }
+    // The derived `space-manifest schema list` and `space-manifest validate
+    // --spec …` (the raw endpoints) stay reachable: the hand-written verb
+    // takes a kind / a directory, never the derived command's own words.
+    const derivedSpaceManifest = (rest[1] === "schema" && rest[2] === "list") ||
+        (rest[1] === "validate" &&
+            (globals.values.has("data") || rest.slice(2).some((t) => t === "--spec" || t.startsWith("--spec="))));
+    if (rest[0] === "space-manifest" && SPACE_MANIFEST_DIR_VERBS.has(rest[1] ?? "") && !derivedSpaceManifest) {
+        // A space's configuration as files (#1809): each verb walks a directory
+        // around one call of the derived `space-manifest list|set`.
+        return runSpaceManifestDir(rest[1], rest.slice(2), space, globals.bools.has("raw"), resolveConfig);
+    }
+    if (rest.length === 0) {
+        console.log(renderRootHelp(spec, commands, style));
+        return 0;
+    }
+    const words = [];
+    for (const token of rest) {
+        if (token.startsWith("--"))
+            break;
+        words.push(token);
+    }
+    const match = matchCommand(commands, words);
+    if (!match) {
+        console.log(renderGroupHelp(words, commands, style));
+        // A valid group listing is help (0); an unknown word is an error (2).
+        const prefix = words.join(" ");
+        const known = commands.some((c) => c.name.startsWith(`${prefix} `));
+        return known ? 0 : 2;
+    }
+    const { command } = match;
+    if (globals.bools.has("help")) {
+        console.log(renderCommandHelp(command, style));
+        return 0;
+    }
+    // Bare group ("datum cases") — words matched nothing longer but the exact
+    // match needs its positionals/flags; a SHORTER match than the words given
+    // means trailing words are positionals, which is the normal call path.
+    const boolFlags = new Set([...command.queryFlags, ...command.bodyFlags]
+        .filter((f) => f.type === "boolean")
+        .map((f) => f.flag));
+    const commandTokens = rest.slice(command.name.split(" ").length);
+    const config = await resolveConfig();
+    if (!config)
+        return 2;
+    try {
+        const args = parseCommandArgs(commandTokens, boolFlags);
+        if (globals.values.has("data")) {
+            args.body = globals.values.get("data");
+        }
+        const request = buildRequest(command, args, config);
+        if (globals.bools.has("curl")) {
+            console.log(toCurl(request, { full: globals.bools.has("full") }));
+            return 0;
+        }
+        const result = await executeRequest(request, {
+            raw: globals.bools.has("raw"),
+            full: globals.bools.has("full"),
+            ...(globals.values.has("fields")
+                ? {
+                    fields: globals.values
+                        .get("fields")
+                        .split(",")
+                        .map((f) => f.trim())
+                        .filter(Boolean),
+                }
+                : {}),
+            out: process.stdout,
+        });
+        if (!result.ok) {
+            const detail = result.detail ? ` — ${result.detail}` : "";
+            console.error(`datum: HTTP ${result.status}${detail} (${command.method} ${request.url})`);
+            if (result.status === 401 && !result.detail) {
+                console.error(config.apiKey
+                    ? "datum: the API key was rejected — check DATUM_API_KEY / --api-key (panel: Settings → API keys)"
+                    : "datum: the sign-in was rejected — run `datum login` again");
+            }
+            // A write waiting for the person's approval (#2719) is not a failure
+            // of the call: its own exit code, like datum-tool's pending_approval.
+            if (result.code === APPROVAL_REQUIRED_CODE)
+                return EXIT_APPROVAL_REQUIRED;
+            return 1;
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            console.error(`datum: ${err.message}`);
+            return 2;
+        }
+        console.error(`datum: ${describeNetworkError(err, config.baseUrl)}`);
+        return 1;
+    }
+}
+/** fetch() failures arrive as TypeError with a coded `cause` — translate. */
+function describeNetworkError(err, baseUrl) {
+    const cause = err.cause;
+    switch (cause?.code) {
+        case "ENOTFOUND":
+        case "EAI_AGAIN":
+            return `cannot resolve the host in ${baseUrl} — check --base-url / DATUM_BASE_URL (and VPN/DNS)`;
+        case "ECONNREFUSED":
+            return `connection refused by ${baseUrl} — is the server running there?`;
+        case "ETIMEDOUT":
+        case "UND_ERR_CONNECT_TIMEOUT":
+            return `connection to ${baseUrl} timed out — network, VPN or firewall?`;
+        case "CERT_HAS_EXPIRED":
+        case "DEPTH_ZERO_SELF_SIGNED_CERT":
+        case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+            return `TLS certificate problem at ${baseUrl}: ${cause.code}`;
+        default: {
+            const message = cause?.message ?? (err instanceof Error ? err.message : String(err));
+            return `request to ${baseUrl} failed — ${message}`;
+        }
+    }
+}
+/** The script name as the OS passed it — both separators, because Windows
+ * hands `C:\…\cli\datum.js` (#1816: the old `/`-only check let the CLI exit
+ * 0 without a word on every Windows machine). */
+export function scriptBaseName(argv1) {
+    return argv1.split(/[\\/]/).pop() ?? "";
+}
+/**
+ * Whether this module runs as the `datum` binary (not imported by tests):
+ * the script node started IS this file (realpath — the npm bin shims
+ * `datum` and `mca` on macOS/Linux are symlinks to it), or its name is
+ * `datum`, `datum.js` or `datum.ts` on either separator. `unrecognised` =
+ * a bin shim's name that matched neither — the caller says so out loud
+ * instead of exiting 0 in silence.
+ */
+export function cliEntryOf(argv1, moduleFile, realpath) {
+    if (!argv1)
+        return "imported";
+    try {
+        if (realpath(argv1) === realpath(moduleFile))
+            return "run";
+    }
+    catch {
+        // an argv[1] that is not a file (a REPL, -e) — the name decides
+    }
+    const name = scriptBaseName(argv1);
+    if (/^datum(\.(ts|js))?$/i.test(name))
+        return "run";
+    return /^(datum|mca)(\.(cmd|ps1|exe))?$/i.test(name) ? "unrecognised" : "imported";
+}
+// Invoked as a binary — directly (…/datum.ts, …\datum.js) or through the
+// npm bin shim (a symlink named `datum`; datum.cmd / datum.ps1 on Windows).
+// NOTE: exitCode, never process.exit() — exit() drops buffered stdout on
+// pipes, truncating large JSON responses mid-stream (seen at ~64 kB during
+// skill testing).
+const cliEntry = cliEntryOf(process.argv[1], fileURLToPath(import.meta.url), realpathSync);
+if (cliEntry === "unrecognised") {
+    console.error(`datum: started as ${process.argv[1]} but did not recognise it as the CLI entry — nothing ran. ` +
+        "Please report this to the Datum team with the path above.");
+    process.exitCode = 1;
+}
+if (cliEntry === "run") {
+    runBin(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        console.error(`datum: ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=datum.js.map