@datumos/datum-cli 0.0.0 → 0.588.0

package/cli/mcpServe.js

@@ -0,0 +1,361 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { runArtifactsPublish } from "./artifactsPublish.js";
+import { LoginFlowError, NotLoggedInError, deviceLogin, ensureAccessToken, spaceBaseUrl, } from "./entraLogin.js";
+/**
+ * `datum mcp serve` — the stdio shim between a developer's Claude Code and
+ * Datum's person MCP endpoint (docs/developer-access.md, #327). Claude Code
+ * starts this process (the plugin's `.mcp.json` declares it), speaks MCP
+ * over stdio, and every `tools/list` / `tools/call` is forwarded 1:1 to
+ * `POST <space host>/api/mcp` with the person's Entra access token — the
+ * token the CLI holds, refreshed here, never seen by the model.
+ *
+ * Why a shim and not a remote HTTP server in `.mcp.json`: the MCP client's
+ * own OAuth expects dynamic client registration, which Entra has none of;
+ * the CLI already owns the device-code sign-in, so it owns the credential
+ * on this side too (issue #327 mini-FAQ).
+ *
+ * Not signed in yet? The shim exposes ONE tool, `datum_login`, whose result
+ * carries the verification URL and user code — the model relays them, the
+ * person signs in in a browser, the shim polls, stores the tokens and sends
+ * `tools/list_changed` so Claude Code re-lists and finds the real tools.
+ * Nothing about this flow lets the model choose a destination: the IdP
+ * endpoints come from the server, the space from the process arguments.
+ */
+export const SHIM_NAME = "datum-mcp-shim";
+export const LOGIN_TOOL = "datum_login";
+export const STATUS_TOOL = "datum_status";
+/**
+ * `datum_publish_artifact` (#645) — the shim's own publish tool, and the
+ * only one whose bytes never enter the conversation.
+ *
+ * The server's `artifact_publish` takes the page as tool ARGUMENTS, so its
+ * content is charged as input tokens on every turn that follows; on
+ * 2026-09-08 one large page cost a session its whole context window. This
+ * tool takes a DIRECTORY PATH instead: the shim runs on the person's
+ * machine, so it reads the files itself, hashes them and hands them to the
+ * same transport `datum artifacts publish` uses — presigned PUTs straight
+ * to storage for anything over the inline body cap. The model sees a path
+ * and a result, never the bytes.
+ *
+ * The path is not a free hand into the filesystem: it is resolved against
+ * ONE root — the directory the shim was started in (Claude Code starts it
+ * in the project), or `DATUM_PUBLISH_ROOT` when the person sets one — and a
+ * directory outside it is refused. The model may name a path; it may not
+ * choose the tree (security-invariants.md I1, the same reason a transport
+ * pins a reply's destination).
+ */
+export const PUBLISH_ARTIFACT_TOOL = "datum_publish_artifact";
+/** Env var by which a person widens the publishable root beyond the cwd. */
+export const PUBLISH_ROOT_ENV = "DATUM_PUBLISH_ROOT";
+const text = (t, isError = false) => ({
+    content: [{ type: "text", text: t }],
+    ...(isError ? { isError: true } : {}),
+});
+/**
+ * Is `candidate` the root itself or something under it? Both paths must be
+ * already resolved (symlinks included) — a link is how a directory outside
+ * the root would otherwise present itself as inside (#645).
+ */
+export function isInsideRoot(candidate, root) {
+    const rel = path.relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * The publishable directory, or the reason it is refused (#645). Resolves
+ * symlinks on both sides, so neither a link inside the root nor a `..`
+ * escapes it, and reports what a person can do about it.
+ */
+export async function resolvePublishDir(dir, root) {
+    let realRoot;
+    try {
+        realRoot = await fsp.realpath(root);
+    }
+    catch {
+        return { ok: false, reason: `the publish root ${root} does not exist — set ${PUBLISH_ROOT_ENV} to a directory that does` };
+    }
+    const target = path.resolve(realRoot, dir);
+    let realTarget;
+    try {
+        realTarget = await fsp.realpath(target);
+    }
+    catch {
+        return { ok: false, reason: `${target} does not exist — write the page and its assets to a directory first, then publish that directory` };
+    }
+    if (!isInsideRoot(realTarget, realRoot)) {
+        return {
+            ok: false,
+            reason: `${realTarget} is outside the publishable tree (${realRoot}) — this tool publishes only from there, so a page cannot ` +
+                `carry files the person did not put in the project. Copy what should be published into a directory under ${realRoot}, ` +
+                `or ask the person to restart the connection with ${PUBLISH_ROOT_ENV} pointing where they want it.`,
+        };
+    }
+    const stat = await fsp.stat(realTarget).catch(() => null);
+    if (!stat?.isDirectory())
+        return { ok: false, reason: `${realTarget} is not a directory — publish the DIRECTORY holding the page and its assets` };
+    return { ok: true, dir: realTarget };
+}
+/** A sink for the publish command's two streams (it writes lines, nothing else). */
+function collector() {
+    const chunks = [];
+    return {
+        stream: { write: (chunk) => (chunks.push(String(chunk)), true) },
+        text: () => chunks.join("").trim(),
+    };
+}
+/** The shim's server half — exported so tests drive it over an in-memory
+ * transport pair instead of stdio. */
+export function createShimServer(opts) {
+    const io = opts.io ?? {};
+    const log = opts.log ?? ((line) => console.error(`[datum mcp] ${line}`));
+    const doFetch = io.fetchImpl ?? fetch;
+    const apiBase = opts.space ? spaceBaseUrl(opts.baseUrl, opts.space) : new URL(opts.baseUrl).origin;
+    const endpoint = new URL(`${apiBase}/api/mcp`);
+    // The one tree `datum_publish_artifact` may read (#645) — the person's
+    // choice, made when they start the connection, never the model's.
+    const publishRoot = opts.publishRoot ?? process.env[PUBLISH_ROOT_ENV] ?? process.cwd();
+    const server = new Server({ name: SHIM_NAME, version: opts.version }, { capabilities: { tools: { listChanged: true } } });
+    let upstream = null;
+    let pendingLogin = null;
+    let lastUpstreamError = "";
+    /** A connected upstream client — lazily, and only with a token in hand. */
+    const connectUpstream = async () => {
+        if (upstream)
+            return upstream;
+        // Token freshness is per request: the transport's fetch re-reads it.
+        await ensureAccessToken(opts.baseUrl, opts.store, io);
+        const client = new Client({ name: SHIM_NAME, version: opts.version });
+        const transport = new StreamableHTTPClientTransport(endpoint, {
+            fetch: async (url, init) => {
+                const token = await ensureAccessToken(opts.baseUrl, opts.store, io);
+                const headers = new Headers(init?.headers);
+                headers.set("authorization", `Bearer ${token}`);
+                return doFetch(url, { ...init, headers });
+            },
+        });
+        await client.connect(transport);
+        upstream = client;
+        log(`connected to ${endpoint}`);
+        return client;
+    };
+    const dropUpstream = async () => {
+        const c = upstream;
+        upstream = null;
+        await c?.close().catch(() => undefined);
+    };
+    /** Turns an upstream failure into what the developer should do. */
+    const explain = (err) => {
+        if (err instanceof NotLoggedInError || err instanceof LoginFlowError)
+            return err.message;
+        const message = err instanceof Error ? err.message : String(err);
+        if (/401/.test(message))
+            return `Datum rejected the sign-in (${message}) — run \`datum login\` again`;
+        if (/403/.test(message)) {
+            return `Datum answered 403 at ${endpoint} — developer access is off for this space (a space admin enables it in Settings → Features), or you have no access to the space`;
+        }
+        if (/404/.test(message))
+            return `no MCP endpoint at ${endpoint} — is the base URL right and is this Datum new enough for developer access?`;
+        return `Datum is unreachable at ${endpoint}: ${message}`;
+    };
+    const loginTool = (why) => ({
+        name: LOGIN_TOOL,
+        description: `Sign in to Datum (${new URL(opts.baseUrl).origin}) with your Microsoft account so Datum's tools appear here. ` +
+            `${why} ` +
+            "The result carries a URL and a code: show BOTH to the user verbatim and ask them to complete the sign-in in a browser; " +
+            "the tools list refreshes by itself once they do.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    });
+    const statusTool = () => ({
+        name: STATUS_TOOL,
+        description: "Sign-in status of this Datum connection (who, where, whether a sign-in is pending).",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    });
+    const publishArtifactTool = () => ({
+        name: PUBLISH_ARTIFACT_TOOL,
+        description: "Publish a page as an ARTIFACT of this Datum space FROM DISK: you give the path of a directory, this tool reads the " +
+            "files itself and uploads them straight to storage. USE THIS, NOT `artifact_publish`, for anything but a tiny text page — " +
+            "and always for images, PDFs or any binary file. Content passed as tool arguments is charged as input tokens on every " +
+            "later turn, so publishing a big page that way costs the session its context window; this tool costs a path. " +
+            "Write the page (index.html or a single .html/.md) plus the assets it references into a directory under the project, " +
+            "then publish that directory. Dotfiles, `node_modules`, symlinks and empty files are never published; at most 200 files. " +
+            "Reuse the same `key` to append a version to an existing artifact. Who may open the page is decided by people in the " +
+            "panel, never here. Never put secrets into a page.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                dir: {
+                    type: "string",
+                    description: "Directory holding the page and its assets — relative to the project the connection was started in, or an " +
+                        "absolute path inside it. A directory outside that tree is refused.",
+                },
+                key: {
+                    type: "string",
+                    description: "Stable artifact identity within the space (letters, digits, `. _ : / -`). Same key = new version of the same " +
+                        "artifact. Required unless the directory holds a manifest.json that carries one.",
+                },
+                title: { type: "string", description: "Title shown in the panel (default: the page's <title> / first heading / file name)." },
+                description: { type: "string", description: "One-paragraph description of the artifact." },
+                entry: { type: "string", description: "Which file is THE page when several are pages (default: index.html or the only page)." },
+            },
+            required: ["dir"],
+            additionalProperties: false,
+        },
+        annotations: { title: "Publish an artifact from disk", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    });
+    const publishArtifact = async (args) => {
+        const str = (value) => (typeof value === "string" && value.length > 0 ? value : undefined);
+        const dir = str(args.dir);
+        if (!dir) {
+            return text(`${PUBLISH_ARTIFACT_TOOL} needs \`dir\` — the directory holding the page and the assets it references.`, true);
+        }
+        const resolved = await resolvePublishDir(dir, publishRoot);
+        if (!resolved.ok)
+            return text(`${PUBLISH_ARTIFACT_TOOL} refused — ${resolved.reason}`, true);
+        let token;
+        try {
+            token = await ensureAccessToken(opts.baseUrl, opts.store, io);
+        }
+        catch (err) {
+            lastUpstreamError = explain(err);
+            return text(lastUpstreamError, true);
+        }
+        const out = collector();
+        const errOut = collector();
+        try {
+            const code = await runArtifactsPublish({
+                dir: resolved.dir,
+                ...(str(args.key) !== undefined ? { key: str(args.key) } : {}),
+                ...(str(args.title) !== undefined ? { title: str(args.title) } : {}),
+                ...(str(args.description) !== undefined ? { description: str(args.description) } : {}),
+                ...(str(args.entry) !== undefined ? { entry: str(args.entry) } : {}),
+            }, { baseUrl: apiBase, bearerToken: token }, { out: out.stream, err: errOut.stream, ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}) });
+            const report = [out.text(), errOut.text()].filter((part) => part.length > 0).join("\n");
+            if (code === 0) {
+                log(`published ${resolved.dir}`);
+                return text(report || "published");
+            }
+            return text(report || `${PUBLISH_ARTIFACT_TOOL} failed (exit ${code})`, true);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log(`publish failed: ${message}`);
+            return text(`${PUBLISH_ARTIFACT_TOOL} failed — ${message}`, true);
+        }
+    };
+    const startLogin = async () => {
+        if (pendingLogin && Date.now() < pendingLogin.device.expiresAt) {
+            const d = pendingLogin.device;
+            return text(`A sign-in is already pending. Open ${d.verificationUriComplete ?? d.verificationUri} and enter the code ${d.userCode} (valid until ${new Date(d.expiresAt).toLocaleTimeString()}).`);
+        }
+        let shown = null;
+        const codeShown = new Promise((resolve) => {
+            // Runs the moment the IdP hands out the code; the poll continues in
+            // the background and the tool call returns right away.
+            void deviceLogin(opts.baseUrl, opts.store, (device) => {
+                shown = device;
+                pendingLogin = { device, startedAt: Date.now() };
+                resolve(device);
+            }, io)
+                .then(async (login) => {
+                pendingLogin = null;
+                log(`signed in as ${login.account}`);
+                await dropUpstream();
+                await server.sendToolListChanged().catch(() => undefined);
+            })
+                .catch((err) => {
+                pendingLogin = null;
+                lastUpstreamError = explain(err);
+                log(`sign-in failed: ${lastUpstreamError}`);
+                if (!shown)
+                    resolve({ deviceCode: "", userCode: "", verificationUri: "", expiresAt: 0, intervalMs: 0 });
+            });
+        });
+        const device = await codeShown;
+        if (!device.userCode)
+            return text(`Sign-in could not start: ${lastUpstreamError}`, true);
+        return text(`To sign in to Datum, open ${device.verificationUriComplete ?? device.verificationUri} and enter the code ${device.userCode} ` +
+            `(valid for about ${Math.max(1, Math.round((device.expiresAt - Date.now()) / 60000))} minutes). ` +
+            "Tell the user the URL and the code exactly as written. Once they finish, Datum's tools appear in this server — re-list the tools before using them.");
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const login = opts.store.get(opts.baseUrl);
+        if (!login) {
+            return { tools: [loginTool("You are not signed in yet."), statusTool()] };
+        }
+        try {
+            const client = await connectUpstream();
+            const listed = await client.listTools();
+            lastUpstreamError = "";
+            // The disk-side publish tool rides next to the server's tools (#645):
+            // it is the shim's own, because only this side can read the files.
+            return { tools: [...listed.tools, statusTool(), publishArtifactTool()] };
+        }
+        catch (err) {
+            lastUpstreamError = explain(err);
+            log(`tools/list failed: ${lastUpstreamError}`);
+            await dropUpstream();
+            const needsLogin = err instanceof NotLoggedInError || err instanceof LoginFlowError || /401/.test(String(err));
+            return {
+                tools: needsLogin
+                    ? [loginTool(`The previous sign-in no longer works: ${lastUpstreamError}`), statusTool()]
+                    : [statusTool()],
+            };
+        }
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === LOGIN_TOOL)
+            return startLogin();
+        if (name === PUBLISH_ARTIFACT_TOOL)
+            return publishArtifact(args ?? {});
+        if (name === STATUS_TOOL) {
+            const login = opts.store.get(opts.baseUrl);
+            return text(JSON.stringify({
+                endpoint: endpoint.toString(),
+                signedIn: Boolean(login),
+                account: login?.account ?? null,
+                tokenExpiresAt: login ? new Date(login.expiresAt).toISOString() : null,
+                pendingSignIn: pendingLogin ? { code: pendingLogin.device.userCode, url: pendingLogin.device.verificationUri } : null,
+                lastError: lastUpstreamError || null,
+                credentials: opts.store.path,
+            }, null, 2));
+        }
+        try {
+            const client = await connectUpstream();
+            const result = await client.callTool({ name, arguments: args ?? {} });
+            return result;
+        }
+        catch (err) {
+            lastUpstreamError = explain(err);
+            log(`tools/call ${name} failed: ${lastUpstreamError}`);
+            await dropUpstream();
+            return text(lastUpstreamError, true);
+        }
+    });
+    return {
+        server,
+        close: async () => {
+            await dropUpstream();
+            await server.close().catch(() => undefined);
+        },
+    };
+}
+/** The command: serve over stdio until Claude Code closes the pipe. */
+export async function runMcpServe(opts) {
+    const shim = createShimServer(opts);
+    const transport = new StdioServerTransport();
+    await shim.server.connect(transport);
+    (opts.log ?? ((line) => console.error(`[datum mcp] ${line}`)))(`serving Datum tools of ${opts.space ? `space ${opts.space}` : "the org host"} at ${new URL(opts.baseUrl).origin} over stdio`);
+    await new Promise((resolve) => {
+        transport.onclose = () => resolve();
+        process.stdin.once("end", () => resolve());
+    });
+    await shim.close();
+    return 0;
+}
+//# sourceMappingURL=mcpServe.js.map

package/cli/outputsDownload.js

@@ -0,0 +1,126 @@
+/**
+ * `datum outputs download <id> [--out <file>]` — an output's BYTES (#2680).
+ *
+ * Hand-written because the bytes do not live under /api: the metadata is
+ * `GET /api/outputs/{id}` (derived as `datum outputs get`), the file is
+ * `GET /outputs/{id}/{name}` on the origin — the gated byte surface that
+ * authenticates the same credential as /api (#570), with no `/public`
+ * prefix for a key. It is how a run fetches a file an earlier run made
+ * without building a raw request (skill `platform-api`): the CLI talks to
+ * the platform's own origin only, and the credential never leaves it.
+ *
+ * The bytes are streamed into a temporary file while they are counted and
+ * hashed — never buffered (an output may be hundreds of MiB) — and the
+ * transfer stops as soon as it runs past the recorded size. Only a file
+ * whose size and sha256 match the metadata is renamed to `--out` or
+ * copied to stdout; a half-written or wrong file never lands anywhere.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { apiSurface, UsageError, X_OA_VARIANT_HEADER } from "./invoke.js";
+/** The byte route outside /api (outputs.interfaces.ts OUTPUTS_DOWNLOAD_PREFIX). */
+export const OUTPUTS_BYTES_PREFIX = "/outputs";
+export async function runOutputsDownload(input, config, io) {
+    const fetchImpl = io.fetchImpl ?? fetch;
+    let surface;
+    try {
+        surface = apiSurface(config);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            io.err.write(`datum: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    const id = input.id.trim();
+    const metaRes = await fetchImpl(surface.url(`/api/outputs/${encodeURIComponent(id)}`), { headers: surface.headers });
+    if (!metaRes.ok) {
+        io.err.write(`datum: output ${id}: ${metaRes.status} ${await failureText(metaRes)}\n`);
+        return 1;
+    }
+    const meta = (await metaRes.json());
+    // The bytes: the origin's own route, never /public (the key authenticates
+    // there exactly as on /api).
+    const origin = config.baseUrl.replace(/\/+$/, "");
+    const bytesRes = await fetchImpl(`${origin}${OUTPUTS_BYTES_PREFIX}/${encodeURIComponent(meta.id)}/${encodeURIComponent(meta.name)}`, {
+        headers: {
+            authorization: surface.headers.authorization,
+            ...(surface.headers[X_OA_VARIANT_HEADER] ? { [X_OA_VARIANT_HEADER]: surface.headers[X_OA_VARIANT_HEADER] } : {}),
+        },
+    });
+    if (!bytesRes.ok) {
+        io.err.write(`datum: download ${meta.name}: ${bytesRes.status} ${await failureText(bytesRes)}\n`);
+        return 1;
+    }
+    // A fresh private directory beside the target (a rename never crosses
+    // filesystems), or under the temp directory when the bytes go to stdout:
+    // an unpredictable path, owner-only, the file created exclusively — no
+    // symlink can be followed and nobody else reads the bytes meanwhile.
+    const target = input.out ? path.resolve(input.out) : null;
+    const staging = await fsp.mkdtemp(path.join(target ? path.dirname(target) : os.tmpdir(), ".datum-download-"));
+    const partial = path.join(staging, "bytes");
+    try {
+        const hash = createHash("sha256");
+        let received = 0;
+        const meter = new Transform({
+            transform(chunk, _enc, done) {
+                received += chunk.length;
+                // Past the recorded size it is not this output: stop at once.
+                if (received > meta.size) {
+                    done(new DamagedError(received));
+                    return;
+                }
+                hash.update(chunk);
+                done(null, chunk);
+            },
+        });
+        if (!bytesRes.body)
+            throw new DamagedError(0);
+        await pipeline(Readable.fromWeb(bytesRes.body), meter, createWriteStream(partial, { flags: "wx", mode: 0o600 }));
+        const sha256 = hash.digest("hex");
+        if (received !== meta.size || sha256 !== meta.sha256)
+            throw new DamagedError(received, sha256);
+        if (!target) {
+            await pipeline(createReadStream(partial), io.out, { end: false });
+            return 0;
+        }
+        await fsp.rename(partial, target);
+        io.err.write(`datum: ${meta.name} → ${input.out} (${received} bytes)\n`);
+        return 0;
+    }
+    catch (err) {
+        if (!(err instanceof DamagedError))
+            throw err;
+        io.err.write(`datum: ${meta.name} arrived damaged (${err.received} bytes${err.sha256 ? `, sha256 ${err.sha256.slice(0, 12)}…` : " or more"}; expected ${meta.size} bytes, ${meta.sha256.slice(0, 12)}…) — nothing written\n`);
+        return 1;
+    }
+    finally {
+        await fsp.rm(staging, { recursive: true, force: true });
+    }
+}
+/** The bytes do not match the output's metadata. */
+class DamagedError extends Error {
+    received;
+    sha256;
+    constructor(received, sha256 = "") {
+        super("damaged download");
+        this.received = received;
+        this.sha256 = sha256;
+    }
+}
+async function failureText(res) {
+    try {
+        const body = (await res.json());
+        return typeof body.error === "string" ? body.error : res.statusText;
+    }
+    catch {
+        return res.statusText;
+    }
+}
+//# sourceMappingURL=outputsDownload.js.map