@blaxel/core 0.2.67-preview.88 → 0.2.67-preview.89

package/dist/cjs/image/image.test.js

@@ -0,0 +1,545 @@
+"use strict";
+/**
+ * @vitest-environment node
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const vitest_1 = require("vitest");
+const image_js_1 = require("./image.js");
+// Test fixtures
+let tempDir;
+let tempFile;
+let tempSourceDir;
+(0, vitest_1.beforeEach)(() => {
+    // Create temp directory
+    tempDir = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "blaxel-test-"));
+    // Create temp file
+    tempFile = (0, path_1.join)(tempDir, "test.txt");
+    (0, fs_1.writeFileSync)(tempFile, "test content");
+    // Create temp source directory with test files
+    tempSourceDir = (0, path_1.join)(tempDir, "source");
+    (0, fs_1.mkdirSync)(tempSourceDir);
+    (0, fs_1.writeFileSync)((0, path_1.join)(tempSourceDir, "file1.txt"), "content1");
+    (0, fs_1.writeFileSync)((0, path_1.join)(tempSourceDir, "file2.txt"), "content2");
+    (0, fs_1.mkdirSync)((0, path_1.join)(tempSourceDir, "subdir"));
+    (0, fs_1.writeFileSync)((0, path_1.join)(tempSourceDir, "subdir", "nested.txt"), "nested content");
+});
+(0, vitest_1.afterEach)(() => {
+    // Cleanup temp directory
+    try {
+        (0, fs_1.rmSync)(tempDir, { recursive: true, force: true });
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+});
+(0, vitest_1.describe)("ImageInstanceInstance.fromRegistry", () => {
+    (0, vitest_1.it)("creates image with correct base image", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim");
+        (0, vitest_1.expect)(image.baseImage).toBe("python:3.11-slim");
+    });
+    (0, vitest_1.it)("works with full DockerHub image tag", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("namanjain12/numpy_final:05aa44d53f4f9528847a0c014fe4bda5caa5fd3d");
+        (0, vitest_1.expect)(image.baseImage).toBe("namanjain12/numpy_final:05aa44d53f4f9528847a0c014fe4bda5caa5fd3d");
+    });
+    (0, vitest_1.it)("generates correct FROM instruction in dockerfile", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("ubuntu:22.04");
+        (0, vitest_1.expect)(image.dockerfile).toContain("FROM ubuntu:22.04");
+    });
+    (0, vitest_1.it)("works with private registry URL", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("gcr.io/my-project/my-image:v1.0.0");
+        (0, vitest_1.expect)(image.baseImage).toBe("gcr.io/my-project/my-image:v1.0.0");
+        (0, vitest_1.expect)(image.dockerfile).toContain("FROM gcr.io/my-project/my-image:v1.0.0");
+    });
+    (0, vitest_1.it)("works with image digest", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890");
+        (0, vitest_1.expect)(image.baseImage).toContain("sha256:abcdef");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.workdir", () => {
+    (0, vitest_1.it)("adds WORKDIR instruction", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        (0, vitest_1.expect)(image.dockerfile).toContain("WORKDIR /app");
+    });
+    (0, vitest_1.it)("returns new image instance (immutability)", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const image2 = image1.workdir("/app");
+        (0, vitest_1.expect)(image1).not.toBe(image2);
+        (0, vitest_1.expect)(image1.dockerfile).not.toContain("WORKDIR /app");
+        (0, vitest_1.expect)(image2.dockerfile).toContain("WORKDIR /app");
+    });
+    (0, vitest_1.it)("supports multiple workdir changes in sequence", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11")
+            .workdir("/first")
+            .runCommands("echo first")
+            .workdir("/second")
+            .runCommands("echo second");
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain("WORKDIR /first");
+        (0, vitest_1.expect)(dockerfile).toContain("WORKDIR /second");
+        // Check order
+        const firstIdx = dockerfile.indexOf("WORKDIR /first");
+        const secondIdx = dockerfile.indexOf("WORKDIR /second");
+        (0, vitest_1.expect)(firstIdx).toBeLessThan(secondIdx);
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.runCommands", () => {
+    (0, vitest_1.it)("adds single RUN instruction", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").runCommands("echo hello");
+        (0, vitest_1.expect)(image.dockerfile).toContain("RUN echo hello");
+    });
+    (0, vitest_1.it)("adds multiple RUN instructions", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").runCommands("echo hello", "echo world");
+        (0, vitest_1.expect)(image.dockerfile).toContain("RUN echo hello");
+        (0, vitest_1.expect)(image.dockerfile).toContain("RUN echo world");
+    });
+    (0, vitest_1.it)("supports chaining multiple runCommands calls", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11")
+            .runCommands("echo first")
+            .runCommands("echo second");
+        (0, vitest_1.expect)(image.dockerfile).toContain("RUN echo first");
+        (0, vitest_1.expect)(image.dockerfile).toContain("RUN echo second");
+    });
+    (0, vitest_1.it)("works with complex shell commands", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").runCommands("cd /app && git clone https://github.com/example/repo.git", "find . -name '*.pyc' -delete", "chmod +x ./run_tests.sh && ./run_tests.sh");
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain("git clone");
+        (0, vitest_1.expect)(dockerfile).toContain("find . -name");
+        (0, vitest_1.expect)(dockerfile).toContain("chmod +x");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.env", () => {
+    (0, vitest_1.it)("sets single variable", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").env({ PYTHONUNBUFFERED: "1" });
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENV PYTHONUNBUFFERED="1"');
+    });
+    (0, vitest_1.it)("sets multiple variables", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").env({
+            PYTHONUNBUFFERED: "1",
+            DEBUG: "true",
+        });
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENV PYTHONUNBUFFERED="1"');
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENV DEBUG="true"');
+    });
+    (0, vitest_1.it)("returns same image with empty object", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const image2 = image1.env({});
+        (0, vitest_1.expect)(image1).toBe(image2);
+    });
+    (0, vitest_1.it)("handles special characters in values", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").env({
+            PATH: "/usr/local/bin:$PATH",
+            CONNECTION_STRING: "host=localhost;port=5432",
+        });
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain('ENV PATH="/usr/local/bin:$PATH"');
+        (0, vitest_1.expect)(dockerfile).toContain('ENV CONNECTION_STRING="host=localhost;port=5432"');
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.copy", () => {
+    (0, vitest_1.it)("adds COPY instruction", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").copy(".", "/app");
+        (0, vitest_1.expect)(image.dockerfile).toContain("COPY . /app");
+    });
+    (0, vitest_1.it)("works with specific paths", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").copy("requirements.txt", "/app/requirements.txt");
+        (0, vitest_1.expect)(image.dockerfile).toContain("COPY requirements.txt /app/requirements.txt");
+    });
+    (0, vitest_1.it)("supports multiple copy instructions", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11")
+            .copy("requirements.txt", "/app/requirements.txt")
+            .copy("src/", "/app/src/");
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain("COPY requirements.txt /app/requirements.txt");
+        (0, vitest_1.expect)(dockerfile).toContain("COPY src/ /app/src/");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.expose", () => {
+    (0, vitest_1.it)("exposes single port", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").expose(8080);
+        (0, vitest_1.expect)(image.dockerfile).toContain("EXPOSE 8080");
+    });
+    (0, vitest_1.it)("exposes multiple ports", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").expose(80, 443, 8080);
+        (0, vitest_1.expect)(image.dockerfile).toContain("EXPOSE 80");
+        (0, vitest_1.expect)(image.dockerfile).toContain("EXPOSE 443");
+        (0, vitest_1.expect)(image.dockerfile).toContain("EXPOSE 8080");
+    });
+    (0, vitest_1.it)("returns same image with no ports", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const image2 = image1.expose();
+        (0, vitest_1.expect)(image1).toBe(image2);
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.entrypoint", () => {
+    (0, vitest_1.it)("sets single arg entrypoint", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").entrypoint("python");
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENTRYPOINT ["python"]');
+    });
+    (0, vitest_1.it)("sets multiple args entrypoint", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").entrypoint("python", "-m", "app");
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENTRYPOINT ["python", "-m", "app"]');
+    });
+    (0, vitest_1.it)("returns same image with no args", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const image2 = image1.entrypoint();
+        (0, vitest_1.expect)(image1).toBe(image2);
+    });
+    (0, vitest_1.it)("escapes double quotes in arguments", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").entrypoint("echo", 'hello"world');
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENTRYPOINT ["echo", "hello\\"world"]');
+    });
+    (0, vitest_1.it)("escapes backslashes in arguments", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").entrypoint("echo", "path\\to\\file");
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENTRYPOINT ["echo", "path\\\\to\\\\file"]');
+    });
+    (0, vitest_1.it)("escapes newlines in arguments", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").entrypoint("echo", "line1\nline2");
+        (0, vitest_1.expect)(image.dockerfile).toContain('ENTRYPOINT ["echo", "line1\\nline2"]');
+    });
+    (0, vitest_1.it)("handles complex strings with multiple special characters", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").entrypoint("/bin/sh", "-c", 'echo "hello\nworld" && cat /path\\to\\file');
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain('ENTRYPOINT ["/bin/sh", "-c", "echo \\"hello\\nworld\\" && cat /path\\\\to\\\\file"]');
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.user", () => {
+    (0, vitest_1.it)("sets user by name", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").user("appuser");
+        (0, vitest_1.expect)(image.dockerfile).toContain("USER appuser");
+    });
+    (0, vitest_1.it)("sets user by UID", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").user("1000");
+        (0, vitest_1.expect)(image.dockerfile).toContain("USER 1000");
+    });
+    (0, vitest_1.it)("sets user with UID:GID format", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").user("1000:1000");
+        (0, vitest_1.expect)(image.dockerfile).toContain("USER 1000:1000");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.label", () => {
+    (0, vitest_1.it)("adds single label", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").label({ version: "1.0" });
+        (0, vitest_1.expect)(image.dockerfile).toContain('LABEL version="1.0"');
+    });
+    (0, vitest_1.it)("adds multiple labels", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").label({
+            version: "1.0",
+            maintainer: "test@example.com",
+        });
+        (0, vitest_1.expect)(image.dockerfile).toContain('LABEL version="1.0"');
+        (0, vitest_1.expect)(image.dockerfile).toContain('LABEL maintainer="test@example.com"');
+    });
+    (0, vitest_1.it)("returns same image with empty object", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const image2 = image1.label({});
+        (0, vitest_1.expect)(image1).toBe(image2);
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.arg", () => {
+    (0, vitest_1.it)("defines arg without default value", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").arg("VERSION");
+        (0, vitest_1.expect)(image.dockerfile).toContain("ARG VERSION");
+    });
+    (0, vitest_1.it)("defines arg with default value", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").arg("VERSION", "1.0");
+        (0, vitest_1.expect)(image.dockerfile).toContain("ARG VERSION=1.0");
+    });
+    (0, vitest_1.it)("supports multiple ARG instructions", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11")
+            .arg("VERSION", "1.0")
+            .arg("BUILD_DATE")
+            .arg("GIT_COMMIT", "unknown");
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain("ARG VERSION=1.0");
+        (0, vitest_1.expect)(dockerfile).toContain("ARG BUILD_DATE");
+        (0, vitest_1.expect)(dockerfile).toContain("ARG GIT_COMMIT=unknown");
+    });
+});
+(0, vitest_1.describe)("ImageInstance chaining", () => {
+    (0, vitest_1.it)("supports full chain of operations", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim")
+            .runCommands("apt-get update && apt-get install -y git curl")
+            .workdir("/app")
+            .copy(".", "/app")
+            .runCommands("pip install -r requirements.txt")
+            .env({ PYTHONUNBUFFERED: "1" })
+            .expose(8080);
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain("FROM python:3.11-slim");
+        (0, vitest_1.expect)(dockerfile).toContain("apt-get install");
+        (0, vitest_1.expect)(dockerfile).toContain("WORKDIR /app");
+        (0, vitest_1.expect)(dockerfile).toContain("COPY . /app");
+        (0, vitest_1.expect)(dockerfile).toContain("RUN pip install -r requirements.txt");
+        (0, vitest_1.expect)(dockerfile).toContain('ENV PYTHONUNBUFFERED="1"');
+        (0, vitest_1.expect)(dockerfile).toContain("EXPOSE 8080");
+    });
+    (0, vitest_1.it)("maintains immutability through chaining", () => {
+        const base = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const withWorkdir = base.workdir("/app");
+        const withEnv = withWorkdir.env({ DEBUG: "true" });
+        // Each should be a different instance
+        (0, vitest_1.expect)(base).not.toBe(withWorkdir);
+        (0, vitest_1.expect)(withWorkdir).not.toBe(withEnv);
+        (0, vitest_1.expect)(base).not.toBe(withEnv);
+        // Original should not be modified
+        (0, vitest_1.expect)(base.dockerfile).not.toContain("WORKDIR");
+        (0, vitest_1.expect)(base.dockerfile).not.toContain("ENV");
+    });
+    (0, vitest_1.it)("supports complex web app image pattern", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim")
+            .arg("APP_VERSION", "1.0.0")
+            .label({
+            maintainer: "dev@example.com",
+            version: "1.0.0",
+        })
+            .runCommands("apt-get update && apt-get install -y curl ca-certificates")
+            .workdir("/app")
+            .env({
+            PYTHONUNBUFFERED: "1",
+            PYTHONDONTWRITEBYTECODE: "1",
+            PIP_NO_CACHE_DIR: "1",
+        })
+            .copy("requirements.txt", "/app/requirements.txt")
+            .runCommands("pip install -r requirements.txt")
+            .copy(".", "/app")
+            .user("1000:1000")
+            .expose(8000)
+            .entrypoint("python", "-m", "gunicorn");
+        const dockerfile = image.dockerfile;
+        (0, vitest_1.expect)(dockerfile).toContain("FROM python:3.11-slim");
+        (0, vitest_1.expect)(dockerfile).toContain("ARG APP_VERSION=1.0.0");
+        (0, vitest_1.expect)(dockerfile).toContain('LABEL maintainer="dev@example.com"');
+        (0, vitest_1.expect)(dockerfile).toContain("apt-get install");
+        (0, vitest_1.expect)(dockerfile).toContain("WORKDIR /app");
+        (0, vitest_1.expect)(dockerfile).toContain("PYTHONUNBUFFERED");
+        (0, vitest_1.expect)(dockerfile).toContain("USER 1000:1000");
+        (0, vitest_1.expect)(dockerfile).toContain("EXPOSE 8000");
+        (0, vitest_1.expect)(dockerfile).toContain("ENTRYPOINT");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.hash", () => {
+    (0, vitest_1.it)("produces consistent hash for same image", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        const image2 = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        (0, vitest_1.expect)(image1.hash).toBe(image2.hash);
+    });
+    (0, vitest_1.it)("produces different hash for different images", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        const image2 = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/other");
+        (0, vitest_1.expect)(image1.hash).not.toBe(image2.hash);
+    });
+    (0, vitest_1.it)("produces different hash for different base images", () => {
+        const image1 = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        const image2 = image_js_1.ImageInstance.fromRegistry("python:3.12").workdir("/app");
+        (0, vitest_1.expect)(image1.hash).not.toBe(image2.hash);
+    });
+    (0, vitest_1.it)("has consistent length of 12 characters", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        (0, vitest_1.expect)(image.hash.length).toBe(12);
+    });
+    (0, vitest_1.it)("throws error when local file is missing", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalFile(tempFile, "/app/file.txt");
+        // Delete the file after adding it to the image
+        (0, fs_1.rmSync)(tempFile);
+        (0, vitest_1.expect)(() => image.hash).toThrow(/Local file not found/);
+    });
+    (0, vitest_1.it)("throws error when local directory is missing", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalDir(tempSourceDir, "/app");
+        // Delete the directory after adding it to the image
+        (0, fs_1.rmSync)(tempSourceDir, { recursive: true });
+        (0, vitest_1.expect)(() => image.hash).toThrow(/Local file not found/);
+    });
+    (0, vitest_1.it)("produces different hash when file content changes", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalFile(tempFile, "/app/file.txt");
+        const hash1 = image.hash;
+        // Modify the file (change mtime)
+        (0, fs_1.writeFileSync)(tempFile, "modified content");
+        const hash2 = image.hash;
+        (0, vitest_1.expect)(hash1).not.toBe(hash2);
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.write", () => {
+    (0, vitest_1.it)("creates Dockerfile", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        const buildDir = image.write(tempDir, "test-image");
+        const dockerfilePath = (0, path_1.join)(buildDir, "Dockerfile");
+        const content = (0, fs_1.readFileSync)(dockerfilePath, "utf-8");
+        (0, vitest_1.expect)(content).toContain("FROM python:3.11");
+        (0, vitest_1.expect)(content).toContain("WORKDIR /app");
+    });
+    (0, vitest_1.it)("creates manifest.json", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        const buildDir = image.write(tempDir, "test-image");
+        const manifestPath = (0, path_1.join)(buildDir, "manifest.json");
+        const manifest = JSON.parse((0, fs_1.readFileSync)(manifestPath, "utf-8"));
+        (0, vitest_1.expect)(manifest.base_image).toBe("python:3.11");
+        (0, vitest_1.expect)(manifest.hash).toBeDefined();
+        (0, vitest_1.expect)(manifest.instructions_count).toBe(1);
+    });
+    (0, vitest_1.it)("auto-generates folder name from hash", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const buildDir = image.write(tempDir);
+        const dirName = buildDir.split("/").pop() || "";
+        (0, vitest_1.expect)(dirName.startsWith("image-")).toBe(true);
+        (0, vitest_1.expect)(dirName.length).toBe(6 + 12); // "image-" + 12 char hash
+    });
+    (0, vitest_1.it)("creates nested directories if needed", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11");
+        const nestedPath = (0, path_1.join)(tempDir, "deep", "nested", "path");
+        const buildDir = image.write(nestedPath, "test-image");
+        const dockerfilePath = (0, path_1.join)(buildDir, "Dockerfile");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)(dockerfilePath, "utf-8")).toContain("FROM python:3.11");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.writeTemp", () => {
+    (0, vitest_1.it)("creates in temporary directory", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").workdir("/app");
+        let buildDir = null;
+        try {
+            buildDir = image.writeTemp();
+            const dockerfilePath = (0, path_1.join)(buildDir, "Dockerfile");
+            const manifestPath = (0, path_1.join)(buildDir, "manifest.json");
+            (0, vitest_1.expect)((0, fs_1.readFileSync)(dockerfilePath, "utf-8")).toContain("FROM python:3.11");
+            (0, vitest_1.expect)((0, fs_1.readFileSync)(manifestPath, "utf-8")).toContain("python:3.11");
+        }
+        finally {
+            if (buildDir) {
+                (0, fs_1.rmSync)((0, path_1.join)(buildDir, ".."), { recursive: true, force: true });
+            }
+        }
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.addLocalFile", () => {
+    (0, vitest_1.it)("adds COPY instruction", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalFile(tempFile, "/app/file.txt");
+        (0, vitest_1.expect)(image.dockerfile).toContain("COPY");
+    });
+    (0, vitest_1.it)("copies file to build context", () => {
+        const outputDir = (0, path_1.join)(tempDir, "output");
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalFile(tempFile, "/app/file.txt", "myfile.txt");
+        const buildDir = image.write(outputDir, "test-image");
+        const copiedFile = (0, path_1.join)(buildDir, "myfile.txt");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)(copiedFile, "utf-8")).toBe("test content");
+    });
+    (0, vitest_1.it)("throws error for missing file", () => {
+        const outputDir = (0, path_1.join)(tempDir, "output");
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalFile("/nonexistent/file.txt", "/app/file.txt");
+        (0, vitest_1.expect)(() => image.write(outputDir, "test-image")).toThrow(/not found/i);
+    });
+    (0, vitest_1.it)("adds multiple local files", () => {
+        const file1 = (0, path_1.join)(tempDir, "file1.txt");
+        const file2 = (0, path_1.join)(tempDir, "file2.txt");
+        (0, fs_1.writeFileSync)(file1, "content1");
+        (0, fs_1.writeFileSync)(file2, "content2");
+        const outputDir = (0, path_1.join)(tempDir, "output");
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11")
+            .addLocalFile(file1, "/app/file1.txt")
+            .addLocalFile(file2, "/app/file2.txt");
+        const buildDir = image.write(outputDir, "test-image");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)((0, path_1.join)(buildDir, "file1.txt"), "utf-8")).toBe("content1");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)((0, path_1.join)(buildDir, "file2.txt"), "utf-8")).toBe("content2");
+    });
+});
+(0, vitest_1.describe)("ImageInstanceInstance.addLocalDir", () => {
+    (0, vitest_1.it)("copies directory to build context", () => {
+        const outputDir = (0, path_1.join)(tempDir, "output");
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalDir(tempSourceDir, "/app", "mydir");
+        const buildDir = image.write(outputDir, "test-image");
+        const copiedDir = (0, path_1.join)(buildDir, "mydir");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)((0, path_1.join)(copiedDir, "file1.txt"), "utf-8")).toBe("content1");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)((0, path_1.join)(copiedDir, "file2.txt"), "utf-8")).toBe("content2");
+    });
+    (0, vitest_1.it)("preserves directory structure", () => {
+        const outputDir = (0, path_1.join)(tempDir, "output");
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11").addLocalDir(tempSourceDir, "/app", "mydir");
+        const buildDir = image.write(outputDir, "test-image");
+        const copiedDir = (0, path_1.join)(buildDir, "mydir");
+        (0, vitest_1.expect)((0, fs_1.readFileSync)((0, path_1.join)(copiedDir, "subdir", "nested.txt"), "utf-8")).toBe("nested content");
+    });
+});
+(0, vitest_1.describe)("ImageInstance sandbox-api preparation", () => {
+    (0, vitest_1.it)("adds sandbox-api COPY instruction", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim");
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox();
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api");
+    });
+    (0, vitest_1.it)("adds default entrypoint if not set", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim");
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox();
+        (0, vitest_1.expect)(prepared.dockerfile).toContain('ENTRYPOINT ["/usr/local/bin/sandbox-api"]');
+    });
+    (0, vitest_1.it)("preserves user-defined entrypoint", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim").entrypoint("/custom/entrypoint");
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox();
+        // User entrypoint should be present
+        (0, vitest_1.expect)(prepared.dockerfile).toContain('ENTRYPOINT ["/custom/entrypoint"]');
+        // Should only have one ENTRYPOINT
+        const entrypointCount = (prepared.dockerfile.match(/ENTRYPOINT/g) || []).length;
+        (0, vitest_1.expect)(entrypointCount).toBe(1);
+    });
+    (0, vitest_1.it)("uses custom sandbox version", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim");
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox("v1.2.3");
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("COPY --from=ghcr.io/blaxel-ai/sandbox:v1.2.3 /sandbox-api /usr/local/bin/sandbox-api");
+    });
+    (0, vitest_1.it)("does not duplicate sandbox-api if base image is sandbox", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("ghcr.io/blaxel-ai/sandbox:latest");
+        // @ts-expect-error - accessing private method for testing
+        (0, vitest_1.expect)(image._hasSandboxApi()).toBe(true);
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox();
+        const copyCount = (prepared.dockerfile.match(/COPY --from=ghcr.io\/blaxel-ai\/sandbox/g) || [])
+            .length;
+        (0, vitest_1.expect)(copyCount).toBe(0);
+    });
+    (0, vitest_1.it)("returns new image instance (immutability)", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim");
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox();
+        (0, vitest_1.expect)(image).not.toBe(prepared);
+        (0, vitest_1.expect)(image.dockerfile).not.toContain("sandbox-api");
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("sandbox-api");
+    });
+    (0, vitest_1.it)("preserves all original instructions", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11-slim")
+            .runCommands("apt-get update && apt-get install -y curl git")
+            .workdir("/app")
+            .runCommands("pip install requests")
+            .env({ DEBUG: "true" });
+        // @ts-expect-error - accessing private method for testing
+        const prepared = image._prepareForSandbox();
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("apt-get install");
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("WORKDIR /app");
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("pip install");
+        (0, vitest_1.expect)(prepared.dockerfile).toContain('DEBUG="true"');
+        (0, vitest_1.expect)(prepared.dockerfile).toContain("sandbox-api");
+    });
+});
+(0, vitest_1.describe)("Dockerfile instruction order", () => {
+    (0, vitest_1.it)("preserves instruction order", () => {
+        const image = image_js_1.ImageInstance.fromRegistry("python:3.11")
+            .env({ FIRST: "1" })
+            .workdir("/app")
+            .env({ SECOND: "2" })
+            .runCommands("echo middle")
+            .env({ THIRD: "3" });
+        const dockerfile = image.dockerfile;
+        const lines = dockerfile.split("\n");
+        const firstIdx = lines.findIndex((line) => line.includes('FIRST="1"'));
+        const workdirIdx = lines.findIndex((line) => line.includes("WORKDIR /app"));
+        const secondIdx = lines.findIndex((line) => line.includes('SECOND="2"'));
+        const runIdx = lines.findIndex((line) => line.includes("echo middle"));
+        const thirdIdx = lines.findIndex((line) => line.includes('THIRD="3"'));
+        (0, vitest_1.expect)(firstIdx).toBeLessThan(workdirIdx);
+        (0, vitest_1.expect)(workdirIdx).toBeLessThan(secondIdx);
+        (0, vitest_1.expect)(secondIdx).toBeLessThan(runIdx);
+        (0, vitest_1.expect)(runIdx).toBeLessThan(thirdIdx);
+    });
+});

package/dist/cjs/image/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANDBOX_API_PATH = exports.SANDBOX_API_IMAGE = exports.ImageInstance = void 0;
+var image_js_1 = require("./image.js");
+Object.defineProperty(exports, "ImageInstance", { enumerable: true, get: function () { return image_js_1.ImageInstance; } });
+Object.defineProperty(exports, "SANDBOX_API_IMAGE", { enumerable: true, get: function () { return image_js_1.SANDBOX_API_IMAGE; } });
+Object.defineProperty(exports, "SANDBOX_API_PATH", { enumerable: true, get: function () { return image_js_1.SANDBOX_API_PATH; } });

package/dist/cjs/index.js

@@ -25,6 +25,7 @@ __exportStar(require("./common/internal.js"), exports);
 __exportStar(require("./common/logger.js"), exports);
 __exportStar(require("./common/settings.js"), exports);
 __exportStar(require("./common/webhook.js"), exports);
+__exportStar(require("./image/index.js"), exports);
 __exportStar(require("./jobs/index.js"), exports);
 __exportStar(require("./mcp/index.js"), exports);
 __exportStar(require("./models/index.js"), exports);

package/dist/cjs/types/image/image.browser.d.ts

@@ -0,0 +1,59 @@
+import { Sandbox } from "../client/types.gen.js";
+export declare const SANDBOX_API_IMAGE = "ghcr.io/blaxel-ai/sandbox";
+export declare const SANDBOX_API_PATH = "/usr/local/bin/sandbox-api";
+/**
+ * Represents a local file to be copied into the build context.
+ */
+export interface LocalFile {
+    sourcePath: string;
+    destinationPath: string;
+    contextName: string;
+}
+/**
+ * Contains all information needed to generate a deployable folder.
+ */
+export interface ImageBuildContext {
+    baseImage: string;
+    instructions: string[];
+    localFiles: LocalFile[];
+    hasEntrypoint: boolean;
+}
+/**
+ * Options for building and deploying an image
+ */
+export interface ImageBuildOptions {
+    name: string;
+    memory?: number;
+    timeout?: number;
+    onStatusChange?: (status: string) => void;
+    sandboxVersion?: string;
+}
+/**
+ * A fluent builder for creating sandbox images programmatically.
+ *
+ * NOTE: This class is only available in Node.js environments.
+ * In browser environments, all methods will throw an error.
+ */
+export declare class ImageInstance {
+    private _context;
+    constructor(_context: ImageBuildContext);
+    static fromRegistry(_tag: string): ImageInstance;
+    workdir(_path: string): ImageInstance;
+    runCommands(..._commands: string[]): ImageInstance;
+    env(_variables: Record<string, string>): ImageInstance;
+    copy(_source: string, _destination: string): ImageInstance;
+    addLocalFile(_sourcePath: string, _destination: string, _contextName?: string): ImageInstance;
+    addLocalDir(_sourcePath: string, _destination: string, _contextName?: string): ImageInstance;
+    expose(..._ports: number[]): ImageInstance;
+    entrypoint(..._args: string[]): ImageInstance;
+    user(_user: string): ImageInstance;
+    label(_labels: Record<string, string>): ImageInstance;
+    arg(_name: string, _defaultValue?: string): ImageInstance;
+    get dockerfile(): string;
+    get hash(): string;
+    get baseImage(): string;
+    write(_outputPath: string, _name?: string): string;
+    writeTemp(): string;
+    build(_options: ImageBuildOptions): Promise<Sandbox>;
+    buildSync(_options: ImageBuildOptions): Promise<Sandbox>;
+}