@anvia/sandbox 0.4.1 → 0.5.0

package/dist/cli.js

@@ -0,0 +1,836 @@
+#!/usr/bin/env node
+import {
+  assertDockerCli
+} from "./chunk-FTNNCT6S.js";
+
+// src/cli.ts
+import { lstat, mkdir, readFile, rm, writeFile } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// src/image-builder.ts
+var defaultSandboxImageVersions = {
+  node: "24.18.0",
+  pnpm: "11.0.4",
+  bun: "1.3.14",
+  python: "3.13.14",
+  uv: "0.11.29",
+  playwright: "1.61.0"
+};
+var artifactPythonPackages = [
+  "matplotlib==3.11.1",
+  "seaborn==0.13.2",
+  "Pillow==12.3.0",
+  "ReportLab==5.0.0",
+  "pypdf==6.14.2",
+  "pandas==3.0.3",
+  "openpyxl==3.1.5",
+  "XlsxWriter==3.2.9",
+  "python-docx==1.2.0"
+];
+var runtimeOrder = ["node", "bun", "python"];
+var featureOrder = ["artifacts", "playwright"];
+var commonAptPackages = ["bash", "ca-certificates", "findutils", "libstdc++6", "procps"];
+function resolveSandboxImageSpec(input) {
+  validateName(input.name);
+  const runtimes = new Set(input.runtimes ?? []);
+  const features = new Set(input.features ?? []);
+  const packages = {
+    apt: unique(input.packages?.apt ?? []),
+    npm: unique(input.packages?.npm ?? []),
+    uv: unique(input.packages?.uv ?? [])
+  };
+  for (const runtime of runtimes) validateRuntime(runtime);
+  for (const feature of features) validateFeature(feature);
+  for (const packageName of packages.apt) validateAptPackage(packageName);
+  for (const packageSpec of packages.npm) parseNpmPackageSpec(packageSpec);
+  for (const requirement of packages.uv) validateUvRequirement(requirement);
+  if (features.has("artifacts") || packages.uv.length > 0) runtimes.add("python");
+  if (features.has("playwright")) runtimes.add("node");
+  if (packages.npm.length > 0 && !runtimes.has("node") && !runtimes.has("bun")) {
+    runtimes.add("node");
+  }
+  if (runtimes.size === 0) {
+    throw new Error("Select at least one runtime or feature.");
+  }
+  const versions = { ...defaultSandboxImageVersions, ...input.versions };
+  for (const [name, version] of Object.entries(versions)) validateVersion(name, version);
+  const tag = input.tag ?? `anvia-sandbox-${input.name}:latest`;
+  validateImageTag(tag);
+  return {
+    name: input.name,
+    tag,
+    runtimes: runtimeOrder.filter((runtime) => runtimes.has(runtime)),
+    features: featureOrder.filter((feature) => features.has(feature)),
+    packages,
+    versions
+  };
+}
+function renderSandboxImageContext(spec, generatorVersion) {
+  const files = /* @__PURE__ */ new Map();
+  const pythonRequirements = [
+    ...spec.features.includes("artifacts") ? artifactPythonPackages : [],
+    ...spec.packages.uv
+  ];
+  const npmDependencies = npmDependenciesFor(spec);
+  files.set("Dockerfile", `${renderDockerfile(spec, pythonRequirements, npmDependencies)}
+`);
+  files.set(
+    ".dockerignore",
+    renderDockerignore(pythonRequirements.length > 0, npmDependencies.size > 0)
+  );
+  if (pythonRequirements.length > 0) {
+    files.set("pyproject.toml", renderPythonProject(spec, unique(pythonRequirements)));
+  }
+  if (npmDependencies.size > 0) {
+    files.set(
+      "package.json",
+      `${JSON.stringify(
+        {
+          private: true,
+          description: `Generated dependencies for ${spec.name}`,
+          dependencies: Object.fromEntries(npmDependencies)
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+  const generatedFiles = [...files.keys(), "anvia-sandbox.json"].sort();
+  const manifest = {
+    schemaVersion: 1,
+    generatedBy: {
+      package: "@anvia/sandbox",
+      version: generatorVersion
+    },
+    ...spec,
+    generatedFiles
+  };
+  files.set("anvia-sandbox.json", `${JSON.stringify(manifest, null, 2)}
+`);
+  return { manifest, files };
+}
+function unpinnedSandboxImagePackages(spec) {
+  const unpinned = [];
+  for (const value of spec.packages.npm) {
+    if (parseNpmPackageSpec(value).version === "latest") unpinned.push(value);
+  }
+  for (const value of spec.packages.uv) {
+    if (!/===|==|@\s*https?:/i.test(value)) unpinned.push(value);
+  }
+  return unpinned;
+}
+function renderDockerfile(spec, pythonRequirements, npmDependencies) {
+  const hasNode = spec.runtimes.includes("node");
+  const hasBun = spec.runtimes.includes("bun");
+  const hasPython = spec.runtimes.includes("python");
+  const hasPlaywright = spec.features.includes("playwright");
+  const lines = [
+    "# Generated by @anvia/sandbox. Edit the manifest and regenerate instead of editing this file."
+  ];
+  if (hasNode) lines.push(`FROM node:${spec.versions.node}-bookworm-slim AS node-runtime`);
+  if (hasPython) lines.push(`FROM python:${spec.versions.python}-slim-bookworm AS python-runtime`);
+  if (hasBun) lines.push(`FROM oven/bun:${spec.versions.bun}-slim AS bun-runtime`);
+  if (hasPython) lines.push(`FROM ghcr.io/astral-sh/uv:${spec.versions.uv} AS uv-runtime`);
+  if (hasPlaywright) {
+    lines.push(`FROM mcr.microsoft.com/playwright:v${spec.versions.playwright}-noble AS final`);
+  } else if (hasPython) {
+    lines.push("FROM python-runtime AS final");
+  } else if (hasNode) {
+    lines.push("FROM node-runtime AS final");
+  } else {
+    lines.push("FROM bun-runtime AS final");
+  }
+  lines.push("", "USER root");
+  if (hasPython && (hasPlaywright || !isFinalRuntime(spec, "python"))) {
+    lines.push("COPY --from=python-runtime /usr/local/ /usr/local/");
+  }
+  if (hasNode && (hasPlaywright || !isFinalRuntime(spec, "node"))) {
+    lines.push("COPY --from=node-runtime /usr/local/bin/ /usr/local/bin/");
+    lines.push(
+      "COPY --from=node-runtime /usr/local/lib/node_modules/ /usr/local/lib/node_modules/"
+    );
+  }
+  if (hasBun && !isFinalRuntime(spec, "bun")) {
+    lines.push("COPY --from=bun-runtime /usr/local/bin/bun /usr/local/bin/bun");
+    lines.push("RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx");
+  }
+  if (hasPython) {
+    lines.push("COPY --from=uv-runtime /uv /uvx /usr/local/bin/");
+  }
+  const aptPackages = unique([
+    ...commonAptPackages,
+    ...spec.features.includes("artifacts") ? ["fonts-dejavu-core"] : [],
+    ...spec.packages.apt
+  ]).sort();
+  lines.push(
+    "",
+    "RUN apt-get update \\",
+    `  && apt-get install -y --no-install-recommends ${aptPackages.map(shellQuote).join(" ")} \\`,
+    "  && rm -rf /var/lib/apt/lists/*"
+  );
+  if (hasNode) {
+    lines.push(
+      "",
+      `RUN npm install --global ${shellQuote(`pnpm@${spec.versions.pnpm}`)} --no-audit --no-fund \\`,
+      "  && npm cache clean --force"
+    );
+  }
+  if (pythonRequirements.length > 0) {
+    lines.push(
+      "",
+      "COPY pyproject.toml /opt/anvia-python/pyproject.toml",
+      "RUN cd /opt/anvia-python \\",
+      "  && uv sync --no-dev --no-cache --no-install-project",
+      "ENV VIRTUAL_ENV=/opt/anvia-python/.venv",
+      "ENV PATH=/opt/anvia-python/.venv/bin:$PATH"
+    );
+  }
+  if (npmDependencies.size > 0) {
+    lines.push("", "COPY package.json /opt/anvia-js/package.json");
+    if (hasNode) {
+      lines.push(
+        "RUN npm install --prefix /opt/anvia-js --omit=dev --no-audit --no-fund \\",
+        "  && ln -s /opt/anvia-js/node_modules /node_modules \\",
+        "  && npm cache clean --force"
+      );
+    } else {
+      lines.push(
+        "RUN cd /opt/anvia-js \\",
+        "  && bun install --production --no-save \\",
+        "  && ln -s /opt/anvia-js/node_modules /node_modules"
+      );
+    }
+    lines.push("ENV NODE_PATH=/opt/anvia-js/node_modules");
+    lines.push("ENV PATH=/opt/anvia-js/node_modules/.bin:$PATH");
+  }
+  lines.push(
+    "",
+    ...hasPlaywright ? ["ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright"] : [],
+    "RUN mkdir -p /workspace",
+    "WORKDIR /workspace",
+    "ENTRYPOINT []",
+    `CMD ["sh", "-c", "trap 'exit 0' TERM INT; while :; do sleep 3600 & wait $!; done"]`
+  );
+  return lines.join("\n");
+}
+function renderDockerignore(hasPython, hasNpm) {
+  return [
+    "**",
+    "!Dockerfile",
+    "!.dockerignore",
+    "!anvia-sandbox.json",
+    ...hasPython ? ["!pyproject.toml"] : [],
+    ...hasNpm ? ["!package.json"] : [],
+    ""
+  ].join("\n");
+}
+function renderPythonProject(spec, requirements) {
+  const [major, minor] = spec.versions.python.split(".");
+  return [
+    "[project]",
+    `name = ${JSON.stringify(`anvia-sandbox-${spec.name}`)}`,
+    'version = "0.0.0"',
+    `requires-python = ${JSON.stringify(`>=${major}.${minor}`)}`,
+    "dependencies = [",
+    ...requirements.map((requirement) => `  ${JSON.stringify(requirement)},`),
+    "]",
+    ""
+  ].join("\n");
+}
+function npmDependenciesFor(spec) {
+  const dependencies = /* @__PURE__ */ new Map();
+  if (spec.features.includes("playwright")) {
+    dependencies.set("playwright", spec.versions.playwright);
+  }
+  for (const packageSpec of spec.packages.npm) {
+    const parsed = parseNpmPackageSpec(packageSpec);
+    if (dependencies.has(parsed.name)) {
+      throw new Error(`Duplicate npm package: ${parsed.name}`);
+    }
+    dependencies.set(parsed.name, parsed.version);
+  }
+  return new Map([...dependencies.entries()].sort(([left], [right]) => left.localeCompare(right)));
+}
+function isFinalRuntime(spec, runtime) {
+  if (spec.features.includes("playwright")) return false;
+  if (spec.runtimes.includes("python")) return runtime === "python";
+  if (spec.runtimes.includes("node")) return runtime === "node";
+  return runtime === "bun";
+}
+function validateName(name) {
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(name)) {
+    throw new Error(
+      "Image name must be 1-63 lowercase letters, numbers, or hyphens and cannot start with a hyphen."
+    );
+  }
+}
+function validateRuntime(runtime) {
+  if (!runtimeOrder.includes(runtime)) {
+    throw new Error(`Unknown runtime: ${runtime}. Expected node, bun, or python.`);
+  }
+}
+function validateFeature(feature) {
+  if (!featureOrder.includes(feature)) {
+    throw new Error(`Unknown feature: ${feature}. Expected artifacts or playwright.`);
+  }
+}
+function validateAptPackage(packageName) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9.+:~=-]*$/.test(packageName)) {
+    throw new Error(`Invalid apt package: ${packageName}`);
+  }
+}
+function parseNpmPackageSpec(packageSpec) {
+  if (/\s/.test(packageSpec) || hasControlCharacter(packageSpec)) {
+    throw new Error(`Invalid npm package spec: ${packageSpec}`);
+  }
+  const separator = packageSpec.startsWith("@") ? packageSpec.indexOf("@", packageSpec.indexOf("/") + 1) : packageSpec.indexOf("@");
+  const name = separator === -1 ? packageSpec : packageSpec.slice(0, separator);
+  const version = separator === -1 ? "latest" : packageSpec.slice(separator + 1);
+  if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i.test(name) || !version) {
+    throw new Error(`Invalid npm package spec: ${packageSpec}`);
+  }
+  if (/[\s'"`$;&|<>\\]/.test(version) || hasControlCharacter(version)) {
+    throw new Error(`Invalid npm package version in: ${packageSpec}`);
+  }
+  return { name, version };
+}
+function validateUvRequirement(requirement) {
+  if (!requirement || requirement.startsWith("-") || hasControlCharacter(requirement)) {
+    throw new Error(`Invalid uv package requirement: ${requirement}`);
+  }
+}
+function validateVersion(name, version) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(version)) {
+    throw new Error(`Invalid ${name} version: ${version}`);
+  }
+}
+function validateImageTag(tag) {
+  if (!tag || tag.startsWith("-") || tag.includes("@") || /\s/.test(tag) || hasControlCharacter(tag)) {
+    throw new Error(`Invalid Docker image tag: ${tag}`);
+  }
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function hasControlCharacter(value) {
+  return [...value].some((character) => character.charCodeAt(0) < 32);
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+// src/cli.ts
+var generatedFileNames = /* @__PURE__ */ new Set([
+  ".dockerignore",
+  "Dockerfile",
+  "anvia-sandbox.json",
+  "package.json",
+  "pyproject.toml"
+]);
+var commonAptPackages2 = [
+  { value: "git", label: "Git", hint: "Source control and repository operations" },
+  { value: "curl", label: "curl", hint: "HTTP downloads and API debugging" },
+  { value: "jq", label: "jq", hint: "JSON processing from the shell" },
+  { value: "ffmpeg", label: "FFmpeg", hint: "Audio and video processing" },
+  { value: "imagemagick", label: "ImageMagick", hint: "Image conversion and editing" },
+  { value: "poppler-utils", label: "Poppler tools", hint: "PDF inspection and conversion" },
+  { value: "libreoffice", label: "LibreOffice", hint: "Large; office document conversion" }
+];
+var commonNpmPackages = [
+  { value: "pdfkit@0.19.1", label: "PDFKit", hint: "Generate PDF documents" },
+  { value: "sharp@0.35.3", label: "Sharp", hint: "Resize and transform images" },
+  { value: "exceljs@4.4.0", label: "ExcelJS", hint: "Read and write Excel workbooks" },
+  { value: "docx@9.7.1", label: "docx", hint: "Generate Word documents" },
+  { value: "pptxgenjs@4.0.1", label: "PptxGenJS", hint: "Generate PowerPoint presentations" }
+];
+var commonUvPackages = [
+  { value: "httpx==0.28.1", label: "HTTPX", hint: "Modern HTTP client" },
+  { value: "beautifulsoup4==4.15.0", label: "Beautiful Soup", hint: "HTML and XML parsing" },
+  { value: "scipy==1.18.0", label: "SciPy", hint: "Scientific computing" },
+  { value: "scikit-learn==1.9.0", label: "scikit-learn", hint: "Machine learning utilities" },
+  { value: "polars==1.42.1", label: "Polars", hint: "Fast dataframe processing" }
+];
+var defaultIo = {
+  log: console.log,
+  warn: console.warn,
+  error: console.error,
+  stdout: (chunk) => process.stdout.write(chunk),
+  stderr: (chunk) => process.stderr.write(chunk)
+};
+async function runCli(argv = process.argv.slice(2), cwd = process.cwd(), io = defaultIo, dependencies = {}) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    io.error(errorMessage(error));
+    io.log(helpText());
+    return 1;
+  }
+  if (options.help || options.command === void 0) {
+    io.log(helpText());
+    return 0;
+  }
+  if (options.command !== "create-image") {
+    io.error(`Unknown command: ${options.command}`);
+    io.log(helpText());
+    return 1;
+  }
+  try {
+    const shouldPrompt = options.name === void 0 || options.runtimes.length === 0 && options.features.length === 0 && options.npm.length === 0 && options.uv.length === 0;
+    if (shouldPrompt) {
+      const isTTY = dependencies.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY);
+      if (!isTTY) {
+        throw new Error(
+          "Non-interactive create-image requires --name and at least one --runtime or --feature."
+        );
+      }
+      const prompt = dependencies.prompt ?? promptForImage;
+      const result = await prompt(options);
+      if (result === void 0) return 130;
+      options = applyPromptResult(options, result);
+    }
+    const input = {
+      name: required(options.name, "Image name is required."),
+      runtimes: options.runtimes,
+      features: options.features,
+      packages: {
+        apt: options.apt,
+        npm: options.npm,
+        uv: options.uv
+      },
+      versions: options.versions
+    };
+    if (options.tag !== void 0) input.tag = options.tag;
+    const spec = resolveSandboxImageSpec(input);
+    const packageVersion = dependencies.packageVersion ?? await readPackageVersion();
+    const context = renderSandboxImageContext(spec, packageVersion);
+    const outputPath = path.resolve(
+      cwd,
+      options.output ?? path.join(".anvia", "sandbox-images", spec.name)
+    );
+    const displayPath = relativeDisplayPath(cwd, outputPath);
+    const unpinned = unpinnedSandboxImagePackages(spec);
+    if (unpinned.length > 0) {
+      io.warn(`Unpinned custom packages may change on rebuild: ${unpinned.join(", ")}`);
+    }
+    if (options.dryRun) {
+      printDryRun(context.files, displayPath, spec.tag, io);
+      return 0;
+    }
+    await writeImageContext(outputPath, context.manifest, context.files, options.force);
+    io.log(`Created ${displayPath}`);
+    if (!options.build) {
+      io.log("");
+      io.log("Build later:");
+      io.log(`  ${shellCommand([options.dockerPath, "build", "--tag", spec.tag, displayPath])}`);
+      printUsageSnippet(spec.tag, io);
+      return 0;
+    }
+    const buildImage = dependencies.buildImage ?? buildDockerImage;
+    await buildImage({
+      contextPath: outputPath,
+      tag: spec.tag,
+      dockerPath: options.dockerPath,
+      io
+    });
+    io.log(`Built ${spec.tag}`);
+    printUsageSnippet(spec.tag, io);
+    return 0;
+  } catch (error) {
+    io.error(errorMessage(error));
+    return 1;
+  }
+}
+async function promptForImage(options) {
+  assertInteractiveNodeVersion();
+  const prompts = await import("@clack/prompts");
+  prompts.intro("Create an Anvia sandbox image");
+  const nameResult = options.name ?? await prompts.text({
+    message: "Image name",
+    placeholder: "reports",
+    validate: (value) => /^[a-z0-9][a-z0-9-]{0,62}$/.test(value ?? "") ? void 0 : "Use 1-63 lowercase letters, numbers, or hyphens."
+  });
+  if (prompts.isCancel(nameResult)) return cancelPrompt(prompts);
+  const name = String(nameResult);
+  let runtimes = [...options.runtimes];
+  let features = [...options.features];
+  if (runtimes.length === 0 && features.length === 0 && options.npm.length === 0 && options.uv.length === 0) {
+    const capabilities = await prompts.multiselect({
+      message: "Select runtimes and features",
+      required: true,
+      options: [
+        { value: "node", label: "Node.js", hint: "Includes npm and pnpm" },
+        { value: "bun", label: "Bun", hint: "Includes bun and bunx" },
+        { value: "python", label: "Python", hint: "Includes uv and uvx" },
+        { value: "artifacts", label: "Reporting and artifacts", hint: "Adds Python automatically" },
+        { value: "playwright", label: "Playwright + Chromium", hint: "Adds Node.js automatically" }
+      ]
+    });
+    if (prompts.isCancel(capabilities)) return cancelPrompt(prompts);
+    runtimes = capabilities.filter(isRuntime);
+    features = capabilities.filter(isFeature);
+  }
+  const aptResult = await selectCommonPackages(
+    prompts,
+    "Select common apt tools (optional)",
+    commonAptPackages2,
+    options.apt
+  );
+  if (aptResult === void 0) return cancelPrompt(prompts);
+  const npmResult = await selectCommonPackages(
+    prompts,
+    "Select common npm libraries (optional)",
+    commonNpmPackages,
+    options.npm
+  );
+  if (npmResult === void 0) return cancelPrompt(prompts);
+  const uvResult = await selectCommonPackages(
+    prompts,
+    "Select common Python libraries with uv (optional)",
+    commonUvPackages,
+    options.uv
+  );
+  if (uvResult === void 0) return cancelPrompt(prompts);
+  const tagResult = options.tag ?? await prompts.text({
+    message: "Docker image tag",
+    initialValue: `anvia-sandbox-${name}:latest`
+  });
+  if (prompts.isCancel(tagResult)) return cancelPrompt(prompts);
+  const outputResult = options.output ?? await prompts.text({
+    message: "Generated source directory",
+    initialValue: path.join(".anvia", "sandbox-images", name)
+  });
+  if (prompts.isCancel(outputResult)) return cancelPrompt(prompts);
+  const buildResult = options.buildExplicit ? options.build : await prompts.confirm({ message: "Build the image now?", initialValue: true });
+  if (prompts.isCancel(buildResult)) return cancelPrompt(prompts);
+  const confirmed = await prompts.confirm({
+    message: "Create this sandbox image?",
+    initialValue: true
+  });
+  if (prompts.isCancel(confirmed) || !confirmed) return cancelPrompt(prompts);
+  prompts.outro("Configuration ready");
+  return {
+    name,
+    runtimes,
+    features,
+    apt: aptResult,
+    npm: npmResult,
+    uv: uvResult,
+    tag: String(tagResult),
+    output: String(outputResult),
+    build: Boolean(buildResult)
+  };
+}
+async function selectCommonPackages(prompts, message, options, existing) {
+  const commonValues = new Set(options.map((option) => option.value));
+  const result = await prompts.multiselect({
+    message,
+    required: false,
+    options: [...options],
+    initialValues: existing.filter((value) => commonValues.has(value))
+  });
+  if (prompts.isCancel(result)) return void 0;
+  return [.../* @__PURE__ */ new Set([...existing, ...result])];
+}
+function cancelPrompt(prompts) {
+  prompts.cancel("Image creation cancelled.");
+  return void 0;
+}
+async function buildDockerImage(input) {
+  await assertDockerCli(["build", "--tag", input.tag, input.contextPath], {
+    dockerPath: input.dockerPath,
+    onStdout: input.io.stdout,
+    onStderr: input.io.stderr
+  });
+}
+async function writeImageContext(outputPath, manifest, files, force) {
+  const outputStat = await safeLstat(outputPath);
+  if (outputStat?.isSymbolicLink()) {
+    throw new Error(`Refusing to write through symlink: ${outputPath}`);
+  }
+  if (outputStat !== void 0) {
+    if (!outputStat.isDirectory()) throw new Error(`Output path is not a directory: ${outputPath}`);
+    const previousManifest = await readGeneratedManifest(outputPath);
+    if (previousManifest === void 0) {
+      throw new Error(
+        `Output directory already exists but was not generated by @anvia/sandbox: ${outputPath}`
+      );
+    }
+    if (!force) throw new Error(`Output directory already exists. Use --force to regenerate it.`);
+    for (const filename of previousManifest.generatedFiles) {
+      const target = path.join(outputPath, filename);
+      const targetStat = await safeLstat(target);
+      if (targetStat?.isSymbolicLink()) throw new Error(`Refusing to replace symlink: ${target}`);
+      if (targetStat !== void 0) await rm(target);
+    }
+  } else {
+    await mkdir(outputPath, { recursive: true });
+  }
+  for (const [filename, content] of files) {
+    if (!generatedFileNames.has(filename))
+      throw new Error(`Unexpected generated filename: ${filename}`);
+    const target = path.join(outputPath, filename);
+    const targetStat = await safeLstat(target);
+    if (targetStat?.isSymbolicLink()) throw new Error(`Refusing to replace symlink: ${target}`);
+    await writeFile(target, content, "utf8");
+  }
+  if (!files.has("anvia-sandbox.json") || manifest.generatedFiles.length !== files.size) {
+    throw new Error("Generated image context manifest is inconsistent.");
+  }
+}
+async function readGeneratedManifest(outputPath) {
+  const manifestPath = path.join(outputPath, "anvia-sandbox.json");
+  const stat = await safeLstat(manifestPath);
+  if (stat === void 0) return void 0;
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`Invalid generated manifest: ${manifestPath}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Unable to read generated manifest: ${manifestPath}`, { cause: error });
+  }
+  if (!isGeneratedManifest(value)) {
+    throw new Error(
+      `Output manifest is not recognized as an @anvia/sandbox manifest: ${manifestPath}`
+    );
+  }
+  return value;
+}
+function isGeneratedManifest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  const generatedBy = record.generatedBy;
+  const files = record.generatedFiles;
+  return record.schemaVersion === 1 && generatedBy?.package === "@anvia/sandbox" && Array.isArray(files) && files.every((file) => typeof file === "string" && generatedFileNames.has(file));
+}
+async function safeLstat(target) {
+  try {
+    return await lstat(target);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function printDryRun(files, outputPath, tag, io) {
+  io.log(`Would create ${outputPath}`);
+  for (const [filename, content] of files) {
+    io.log("");
+    io.log(`--- ${filename}`);
+    io.log(content.trimEnd());
+  }
+  io.log("");
+  io.log(`Would build ${tag}`);
+}
+function printUsageSnippet(tag, io) {
+  io.log("");
+  io.log("Use with @anvia/sandbox:");
+  io.log("  const sandbox = new DockerSandbox({");
+  io.log(`    image: ${JSON.stringify(tag)},`);
+  io.log('    pull: "never",');
+  io.log("  });");
+}
+function applyPromptResult(options, result) {
+  const next = {
+    ...options,
+    name: result.name,
+    runtimes: result.runtimes,
+    features: result.features,
+    apt: result.apt,
+    npm: result.npm,
+    uv: result.uv,
+    build: result.build,
+    buildExplicit: true
+  };
+  if (result.tag !== void 0) next.tag = result.tag;
+  if (result.output !== void 0) next.output = result.output;
+  return next;
+}
+function parseArgs(argv) {
+  const options = {
+    runtimes: [],
+    features: [],
+    apt: [],
+    npm: [],
+    uv: [],
+    versions: {},
+    dockerPath: "docker",
+    build: true,
+    buildExplicit: false,
+    dryRun: false,
+    force: false,
+    help: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index] ?? "";
+    if (!argument.startsWith("-")) {
+      if (options.command !== void 0) throw new Error(`Unexpected argument: ${argument}`);
+      options.command = argument;
+      continue;
+    }
+    const [flag, inlineValue] = splitFlag(argument);
+    const value = () => inlineValue ?? required(argv[++index], `${flag} requires a value.`);
+    switch (flag) {
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      case "--name":
+        options.name = value();
+        break;
+      case "--tag":
+        options.tag = value();
+        break;
+      case "--output":
+        options.output = value();
+        break;
+      case "--runtime":
+        options.runtimes.push(parseRuntime(value()));
+        break;
+      case "--feature":
+        options.features.push(parseFeature(value()));
+        break;
+      case "--apt":
+        options.apt.push(value());
+        break;
+      case "--npm":
+        options.npm.push(value());
+        break;
+      case "--uv":
+        options.uv.push(value());
+        break;
+      case "--node-version":
+        options.versions.node = value();
+        break;
+      case "--pnpm-version":
+        options.versions.pnpm = value();
+        break;
+      case "--bun-version":
+        options.versions.bun = value();
+        break;
+      case "--python-version":
+        options.versions.python = value();
+        break;
+      case "--uv-version":
+        options.versions.uv = value();
+        break;
+      case "--playwright-version":
+        options.versions.playwright = value();
+        break;
+      case "--docker-path":
+        options.dockerPath = value();
+        break;
+      case "--no-build":
+        rejectInlineValue(flag, inlineValue);
+        options.build = false;
+        options.buildExplicit = true;
+        break;
+      case "--dry-run":
+        rejectInlineValue(flag, inlineValue);
+        options.dryRun = true;
+        break;
+      case "--force":
+        rejectInlineValue(flag, inlineValue);
+        options.force = true;
+        break;
+      default:
+        throw new Error(`Unknown option: ${flag}`);
+    }
+  }
+  return options;
+}
+function splitFlag(argument) {
+  const separator = argument.indexOf("=");
+  return separator === -1 ? [argument, void 0] : [argument.slice(0, separator), argument.slice(separator + 1)];
+}
+function rejectInlineValue(flag, value) {
+  if (value !== void 0) throw new Error(`${flag} does not accept a value.`);
+}
+function parseRuntime(value) {
+  if (isRuntime(value)) return value;
+  throw new Error(`Unknown runtime: ${value}. Expected node, bun, or python.`);
+}
+function parseFeature(value) {
+  if (isFeature(value)) return value;
+  throw new Error(`Unknown feature: ${value}. Expected artifacts or playwright.`);
+}
+function isRuntime(value) {
+  return value === "node" || value === "bun" || value === "python";
+}
+function isFeature(value) {
+  return value === "artifacts" || value === "playwright";
+}
+function assertInteractiveNodeVersion() {
+  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+  if (major < 20 || major === 20 && minor < 12) {
+    throw new Error("The interactive create-image wizard requires Node.js 20.12 or newer.");
+  }
+}
+async function readPackageVersion() {
+  const packageJson = JSON.parse(
+    await readFile(new URL("../package.json", import.meta.url), "utf8")
+  );
+  return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+}
+function relativeDisplayPath(cwd, target) {
+  const relative = path.relative(cwd, target);
+  return relative && !relative.startsWith("..") ? relative : target;
+}
+function shellCommand(args) {
+  return args.map(shellArgument).join(" ");
+}
+function shellArgument(value) {
+  if (/^[a-zA-Z0-9_./:@+-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function required(value, message) {
+  if (value === void 0 || value === "") throw new Error(message);
+  return value;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function helpText() {
+  return `Usage:
+  pnpm dlx @anvia/sandbox create-image [options]
+
+Options:
+  --name <slug>                  Image profile name
+  --runtime <node|bun|python>    Runtime to include; repeatable
+  --feature <artifacts|playwright>
+                                 Curated feature to include; repeatable
+  --apt <package>                Additional apt package; repeatable
+  --npm <package[@version]>      Additional npm package; repeatable
+  --uv <requirement>             Additional Python package installed with uv; repeatable
+  --tag <tag>                    Local image tag
+  --output <directory>           Generated context directory
+  --node-version <version>       Override Node.js version
+  --pnpm-version <version>       Override pnpm version
+  --bun-version <version>        Override Bun version
+  --python-version <version>     Override Python version
+  --uv-version <version>         Override uv version
+  --playwright-version <version> Override Playwright and browser image version
+  --docker-path <path>           Docker CLI path (default: docker)
+  --no-build                     Generate files without building
+  --dry-run                      Print generated files without writing or building
+  --force                        Regenerate a context previously created by this CLI
+  -h, --help                     Show this help
+
+Examples:
+  pnpm dlx @anvia/sandbox create-image
+  pnpm dlx @anvia/sandbox create-image --name reports --feature artifacts
+  pnpm dlx @anvia/sandbox create-image --name browser --runtime bun --feature playwright`;
+}
+var invokedPath = process.argv[1] === void 0 ? void 0 : path.resolve(process.argv[1]);
+if (invokedPath !== void 0 && invokedPath === fileURLToPath(import.meta.url)) {
+  runCli().then((code) => {
+    process.exitCode = code;
+  });
+}
+export {
+  runCli
+};
+//# sourceMappingURL=cli.js.map