@nimbus-dev/connectors 0.8.0 → 0.9.0

package/connectors/kubernetes/src/tools.ts

@@ -1,7 +1,13 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { z } from "zod";
 import { cliArg } from "../../../shared/cli-json-kit.ts";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createPrepareToolRegistrar,
+  createWriteToolRegistrar,
+} from "../../../shared/consent-kit.ts";
 import { isKubectlNotFound, projectDeployment } from "../../../shared/k8s-deployment-view.ts";
 import {
   createRegisterSimpleTool,
@@ -9,7 +15,9 @@ import {
   mcpJsonResult as jsonResult,
 } from "../../../shared/mcp-tool-kit.ts";
 import { withPrivateKubeconfig } from "../../../shared/private-kubeconfig.ts";
-import { runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+import { withScratchDir } from "../../../shared/private-scratch.ts";
+import { runCliCode, runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+import { type ScannedObject, scanNamespacedManifest } from "./manifest-scan.ts";
 
 function kubectlBase(): string[] {
   const args = ["kubectl"];
@@ -33,6 +41,185 @@ function kubectlJson(rest: string[]): Promise<unknown> {
   return withKube((env) => runCliJsonThrowing(cmd, env));
 }
 
+/** A manifest may be at most this many UTF-8 bytes (the schema's character cap is a floor of it). */
+const MANIFEST_MAX_BYTES = 262_144;
+/** The diff in a plan reply; the owner approves what the preview shows, so a bigger one is refused. */
+const DIFF_MAX_BYTES = 65_536;
+/** The whole plan reply, which the gateway refuses above this size. */
+const PLAN_REPLY_MAX_BYTES = 262_144;
+/** Domain separator of the plan hash: sha256 of this, a newline, the namespace, a newline, the manifest. */
+const PLAN_HASH_DOMAIN = "nimbus-k8s-manifest-v1";
+const MISMATCH = "manifest does not match the approved hash";
+
+interface ManifestInput {
+  readonly namespace: string;
+  readonly manifest: string;
+}
+
+/**
+ * The checks every manifest tool makes before it touches a file or a process, in this order: size
+ * in UTF-8 bytes, the namespaced-subset scan (manifest-scan.ts), and the hash of the exact bytes
+ * kubectl will be handed. Throws a fixed message.
+ */
+function checkedManifest(p: ManifestInput): {
+  bytes: Buffer;
+  sha256: string;
+  scanned: ScannedObject[];
+} {
+  const bytes = Buffer.from(p.manifest, "utf8");
+  if (bytes.length > MANIFEST_MAX_BYTES) {
+    throw new Error(`manifest is larger than ${String(MANIFEST_MAX_BYTES)} bytes`);
+  }
+  const scanned = scanNamespacedManifest(p.manifest, p.namespace);
+  // The hash binds the namespace to the manifest, so an approved plan for one namespace cannot be
+  // replayed against another. The kube CONTEXT is owner environment (KUBE_CONTEXT), not caller
+  // input, and is deliberately not part of it.
+  const hashed = [PLAN_HASH_DOMAIN, p.namespace, p.manifest].join("\n");
+  const sha256 = createHash("sha256").update(hashed, "utf8").digest("hex");
+  return { bytes, sha256, scanned };
+}
+
+/** {@link checkedManifest}, then the apply's own check: the manifest must hash to what was approved. */
+function approvedManifest(p: ManifestInput & { readonly planSha256: string }) {
+  const checked = checkedManifest(p);
+  const want = Buffer.from(p.planSha256, "hex");
+  const have = Buffer.from(checked.sha256, "hex");
+  // Equal length is checked first: timingSafeEqual throws on unequal buffers. The schema pins 64 hex.
+  if (want.length !== have.length || !timingSafeEqual(want, have)) {
+    throw new Error(MISMATCH);
+  }
+  return checked;
+}
+
+function refusalOf(check: () => unknown): string | undefined {
+  try {
+    check();
+    return undefined;
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+}
+
+/**
+ * kubectl's failure as an error. A Secret in the manifest means kubectl's stderr may quote its
+ * data (an invalid value is often echoed), so the snippet is withheld whenever one is present.
+ */
+function kubectlFailure(
+  label: string,
+  code: number,
+  stderr: string,
+  scanned: readonly ScannedObject[],
+): Error {
+  const detail = scanned.some((o) => o.kind === "Secret")
+    ? "(stderr withheld: the manifest holds a Secret)"
+    : stderr.slice(0, 500);
+  return new Error(`${label} exited ${String(code)}: ${detail}`);
+}
+
+/** What a plan's `diff` holds in place of kubectl's when the manifest holds a Secret. */
+export const SECRET_DIFF_WITHHELD = "(diff withheld: the manifest holds a Secret)";
+
+/** The `kubectl ... -o name` resource prefix of each allowlisted kind. */
+const RESOURCE_PREFIX: Readonly<Record<string, string>> = {
+  ConfigMap: "configmap",
+  Secret: "secret",
+  Service: "service",
+  Pod: "pod",
+  ServiceAccount: "serviceaccount",
+  PersistentVolumeClaim: "persistentvolumeclaim",
+  Deployment: "deployment.apps",
+  StatefulSet: "statefulset.apps",
+  DaemonSet: "daemonset.apps",
+  ReplicaSet: "replicaset.apps",
+  Job: "job.batch",
+  CronJob: "cronjob.batch",
+  Ingress: "ingress.networking.k8s.io",
+  NetworkPolicy: "networkpolicy.networking.k8s.io",
+  Role: "role.rbac.authorization.k8s.io",
+  RoleBinding: "rolebinding.rbac.authorization.k8s.io",
+  HorizontalPodAutoscaler: "horizontalpodautoscaler.autoscaling",
+  PodDisruptionBudget: "poddisruptionbudget.policy",
+};
+
+/**
+ * Order by UTF-16 code unit, the same on every machine. Not `localeCompare`: collation can tie two
+ * distinct strings, and these lists are compared element by element.
+ */
+function compareCodeUnits(a: string, b: string): number {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+}
+
+/** The sorted `<prefix>/<name>` list the scan expects kubectl to report. */
+function expectedNames(scanned: readonly ScannedObject[]): string[] {
+  return scanned
+    .map((o) => `${RESOURCE_PREFIX[o.kind] ?? o.kind}/${o.name}`)
+    .sort(compareCodeUnits);
+}
+
+/**
+ * Defence in depth behind the scanner: what kubectl itself reports (`-o name`) must be, as a
+ * multiset, exactly what the scan read. A document kubectl reads differently (a List flattened into
+ * its items, a kind the scan mis-paired) shows up here as a different set, before the diff and
+ * before the real apply. Names only, so the message is safe to show.
+ */
+function assertSameObjects(
+  reported: readonly string[],
+  scanned: readonly ScannedObject[],
+  when: string,
+): void {
+  const have = [...reported].sort(compareCodeUnits);
+  const want = expectedNames(scanned);
+  if (have.length !== want.length || have.some((n, i) => n !== want[i])) {
+    throw new Error(
+      `kubectl ${when} reported different objects than the manifest scan (kubectl: ${have.join(", ")}; scan: ${want.join(", ")})`,
+    );
+  }
+}
+
+/** Write the manifest into the call's private scratch directory: exclusive create, owner-only. */
+async function writeManifestFile(dir: string, bytes: Buffer): Promise<string> {
+  const file = join(dir, "manifest.yaml");
+  await writeFile(file, bytes, { flag: "wx", mode: 0o600 });
+  return file;
+}
+
+/** `kubectl apply --server-side --dry-run=server -o name`, cross-checked against the scan. */
+async function serverDryRun(
+  kube: { readonly KUBECONFIG: string },
+  ns: string,
+  file: string,
+  scanned: readonly ScannedObject[],
+): Promise<string[]> {
+  const dry = await runCliCode(
+    [
+      ...kubectlBase(),
+      "apply",
+      "--server-side",
+      "--dry-run=server",
+      "--field-manager=nimbus",
+      "-n",
+      ns,
+      "-f",
+      file,
+      "-o",
+      "name",
+    ],
+    kube,
+  );
+  if (dry.code !== 0) throw kubectlFailure("kubectl", dry.code, dry.stderr, scanned);
+  const objects = objectLines(dry.stdout);
+  assertSameObjects(objects, scanned, "dry run");
+  return objects;
+}
+
+function objectLines(stdout: string): string[] {
+  return stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l !== "");
+}
+
 const optionalNamespaceSchema = z.object({ namespace: cliArg.optional() });
 
 async function k8sListNamespacedResource(p: { namespace?: string | undefined }, resource: string) {
@@ -50,6 +237,8 @@ export const KUBERNETES_TOOL_NAMES = [
   "k8s_rollout_restart",
   "k8s_pod_delete",
   "k8s_deployment_scale",
+  "k8s_manifest_plan",
+  "k8s_manifest_apply",
 ] as const;
 
 export function registerKubernetesTools(
@@ -68,6 +257,16 @@ export function registerKubernetesTools(
     scopeKinds: ["namespace"],
   });
 
+  /**
+   * Prepare tools (shared/prepare-tool-ids.ts) read the state a write is bound to, for the gateway
+   * to call BEFORE the write's approval prompt; they are neither reads nor writes to the kit.
+   */
+  const registerPrepareTool = createPrepareToolRegistrar(server, {
+    connector: "kubernetes",
+    scopeEnv: "NIMBUS_MCP_KUBERNETES_WRITE_SCOPE",
+    scopeKinds: ["namespace"],
+  });
+
   reg(
     "k8s_pod_list",
     "List pods in a namespace (default namespace: default).",
@@ -177,4 +376,134 @@ export function registerKubernetesTools(
       return jsonResult({ ok: true });
     },
   );
+
+  registerPrepareTool(
+    "k8s_manifest_plan",
+    { scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }) },
+    "Plan a k8s_manifest_apply: scan the manifest (namespaced kinds from an allowlist only, in the given namespace), then ask the API server for a server-side dry run and a server-side diff. Returns {planSha256, namespace, objects, scanned, diff, hasDifferences}; the apply must be given the same namespace, manifest and planSha256. Changes nothing.",
+    z.object({ namespace: cliArg, manifest: z.string().min(1).max(MANIFEST_MAX_BYTES) }),
+    async (p) => {
+      const { bytes, sha256, scanned } = checkedManifest(p);
+      const ns = p.namespace;
+      const reply = await withScratchDir("nimbus-k8s-", async (dir) => {
+        const file = await writeManifestFile(dir, bytes);
+        return withKube(async (kube) => {
+          // The dry run: the API server validates and admits the manifest and names each object,
+          // and the names must be the ones the scan read (see assertSameObjects).
+          const objects = await serverDryRun(kube, ns, file, scanned);
+
+          // kubectl diff runs the program KUBECTL_EXTERNAL_DIFF names (default `diff -u -N`). The
+          // variable is removed from the child whatever the owner's shell sets, so the diff is
+          // never produced by an arbitrary program. TMPDIR/TMP/TEMP point kubectl's own temp files
+          // (Go reads TMP and TEMP on Windows) into this call's private directory. Exit codes:
+          // https://kubernetes.io/docs/reference/kubectl/generated/kubectl_diff/ (0 no
+          // differences, 1 differences, >1 error). --force-conflicts is never passed.
+          const diff = await runCliCode(
+            [
+              ...kubectlBase(),
+              "diff",
+              "--server-side",
+              "--field-manager=nimbus",
+              "-n",
+              ns,
+              "-f",
+              file,
+            ],
+            {
+              KUBECONFIG: kube.KUBECONFIG,
+              KUBECTL_EXTERNAL_DIFF: undefined,
+              TMPDIR: dir,
+              TMP: dir,
+              TEMP: dir,
+            },
+          );
+          if (diff.code !== 0 && diff.code !== 1) {
+            throw kubectlFailure("kubectl diff", diff.code, diff.stderr, scanned);
+          }
+          if (Buffer.byteLength(diff.stdout, "utf8") > DIFF_MAX_BYTES) {
+            throw new Error(`diff too large (over ${String(DIFF_MAX_BYTES)} bytes)`);
+          }
+          // kubectl masks a Secret's `data`, but the diff's context lines can still carry its
+          // plaintext (a `last-applied-configuration` annotation, `stringData`), so with a Secret
+          // in the manifest only the fact of a difference is returned, never the body.
+          const holdsSecret = scanned.some((o) => o.kind === "Secret");
+          return {
+            planSha256: sha256,
+            namespace: ns,
+            objects,
+            scanned,
+            diff: holdsSecret ? SECRET_DIFF_WITHHELD : diff.stdout,
+            hasDifferences: diff.code === 1,
+          };
+        });
+      });
+      if (Buffer.byteLength(JSON.stringify(reply), "utf8") > PLAN_REPLY_MAX_BYTES) {
+        throw new Error("plan reply too large");
+      }
+      return jsonResult(reply);
+    },
+  );
+
+  registerWriteTool(
+    "k8s_manifest_apply",
+    {
+      mutates: "kubernetes.manifest.apply",
+      // An applied manifest is not undone by this tool; the objects it names are all that remain.
+      recoverable: false,
+      capturePreState: (p) =>
+        Promise.resolve({
+          namespace: p.namespace,
+          planSha256: p.planSha256,
+          objects: checkedManifest(p).scanned,
+        }),
+      scopeTargetOf: (p) => ({ kind: "namespace", value: p.namespace }),
+      // Standalone only: a manifest no consent could make safe is refused before any prompt. The
+      // handler repeats the same checks, because gateway mode registers the raw handler.
+      refuseBefore: (p) => refusalOf(() => approvedManifest(p)),
+    },
+    "Apply a manifest with a server-side apply, in the given namespace. The namespace and manifest must be the ones k8s_manifest_plan planned (planSha256) and the manifest must hold namespaced objects of allowlisted kinds only. Runs a server-side dry run first and applies only if kubectl reports the objects the scan read.",
+    z.object({
+      namespace: cliArg,
+      manifest: z.string().min(1).max(MANIFEST_MAX_BYTES),
+      planSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    }),
+    async (p) => {
+      const { bytes, scanned } = approvedManifest(p);
+      return withScratchDir("nimbus-k8s-", async (dir) => {
+        const file = await writeManifestFile(dir, bytes);
+        return withKube(async (kube) => {
+          // Dry run and cross-check FIRST, so an object kubectl would apply that the scan did not
+          // read stops the call before anything changes.
+          await serverDryRun(kube, p.namespace, file, scanned);
+          // The file the real apply reads must still hold the approved bytes: the dry run was a
+          // child process with the same file, and on Windows the 0600 mode is not enforced.
+          if (!bytes.equals(await readFile(file))) {
+            throw new Error("the manifest file changed before the apply");
+          }
+          const applied = await runCliCode(
+            [
+              ...kubectlBase(),
+              "apply",
+              "--server-side",
+              "--field-manager=nimbus",
+              "-n",
+              p.namespace,
+              "-f",
+              file,
+              "-o",
+              "name",
+            ],
+            kube,
+          );
+          if (applied.code !== 0) {
+            throw kubectlFailure("kubectl", applied.code, applied.stderr, scanned);
+          }
+          const objects = objectLines(applied.stdout);
+          // After the fact: the objects are already applied, so this is reported, not prevented.
+          assertSameObjects(objects, scanned, "applied and");
+          return jsonResult({ ok: true, status: "applied", objects });
+        });
+      });
+    },
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },

package/shared/consent-kit.ts

@@ -82,6 +82,14 @@ export type WriteToolConfig<T> = {
   readonly capturePreState?: (args: T) => Promise<Record<string, unknown>>;
   /** The scope target this invocation would touch, checked against the allow-list. */
   readonly scopeTargetOf: (args: T) => { kind: string; value: string };
+  /**
+   * A refusal no consent can lift (an input the tool will reject, a tool that is refused outright),
+   * as its message, or `undefined` to proceed. Standalone only, and checked FIRST, before scope,
+   * budget and prompt: asking a human to approve a call that is certain to fail trains them to
+   * click through. It does NOT replace the handler's own check: in gateway mode the raw handler is
+   * registered and this is never called, so the handler must refuse the same input itself.
+   */
+  readonly refuseBefore?: (args: T) => string | undefined;
 };
 
 export type WriteToolRegistrar = <T>(
@@ -348,6 +356,13 @@ export function createWriteToolRegistrar(
     const guarded = async (args: T): Promise<McpListResult> => {
       const target = toolCfg.scopeTargetOf(args);
 
+      // 0. A refusal no consent can lift comes before everything that could involve a human.
+      const early = toolCfg.refuseBefore?.(args);
+      if (early !== undefined) {
+        await record(name, "refused", { reason: early, target });
+        return refused(early);
+      }
+
       // 1. SCOPE FIRST — before prompting. Asking a human to approve something the operator
       //    already forbade cannot change the outcome, and training people to click through
       //    prompts that do not matter is how you make the prompts that do matter ineffective.

package/shared/prepare-tool-ids.ts

@@ -7,11 +7,20 @@
  * is here. A naming convention would not do: a suffix rule passes `*_files_get`-style names that
  * the gateway treats as plain reads, and ids of the same class do not share a suffix.
  *
- * Grows per release: this one lists the two commit tools; the IaC, CloudFormation and Kubernetes
- * ones are added by the PR that registers them. `prepare-tool-ids.test.ts` requires every id here
- * to be registered exactly once, through `createPrepareToolRegistrar` and nothing else.
+ * Grows per release: 0.8.0 listed the two commit tools; the next release adds the Terraform plan,
+ * destroy-plan and show-json tools, the CloudFormation change-set create and the Kubernetes
+ * manifest plan. `prepare-tool-ids.test.ts` requires every id here to be registered exactly once,
+ * through `createPrepareToolRegistrar` and nothing else.
  */
-export const PREPARE_TOOL_IDS = ["github_commit_prepare", "gitlab_commit_prepare"] as const;
+export const PREPARE_TOOL_IDS = [
+  "github_commit_prepare",
+  "gitlab_commit_prepare",
+  "iac_terraform_plan",
+  "iac_terraform_destroy_plan",
+  "iac_terraform_show_json",
+  "iac_cloudformation_changeset_create",
+  "k8s_manifest_plan",
+] as const;
 
 export type PrepareToolId = (typeof PREPARE_TOOL_IDS)[number];
 

package/shared/private-kubeconfig.ts

@@ -21,10 +21,11 @@
 import { constants } from "node:fs";
 import { lstat, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { delimiter, isAbsolute, join } from "node:path";
+import { delimiter, join } from "node:path";
+import { configuredScratchBase } from "./private-scratch.ts";
 
 /** Names the directory private kubeconfigs are made in; an absolute path, else `os.tmpdir()`. */
-export const SCRATCH_DIR_ENV = "NIMBUS_CONNECTOR_SCRATCH_DIR";
+export { SCRATCH_DIR_ENV } from "./private-scratch.ts";
 
 /**
  * The one path `raw` (a `KUBECONFIG` value) names. A list of paths throws: a tool that cannot say
@@ -57,14 +58,14 @@ export function singleKubeconfigPath(
   return only;
 }
 
-/** The base directory private kubeconfigs are made under. */
+/**
+ * The base directory private kubeconfigs are made under: the configured scratch base, else
+ * `os.tmpdir()` on every platform. Unlike `withScratchDir` (private-scratch.ts) this does NOT
+ * refuse on Windows under the gateway: the before-state reads shipped in 0.8.0 run there today
+ * without the env var, and the gateway grants it with the Kubernetes write rows (D3).
+ */
 function scratchBase(): string {
-  const configured = process.env[SCRATCH_DIR_ENV]?.trim();
-  if (configured === undefined || configured === "") return tmpdir();
-  if (!isAbsolute(configured)) {
-    throw new Error(`${SCRATCH_DIR_ENV} must be an absolute path`);
-  }
-  return configured;
+  return configuredScratchBase() ?? tmpdir();
 }
 
 /** Refuse a source that is not a plain file: a symlink, a directory, a device. */

package/shared/private-scratch.ts

@@ -0,0 +1,68 @@
+/**
+ * private-scratch — a private directory for one tool call's files, removed when the call settles.
+ *
+ * The CLI-backed write tools hand their CLI a file rather than an argument: a CloudFormation
+ * template, a Kubernetes manifest. Each call gets its own 0700 directory under the configured
+ * scratch base, so concurrent calls never share a file and nothing outlives the call.
+ *
+ * The base is `NIMBUS_CONNECTOR_SCRATCH_DIR` (absolute) when set. When it is not, `os.tmpdir()`,
+ * with one exception: a Windows connector running under the gateway REFUSES. The gateway sandboxes
+ * a Windows connector in an AppContainer and grants it a per-action directory through that env
+ * var; the user temp directory is not that grant, so a file written there is either refused by
+ * the sandbox or, worse, shared with every other process of the user. Failing closed names the
+ * missing grant instead.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { getConnectorMode } from "./connector-mode.ts";
+
+/** Names the directory scratch directories are made in; an absolute path. */
+export const SCRATCH_DIR_ENV = "NIMBUS_CONNECTOR_SCRATCH_DIR";
+
+/**
+ * The configured scratch base, or `undefined` when none is configured. Throws on a relative
+ * value: a relative base would resolve against whatever the connector's cwd happens to be.
+ */
+export function configuredScratchBase(): string | undefined {
+  const configured = process.env[SCRATCH_DIR_ENV]?.trim();
+  if (configured === undefined || configured === "") return undefined;
+  if (!isAbsolute(configured)) {
+    throw new Error(`${SCRATCH_DIR_ENV} must be an absolute path`);
+  }
+  return configured;
+}
+
+/**
+ * The base a {@link withScratchDir} directory is made under (see the module comment for the
+ * Windows-under-the-gateway refusal). `platform` is a parameter so both sides are testable.
+ */
+export function scratchDirBase(platform: NodeJS.Platform = process.platform): string {
+  const configured = configuredScratchBase();
+  if (configured !== undefined) return configured;
+  if (platform === "win32" && getConnectorMode() === "gateway") {
+    throw new Error(
+      `${SCRATCH_DIR_ENV} is not set: on Windows the gateway must grant this connector a scratch ` +
+        "directory, and the user temp directory is not one",
+    );
+  }
+  return tmpdir();
+}
+
+/**
+ * Run `body` with a fresh 0700 directory of its own, removed when `body` settles, success or
+ * failure. `prefix` names the directory (`nimbus-cfn-`, `nimbus-k8s-`).
+ */
+export async function withScratchDir<T>(
+  prefix: string,
+  body: (dir: string) => Promise<T>,
+): Promise<T> {
+  const base = scratchDirBase();
+  const dir = await mkdtemp(join(base, prefix));
+  try {
+    return await body(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+  }
+}

package/shared/run-cli-json.ts

@@ -1,4 +1,4 @@
-import { nimbusSpawn } from "./nimbus-spawn.ts";
+import { nimbusSpawn, type SpawnResult } from "./nimbus-spawn.ts";
 
 export type RunCliJsonResult = { ok: true; data: unknown } | { ok: false; message: string };
 
@@ -75,3 +75,19 @@ export async function runCliJsonThrowing(
   }
   return r.data;
 }
+
+/**
+ * Spawn `command` and hand back its exit code with its output, for a CLI whose non-zero exits are
+ * answers rather than failures (`terraform plan -detailed-exitcode` exits 2 for "changes";
+ * `kubectl diff` exits 1 for "differences"). The caller maps every code itself, so an
+ * unexpected one is never taken for success. An empty command is code 1, as nimbusSpawn reports.
+ */
+export async function runCliCode(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<SpawnResult> {
+  if (command.length === 0) {
+    return { code: 1, stdout: "", stderr: "empty command" };
+  }
+  return nimbusSpawn(command, env);
+}