@datumos/datum-cli 0.0.0 → 0.589.0

package/cli/invoke.js

@@ -0,0 +1,427 @@
+/**
+ * Turns a matched CLI command + parsed arguments into an HTTP request and
+ * executes it. Pure request-building is separated from I/O so tests cover
+ * the full URL/header/body derivation without a server.
+ */
+import { readFileSync } from "node:fs";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { insecureOriginReason } from "./secureOrigin.js";
+/**
+ * Neither of the two caps below is about bandwidth. They exist because this
+ * CLI is driven by agents as often as by people, and everything a command
+ * PRINTS becomes part of the model's context — which is re-sent on every
+ * later turn, so a megabyte printed once is paid for many times over
+ * (#646). The request bytes themselves are free; only what reaches stdout
+ * is not.
+ */
+/** Above this, `--curl` names the body instead of rendering it. */
+export const MAX_CURL_BODY_BYTES = 2 * 1024;
+/** Above this, a pretty-printed JSON response is written to a file. */
+export const MAX_PRINTED_RESPONSE_BYTES = 256 * 1024;
+/** Variant-pinning header understood by the Ring Accelerator. */
+export const X_OA_VARIANT_HEADER = "x-oa-variant";
+export class UsageError extends Error {
+}
+function coerce(flag, raw) {
+    switch (flag.type) {
+        case "boolean": {
+            const v = raw[raw.length - 1];
+            if (v === "" || v === undefined || v === "true")
+                return true;
+            if (v === "false")
+                return false;
+            throw new UsageError(`--${flag.flag} takes true/false, got "${v}"`);
+        }
+        case "number":
+        case "integer": {
+            const v = Number(raw[raw.length - 1]);
+            if (Number.isNaN(v)) {
+                throw new UsageError(`--${flag.flag} expects a number`);
+            }
+            return v;
+        }
+        case "array":
+            // Arrays of OBJECTS (e.g. provision's repos: [{owner, repo}]) are
+            // expressible per item: a value that looks like JSON is parsed —
+            // half-typed JSON errors loudly instead of shipping a string the
+            // server will 400 on. Plain values stay strings.
+            return raw.map((v) => {
+                const t = v.trim();
+                if (!t.startsWith("{") && !t.startsWith("["))
+                    return v;
+                try {
+                    return JSON.parse(t);
+                }
+                catch {
+                    throw new UsageError(`--${flag.flag}: "${v.slice(0, 40)}…" looks like JSON but does not parse`);
+                }
+            });
+        case "object": {
+            try {
+                return JSON.parse(raw[raw.length - 1]);
+            }
+            catch {
+                throw new UsageError(`--${flag.flag} expects JSON`);
+            }
+        }
+        default:
+            return raw[raw.length - 1];
+    }
+}
+/** Resolves --data: inline JSON, @file, or "-" (stdin already read). */
+export function resolveBodyArg(body, readStdin = () => readFileSync(0, "utf8")) {
+    const text = body === "-"
+        ? readStdin()
+        : body.startsWith("@")
+            ? readFileSync(body.slice(1), "utf8")
+            : body;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError("--data must be valid JSON (inline, @file or - for stdin)");
+    }
+}
+/**
+ * Builds the request. Enum values are validated here (the server would 400
+ * anyway, but a local message with the allowed values is kinder).
+ */
+export function buildRequest(command, args, config) {
+    if (args.positionals.length !== command.positionals.length) {
+        const expected = command.positionals.map((p) => `<${p.name}>`).join(" ");
+        throw new UsageError(`expected ${command.positionals.length} argument${command.positionals.length === 1 ? "" : "s"}` +
+            `${expected ? ` (${expected})` : ""}, got ${args.positionals.length} — see: datum ${command.name} --help`);
+    }
+    // Path params, in spec order.
+    let path = command.path;
+    command.positionals.forEach((p, i) => {
+        path = path.replace(`{${p.name}}`, encodeURIComponent(args.positionals[i]));
+    });
+    const known = new Map();
+    for (const f of [...command.queryFlags, ...command.bodyFlags]) {
+        known.set(f.flag, f);
+    }
+    for (const flag of args.flags.keys()) {
+        if (!known.has(flag)) {
+            const hint = known.size > 0
+                ? ` Known flags: ${[...known.keys()].map((f) => `--${f}`).join(", ")}.`
+                : command.hasBody
+                    ? " This command takes its input via --data."
+                    : "";
+            throw new UsageError(`unknown flag --${flag}.${hint}`);
+        }
+    }
+    const query = new URLSearchParams();
+    const bodyFromFlags = {};
+    for (const [flag, raw] of args.flags) {
+        const spec = known.get(flag);
+        const value = coerce(spec, raw);
+        if (spec.enum && !spec.enum.includes(String(value))) {
+            throw new UsageError(`--${flag} must be one of: ${spec.enum.join(", ")}`);
+        }
+        if (spec.source === "query") {
+            for (const v of Array.isArray(value) ? value : [value]) {
+                query.append(spec.name, String(v));
+            }
+        }
+        else {
+            bodyFromFlags[spec.name] = value;
+        }
+    }
+    for (const f of [...command.queryFlags, ...command.bodyFlags]) {
+        if (f.required && !args.flags.has(f.flag)) {
+            // --data may carry required body fields; only query flags are
+            // strictly checkable client-side.
+            if (f.source === "query" || !args.body) {
+                throw new UsageError(`missing required flag --${f.flag} — see: datum ${command.name} --help`);
+            }
+        }
+    }
+    let body;
+    let bodySource;
+    if (args.body !== undefined || Object.keys(bodyFromFlags).length > 0) {
+        if (!command.hasBody) {
+            throw new UsageError(`${command.method} ${command.path} takes no request body`);
+        }
+        const base = args.body !== undefined ? resolveBodyArg(args.body) : {};
+        // The source is only quotable when nothing was merged into it.
+        const merged = Object.keys(bodyFromFlags).length > 0;
+        bodySource =
+            !merged && args.body !== undefined
+                ? args.body === "-"
+                    ? { kind: "stdin" }
+                    : args.body.startsWith("@")
+                        ? { kind: "file", path: args.body.slice(1) }
+                        : { kind: "inline" }
+                : { kind: "inline" };
+        if (base !== null && typeof base === "object" && !Array.isArray(base)) {
+            body = JSON.stringify({ ...base, ...bodyFromFlags });
+        }
+        else {
+            // Non-object bodies pass through untouched (flags can't merge).
+            body = JSON.stringify(base);
+        }
+    }
+    else if (command.hasBody && command.bodyRequired) {
+        body = JSON.stringify({});
+        bodySource = { kind: "inline" };
+    }
+    const surface = apiSurface(config);
+    const qs = query.size > 0 ? `?${query.toString()}` : "";
+    const headers = { ...surface.headers };
+    if (body !== undefined)
+        headers["content-type"] = "application/json";
+    return {
+        url: `${surface.url(path)}${qs}`,
+        method: command.method,
+        headers,
+        ...(body !== undefined ? { body } : {}),
+        ...(bodySource !== undefined ? { bodySource } : {}),
+    };
+}
+/**
+ * Where an API call goes and what credential it carries — the ONE place
+ * that decides the surface, so the hand-written commands
+ * (`artifacts publish`) address the API exactly like a derived one.
+ *
+ * The credential decides: an API key rides /public/api (a key is mandatory
+ * there — docs/public-api.md); a person token from `datum login` rides
+ * /api, where bearerIdentity verifies it and the role gate applies the
+ * person's (operator-capped) role. Same handlers either way.
+ */
+export function apiSurface(config) {
+    if (!config.apiKey && !config.bearerToken && !config.allowMissingKey) {
+        throw new UsageError("no credentials — run `datum login` (sign in with your Microsoft account), " +
+            "or pass --api-key / set DATUM_API_KEY (panel: Settings → API keys)");
+    }
+    const insecure = insecureOriginReason(config.baseUrl);
+    if (insecure)
+        throw new UsageError(insecure);
+    const origin = config.baseUrl.replace(/\/+$/, "");
+    const useKey = Boolean(config.apiKey) || !config.bearerToken;
+    const headers = {
+        authorization: `Bearer ${useKey ? (config.apiKey ?? "") : config.bearerToken}`,
+    };
+    if (config.variant) {
+        let host;
+        try {
+            host = new URL(origin).hostname;
+        }
+        catch {
+            throw new UsageError(`--base-url is not a valid URL: ${config.baseUrl}`);
+        }
+        headers[X_OA_VARIANT_HEADER] = `${host}::${config.variant}`;
+    }
+    return {
+        url: (path) => `${origin}${useKey ? "/public" : ""}${path}`,
+        headers,
+    };
+}
+/** Single-quotes a value for a POSIX shell, escaping embedded quotes. */
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Human-readable byte count for the notes below. */
+function humanBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * How `-d` is rendered. A body that fits is shown as it is — a short body
+ * in the preview is exactly what `--curl` is reached for. A large one is
+ * NAMED: `@path` when the body is that file unchanged (runnable as
+ * printed), `@-` for stdin, and a placeholder plus a note when it was
+ * typed inline, because expanding it would put the whole payload on stdout
+ * and that is the cost this flag existed to avoid.
+ */
+export function curlBodyArg(req, full) {
+    const body = req.body ?? "";
+    const size = Buffer.byteLength(body);
+    if (full || size <= MAX_CURL_BODY_BYTES)
+        return { arg: shellQuote(body) };
+    const source = req.bodySource ?? { kind: "inline" };
+    // Quoted like any other argument: a path with a space or a quote in it
+    // would otherwise split into two arguments (or worse), and the whole
+    // point of naming the body is that the line stays runnable as printed.
+    if (source.kind === "file")
+        return { arg: shellQuote(`@${source.path}`) };
+    if (source.kind === "stdin")
+        return { arg: shellQuote("@-") };
+    return {
+        arg: shellQuote("@body.json"),
+        note: `# body not rendered: ${humanBytes(size)} of JSON. Write it to ` +
+            "body.json, or re-run with --full to print it here.",
+    };
+}
+/** The --curl rendering (secrets stay in env-style placeholders). */
+export function toCurl(req, opts = {}) {
+    const parts = [`curl -X ${req.method}`];
+    for (const [k, v] of Object.entries(req.headers)) {
+        // Secrets never render: the key placeholder on the public surface, a
+        // token placeholder on the internal one (`datum login` credentials).
+        const shown = k === "authorization"
+            ? req.url.includes("/public/api/")
+                ? "authorization: Bearer $DATUM_API_KEY"
+                : "authorization: Bearer $DATUM_TOKEN"
+            : `${k}: ${v}`;
+        parts.push(`-H '${shown}'`);
+    }
+    let note;
+    if (req.body !== undefined) {
+        const rendered = curlBodyArg(req, opts.full === true);
+        parts.push(`-d ${rendered.arg}`);
+        note = rendered.note;
+    }
+    parts.push(`'${req.url}'`);
+    const command = parts.join(" \\\n  ");
+    return note ? `${command}\n${note}` : command;
+}
+/** Best short description of a non-JSON (usually HTML) response body. */
+function describeTextBody(text) {
+    const title = /<title[^>]*>([^<]+)<\/title>/i.exec(text)?.[1]?.trim();
+    if (title)
+        return `page titled "${title}"`;
+    const line = text
+        .replaceAll(/<[^>]+>/g, " ")
+        .split("\n")
+        .map((l) => l.trim())
+        .find(Boolean);
+    return line ? line.slice(0, 120) : undefined;
+}
+/**
+ * Client-side projection for --fields: keeps only the named top-level
+ * keys of an object (or of every element of an array). Solves the "list
+ * responses are huge" class of problems (e.g. embedded avatar data URLs)
+ * without any server change.
+ */
+export function projectFields(value, fields) {
+    const pick = (item) => item !== null && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(fields
+            .filter((f) => f in item)
+            .map((f) => [f, item[f]]))
+        : item;
+    return Array.isArray(value) ? value.map(pick) : pick(value);
+}
+/**
+ * Where an oversized response is parked, and what the reader is told
+ * instead. Separated so a test can point it somewhere writable.
+ */
+export async function spillResponse(rendered, dir = tmpdir()) {
+    // A response can carry tenant or personal data, so it never lands on a
+    // guessable path in a shared directory: `mkdtemp` creates a fresh 0700
+    // directory (nothing to pre-plant a symlink on, no collision between
+    // parallel invocations), and the file inside is created exclusively with
+    // 0600 rather than whatever the umask would have allowed.
+    const home = await mkdtemp(join(dir, "datum-response-"));
+    const file = join(home, "response.json");
+    await writeFile(file, `${rendered}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+    });
+    return file;
+}
+/** The notice that replaces a spilled body on stdout. */
+export function spillNotice(bytes, file, parsed, opts = {}) {
+    const items = Array.isArray(parsed) ? parsed.length : undefined;
+    const shape = items === undefined ? "" : ` (${items} item${items === 1 ? "" : "s"})`;
+    const hint = opts.hint ?? "narrow it with --fields a,b, or re-run with --full";
+    return (`datum: ${opts.what ?? "response"} is ${humanBytes(bytes)}${shape} — ` +
+        `written to ${file}\n` +
+        "datum: printing it here would cost more than reading it does; " +
+        `${hint} to print it anyway\n`);
+}
+/**
+ * Executes the request and writes the response to `out`. JSON is
+ * pretty-printed (unless raw); event streams and other text stream through
+ * line by line; anything else pipes raw bytes (logo downloads etc.).
+ *
+ * The API never redirects and never answers with HTML — both mean the call
+ * hit an SSO proxy or a wrong host, so instead of dumping a login page to
+ * stdout they fail with a hint (--raw restores blind piping for the body).
+ *
+ * A pretty-printed JSON answer above MAX_PRINTED_RESPONSE_BYTES is written
+ * to a file and replaced by a two-line notice (#646): that branch exists to
+ * be READ, and an answer nobody can read is worth less than the context it
+ * costs. The raw and binary branches below are deliberately NOT capped —
+ * their contract is byte-exact passthrough, and `datum … > logo.png` must
+ * keep producing a logo, not a notice.
+ */
+export async function executeRequest(req, opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const res = await doFetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        redirect: "manual",
+        ...(req.body !== undefined ? { body: req.body } : {}),
+    });
+    const type = res.headers.get("content-type") ?? "";
+    if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get("location") ?? "(no location header)";
+        return {
+            status: res.status,
+            ok: false,
+            detail: `the server redirected to ${location} — the API never redirects; ` +
+                "this is usually an SSO/login page or a wrong --base-url",
+        };
+    }
+    if (!opts.raw && type.includes("application/json")) {
+        const text = await res.text();
+        try {
+            let parsed = JSON.parse(text);
+            // Projection runs BEFORE the size check on purpose: --fields is the
+            // cheap way under the cap, and it should keep working as one.
+            if (opts.fields?.length)
+                parsed = projectFields(parsed, opts.fields);
+            const rendered = JSON.stringify(parsed, null, 2);
+            const bytes = Buffer.byteLength(rendered);
+            if (!opts.full && bytes > MAX_PRINTED_RESPONSE_BYTES) {
+                const file = await spillResponse(rendered, opts.spillDir);
+                opts.out.write(spillNotice(bytes, file, parsed));
+            }
+            else {
+                opts.out.write(`${rendered}\n`);
+            }
+            const error = parsed !== null && typeof parsed === "object"
+                ? parsed
+                : {};
+            const detail = error.error ?? error.message;
+            return {
+                status: res.status,
+                ok: res.ok,
+                ...(typeof detail === "string" && !res.ok ? { detail } : {}),
+                ...(typeof error.code === "string" && !res.ok ? { code: error.code } : {}),
+            };
+        }
+        catch {
+            opts.out.write(`${text}\n`);
+            return { status: res.status, ok: res.ok };
+        }
+    }
+    if (!opts.raw && (type.includes("text/html") || !res.ok)) {
+        // HTML (even a 200) or a non-JSON error: describe it, don't dump it.
+        const text = res.body ? await res.text() : "";
+        const described = describeTextBody(text);
+        const detail = type.includes("text/html")
+            ? `the response is a web page${described ? ` (${described})` : ""}, ` +
+                "not API JSON — check --base-url points at the API origin"
+            : described;
+        return {
+            status: res.status,
+            ok: false,
+            ...(detail ? { detail } : {}),
+        };
+    }
+    if (res.body) {
+        for await (const chunk of res.body) {
+            opts.out.write(Buffer.from(chunk));
+        }
+    }
+    return { status: res.status, ok: res.ok };
+}
+//# sourceMappingURL=invoke.js.map