@datumos/datum-cli 0.0.0 → 0.588.0

package/cli/previewCommand.js

@@ -0,0 +1,333 @@
+/**
+ * `datum preview up | down | trace` and `datum previews` (#2928) — the ACC
+ * preview gateway from a developer's terminal, the twins of `cde app start`,
+ * `cde interfaces` and `cde trace`:
+ *
+ *   datum preview up --port 5173 [--vhost shop.example.com] [--machine laptop]
+ *   datum previews [--json]
+ *   datum preview trace <id> [--follow] [--limit N]
+ *   datum preview down <id>
+ *
+ * `up` asks the platform for a gateway route to a port of the PERSON's own
+ * machine; the machine's personal satellite then holds the preview link
+ * (#2927) — this process carries no traffic and holds no key or token of the
+ * link. It stays in the foreground, printing the link and the state, and
+ * Ctrl+C closes the preview (`down`). Hand-written because the derived tree
+ * cannot express a foreground loop or a follow: the API is
+ * /api/acc-previews (derived as `datum acc-previews …`, raw).
+ *
+ * A person's only: the routes answer 403 `not-a-person` to an API key — the
+ * hint says to `datum login`.
+ */
+import os from "node:os";
+import { apiSurface, UsageError } from "./invoke.js";
+/** How often `up` and `trace --follow` ask again. */
+export const PREVIEW_POLL_MS = 5_000;
+export const PREVIEW_TRACE_FOLLOW_MS = 2_000;
+/** `up` renews the preview's lease this often (at most a third of the lease). */
+export const PREVIEW_LEASE_RENEW_MS = 60_000;
+/** The lease when the platform did not say (it answers `leaseMs`). */
+const PREVIEW_LEASE_FALLBACK_MS = 3 * 60_000;
+class ApiFailure extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+function client(config, io) {
+    apiSurface(config); // no credentials at all: a usage error before anything runs
+    const fetchImpl = io.fetchImpl ?? fetch;
+    return async (method, path, body) => {
+        const refresh = io.freshToken && !config.apiKey && config.bearerToken;
+        const surface = apiSurface(refresh ? { ...config, bearerToken: await io.freshToken() } : config);
+        const res = await fetchImpl(surface.url(path), {
+            method,
+            headers: { ...surface.headers, ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch {
+            // a non-JSON answer: its status says it
+        }
+        if (!res.ok) {
+            const code = typeof json.code === "string" ? json.code : undefined;
+            const why = typeof json.error === "string" ? json.error : `HTTP ${res.status}`;
+            throw new ApiFailure(res.status, code, why);
+        }
+        return json;
+    };
+}
+/** The probe's word for "the machine has no preview link" — `GATEWAY_PROBE_LINK_DOWN` (accGateway/gatewayProbe.ts),
+ * spelled here because the CLI package ships cli/ alone (scripts/release/cliPackageFiles.mjs); a test pins the two. */
+export const PROBE_LINK_DOWN = "the machine's preview link is down";
+/** The role gate's refusal of a space the caller is no member of — `SPACE_ACCESS_DENIED_CODE` (auth/roleGate.ts),
+ * spelled here so the CLI bundle stays free of the server's Express modules; a test pins the two together. */
+export const SPACE_ACCESS_DENIED = "space_access_denied";
+/** One failure as the person reads it, with what to do. */
+function explain(err, config) {
+    if (err instanceof UsageError)
+        return err.message;
+    if (err instanceof ApiFailure) {
+        if (err.code === "not-a-person" || (err.status === 403 && config.apiKey)) {
+            return `${err.message} — previews from a terminal are yours: unset DATUM_API_KEY and run \`datum login\``;
+        }
+        if (err.code === "feature_disabled")
+            return "the preview gateway is off in this space (Settings → Features → ACC preview gateway)";
+        // Previews live in a space (#2958): without --space the CLI asks the default one, which is often not yours.
+        if (err.code === SPACE_ACCESS_DENIED)
+            return `${err.message} — name the space your previews are in: --space <slug> (or DATUM_SPACE=<slug>)`;
+        return err.message;
+    }
+    return err?.message ?? String(err);
+}
+/**
+ * What `up` reports of a preview (#2958): "ready" only once the app answered through the machine's link — a port
+ * nothing listens on is said at once, and so is a link that went and came back. `key` changes = a line is printed.
+ */
+export function upStateOf(p) {
+    if (p.status !== "provisioned")
+        return { key: p.status, line: p.status };
+    // An older server sends no probe: the route stands, which was all "ready" ever said.
+    if (!p.app)
+        return { key: "ready", line: "ready" };
+    const { status, ms, error } = p.app;
+    if (status > 0 && status < 500)
+        return { key: "ready", line: `ready — the app answers (${status} · ${ms} ms)` };
+    if (status >= 500)
+        return { key: "app-error", line: `the app on port ${p.port} answers with an error (${status}) — visitors see it as it is` };
+    if (error === PROBE_LINK_DOWN) {
+        return { key: "link-down", line: `${p.machine.name} has no preview link to Datum right now — visitors see "Waiting for the machine…"; it comes back by itself once the satellite reconnects` };
+    }
+    return { key: "no-answer", line: `no answer from port ${p.port} on ${p.machine.name}${error ? ` (${error})` : ""} — is the app listening there (127.0.0.1 or ::1)?` };
+}
+const ago = (iso) => (iso ? iso.replace("T", " ").slice(0, 16) + " UTC" : "—");
+function printHeaders(io, headers) {
+    if (!headers)
+        return;
+    io.out.write("  your own requests through the edge send:\n");
+    for (const [k, v] of Object.entries(headers))
+        io.out.write(`    ${k}: ${v}\n`);
+}
+/** `datum preview up --port N [--vhost V] [--machine M]`. */
+export async function runPreviewUp(input, config, io) {
+    const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = io.now ?? (() => Date.now());
+    let call;
+    try {
+        call = client(config, io);
+    }
+    catch (err) {
+        io.err.write(`datum: ${explain(err, config)}\n`);
+        return 2;
+    }
+    let id;
+    let leaseMs = PREVIEW_LEASE_FALLBACK_MS;
+    try {
+        const opened = await call("POST", "/api/acc-previews?wait=0", {
+            port: input.port,
+            ...(input.vhost ? { vhost: input.vhost } : {}),
+            ...(input.machine ? { machine: input.machine } : {}),
+            // Which of your machines this terminal is: an unnamed `up` previews THIS computer only.
+            fromHost: input.fromHost ?? os.hostname(),
+        });
+        if (!opened.preview) {
+            io.err.write(`datum: the preview did not come up${opened.entry?.error ? ` — ${opened.entry.error}` : ""}\n`);
+            return 1;
+        }
+        if (typeof opened.leaseMs === "number" && opened.leaseMs > 0)
+            leaseMs = opened.leaseMs;
+        const p = opened.preview;
+        id = p.id;
+        io.out.write(`Previewing port ${p.port} of ${p.machine.name} through ${p.vhost} (preview ${p.id})\n`);
+        io.out.write(`  open: ${p.link ?? "(no link yet)"}\n`);
+        printHeaders(io, p.testHeaders);
+        io.out.write("  it stands while this command runs — Ctrl+C closes it\n");
+    }
+    catch (err) {
+        io.err.write(`datum: ${explain(err, config)}\n`);
+        return 1;
+    }
+    // Foreground: renew the lease, report state changes and requests the
+    // machine did not answer — until Ctrl+C / SIGHUP / SIGTERM (or the end).
+    let stop = false;
+    void io.interrupted?.then(() => {
+        stop = true;
+    });
+    let last = "";
+    let renewedAt = now();
+    let traceCursor = "";
+    let warnedNoAnswer = false;
+    while (!stop) {
+        try {
+            // The lease (#2941 review): this command is what keeps the port on the edge.
+            if (now() - renewedAt >= Math.min(leaseMs / 3, PREVIEW_LEASE_RENEW_MS)) {
+                try {
+                    await call("POST", `/api/acc-previews/${encodeURIComponent(id)}/lease`);
+                    renewedAt = now();
+                }
+                catch (err) {
+                    if (err instanceof ApiFailure && (err.status === 410 || err.status === 404)) {
+                        io.err.write("datum: the preview's lease is over (it was closed, or this command could not renew it in time) — run datum preview up again\n");
+                        return 1;
+                    }
+                    throw err;
+                }
+            }
+            const { previews } = await call("GET", "/api/acc-previews?wait=1");
+            const p = previews.find((x) => x.id === id);
+            if (!p) {
+                io.err.write("datum: the preview is gone (closed elsewhere)\n");
+                return 1;
+            }
+            // A change of state is a line (#2958): ready only once the app answers, a lost link and its return said as they happen.
+            const state = upStateOf(p);
+            if (state.key !== last) {
+                // "Back" only on evidence: a provisioned preview whose probe no longer says the link is down (#2960 review).
+                const back = last === "link-down" && p.status === "provisioned" && p.app !== undefined && state.key !== "link-down" ? " (the preview link is back)" : "";
+                io.out.write(`  ${new Date(now()).toISOString().slice(11, 19)} ${state.line}${back}\n`);
+                last = state.key;
+            }
+            if (p.status === "expired" || p.status === "error") {
+                io.err.write(`datum: the preview is ${p.status} — run datum preview up again\n`);
+                return 1;
+            }
+            // A request the machine did not answer: nothing listens on the port, or
+            // it is one of the machine's own (the daemon's, a runtime's) — said once.
+            // A server that probes the app (#2958) has said so in the state line already.
+            if (!warnedNoAnswer && !p.app) {
+                const { entries } = await call("GET", `/api/acc-previews/${encodeURIComponent(id)}/trace${traceCursor ? `?after=${traceCursor}` : "?limit=50"}`);
+                if (entries.length > 0)
+                    traceCursor = entries.at(-1).seq;
+                if (entries.some((e) => e.status === 0)) {
+                    warnedNoAnswer = true;
+                    io.err.write(`datum: requests to port ${p.port} get no answer from ${p.machine.name} — is the app listening there (127.0.0.1 or ::1)? A port the machine itself uses (the satellite's own) is refused.\n`);
+                }
+            }
+        }
+        catch (err) {
+            io.err.write(`datum: ${explain(err, config)} — retrying\n`);
+        }
+        await Promise.race([sleep(PREVIEW_POLL_MS), io.interrupted ?? new Promise(() => undefined)]);
+    }
+    return runPreviewDown({ id }, config, io);
+}
+/** `datum preview down <id>`. */
+export async function runPreviewDown(input, config, io) {
+    try {
+        const { closed = [] } = await client(config, io)("DELETE", `/api/acc-previews/${encodeURIComponent(input.id)}`);
+        // The close answers 200 per row; a row that could not be taken down still stands.
+        const failed = closed.filter((c) => c.state === "failed");
+        if (failed.length > 0) {
+            for (const f of failed)
+                io.err.write(`datum: preview ${input.id} (${f.vhost}) could not be closed: ${f.error ?? "unknown error"} — try datum preview down ${input.id}\n`);
+            return 1;
+        }
+        io.out.write(`Closed preview ${input.id}\n`);
+        return 0;
+    }
+    catch (err) {
+        io.err.write(`datum: ${explain(err, config)}\n`);
+        return 1;
+    }
+}
+/** `datum previews [--json]` — the gateway's `cde interfaces`. */
+export async function runPreviewsList(input, config, io) {
+    try {
+        const answer = await client(config, io)("GET", "/api/acc-previews");
+        if (input.json) {
+            io.out.write(`${JSON.stringify(answer, null, 2)}\n`);
+            return 0;
+        }
+        if (answer.previews.length === 0) {
+            io.out.write("No previews on your machines. Start one: datum preview up --port <port>\n");
+        }
+        else {
+            const rows = answer.previews.map((p) => [p.id, p.vhost, p.machine.name, String(p.port), p.status === "provisioned" ? "ready" : p.status, p.owner.mine ? "you" : p.owner.kind, ago(p.expiresAt), p.link ?? "—"]);
+            const head = ["ID", "VHOST", "MACHINE", "PORT", "STATE", "OWNER", "EXPIRES", "LINK"];
+            const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+            for (const r of [head, ...rows])
+                io.out.write(`${r.map((c, i) => (i === r.length - 1 ? c : c.padEnd(widths[i]))).join("  ")}\n`);
+        }
+        const machines = answer.machines.map((m) => `${m.name} (${m.connected ? "online" : "offline"}${m.previewLink ? "" : ", no preview link — upgrade the satellite"})`);
+        io.out.write(`Your machines here: ${machines.join(", ") || "none — pair this computer: datum satellite up --pair"}\n`);
+        return 0;
+    }
+    catch (err) {
+        io.err.write(`datum: ${explain(err, config)}\n`);
+        return 1;
+    }
+}
+/** One trace line: time, method, path, status, timing, size. */
+export function traceLine(e) {
+    const size = e.bytesOut >= 1024 * 1024 ? `${(e.bytesOut / 1024 / 1024).toFixed(1)} MB` : e.bytesOut >= 1024 ? `${(e.bytesOut / 1024).toFixed(1)} KB` : `${e.bytesOut} B`;
+    const status = e.status === 0 ? "no answer" : String(e.status);
+    return `${e.at.slice(11, 23)}  ${(e.websocket ? "WS" : e.method).padEnd(6)} ${e.path}  → ${status}  ${e.ms} ms  ${size}`;
+}
+/** `datum preview trace <id> [--follow] [--limit N]` — the gateway's `cde trace`. */
+export async function runPreviewTrace(input, config, io) {
+    const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let call;
+    try {
+        call = client(config, io);
+    }
+    catch (err) {
+        io.err.write(`datum: ${explain(err, config)}\n`);
+        return 2;
+    }
+    const base = `/api/acc-previews/${encodeURIComponent(input.id)}/trace`;
+    let after = "";
+    let stop = false;
+    let read = false;
+    void io.interrupted?.then(() => {
+        stop = true;
+    });
+    do {
+        try {
+            const query = after ? `?after=${encodeURIComponent(after)}` : `?limit=${input.limit ?? 50}`;
+            const { entries } = await call("GET", `${base}${query}`);
+            read = true;
+            for (const e of entries)
+                io.out.write(`${traceLine(e)}\n`);
+            // The cursor is the insert order, never a time: a replica writes its batch late (#2941 review).
+            if (entries.length > 0)
+                after = entries.at(-1).seq;
+            else if (!input.follow && !after)
+                io.out.write("No requests yet.\n");
+        }
+        catch (err) {
+            // A closed preview takes its trace with it: a follow that read it before says so (#2948).
+            if (read && err instanceof ApiFailure && err.status === 404) {
+                io.out.write(`Preview ${input.id} was closed — the trace ends.\n`);
+                return 0;
+            }
+            io.err.write(`datum: ${explain(err, config)}\n`);
+            return 1;
+        }
+        if (!input.follow)
+            break;
+        await Promise.race([sleep(PREVIEW_TRACE_FOLLOW_MS), io.interrupted ?? new Promise(() => undefined)]);
+    } while (!stop);
+    return 0;
+}
+/** Ctrl+C / SIGTERM as a promise (the real terminal's `interrupted`). */
+export function interruptedBySignal() {
+    // SIGHUP too (#2941 review): a closed terminal window ends `up` cleanly — its preview closed, not left to its lease.
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    return new Promise((resolve) => {
+        const done = () => {
+            for (const s of signals)
+                process.off(s, done);
+            resolve();
+        };
+        for (const s of signals)
+            process.once(s, done);
+    });
+}
+//# sourceMappingURL=previewCommand.js.map

package/cli/satellitePairToken.js

@@ -0,0 +1,48 @@
+/**
+ * `datum satellite up --pair <token>` (#2948): the launcher waits for the daemon it starts, so a token
+ * on either command line stays readable in `ps` for the daemon's whole life. The launcher takes it OUT
+ * of the arguments and hands it over in the daemon's environment (the daemon reads
+ * PAIR_TOKEN_ENV since 0.21.2); its own title drops it too.
+ */
+/** The daemon's variable for the one-time pairing token (satellite/src/pair.ts PAIR_TOKEN_ENV). */
+export const SATELLITE_PAIR_TOKEN_ENV = "DATUM_SATELLITE_PAIR_TOKEN";
+/** The first daemon that reads it (and answers `satellite --version`). */
+export const SATELLITE_PAIR_TOKEN_ENV_SINCE = "0.21.2";
+/** Does the daemon that answered `satellite --version` with `output` read the token from the
+ * environment? An older one prints its usage (no version) — it gets the flag, as before (#2949 review). */
+export function daemonReadsPairTokenEnv(output) {
+    const m = /^(\d+)\.(\d+)\.(\d+)\s*$/.exec(output.trim());
+    if (!m)
+        return false;
+    const [have, need] = [m.slice(1).map(Number), SATELLITE_PAIR_TOKEN_ENV_SINCE.split(".").map(Number)];
+    for (let i = 0; i < 3; i++)
+        if (have[i] !== need[i])
+            return have[i] > need[i];
+    return true;
+}
+/** The arguments without `--pair <token>` / `--pair=<token>`, and the token (null = none given). */
+export function pairTokenOutOfArgs(args) {
+    const out = [];
+    let token = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--pair" && i + 1 < args.length) {
+            token = args[++i];
+            continue;
+        }
+        if (a.startsWith("--pair=")) {
+            token = a.slice("--pair=".length);
+            continue;
+        }
+        out.push(a);
+    }
+    return { args: out, token };
+}
+/** The launcher's own title with the token masked (`ps` shows the title once it is set). */
+export function maskedTitle(argv, token) {
+    return argv
+        .slice(1)
+        .map((a) => (a === token ? "***" : a.endsWith(`=${token}`) ? `${a.slice(0, a.length - token.length)}***` : a))
+        .join(" ");
+}
+//# sourceMappingURL=satellitePairToken.js.map

package/cli/secureOrigin.js

@@ -0,0 +1,37 @@
+/**
+ * Which servers the CLI hands a credential to (#2605).
+ *
+ * A sign-in token or an API key travels in the `authorization` header of
+ * every call. Over plain http anybody on the path reads it, so the CLI
+ * sends one only to an https:// origin — or to a loopback host, the local
+ * dev stack and the pod-local API an agent run talks to, where the path is
+ * this machine.
+ */
+/** `1` lifts the refusal for this process — a dev stack on a private network. */
+export const ENV_ALLOW_INSECURE_HTTP = "DATUM_ALLOW_INSECURE_HTTP";
+export function isLoopbackHost(hostname) {
+    return ["localhost", "127.0.0.1", "[::1]"].includes(hostname);
+}
+/**
+ * Why `baseUrl` must not receive a credential — null when it may. An
+ * unparsable URL is not judged here: the caller's own "not a valid URL"
+ * names that problem better.
+ */
+export function insecureOriginReason(baseUrl, env = process.env) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol === "https:")
+        return null;
+    if (url.protocol === "http:" && isLoopbackHost(url.hostname))
+        return null;
+    if (env[ENV_ALLOW_INSECURE_HTTP]?.trim() === "1")
+        return null;
+    return (`refusing to send credentials to ${url.origin} — the CLI signs in and sends tokens or API keys only over https:// ` +
+        `(or to a loopback http:// host). Use the server's https:// address; ${ENV_ALLOW_INSECURE_HTTP}=1 lifts this for a private dev stack.`);
+}
+//# sourceMappingURL=secureOrigin.js.map