@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/cli-images.ts

@@ -1,672 +0,0 @@
-/**
- * `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]);
-    },
-  };
-}