@cursor/bdk 0.2.1

package/src/internal/cli-images.ts

@@ -0,0 +1,672 @@
+/**
+ * `agent-sdk images push|list|rm`: a team's container images for
+ * `persistent: true` agents. `push` first checks the image locally for
+ * what the hosted install needs (linux/amd64, bash, git, node, npm) by
+ * inspecting it and running one probe container, then streams
+ * `docker save <image>` through gzip into a temp file (hashing as it
+ * goes), reserves a slot under the team cap, uploads the parts to the
+ * presigned URLs the backend handed back, and finalizes. Bytes never pass
+ * through the Cursor backend.
+ */
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdtemp, open, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { type DeployCliOptions, prepare, renderApiError, renderTable } from "./cli-deploy.js";
+import { type ContainerImageInfo, DeployApiError } from "./deploy-client.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { MAX_CONTAINER_IMAGE_BYTES, validateContainerImageName } from "./hosting.js";
+
+/** Persistent VMs are x86_64; an arm64 image (Apple Silicon default) will not start there. */
+const REQUIRED_PLATFORM = "linux/amd64";
+/** Same floor as `engines.node` in this package: the image runs `agent-sdk serve`. */
+const MIN_NODE_VERSION: readonly [number, number] = [22, 13];
+/** glibc Debian-family bases are what the hosted install is exercised on. */
+const KNOWN_GOOD_OS_IDS: ReadonlySet<string> = new Set(["debian", "ubuntu"]);
+const UPLOAD_CONCURRENCY = 4;
+const UPLOAD_ATTEMPTS = 3;
+/** Same anchor the backend's cap error points at. */
+const IMAGES_DASHBOARD_URL = "https://cursor.com/dashboard/deployed-agents#images";
+
+/**
+ * What a container reports about itself when asked; every key may be
+ * missing or empty when the tool is absent. `os` / `osLike` come from
+ * `/etc/os-release` `ID` / `ID_LIKE`.
+ */
+export type ImageProbe = Partial<
+  Record<"bash" | "git" | "node" | "npm" | "user" | "os" | "osLike", string>
+>;
+
+/**
+ * POSIX `sh` body run inside the image (host shell never sees it). Prints
+ * one `key=value` per line; a missing tool prints an empty value.
+ */
+const PROBE_SCRIPT = [
+  'echo "bash=$(command -v bash 2>/dev/null || true)"',
+  'echo "git=$(command -v git 2>/dev/null || true)"',
+  'echo "node=$(node --version 2>/dev/null || true)"',
+  'echo "npm=$(npm --version 2>/dev/null || true)"',
+  'echo "user=$(id -un 2>/dev/null || id -u 2>/dev/null || true)"',
+  'if [ -r /etc/os-release ]; then . /etc/os-release; echo "os=${ID:-}"; echo "osLike=${ID_LIKE:-}"; fi',
+].join("; ");
+
+/** What `push` needs from the local Docker daemon; injectable for tests. */
+export interface DockerImageSource {
+  /** `docker image inspect`: id, os/arch and uncompressed size, or undefined when the image is not local. */
+  inspect(image: string): Promise<{ id: string; platform: string; sizeBytes: number } | undefined>;
+  /**
+   * `docker run --rm --entrypoint sh <image> -c <probe>`: what the image
+   * has on PATH and who it runs as, or undefined when no container could
+   * run at all (no `sh`, or the daemon refused).
+   */
+  probe(image: string): Promise<ImageProbe | undefined>;
+  /** `docker save`: the image as a tar stream. */
+  save(image: string): Readable;
+}
+
+function parseProbe(stdout: string): ImageProbe {
+  const probe: ImageProbe = {};
+  for (const line of stdout.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq <= 0) {
+      continue;
+    }
+    const key = line.slice(0, eq) as keyof ImageProbe;
+    if (
+      key === "bash" ||
+      key === "git" ||
+      key === "node" ||
+      key === "npm" ||
+      key === "user" ||
+      key === "os" ||
+      key === "osLike"
+    ) {
+      probe[key] = line.slice(eq + 1).trim();
+    }
+  }
+  return probe;
+}
+
+/** `v22.14.0` → `[22, 14]`; undefined for anything else. */
+function parseNodeVersion(raw: string): [number, number] | undefined {
+  const match = /^v?(\d+)\.(\d+)(?:\.\d+)?/.exec(raw.trim());
+  if (match === null) {
+    return undefined;
+  }
+  return [Number(match[1]), Number(match[2])];
+}
+
+function nodeMeetsFloor(version: [number, number]): boolean {
+  return (
+    version[0] > MIN_NODE_VERSION[0] ||
+    (version[0] === MIN_NODE_VERSION[0] && version[1] >= MIN_NODE_VERSION[1])
+  );
+}
+
+type ImageCheck = {
+  label: string;
+  value: string;
+  status: "ok" | "warning" | "failed";
+  /** Shown under the row for warnings and failures. */
+  detail?: string;
+};
+
+/**
+ * What the hosted install needs from the image, decided from `inspect` and
+ * `probe`. Failures stop the push; warnings print and continue.
+ */
+export function checkImage(
+  inspected: { platform: string },
+  probe: ImageProbe | undefined,
+): ImageCheck[] {
+  const checks: ImageCheck[] = [];
+  if (inspected.platform === REQUIRED_PLATFORM) {
+    checks.push({ label: "platform", value: inspected.platform, status: "ok" });
+  } else {
+    checks.push({
+      label: "platform",
+      value: inspected.platform,
+      status: "failed",
+      detail: `Hosted agents run on ${REQUIRED_PLATFORM}. Rebuild with \`docker buildx build --platform ${REQUIRED_PLATFORM} …\`.`,
+    });
+  }
+  if (probe === undefined) {
+    checks.push({
+      label: "shell",
+      value: "no sh",
+      status: "failed",
+      detail:
+        "The image could not run `sh`. Start from a standard Debian or Ubuntu base such as node:22-bookworm-slim.",
+    });
+    return checks;
+  }
+  for (const tool of ["bash", "git"] as const) {
+    const path = probe[tool] ?? "";
+    checks.push(
+      path === ""
+        ? {
+            label: tool,
+            value: "missing",
+            status: "failed",
+            detail: `Install ${tool} in the image (\`apt-get install -y ${tool}\`).`,
+          }
+        : { label: tool, value: path, status: "ok" },
+    );
+  }
+  const nodeRaw = probe.node ?? "";
+  const nodeVersion = parseNodeVersion(nodeRaw);
+  const floor = `${MIN_NODE_VERSION[0]}.${MIN_NODE_VERSION[1]}`;
+  if (nodeVersion === undefined) {
+    checks.push({
+      label: "node",
+      value: nodeRaw === "" ? "missing" : nodeRaw,
+      status: "failed",
+      detail: `Node.js ${floor} or newer must be on PATH; the image runs \`${CLI} serve\`.`,
+    });
+  } else if (!nodeMeetsFloor(nodeVersion)) {
+    checks.push({
+      label: "node",
+      value: nodeRaw,
+      status: "failed",
+      detail: `Node.js ${floor} or newer is required.`,
+    });
+  } else {
+    checks.push({ label: "node", value: nodeRaw, status: "ok" });
+  }
+  const npm = probe.npm ?? "";
+  checks.push(
+    npm === ""
+      ? {
+          label: "npm",
+          value: "missing",
+          status: "failed",
+          detail: "npm must be on PATH; the hosted install runs it.",
+        }
+      : { label: "npm", value: npm, status: "ok" },
+  );
+  const user = probe.user ?? "";
+  checks.push(
+    user === "" || user === "root" || user === "0"
+      ? { label: "user", value: user === "" ? "root" : user, status: "ok" }
+      : {
+          label: "user",
+          value: user,
+          status: "warning",
+          detail:
+            "The image runs as a non-root user. The hosted state directory is mounted root-owned, so installs may fail to write it; prefer no USER instruction or USER root.",
+        },
+  );
+  const osIds = [probe.os ?? "", ...(probe.osLike ?? "").split(/\s+/)]
+    .map(id => id.trim().toLowerCase())
+    .filter(id => id !== "");
+  const osValue = probe.os === undefined || probe.os === "" ? "unknown" : probe.os;
+  if (osIds.some(id => KNOWN_GOOD_OS_IDS.has(id))) {
+    checks.push({ label: "base", value: osValue, status: "ok" });
+  } else if (osIds.includes("alpine")) {
+    checks.push({
+      label: "base",
+      value: osValue,
+      status: "warning",
+      detail:
+        "Alpine is musl-based; native Node modules without musl builds fail at install. Debian or Ubuntu bases are known to work.",
+    });
+  } else {
+    checks.push({
+      label: "base",
+      value: osValue,
+      status: "warning",
+      detail:
+        "Could not identify a Debian or Ubuntu base. Other distributions may fail when the VM starts; node:22-bookworm-slim is a known-good starting point.",
+    });
+  }
+  return checks;
+}
+
+function renderChecks(image: string, checks: ImageCheck[]): string {
+  const width = Math.max(...checks.map(check => check.label.length));
+  const valueWidth = Math.max(...checks.map(check => check.value.length));
+  const lines = [`Checking ${image}…`];
+  for (const check of checks) {
+    lines.push(
+      `  ${check.label.padEnd(width)}  ${check.value.padEnd(valueWidth)}  ${check.status}`,
+    );
+    if (check.detail !== undefined && check.status !== "ok") {
+      lines.push(`    ${check.detail}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export interface ImagesCliOptions extends DeployCliOptions {
+  docker?: DockerImageSource;
+}
+
+function runDocker(
+  args: string[],
+): Promise<{ code: number | null; stdout: string; stderr: string }> {
+  return new Promise(resolvePromise => {
+    const child = spawn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", chunk => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", chunk => {
+      stderr += String(chunk);
+    });
+    child.on("error", error => resolvePromise({ code: 1, stdout: "", stderr: error.message }));
+    child.on("close", code => resolvePromise({ code, stdout, stderr }));
+  });
+}
+
+/**
+ * Real Docker. A multi-platform image (an arm64 laptop pulling
+ * `--platform linux/amd64`) reports no os/arch at the top level, so inspect
+ * and save ask for the target platform explicitly where the daemon supports
+ * it (Docker 28+); older daemons fall back to the single-platform fields.
+ */
+function shellDocker(): DockerImageSource {
+  let savePlatform = false;
+  const format = "{{.Id}} {{.Os}}/{{.Architecture}} {{.Size}}";
+  const parse = (stdout: string) => {
+    const [id, platform, size] = stdout.trim().split(" ");
+    if (id === undefined || platform === undefined || size === undefined) {
+      return undefined;
+    }
+    return { id, platform, sizeBytes: Number(size) };
+  };
+  return {
+    async inspect(image) {
+      const scoped = await runDocker([
+        "image",
+        "inspect",
+        "--platform",
+        REQUIRED_PLATFORM,
+        image,
+        "--format",
+        format,
+      ]);
+      const variant = scoped.code === 0 ? parse(scoped.stdout) : undefined;
+      // An image with no linux/amd64 variant answers the scoped inspect
+      // with the manifest list itself: no os/arch. Fall through so the
+      // plain inspect names the platform it does have.
+      if (variant !== undefined && variant.platform !== "/") {
+        savePlatform = true;
+        return variant;
+      }
+      // Older daemon, a missing image, or one with no linux/amd64 variant:
+      // the plain inspect tells those apart (absent vs. the wrong platform).
+      const plain = await runDocker(["image", "inspect", image, "--format", format]);
+      return plain.code === 0 ? parse(plain.stdout) : undefined;
+    },
+    async probe(image) {
+      // Same platform selection as save: on an arm64 host Docker runs the
+      // amd64 variant under emulation, which is enough for `command -v`.
+      const run = await runDocker([
+        "run",
+        "--rm",
+        "--pull=never",
+        ...(savePlatform ? ["--platform", REQUIRED_PLATFORM] : []),
+        "--entrypoint",
+        "sh",
+        image,
+        "-c",
+        PROBE_SCRIPT,
+      ]);
+      return run.code === 0 ? parseProbe(run.stdout) : undefined;
+    },
+    save(image) {
+      const child = spawn(
+        "docker",
+        savePlatform ? ["save", "--platform", REQUIRED_PLATFORM, image] : ["save", image],
+        { stdio: ["ignore", "pipe", "inherit"] },
+      );
+      const stream = child.stdout;
+      child.on("close", code => {
+        if (code !== 0) {
+          stream.destroy(new Error(`docker save exited with ${code}`));
+        }
+      });
+      return stream;
+    },
+  };
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes >= 1024 ** 3) {
+    return `${(bytes / 1024 ** 3).toFixed(2)} GiB`;
+  }
+  if (bytes >= 1024 ** 2) {
+    return `${(bytes / 1024 ** 2).toFixed(1)} MiB`;
+  }
+  return `${Math.ceil(bytes / 1024)} KiB`;
+}
+
+async function saveCompressed(
+  docker: DockerImageSource,
+  image: string,
+  path: string,
+): Promise<{ sha256: string; sizeBytes: number }> {
+  const hash = createHash("sha256");
+  await pipeline(
+    docker.save(image),
+    createGzip(),
+    async function* (source) {
+      for await (const chunk of source) {
+        hash.update(chunk as Buffer);
+        yield chunk;
+      }
+    },
+    createWriteStream(path),
+  );
+  return {
+    sha256: hash.digest("hex"),
+    sizeBytes: (await stat(path)).size,
+  };
+}
+
+async function uploadPart(
+  fetchImpl: typeof fetch,
+  path: string,
+  part: { partNumber: number; url: string },
+  range: { start: number; end: number },
+): Promise<string> {
+  const handle = await open(path, "r");
+  try {
+    const length = range.end - range.start;
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, range.start);
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= UPLOAD_ATTEMPTS; attempt++) {
+      try {
+        const response = await fetchImpl(part.url, {
+          method: "PUT",
+          body: buffer,
+          headers: { "content-length": String(length) },
+        });
+        if (!response.ok) {
+          throw new Error(
+            `part ${part.partNumber}: HTTP ${response.status} ${await response.text()}`,
+          );
+        }
+        const etag = response.headers.get("etag");
+        if (etag === null || etag === "") {
+          throw new Error(`part ${part.partNumber}: S3 returned no ETag`);
+        }
+        return etag;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError;
+  } finally {
+    await handle.close();
+  }
+}
+
+async function uploadParts(
+  fetchImpl: typeof fetch,
+  path: string,
+  sizeBytes: number,
+  upload: {
+    partSizeBytes: number;
+    parts: Array<{ partNumber: number; url: string }>;
+  },
+  onPart: (done: number, total: number) => void,
+): Promise<Array<{ partNumber: number; etag: string }>> {
+  const queue = [...upload.parts];
+  const results: Array<{ partNumber: number; etag: string }> = [];
+  let done = 0;
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const part = queue.shift();
+      if (part === undefined) {
+        return;
+      }
+      const start = (part.partNumber - 1) * upload.partSizeBytes;
+      const end = Math.min(start + upload.partSizeBytes, sizeBytes);
+      const etag = await uploadPart(fetchImpl, path, part, { start, end });
+      results.push({ partNumber: part.partNumber, etag });
+      done++;
+      onPart(done, upload.parts.length);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, queue.length) }, worker));
+  return results.sort((a, b) => a.partNumber - b.partNumber);
+}
+
+export async function cmdImagesPush(
+  args: { image: string | undefined; name: string | undefined },
+  options: ImagesCliOptions,
+): Promise<number> {
+  const err = options.err ?? ((text: string) => void process.stderr.write(text));
+  if (args.image === undefined || args.image === "") {
+    err(`Usage: ${CLI} images push <local-image> --name <name> [--team <id>]\n`);
+    return 1;
+  }
+  if (args.name === undefined || args.name === "") {
+    err(`--name is required: ${CLI} images push ${args.image} --name <name>\n`);
+    return 1;
+  }
+  const nameError = validateContainerImageName(args.name);
+  if (nameError !== undefined) {
+    err(`${nameError}\n`);
+    return 1;
+  }
+  const out = options.out ?? ((text: string) => void process.stdout.write(text));
+  const docker = options.docker ?? shellDocker();
+  const inspected = await docker.inspect(args.image);
+  if (inspected === undefined) {
+    err(
+      `No local image named ${args.image}. Build or pull it first (\`docker image ls\` shows what is available).\n`,
+    );
+    return 1;
+  }
+  // Everything the hosted install needs is knowable locally; decide it
+  // before signing in or moving any bytes. The platform check gates the
+  // probe: a wrong-arch container cannot run here to be probed.
+  const checks = checkImage(
+    inspected,
+    inspected.platform === REQUIRED_PLATFORM ? await docker.probe(args.image) : undefined,
+  ).filter(check => inspected.platform === REQUIRED_PLATFORM || check.label === "platform");
+  if (options.json !== true) {
+    out(renderChecks(args.image, checks));
+  }
+  const failed = checks.filter(check => check.status === "failed");
+  if (failed.length > 0) {
+    err(
+      `${args.image} cannot run as a hosted agent image:\n${failed
+        .map(check => `  ${check.label}: ${check.value}. ${check.detail ?? ""}`)
+        .join("\n")}\n`,
+    );
+    return 1;
+  }
+
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  const fetchImpl = options.fetchImpl ?? fetch;
+  // `docker save` of a real image takes minutes; learn about a full team
+  // before paying for it. The backend re-checks at begin.
+  let listed: { images: ContainerImageInfo[]; limit: number };
+  try {
+    listed = await ctx.client.listContainerImages({ teamId: ctx.teamId });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (
+    listed.images.length >= listed.limit &&
+    !listed.images.some(image => image.name === args.name)
+  ) {
+    ctx.err(
+      `${listed.images.length} of ${listed.limit} images used; delete some at ${IMAGES_DASHBOARD_URL} or with \`${CLI} images rm <name>\`.\n`,
+    );
+    return 1;
+  }
+  const dir = await mkdtemp(join(tmpdir(), "agent-sdk-image-"));
+  const tarball = join(dir, "image.tar.gz");
+  try {
+    if (!ctx.json) {
+      ctx.out(`Saving ${args.image} (${formatBytes(inspected.sizeBytes)} uncompressed)…\n`);
+    }
+    const saved = await saveCompressed(docker, args.image, tarball);
+    if (saved.sizeBytes > MAX_CONTAINER_IMAGE_BYTES) {
+      err(
+        `Compressed image is ${formatBytes(saved.sizeBytes)}; the limit is ${formatBytes(MAX_CONTAINER_IMAGE_BYTES)}.\n`,
+      );
+      return 1;
+    }
+
+    const upload = await ctx.client.beginContainerImageUpload({
+      teamId: ctx.teamId,
+      name: args.name,
+      sizeBytes: saved.sizeBytes,
+      sha256: saved.sha256,
+      dockerImageId: inspected.id,
+      platform: inspected.platform,
+    });
+    if (!ctx.json) {
+      ctx.out(
+        `Uploading ${formatBytes(saved.sizeBytes)} in ${upload.parts.length} part${upload.parts.length === 1 ? "" : "s"}…\n`,
+      );
+    }
+    const parts = await uploadParts(fetchImpl, tarball, saved.sizeBytes, upload, (done, total) => {
+      if (!ctx.json && total > 1) {
+        ctx.out(`  ${done}/${total}\n`);
+      }
+    });
+    const image = await ctx.client.finalizeContainerImage({
+      teamId: ctx.teamId,
+      name: args.name,
+      uploadId: upload.uploadId,
+      parts,
+    });
+    if (ctx.json) {
+      ctx.out(`${JSON.stringify({ image }, null, 2)}\n`);
+    } else {
+      ctx.out(
+        `Pushed ${image.name} (${formatBytes(image.sizeBytes)}, sha256 ${saved.sha256.slice(0, 12)}).\n` +
+          `Use it from a persistent agent: defineAgent({ persistent: true, hosting: { image: "${image.name}" } }).\n`,
+      );
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof DeployApiError) {
+      return renderApiError(error, ctx.err);
+    }
+    ctx.err(
+      `Push failed: ${error instanceof Error ? error.message : String(error)}\nRun the same command again to retry.\n`,
+    );
+    return 1;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+export async function cmdImagesList(options: DeployCliOptions): Promise<number> {
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let listed: { images: ContainerImageInfo[]; limit: number };
+  try {
+    listed = await ctx.client.listContainerImages({ teamId: ctx.teamId });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify(listed, null, 2)}\n`);
+    return 0;
+  }
+  if (listed.images.length === 0) {
+    ctx.out(
+      `No images pushed yet. Push one with \`${CLI} images push <local-image> --name <name>\`.\n`,
+    );
+    return 0;
+  }
+  ctx.out(
+    `${renderTable(
+      ["NAME", "SIZE", "PLATFORM", "SHA256", "PUSHED"],
+      listed.images.map(image => [
+        image.name,
+        formatBytes(image.sizeBytes),
+        image.platform ?? "",
+        image.sha256?.slice(0, 12) ?? "",
+        image.pushedAt,
+      ]),
+    )}\n${listed.images.length} of ${listed.limit} images.\n`,
+  );
+  return 0;
+}
+
+export async function cmdImagesRm(
+  name: string | undefined,
+  options: DeployCliOptions,
+): Promise<number> {
+  if (name === undefined || name === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} images rm <name> [--team <id>]\n`,
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  try {
+    await ctx.client.deleteContainerImage({ teamId: ctx.teamId, name });
+  } catch (error) {
+    if (error instanceof DeployApiError && error.status === 404) {
+      ctx.err(`No image named ${name} — check \`${CLI} images list\`.\n`);
+      return 1;
+    }
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ removed: name }, null, 2)}\n`);
+  } else {
+    ctx.out(`Removed image ${name}.\n`);
+  }
+  return 0;
+}
+
+/** Test seam: a `DockerImageSource` over in-memory bytes. */
+export function memoryDockerImageSource(
+  images: Record<
+    string,
+    {
+      id: string;
+      platform: string;
+      tar: Buffer;
+      /** Omit for an image whose container cannot run `sh`. */
+      probe?: ImageProbe;
+    }
+  >,
+): DockerImageSource {
+  return {
+    async inspect(image) {
+      const found = images[image];
+      return found === undefined
+        ? undefined
+        : {
+            id: found.id,
+            platform: found.platform,
+            sizeBytes: found.tar.length,
+          };
+    },
+    async probe(image) {
+      return images[image]?.probe;
+    },
+    save(image) {
+      const found = images[image];
+      return Readable.from(found === undefined ? [] : [found.tar]);
+    },
+  };
+}