@datumos/datum-cli 0.0.0-stage → 0.588.0

package/cli/commandTree.js

@@ -0,0 +1,243 @@
+/**
+ * Derives the `datum` command tree from the OpenAPI spec — the CLI has NO
+ * hand-written command definitions, so it updates itself with every API
+ * change (the spec is the maintained contract, CLAUDE.md "API = kontrakt").
+ *
+ * Mapping rules (deterministic; commandTree.test.ts proves uniqueness
+ * against the real spec):
+ * - command tokens = static path segments after `/api`
+ *   (`/api/cases/{id}/links` → `cases links`);
+ * - path params become positional arguments in path order;
+ * - the verb comes from the method + path shape:
+ *   GET → `get` when the path ends with a param, else `list`;
+ *   POST → the trailing action segment when there is one after the
+ *   resource (`/api/cases/{id}/escalate` → `escalate`), else `create`;
+ *   PATCH → `update`, PUT → `set`, DELETE → `delete`;
+ * - query params and top-level JSON body properties become `--kebab-case`
+ *   flags (typed from their schema);
+ * - `x-cli-name` names a command the rules would give a taken name
+ *   (X_CLI_NAME below); `x-cli: hidden` keeps an operation out;
+ *   `x-cli-flag` on a body property names its flag (X_CLI_FLAG).
+ */
+/** OpenAPI extension on a BODY property that names its CLI flag instead of
+ * the kebab-cased wire name (#2905) — for a field whose derived flag would
+ * shadow a global one (RESERVED_GLOBAL_FLAGS): the page state's `data`
+ * becomes `--doc`. The wire name is unchanged. */
+export const X_CLI_FLAG = "x-cli-flag";
+const METHODS = ["get", "post", "put", "patch", "delete"];
+/**
+ * Global CLI flag names — derived command flags must never collide with
+ * these (commandTree.test.ts checks the real spec; a colliding new API
+ * field should get a different wire name).
+ */
+export const RESERVED_GLOBAL_FLAGS = new Set([
+    "base-url",
+    "api-key",
+    "actor",
+    "data",
+    "fields",
+    "curl",
+    "raw",
+    "help",
+    "version",
+]);
+export function kebabCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[_\s]+/g, "-")
+        .toLowerCase();
+}
+function schemaType(schema) {
+    const t = schema?.type;
+    if (t === "number" ||
+        t === "integer" ||
+        t === "boolean" ||
+        t === "array" ||
+        t === "object") {
+        return t;
+    }
+    return "string";
+}
+function deriveVerb(method, segments) {
+    const tokens = segments.filter((s) => !s.startsWith("{"));
+    const endsWithParam = segments[segments.length - 1]?.startsWith("{") ?? false;
+    switch (method) {
+        case "get":
+            return { verb: endsWithParam ? "get" : "list", tokens };
+        case "post":
+            // A trailing static segment AFTER the resource is the action itself
+            // (`…/{id}/escalate` → `escalate`, `…/sync` → `sync`).
+            if (!endsWithParam && tokens.length > 1) {
+                return { verb: tokens[tokens.length - 1], tokens: tokens.slice(0, -1) };
+            }
+            return { verb: "create", tokens };
+        case "patch":
+            return { verb: "update", tokens };
+        case "put":
+            return { verb: "set", tokens };
+        case "delete":
+            return { verb: "delete", tokens };
+        default:
+            return { verb: method, tokens };
+    }
+}
+function buildCommand(method, path, op) {
+    // Segments after the leading "/api".
+    const segments = path.split("/").filter(Boolean).slice(1);
+    const derived = deriveVerb(method, segments);
+    const { verb, tokens } = cliNameOverride(method, path, op, derived.tokens) ?? derived;
+    const positionals = [];
+    const queryFlags = [];
+    for (const param of op.parameters ?? []) {
+        if (param.in === "path") {
+            positionals.push({
+                name: param.name,
+                description: param.description ?? "",
+            });
+        }
+        else if (param.in === "query") {
+            queryFlags.push({
+                flag: kebabCase(param.name),
+                name: param.name,
+                source: "query",
+                required: param.required ?? false,
+                type: schemaType(param.schema),
+                ...(param.schema?.enum
+                    ? { enum: param.schema.enum.map(String) }
+                    : {}),
+                description: param.description ?? "",
+            });
+        }
+    }
+    const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+    const bodyFlags = [];
+    const requiredProps = new Set(bodySchema?.required ?? []);
+    for (const [name, schema] of Object.entries(bodySchema?.properties ?? {})) {
+        bodyFlags.push({
+            // `x-cli-flag` renames a body field whose derived flag would shadow a
+            // global one (the page state's `data` vs `--data`, #2905); the wire
+            // name stays.
+            flag: schema[X_CLI_FLAG] ?? kebabCase(name),
+            name,
+            source: "body",
+            required: requiredProps.has(name),
+            type: schemaType(schema),
+            ...(schema.enum ? { enum: schema.enum.map(String) } : {}),
+            description: schema.description ?? "",
+        });
+    }
+    return {
+        name: [...tokens, verb].join(" "),
+        tokens,
+        verb,
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary ?? "",
+        description: op.description ?? "",
+        tags: op.tags ?? [],
+        positionals,
+        queryFlags,
+        bodyFlags,
+        hasBody: Boolean(op.requestBody),
+        bodyRequired: op.requestBody?.required ?? false,
+        bodyDescription: bodySchema?.description ?? "",
+        bodyOpen: bodySchema?.additionalProperties !== false && Boolean(bodySchema),
+        responses: Object.entries(op.responses ?? {}).map(([status, r]) => ({ status, description: r.description ?? "" })),
+        examples: cliExamples(method, path, op, [...tokens, verb].join(" ")),
+    };
+}
+/** OpenAPI extension an operation sets to stay OUT of the CLI tree: a
+ * JSON-RPC endpoint (`/api/mcp`) that a flag-based command could not drive
+ * and whose name would shadow a hand-written built-in (`datum mcp serve`).
+ * The endpoint stays documented in the spec; only the CLI skips it. */
+export const X_CLI_HIDDEN = "hidden";
+/** OpenAPI extension that NAMES an operation's command instead of the
+ * derivation (#1562) — for the one case the rules cannot tell apart: a
+ * static segment where another path has a parameter
+ * (`GET /api/flows/runs` and `GET /api/flows/{id}/runs` both derive to
+ * `flows runs list`). The value is the whole command, space-separated —
+ * group tokens first, the verb last (`"flows runs all"`); it keeps the
+ * derived group (first token), so the command stays under `datum <group>`.
+ * Anything else is a spec bug and throws: the CLI must never guess. */
+export const X_CLI_NAME = "x-cli-name";
+const CLI_WORD = /^[a-z0-9][a-z0-9-]*$/;
+function cliNameOverride(method, path, op, derivedTokens) {
+    const raw = op[X_CLI_NAME];
+    if (raw === undefined)
+        return null;
+    const where = `${method.toUpperCase()} ${path}: ${X_CLI_NAME}`;
+    if (typeof raw !== "string")
+        throw new Error(`${where} must be a string`);
+    const words = raw.trim().split(/\s+/).filter(Boolean);
+    if (words.length < 2) {
+        throw new Error(`${where} "${raw}" needs a group and a verb ("flows runs all")`);
+    }
+    const bad = words.find((w) => !CLI_WORD.test(w));
+    if (bad !== undefined) {
+        throw new Error(`${where} "${raw}": "${bad}" is not a lowercase command word`);
+    }
+    if (derivedTokens[0] !== undefined && words[0] !== derivedTokens[0]) {
+        throw new Error(`${where} "${raw}" must stay in the "${derivedTokens[0]}" group`);
+    }
+    return { verb: words[words.length - 1], tokens: words.slice(0, -1) };
+}
+/** OpenAPI extension listing hand-picked invocations of an operation's
+ * command (#1562) — what `--help` and cli-reference.md show under
+ * *Examples* when a command's useful calls are not its required flags
+ * (`datum flows runs all --attention`). Each entry is a whole command line
+ * that starts with `datum <the command's name>`; anything else is a spec
+ * bug and throws, like a malformed `x-cli-name`. */
+export const X_CLI_EXAMPLES = "x-cli-examples";
+function cliExamples(method, path, op, name) {
+    const raw = op[X_CLI_EXAMPLES];
+    if (raw === undefined)
+        return [];
+    const where = `${method.toUpperCase()} ${path}: ${X_CLI_EXAMPLES}`;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error(`${where} must be a non-empty list of command lines`);
+    }
+    return raw.map((example) => {
+        if (typeof example !== "string")
+            throw new Error(`${where} entries must be strings`);
+        const line = example.trim().replace(/\s+/g, " ");
+        if (line !== `datum ${name}` && !line.startsWith(`datum ${name} `)) {
+            throw new Error(`${where} "${example}" must start with "datum ${name}"`);
+        }
+        return line;
+    });
+}
+/** All CLI commands derived from the spec, sorted by name. */
+export function buildCommandTree(spec) {
+    const commands = [];
+    for (const [path, operations] of Object.entries(spec.paths)) {
+        for (const method of METHODS) {
+            const op = operations[method];
+            if (op && op["x-cli"] !== X_CLI_HIDDEN) {
+                commands.push(buildCommand(method, path, op));
+            }
+        }
+    }
+    return commands.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Matches argv words against the tree: the longest command whose
+ * `name` tokens are a prefix of the given words wins. Returns the command
+ * and the remaining words (positionals/flags).
+ */
+export function matchCommand(commands, words) {
+    let best = null;
+    for (const command of commands) {
+        const parts = command.name.split(" ");
+        if (parts.length > words.length)
+            continue;
+        if (parts.every((p, i) => p === words[i])) {
+            if (!best || parts.length > best.length) {
+                best = { command, length: parts.length };
+            }
+        }
+    }
+    return best
+        ? { command: best.command, rest: words.slice(best.length) }
+        : null;
+}
+//# sourceMappingURL=commandTree.js.map

package/cli/credentialProcess.js

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+/**
+ * The CLI's credential process (#2719) — the `credential_process` pattern
+ * of the AWS CLI (#111): `DATUM_CREDENTIAL_PROCESS` names a command whose
+ * stdout is `{ "token": "datum_…", "expiresAt": "<ISO>" }`. The CLI runs it
+ * once per invocation and uses the token as its API key; nothing is
+ * written to the CLI's own files. On a personal agent's machine the
+ * runtime points it at the run plane's /datum-token (the person's own
+ * 15-minute token), so no long-lived secret lies on the disk.
+ *
+ * Precedence: `--api-key` > DATUM_CREDENTIAL_PROCESS > DATUM_API_KEY >
+ * the stored sign-in (docs/cli.md "Auth").
+ */
+export const CREDENTIAL_PROCESS_ENV = "DATUM_CREDENTIAL_PROCESS";
+/** How long the command may take (it makes one HTTPS call). */
+export const CREDENTIAL_PROCESS_TIMEOUT_MS = 30_000;
+export class CredentialProcessError extends Error {
+}
+const defaultRunner = (command) => {
+    // The value is the run's own configuration (the runtime writes it, or the
+    // person sets it); it runs under a shell like the AWS CLI's.
+    const out = spawnSync(command, {
+        shell: true,
+        encoding: "utf8",
+        timeout: CREDENTIAL_PROCESS_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { status: out.status, stdout: out.stdout ?? "", stderr: out.stderr ?? "", ...(out.error ? { error: out.error } : {}) };
+};
+/** Runs the credential process and reads its answer. Throws
+ * CredentialProcessError with a message for the person — never the
+ * process's stdout (it may carry the token). */
+export function readCredentialProcess(command, run = defaultRunner) {
+    const res = run(command);
+    if (res.error)
+        throw new CredentialProcessError(`${CREDENTIAL_PROCESS_ENV} could not run: ${res.error.message}`);
+    if (res.status !== 0) {
+        const why = res.stderr.trim().split("\n").slice(-1)[0] ?? "";
+        throw new CredentialProcessError(`${CREDENTIAL_PROCESS_ENV} exited ${res.status ?? "?"}${why ? ` — ${why.slice(0, 300)}` : ""}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(res.stdout);
+    }
+    catch {
+        throw new CredentialProcessError(`${CREDENTIAL_PROCESS_ENV} did not print JSON { token, expiresAt }`);
+    }
+    const p = (parsed && typeof parsed === "object" ? parsed : {});
+    const token = typeof p.token === "string" ? p.token.trim() : "";
+    if (!token)
+        throw new CredentialProcessError(`${CREDENTIAL_PROCESS_ENV} printed no token`);
+    return { token, expiresAt: typeof p.expiresAt === "string" ? p.expiresAt : "" };
+}
+//# sourceMappingURL=credentialProcess.js.map

package/cli/credentials.js

@@ -0,0 +1,93 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * Where `datum login` keeps what it obtained (docs/developer-access.md):
+ * ONE JSON file, mode 0600 in a 0700 directory — the same posture `gh`
+ * takes on Linux. No keychain: the CLI is dependency-free and headless
+ * (ssh, containers) by design; the refresh token is the sensitive part and
+ * it lives only here, never in env or in a shell history.
+ *
+ * Location: `$DATUM_CONFIG_DIR/credentials.json`, else
+ * `$XDG_CONFIG_HOME/datum/credentials.json`, else `~/.config/datum/…`.
+ * Keyed by the ORG origin the login ran against (`https://datum.example`);
+ * space subdomains reuse the org's tokens — the token is the same
+ * person on the same app registration whichever space host answers.
+ */
+export const CREDENTIALS_FILE = "credentials.json";
+export const CREDENTIALS_VERSION = 1;
+const EMPTY = { version: CREDENTIALS_VERSION, logins: {} };
+export function credentialsDir(env = process.env) {
+    if (env.DATUM_CONFIG_DIR?.trim())
+        return env.DATUM_CONFIG_DIR.trim();
+    const xdg = env.XDG_CONFIG_HOME?.trim();
+    return path.join(xdg || path.join(homedir(), ".config"), "datum");
+}
+export function credentialsPath(env = process.env) {
+    return path.join(credentialsDir(env), CREDENTIALS_FILE);
+}
+/** The credentials key for a base URL: scheme + host + port, no path. */
+export function originOf(baseUrl) {
+    return new URL(baseUrl).origin;
+}
+export class CredentialStore {
+    file;
+    constructor(file = credentialsPath()) {
+        this.file = file;
+    }
+    get path() {
+        return this.file;
+    }
+    read() {
+        if (!existsSync(this.file))
+            return { ...EMPTY, logins: {} };
+        try {
+            const parsed = JSON.parse(readFileSync(this.file, "utf8"));
+            if (parsed.version !== CREDENTIALS_VERSION || typeof parsed.logins !== "object" || !parsed.logins) {
+                return { ...EMPTY, logins: {} };
+            }
+            return {
+                version: CREDENTIALS_VERSION,
+                ...(parsed.defaultBaseUrl ? { defaultBaseUrl: parsed.defaultBaseUrl } : {}),
+                logins: parsed.logins,
+            };
+        }
+        catch {
+            // A corrupt file must not brick the CLI — the next login rewrites it.
+            return { ...EMPTY, logins: {} };
+        }
+    }
+    write(file) {
+        const dir = path.dirname(this.file);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, this.file);
+    }
+    get(baseUrl) {
+        return this.read().logins[originOf(baseUrl)] ?? null;
+    }
+    set(login) {
+        const file = this.read();
+        const origin = originOf(login.baseUrl);
+        file.logins[origin] = { ...login, baseUrl: origin };
+        file.defaultBaseUrl = origin;
+        this.write(file);
+    }
+    /** Forgets one login; returns whether there was one. */
+    delete(baseUrl) {
+        const file = this.read();
+        const origin = originOf(baseUrl);
+        const had = origin in file.logins;
+        delete file.logins[origin];
+        if (file.defaultBaseUrl === origin)
+            delete file.defaultBaseUrl;
+        this.write(file);
+        return had;
+    }
+    defaultBaseUrl() {
+        return this.read().defaultBaseUrl ?? null;
+    }
+}
+//# sourceMappingURL=credentials.js.map