@tinycloud/cli 1.5.0-beta.12 → 1.5.0-beta.13

package/README.md

@@ -87,6 +87,7 @@ tc kv list
 tc secrets network init
 printf '%s' "$ANTHROPIC_API_KEY" | tc secrets put ANTHROPIC_API_KEY --stdin
 tc secrets get ANTHROPIC_API_KEY
+tc secrets run ANTHROPIC_API_KEY -- python train.py   # the value only in the command's environment
 
 # Ask the owner for a secret an agent needs, then wait for it
 # (call TinyCloud's CLI by absolute path: a bare `tc` can be iproute2's /usr/sbin/tc)
@@ -138,6 +139,7 @@ tc delegation create --to did:pkh:eip155:1:0x...
 | `tc secrets network show` | Show a secrets decryption network |
 | `tc secrets network init` | Create or fetch the default secrets network |
 | `tc secrets network grant` | Grant `tinycloud.encryption/decrypt` on a secrets network |
+| `tc secrets run` | Run a command with secrets in its environment |
 | `tc secrets request` | Print a Secret Manager link asking the owner to add secrets (offline) |
 | `tc secrets wait` | Wait until secrets exist and are readable (never signs in; needs a stored session; exit 8 pending, 130 interrupted) |
 | `tc secrets manage` | Print or open the Secret Manager page, `{url, opened}` |
@@ -159,6 +161,62 @@ still exits 0 and installs the rest. If the schema fails after notes were
 written, it says "notes saved; tables not set up: run again"; running it again
 is safe.
 
+### Running a command with secrets
+
+```bash
+tc secrets run NAME... [--map NAME=ENV_VAR]... [--scope S] [--space S] [--delegation SOURCE] [--private-key HEX] -- <command> [args...]
+
+tc secrets run ANTHROPIC_API_KEY OPENAI_API_KEY -- python train.py
+tc secrets run --map ANTHROPIC_KEY=ANTHROPIC_API_KEY -- node server.js
+```
+
+`tc secrets run` reads every named secret as `tc secrets get` does, then
+starts `<command>` directly, without a shell, with each value in its
+environment: under the secret's name, or under `ENV_VAR` for `--map
+NAME=ENV_VAR`. A value replaces an inherited variable of the same name.
+tc doesn't pass its own `TC_PRIVATE_KEY` to the command. To give the command
+a key from a secret, use `--map NAME=TC_PRIVATE_KEY`.
+Everything after the first `--`, including any further `--`, goes to the
+command unchanged. The command uses tc's stdin, stdout and stderr; tc itself
+writes nothing to stdout, and its own messages go to stderr.
+
+Name at least one secret, as an argument or with `--map`. `ENV_VAR` must
+match `[A-Za-z_][A-Za-z0-9_]*`, and two secrets cannot be mapped to the same
+variable (exit 2). If any secret cannot be read, the command does not start
+and tc exits with the code and error `tc secrets get` gives for that secret.
+Otherwise tc exits with the command's exit code. If the command was ended by
+SIGINT, SIGTERM, SIGHUP, SIGKILL, SIGALRM or SIGUSR2, tc ends by the same
+signal (or exits with 128 plus the signal number if that signal doesn't end
+tc). If any other signal ended it, such as SIGQUIT or SIGSEGV, tc exits with
+128 plus the signal number instead, so tc does not cause a core dump
+(SIGUSR1 and SIGPIPE are left out too: Node uses SIGUSR1 for its inspector
+and ignores SIGPIPE).
+
+SIGINT, SIGTERM, SIGHUP and SIGQUIT sent to tc go to the command. When tc
+runs in the foreground of a terminal, it doesn't pass on SIGINT, SIGQUIT or
+SIGHUP: the terminal already sends them (Ctrl-C, Ctrl-\, hangup) to the
+command, so the command normally gets each one once. tc checks whether it's
+in the foreground using `/proc`, or `ps` where `/proc` isn't available. If
+neither works, it passes the signals on. When tc runs in the background, it
+passes them on, so a signal sent to the whole job (for example `kill -INT
+%1`) can reach the command twice.
+
+From a script, stop the command by sending SIGTERM to tc's process ID. tc
+passes it on, waits for the command to exit, then exits the way the command
+did (the command's own exit code if it handles SIGTERM itself). If the
+command ignores SIGTERM, tc keeps waiting.
+
+A command that does not exist exits 127; one that cannot be executed, or
+cannot be started for another reason, exits 126. These cases print one plain
+line on stderr, even with `--json`: `tc secrets run: <command>: command not
+found`, `…: permission denied` or `…: cannot run (<error code>)`.
+
+Limits: `tc secrets run` keeps values out of the command line, your shell
+history and tc's own output. It doesn't hide them from the command: the
+command, and anything it starts, receives the values and can print, log or
+pass them on. Other programs running as the same user can often read a
+process's environment too.
+
 ## Global Options
 
 ```

package/dist/legacy-entry.js

@@ -39188,7 +39188,7 @@ init_constants();
 import { CLI_NAME as CLI_NAME32 } from "@tinycloud/operations/cli-name";
 import { readFile as readFile14 } from "fs/promises";
 import { join as join17 } from "path";
-import { homedir, hostname, userInfo } from "os";
+import { constants as osConstants, homedir, hostname, userInfo } from "os";
 import { appSecretScope } from "@tinycloud/sdk-core";
 import { invokeOperation as invokeOperation3 } from "@tinycloud/operations";
 import { isLocalOwnerProfile as isLocalOwnerProfile4, ownerSessionLacksProof as ownerSessionLacksProof5 } from "@tinycloud/operations/profile";
@@ -39209,6 +39209,7 @@ import {
 } from "@tinycloud/operations/secret-capabilities";
 import { invokeSecretsGetWithLocalAuthorityRetry } from "@tinycloud/operations/cli-runtime";
 init_sdk();
+init_replication_registry();
 init_session_expired();
 init_space();
 
@@ -39274,14 +39275,14 @@ function runProbeChild(request, options = {}) {
   const args = options.argv ?? probeChildArgv(request);
   const budgetMs = options.budgetMs ?? ATTEMPT_BUDGET_MS;
   const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
-  const spawn2 = options.spawn ?? nodeSpawn;
+  const spawn3 = options.spawn ?? nodeSpawn;
   const signal = options.signal;
   return new Promise((resolve9) => {
     if (signal?.aborted) {
       resolve9({ kind: "cancelled" });
       return;
     }
-    const child = spawn2(command, args, { env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn3(command, args, { env: process.env, stdio: ["ignore", "pipe", "pipe"] });
     let outcome;
     let stdout = Buffer.alloc(0);
     let stderr = Buffer.alloc(0);
@@ -39393,6 +39394,75 @@ function parseStatusEnvelope(line) {
   return void 0;
 }
 
+// src/lib/run-command.ts
+import { execFileSync, spawn as spawn2 } from "child_process";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+var FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+var TERMINAL_SIGNALS = { SIGINT: true, SIGQUIT: true, SIGHUP: true };
+function psGroupArgs(pid) {
+  return ["-o", "pgid=", "-o", "tpgid=", "-p", String(pid)];
+}
+function parsePsGroups(output2) {
+  const columns = output2.trim().split(/\s+/);
+  if (columns.length !== 2) return void 0;
+  const group = Number(columns[0]);
+  const foreground = Number(columns[1]);
+  return Number.isSafeInteger(group) && Number.isSafeInteger(foreground) ? { group, foreground } : void 0;
+}
+function processGroups() {
+  try {
+    const stat8 = readFileSync2("/proc/self/stat", "utf8");
+    const fields = stat8.slice(stat8.lastIndexOf(")") + 2).split(" ");
+    return { group: Number(fields[2]), foreground: Number(fields[5]) };
+  } catch {
+  }
+  try {
+    const ps = existsSync("/bin/ps") ? "/bin/ps" : "/usr/bin/ps";
+    return parsePsGroups(execFileSync(ps, psGroupArgs(process.pid), {
+      env: {},
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    }));
+  } catch {
+    return void 0;
+  }
+}
+function inTerminalForeground() {
+  const groups = processGroups();
+  return groups !== void 0 && groups.foreground > 0 && groups.group === groups.foreground;
+}
+function runCommand(argv, env) {
+  return new Promise((resolve9) => {
+    let child;
+    try {
+      child = spawn2(argv[0], argv.slice(1), { stdio: "inherit", env, shell: false });
+    } catch (error) {
+      const code5 = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
+      resolve9({ kind: "not_started", ...code5 === void 0 ? {} : { errno: code5 } });
+      return;
+    }
+    const forward = (signal) => {
+      if (TERMINAL_SIGNALS[signal] && inTerminalForeground()) return;
+      child.kill(signal);
+    };
+    for (const signal of FORWARDED_SIGNALS) process.on(signal, forward);
+    const settle = (outcome) => {
+      for (const signal of FORWARDED_SIGNALS) process.off(signal, forward);
+      resolve9(outcome);
+    };
+    child.on("error", (error) => {
+      if (child.pid === void 0) settle({ kind: "not_started", ...error.code === void 0 ? {} : { errno: error.code } });
+    });
+    child.once("exit", (code5, signal) => {
+      settle(signal !== null ? { kind: "signaled", signal } : { kind: "exited", code: code5 ?? 1 });
+    });
+  });
+}
+
+// src/commands/secrets.ts
+init_safe_text();
+
 // src/lib/secrets-wait.ts
 init_constants();
 init_errors();
@@ -40347,6 +40417,153 @@ function outputSecretDoctor(result) {
     process.stdout.write(theme.warn(`${failed} secrets check${failed > 1 ? "s" : ""} need attention.`) + "\n");
   }
 }
+async function resolveSecretReadTarget(ctx, name, options) {
+  const scopeOptions = resolveSecretScope(options);
+  const legacySpaceUri = await resolveSecretSpace(options.space, ctx.profile);
+  const resolved = resolveSecretPath2(name, scopeOptions);
+  return { name, scopeOptions, scope: resolved.scope, legacySpaceUri, secretPath: resolved.permissionPaths.vault };
+}
+async function readSecret(params) {
+  const { ctx, target, options } = params;
+  const { name } = target;
+  if (options.delegation) {
+    const delegated = await resolveDelegatedSecretSource(
+      options.delegation,
+      target.secretPath,
+      target.legacySpaceUri ?? SECRETS_SPACE2
+    );
+    const effectiveHost = params.host ?? delegated.delegation.host ?? ctx.host;
+    const delegatedCtx = { ...ctx, host: effectiveHost };
+    const local = effectiveLocal(await ProfileManager.getProfile(ctx.profile).catch(() => null), options);
+    const node = await ensureSecretsNode(delegatedCtx, options);
+    const value = await withSpinner(
+      `Getting secret ${name}...`,
+      () => readDelegatedSecretValue({
+        node,
+        delegation: delegated.delegation,
+        delegationCid: delegated.delegation.cid,
+        permissions: delegated.permissions,
+        secretPath: target.secretPath,
+        space: target.legacySpaceUri ?? SECRETS_SPACE2,
+        name,
+        ...target.scope === void 0 ? {} : { scope: target.scope },
+        local
+      })
+    );
+    return { value };
+  }
+  const privateKey = authOptions(options)?.privateKey;
+  const spaceUri = privateKey !== void 0 && options.space !== void 0 && !options.space.startsWith("tinycloud:") ? options.space : target.legacySpaceUri;
+  const result = await invokeCanonicalSecretGet({
+    ctx,
+    name,
+    ...target.scopeOptions?.scope === void 0 ? {} : { scope: target.scopeOptions.scope },
+    ...spaceUri === void 0 ? {} : { space: spaceUri },
+    options,
+    label: `Getting secret ${name}...`,
+    openKeyAcquisition: params.openKeyAcquisition
+  });
+  if (result.status !== "ok") {
+    try {
+      throwCanonicalSecretGetError(result, name);
+    } catch (error) {
+      throw withOperationWarnings(error, result.warnings);
+    }
+  }
+  return { value: result.output.value, warnings: result.warnings };
+}
+var ENV_VAR_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function argvAfterSeparator(cmd) {
+  let root = cmd;
+  while (root.parent) root = root.parent;
+  const raw = "rawArgs" in root ? root.rawArgs : void 0;
+  if (!Array.isArray(raw)) return void 0;
+  const args = raw.map(String);
+  const withValue = (flag) => root.options.some((option) => option.required && (option.long === flag || option.short === flag));
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--") return args.slice(index + 1);
+    if (arg.startsWith("--")) {
+      if (withValue(arg)) index += 1;
+      continue;
+    }
+    if (arg.length < 2 || !arg.startsWith("-")) continue;
+    for (let char = 1; char < arg.length; char += 1) {
+      const option = root.options.find((candidate) => candidate.short === `-${arg[char]}`);
+      if (option === void 0) break;
+      if (option.required) {
+        if (char === arg.length - 1) index += 1;
+        break;
+      }
+    }
+  }
+  return void 0;
+}
+function secretRunPlan(cmd, operands, maps) {
+  const usage3 = `${CLI_NAME32} secrets run NAME... [--map NAME=ENV_VAR] -- <command> [args...]`;
+  const after = argvAfterSeparator(cmd);
+  if (after === void 0 || after.length > operands.length) {
+    throw new CLIError("USAGE_ERROR", `Put the command after \`--\`: ${usage3}`, ExitCode.USAGE_ERROR);
+  }
+  const [program, ...args] = after;
+  if (program === void 0) {
+    throw new CLIError("USAGE_ERROR", `Add the command to run after \`--\`: ${usage3}`, ExitCode.USAGE_ERROR);
+  }
+  const exports = [];
+  for (const name of operands.slice(0, operands.length - after.length)) {
+    if (!ENV_VAR_RE.test(name)) {
+      throw new CLIError(
+        "USAGE_ERROR",
+        `${JSON.stringify(name)} can't be used as an environment variable name. Use \`--map ${name}=ENV_VAR\` to choose one.`,
+        ExitCode.USAGE_ERROR
+      );
+    }
+    exports.push({ name, variable: name });
+  }
+  for (const map of maps) {
+    const equals7 = map.indexOf("=");
+    const variable = map.slice(equals7 + 1);
+    if (equals7 <= 0 || !ENV_VAR_RE.test(variable)) {
+      throw new CLIError(
+        "USAGE_ERROR",
+        `Invalid \`--map ${JSON.stringify(map)}\`: use NAME=ENV_VAR, where ENV_VAR starts with a letter or _ and uses only letters, digits and _.`,
+        ExitCode.USAGE_ERROR
+      );
+    }
+    exports.push({ name: map.slice(0, equals7), variable });
+  }
+  if (exports.length === 0) {
+    throw new CLIError("USAGE_ERROR", `Name at least one secret: ${usage3}`, ExitCode.USAGE_ERROR);
+  }
+  const variables = /* @__PURE__ */ new Set();
+  for (const { variable } of exports) {
+    if (variables.has(variable)) {
+      throw new CLIError("USAGE_ERROR", `Two secrets are mapped to ${variable}. Give each its own variable.`, ExitCode.USAGE_ERROR);
+    }
+    variables.add(variable);
+  }
+  return { command: [program, ...args], exports };
+}
+var RERAISED_SIGNALS = {
+  SIGINT: true,
+  SIGTERM: true,
+  SIGHUP: true,
+  SIGKILL: true,
+  SIGALRM: true,
+  SIGUSR2: true
+};
+var TC_CREDENTIAL_VARIABLES = ["TC_PRIVATE_KEY"];
+function exitAsCommand(outcome, program) {
+  if (outcome.kind === "exited") return process.exit(outcome.code);
+  if (outcome.kind === "signaled") {
+    if (RERAISED_SIGNALS[outcome.signal]) process.kill(process.pid, outcome.signal);
+    return process.exit(128 + (osConstants.signals[outcome.signal] ?? 0));
+  }
+  const reason = outcome.errno === "ENOENT" ? "command not found" : outcome.errno === "EACCES" ? "permission denied" : `cannot run (${outcome.errno ?? "unknown error"})`;
+  process.stderr.write(`${CLI_NAME32} secrets run: ${safeInline(program)}: ${reason}
+`);
+  return process.exit(outcome.errno === "ENOENT" ? 127 : 126);
+}
 function registerSecretsCommand(program, openKeyAcquisition) {
   const secrets = program.command("secrets").description("Encrypted secrets management");
   const network = secrets.command("network").description("Manage the default secrets encryption network");
@@ -40514,66 +40731,23 @@ function registerSecretsCommand(program, openKeyAcquisition) {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
-      const scopeOptions = resolveSecretScope(options);
-      const legacySpaceUri = await resolveSecretSpace(options.space, ctx.profile);
-      const secretPath = resolveSecretPath2(name, scopeOptions).permissionPaths.vault;
+      const target = await resolveSecretReadTarget(ctx, name, options);
       if (options.output) await validatePrivateOutput(options.output, "Secret output");
+      const secret = await readSecret({ ctx, host: globalOpts.host, target, options, openKeyAcquisition });
+      const value = secret.value;
       if (options.delegation) {
-        const delegated = await resolveDelegatedSecretSource(
-          options.delegation,
-          secretPath,
-          legacySpaceUri ?? SECRETS_SPACE2
-        );
-        const effectiveHost = globalOpts.host ?? delegated.delegation.host ?? ctx.host;
-        const delegatedCtx = { ...ctx, host: effectiveHost };
-        const local = effectiveLocal(await ProfileManager.getProfile(ctx.profile).catch(() => null), options);
-        const scope = resolveSecretPath2(name, scopeOptions).scope;
-        const node = await ensureSecretsNode(delegatedCtx, options);
-        const value2 = await withSpinner(
-          `Getting secret ${name}...`,
-          () => readDelegatedSecretValue({
-            node,
-            delegation: delegated.delegation,
-            delegationCid: delegated.delegation.cid,
-            permissions: delegated.permissions,
-            secretPath,
-            space: legacySpaceUri ?? SECRETS_SPACE2,
-            name,
-            ...scope === void 0 ? {} : { scope },
-            local
-          })
-        );
         if (options.output) {
-          await writePrivateOutput(options.output, value2, "Secret output");
+          await writePrivateOutput(options.output, value, "Secret output");
           outputJson({ name, written: options.output });
           return;
         }
         if (options.raw) {
-          process.stdout.write(value2);
+          process.stdout.write(value);
           return;
         }
-        outputJson({ name, value: value2 });
+        outputJson({ name, value });
         return;
       }
-      const privateKey = authOptions(options)?.privateKey;
-      const spaceUri = privateKey !== void 0 && options.space !== void 0 && !options.space.startsWith("tinycloud:") ? options.space : legacySpaceUri;
-      const result = await invokeCanonicalSecretGet({
-        ctx,
-        name,
-        ...scopeOptions?.scope === void 0 ? {} : { scope: scopeOptions.scope },
-        ...spaceUri === void 0 ? {} : { space: spaceUri },
-        options,
-        label: `Getting secret ${name}...`,
-        openKeyAcquisition
-      });
-      if (result.status !== "ok") {
-        try {
-          throwCanonicalSecretGetError(result, name);
-        } catch (error) {
-          throw withOperationWarnings(error, result.warnings);
-        }
-      }
-      const value = result.output.value;
       try {
         if (options.output) {
           await writePrivateOutput(options.output, value, "Secret output");
@@ -40584,9 +40758,47 @@ function registerSecretsCommand(program, openKeyAcquisition) {
           outputJson({ name, value });
         }
       } catch (error) {
-        throw withOperationWarnings(error, result.warnings);
+        throw withOperationWarnings(error, secret.warnings);
       }
-      outputWarnings(operationWarnings(result.warnings));
+      outputWarnings(operationWarnings(secret.warnings));
+    } catch (error) {
+      return handleError(error);
+    }
+  });
+  secrets.command("run [names...]").description("Run a command with secrets in its environment").usage("[options] [names...] -- <command> [args...]").option(
+    "--map <NAME=ENV_VAR>",
+    "Give secret NAME to the command as environment variable ENV_VAR (repeatable)",
+    (value, previous) => [...previous ?? [], value]
+  ).option("--scope <scope>", "Logical secret scope").option("--space <name|uri>", "Target a non-default secrets space (short name or full URI)").option("--delegation <source>", "Delegation file path or imported profile name").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (operands, options, cmd) => {
+    try {
+      const plan = secretRunPlan(cmd, operands, options.map ?? []);
+      const globalOpts = cmd.optsWithGlobals();
+      const ctx = await ProfileManager.resolveContext(globalOpts);
+      const targets = [];
+      for (const name of new Set(plan.exports.map((entry) => entry.name))) {
+        targets.push(await resolveSecretReadTarget(ctx, name, options));
+      }
+      const values = /* @__PURE__ */ new Map();
+      let warnings = [];
+      for (const target of targets) {
+        const secret = await readSecret({ ctx, host: globalOpts.host, target, options, openKeyAcquisition });
+        if (secret.value.includes("\0")) {
+          throw new CLIError(
+            "SECRET_NOT_EXPORTABLE",
+            `Secret "${target.name}" contains a NUL character, so it can't be put in an environment variable. The command wasn't started.`,
+            ExitCode.ERROR
+          );
+        }
+        values.set(target.name, secret.value);
+        warnings = mergeWarnings(warnings, secret.warnings ?? []);
+      }
+      outputWarnings(operationWarnings(warnings));
+      await closeReplication();
+      const env = { ...process.env };
+      for (const variable of TC_CREDENTIAL_VARIABLES) delete env[variable];
+      for (const entry of plan.exports) env[entry.variable] = values.get(entry.name);
+      values.clear();
+      exitAsCommand(await runCommand(plan.command, env), plan.command[0]);
     } catch (error) {
       return handleError(error);
     }
@@ -41048,7 +41260,7 @@ async function writeShareOutput(directory, filename, bytes, force) {
 init_profiles();
 
 // src/share/html-folder.ts
-import { constants as constants2, existsSync } from "fs";
+import { constants as constants2, existsSync as existsSync2 } from "fs";
 import { lstat as lstat11, open as open14, readdir as readdir7, realpath as realpath3, stat as stat7 } from "fs/promises";
 import { basename as basename5, dirname as dirname9, isAbsolute, join as join19, relative as relativePath, resolve as resolve7, sep as sep4 } from "path";
 
@@ -41986,7 +42198,7 @@ function isRaceError(error) {
 }
 var PROC_FD = "/proc/self/fd";
 async function linuxDescriptorPath(fd) {
-  if (process.platform !== "linux" || !existsSync(PROC_FD)) return void 0;
+  if (process.platform !== "linux" || !existsSync2(PROC_FD)) return void 0;
   return realpath3(`${PROC_FD}/${fd}`);
 }
 async function parentChainIsRealDirectories(root, path) {
@@ -43623,11 +43835,11 @@ function plural(count, label) {
 init_theme();
 init_errors();
 import { execSync } from "child_process";
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 var PACKAGE_NAME = "@tinycloud/cli";
 function getCurrentVersion() {
   const pkg = JSON.parse(
-    readFileSync2(new URL("../package.json", import.meta.url), "utf-8")
+    readFileSync3(new URL("../package.json", import.meta.url), "utf-8")
   );
   return pkg.version;
 }