@datumos/datum-cli 0.0.0 → 0.588.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+Datum CLI
+Copyright 2026 Ringier Axel Springer Polska sp. z o.o.
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+"Datum" and "DatumOS" are trademarks of their owner. The license grants no
+right to use them, except as required to describe the origin of this
+software (Apache License 2.0, section 6).

package/README.md

@@ -0,0 +1,37 @@
+# datum
+
+Official command-line client of the [Datum](https://datumos.ai) API. Every
+command, flag and `--help` page is derived from the platform's OpenAPI
+contract — the package version equals the platform (and therefore API)
+release it was built from.
+
+```bash
+npm install -g @datumos/datum-cli
+datum login --base-url https://<your-datum-host>   # sign in with your organisation account
+datum whoami
+datum --help
+datum mcp serve --space <slug>   # stdio MCP server for Claude Code
+```
+
+You need access to a Datum instance — the CLI is a client, it does not
+contain the platform. Integrations use an API key instead of a sign-in
+(`DATUM_API_KEY`, panel: Settings → API keys); with a key every call goes
+through the public API surface.
+
+## Updates
+
+The CLI keeps itself on the version of the server it talks to: it
+downloads the server's CLI bundle and installs it only when the bundle
+carries a signature that chains to the Datum release key pinned in this
+package. `datum update --check` shows what it would do,
+`DATUM_AUTOUPDATE=off` turns it off.
+
+## Security
+
+Credentials are sent only over `https://` (or to a loopback host). Report
+a vulnerability to support@datumos.ai — please do not open a public issue.
+
+## License
+
+Apache-2.0 — see `LICENSE` and `NOTICE`. `Datum` and `DatumOS` are
+trademarks; the license does not grant rights to them.

package/cli/a2aCommand.js

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { originOf } from "./credentials.js";
+import { LoginFlowError, NotLoggedInError, ensureAccessToken, spaceBaseUrl } from "./entraLogin.js";
+/**
+ * `datum a2a [--space <slug>] [--agent <nick>] <a2a args…>` (#1382,
+ * docs/a2a.md): the official `a2a` CLI against a space's A2A channel, signed
+ * in as the person — without the token ever leaving this process tree. The
+ * model driving a terminal never sees the credential (I3) and never chooses
+ * where it goes (I1): the
+ * CLI pins the destination to the space host the sign-in addresses and
+ * injects the bearer into the child's environment only.
+ *
+ * Pinning, against everything `a2a` would otherwise read:
+ *  - `-a <space host>` as an explicit flag — flags beat the environment and
+ *    every configuration file (a2a-cli "Precedence"); with `--agent <nick>`
+ *    (#1647) the full card URL of that agent on the same host instead;
+ *  - `--config <empty file>` in place of the nearest `.env` walking up from
+ *    the working directory — a repository's `.env` (untrusted input) cannot
+ *    add an endpoint, headers or a tenant;
+ *  - `--transport rest,jsonrpc` — the built-in bindings only: a named
+ *    transport would make a2a launch `a2a-transport-<name>` from PATH with
+ *    the bearer in its environment;
+ *  - the inherited `A2ACLI_*` variables are dropped, the bearer set;
+ *  - the client is `a2a` on PATH — no override of the binary;
+ *  - only the delegating verbs pass (`card`, `send`, `task`), never flags
+ *    that name a destination or a credential, never a card URL of its own.
+ */
+/** The `a2a` verbs a person delegates with — `server`, `plugin`, `config`
+ * and the rest stay out of reach of the injected credential. */
+export const A2A_ALLOWED_COMMANDS = ["card", "send", "task", "version", "help"];
+/** Flags that would move the destination or the credential. */
+const PINNED_FLAGS = [
+    "-a",
+    "--agent-card",
+    "-e",
+    "--endpoint",
+    "--auth",
+    "--svc-param",
+    "--config",
+    "--tenant",
+    "--insecure",
+    // a2a launches `a2a-transport-<name>` from PATH for a non-built-in
+    // transport — with the bearer in its environment. Only the built-ins run.
+    "--transport",
+];
+/** The built-in bindings the channel serves (the card lists HTTP+JSON first). */
+const PINNED_TRANSPORT = "rest,jsonrpc";
+export class A2aUsageError extends Error {
+}
+/** An agent's nick as the per-agent A2A routes take it (#1647) — a single
+ * path segment, so it can never step off `/a2a/agents/` on the space host. */
+const AGENT_NICK = /^[a-z0-9][a-z0-9._-]{1,63}$/i;
+/** The env default of `--agent`, as DATUM_SPACE is the default of `--space`. */
+export const A2A_AGENT_ENV = "DATUM_A2A_AGENT";
+/**
+ * Pulls datum's own `--agent <nick>` (or `--agent=<nick>`) out of the a2a
+ * args — it is never passed to the child — falling back to
+ * `DATUM_A2A_AGENT`. Everything after `--` is a positional and stays. Pure,
+ * tested.
+ */
+export function a2aAgentOf(args, env) {
+    let agent = env[A2A_AGENT_ENV] || undefined;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--") {
+            rest.push(...args.slice(i));
+            break;
+        }
+        if (arg === "--agent" || arg.startsWith("--agent=")) {
+            const value = arg === "--agent" ? args[++i] : arg.slice("--agent=".length);
+            if (value === undefined || value.startsWith("-"))
+                throw new A2aUsageError("--agent needs a value — the agent's nick");
+            agent = value;
+            continue;
+        }
+        rest.push(arg);
+    }
+    if (agent !== undefined && !AGENT_NICK.test(agent)) {
+        throw new A2aUsageError(`--agent ${JSON.stringify(agent)} is not an agent nick (letters, digits, ".", "_", "-"; 2–64 characters)`);
+    }
+    return { agent, rest };
+}
+/**
+ * What `-a` pins: the space host (its default agent), or with an agent the
+ * full URL of that agent's card on the same host — a2a-cli reads an `-a`
+ * value with a path as the card URL itself.
+ */
+export function a2aTarget(spaceBase, agent) {
+    return agent ? `${spaceBase}/a2a/agents/${agent}/.well-known/agent-card.json` : spaceBase;
+}
+/** The child's argv, or the reason the call is refused. Pure, tested. */
+export function a2aArgs(args, target, configPath) {
+    // The verb comes first: a value of a global flag placed before it would
+    // otherwise read as the verb.
+    const command = args[0];
+    if (!command || command.startsWith("-")) {
+        throw new A2aUsageError("usage: datum a2a <card get | send \"…\" | task get|list|cancel …> [a2a flags] [--space <slug>] [--agent <nick>]");
+    }
+    if (!A2A_ALLOWED_COMMANDS.includes(command)) {
+        throw new A2aUsageError(`datum a2a runs only ${A2A_ALLOWED_COMMANDS.join(", ")} — "${command}" is not delegated through your sign-in`);
+    }
+    for (const arg of args) {
+        // After `--` everything is a positional (pflag stops parsing flags).
+        if (arg === "--")
+            break;
+        // Short options only one at a time and never with an attached value:
+        // pflag reads `-ahttps://evil.example` (or `-va…`) as `-a <value>`,
+        // which would move the destination past the check below.
+        if (/^-[^-]/.test(arg) && arg.length > 2) {
+            throw new A2aUsageError(`${arg}: pass short options one at a time, value as the next argument (e.g. "-o json")`);
+        }
+        const flag = arg.split("=")[0];
+        if (PINNED_FLAGS.includes(flag)) {
+            throw new A2aUsageError(`${flag} is set by datum: the destination is the space host of your sign-in and the credential is yours`);
+        }
+    }
+    // `card get [url]`: a positional would fetch — and authenticate to — a
+    // card of the caller's choosing.
+    if (command === "card" && args.slice(2).some((a) => !a.startsWith("-"))) {
+        throw new A2aUsageError("datum a2a card get takes no card URL — it reads the card of the space host");
+    }
+    return ["--config", configPath, "-a", target, "--transport", PINNED_TRANSPORT, ...args];
+}
+/** The child's environment: the caller's, minus every `A2ACLI_*`, plus the bearer. */
+export function a2aEnv(env, token) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (!k.startsWith("A2ACLI_"))
+            out[k] = v;
+    out.A2ACLI_AUTH = `Bearer ${token}`;
+    return out;
+}
+/**
+ * How to get the official a2a CLI. A current Homebrew refuses a formula from
+ * a third-party tap until it is trusted — without `brew trust` the install
+ * stops at "Refusing to load formula … from untrusted tap" (#1428).
+ */
+export const A2A_INSTALL_HINT = "macOS: brew tap a2aproject/a2a-cli https://github.com/a2aproject/a2a-cli && brew trust --formula a2aproject/a2a-cli/a2a && brew install a2a; Windows: winget install a2aproject.a2acli";
+/**
+ * A 403 from the channel names no cause in the a2a CLI's words ("check the
+ * --agent-card reference" — the host is datum's, not the person's), so datum
+ * says what it means here (docs/a2a.md "Refusals"). With `--agent` the 403
+ * can also mean the nick names no agent of this space (#1647).
+ */
+export function a2aForbiddenHint(agent) {
+    const causes = [
+        "the space's A2A feature is off (an organisation admin turns it on: Spaces → the space → Features → A2A)",
+        "Developer access is off in the space (the terminal signs in with your person token)",
+        ...(agent ? [`"${agent}" is not an agent of this space`] : []),
+        "your role in the space cannot start a run (a task needs operator; `datum whoami --space <slug>` shows yours)",
+    ];
+    return `datum: the space's A2A channel answered 403 — one of: ${causes.join("; ")}\n`;
+}
+// Enough of the child's stderr to find its HTTP status line.
+const STDERR_TAIL_BYTES = 8192;
+// The a2a CLI's HTTP status marker (`card request failed, status: 403
+// Forbidden`) — not any 403 in the text, which may be an id it echoes.
+const HTTP_FORBIDDEN = /\bstatus:?\s*403\b|\b403 Forbidden\b/;
+export const spawnChild = (bin, argv, env, err) => new Promise((resolve, reject) => {
+    const child = spawn(bin, argv, { env, stdio: ["inherit", "inherit", "pipe"] });
+    let stderrTail = "";
+    child.stderr?.on("data", (chunk) => {
+        err.write(chunk);
+        stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_BYTES);
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), stderrTail }));
+});
+export async function runA2a(baseUrl, space, args, io) {
+    const origin = originOf(baseUrl);
+    const spaceBase = space ? spaceBaseUrl(origin, space) : origin;
+    const env = io.env ?? process.env;
+    const dir = mkdtempSync(path.join(tmpdir(), "datum-a2a-"));
+    const configPath = path.join(dir, "a2a.yaml");
+    try {
+        writeFileSync(configPath, "# datum a2a — no local configuration: the destination and the credential come from datum\n", { mode: 0o600 });
+        let argv;
+        let agent;
+        try {
+            const picked = a2aAgentOf(args, env);
+            agent = picked.agent;
+            argv = a2aArgs(picked.rest, a2aTarget(spaceBase, agent), configPath);
+        }
+        catch (err) {
+            if (err instanceof A2aUsageError) {
+                io.err.write(`datum: ${err.message}\n`);
+                return 2;
+            }
+            throw err;
+        }
+        let token;
+        try {
+            token = await ensureAccessToken(origin, io.store, io);
+        }
+        catch (err) {
+            if (err instanceof NotLoggedInError || err instanceof LoginFlowError) {
+                io.err.write(`datum: ${err.message}\n`);
+                return 1;
+            }
+            throw err;
+        }
+        let result;
+        try {
+            result = await (io.run ?? spawnChild)("a2a", argv, a2aEnv(env, token), io.err);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                io.err.write(`datum: the a2a CLI is not on PATH — install it (${A2A_INSTALL_HINT})\n`);
+                return 127;
+            }
+            throw err;
+        }
+        if (result.code !== 0 && HTTP_FORBIDDEN.test(result.stderrTail))
+            io.err.write(a2aForbiddenHint(agent));
+        return result.code;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=a2aCommand.js.map