@hyperbrowser/sdk 0.92.7 → 1.0.0

package/dist/sandbox/image-build/gzip.d.ts

@@ -0,0 +1,11 @@
+import { PaxTarWriter } from "./tar";
+export interface GzipTarResult {
+    sizeBytes: number;
+    sha256Hex: string;
+    uncompressedSizeBytes: number;
+}
+/**
+ * Write a deterministic gzip-compressed tar archive to `path`. The `populate`
+ * callback adds entries through the supplied writer.
+ */
+export declare const writeGzipTar: (path: string, populate: (writer: PaxTarWriter) => Promise<void>) => Promise<GzipTarResult>;

package/dist/sandbox/image-build/gzip.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeGzipTar = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const events_1 = require("events");
+const zlib_1 = require("zlib");
+const tar_1 = require("./tar");
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let index = 0; index < 256; index += 1) {
+        let value = index;
+        for (let bit = 0; bit < 8; bit += 1) {
+            value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+        }
+        table[index] = value >>> 0;
+    }
+    return table;
+})();
+const updateCrc32 = (crc, chunk) => {
+    let value = ~crc >>> 0;
+    for (const byte of chunk) {
+        value = CRC_TABLE[(value ^ byte) & 0xff] ^ (value >>> 8);
+    }
+    return ~value >>> 0;
+};
+/** gzip member header matching CPython `GzipFile(filename="", mtime=0)` at compresslevel 1. */
+const GZIP_HEADER = Buffer.from([0x1f, 0x8b, 0x08, 0x00, 0, 0, 0, 0, 0x00, 0xff]);
+/**
+ * Write a deterministic gzip-compressed tar archive to `path`. The `populate`
+ * callback adds entries through the supplied writer.
+ */
+const writeGzipTar = async (path, populate) => {
+    const output = (0, fs_1.createWriteStream)(path, { flags: "wx" });
+    // Observe write errors immediately, including failures before the first drain.
+    let outputError;
+    output.on("error", (error) => { outputError = error; deflate.destroy(error); });
+    const hasher = (0, crypto_1.createHash)("sha256");
+    let compressedSize = 0;
+    let crc = 0;
+    let uncompressedSize = 0;
+    const writeOutput = async (chunk) => {
+        if (outputError)
+            throw outputError;
+        hasher.update(chunk);
+        compressedSize += chunk.length;
+        if (!output.write(chunk)) {
+            await (0, events_1.once)(output, "drain");
+        }
+    };
+    const deflate = (0, zlib_1.createDeflateRaw)({ level: 1 });
+    const drainDeflate = (async () => {
+        for await (const chunk of deflate) {
+            await writeOutput(chunk);
+        }
+    })();
+    // A source failure can occur while compression is still draining.
+    void drainDeflate.catch(() => undefined);
+    try {
+        await writeOutput(GZIP_HEADER);
+        const writer = new tar_1.PaxTarWriter(async (chunk) => {
+            crc = updateCrc32(crc, chunk);
+            uncompressedSize += chunk.length;
+            if (!deflate.write(chunk)) {
+                await (0, events_1.once)(deflate, "drain");
+            }
+        });
+        await populate(writer);
+        await writer.close();
+        deflate.end();
+        await drainDeflate;
+        const trailer = Buffer.alloc(8);
+        trailer.writeUInt32LE(crc >>> 0, 0);
+        trailer.writeUInt32LE(uncompressedSize % 2 ** 32, 4);
+        await writeOutput(trailer);
+        output.end();
+        await (0, events_1.once)(output, "finish");
+    }
+    catch (error) {
+        deflate.destroy();
+        output.destroy();
+        await drainDeflate.catch(() => undefined);
+        throw error;
+    }
+    return {
+        sizeBytes: compressedSize,
+        sha256Hex: hasher.digest("hex"),
+        uncompressedSizeBytes: uncompressedSize,
+    };
+};
+exports.writeGzipTar = writeGzipTar;

package/dist/sandbox/image-build/image-init.d.ts

@@ -0,0 +1,5 @@
+import { SandboxImageInit } from "../../types/sandbox";
+/** Derive default sandbox initialization from a Docker image config. */
+export declare const deriveAutoImageInit: (config: Record<string, unknown>) => SandboxImageInit | undefined;
+/** Layer explicit overrides over image-derived initialization defaults. */
+export declare const mergeImageInit: (automatic: SandboxImageInit | undefined, explicit: SandboxImageInit | undefined) => SandboxImageInit | undefined;

package/dist/sandbox/image-build/image-init.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeImageInit = exports.deriveAutoImageInit = void 0;
+const IMAGE_INIT_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED_IMAGE_INIT_ENV_KEYS = new Set([
+    "SANDBOX_ENABLED",
+    "SANDBOX_DEFAULT_WORKING_DIR",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "PWD",
+    "DISPLAY",
+]);
+const listStringConfig = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+const normalizeInitArgs = (values) => (values ?? []).filter((value) => value);
+const deriveAutoImageEnv = (entries) => {
+    const env = new Map();
+    for (const entry of entries) {
+        const separator = entry.indexOf("=");
+        if (separator === -1) {
+            continue;
+        }
+        const key = entry.slice(0, separator).trim();
+        if (!key || !IMAGE_INIT_ENV_KEY_PATTERN.test(key) || RESERVED_IMAGE_INIT_ENV_KEYS.has(key)) {
+            continue;
+        }
+        env.set(key, entry.slice(separator + 1));
+    }
+    return Object.fromEntries(env);
+};
+const deriveAutoStartupArgs = (entrypoint, cmd) => (entrypoint.length > 0 ? [...entrypoint, ...cmd] : [...cmd]).filter((arg) => arg);
+/** Derive default sandbox initialization from a Docker image config. */
+const deriveAutoImageInit = (config) => {
+    const env = deriveAutoImageEnv(listStringConfig(config.Env));
+    const args = deriveAutoStartupArgs(listStringConfig(config.Entrypoint), listStringConfig(config.Cmd));
+    const workingDir = String(config.WorkingDir ?? "").trim();
+    if (Object.keys(env).length === 0 && args.length === 0 && !workingDir) {
+        return undefined;
+    }
+    const init = {};
+    if (Object.keys(env).length > 0) {
+        init.env = env;
+    }
+    if (args.length > 0) {
+        init.args = args;
+    }
+    if (workingDir) {
+        init.workingDir = workingDir;
+    }
+    return init;
+};
+exports.deriveAutoImageInit = deriveAutoImageInit;
+/** Layer explicit overrides over image-derived initialization defaults. */
+const mergeImageInit = (automatic, explicit) => {
+    if (automatic === undefined && explicit === undefined) {
+        return undefined;
+    }
+    const env = { ...(automatic?.env ?? {}), ...(explicit?.env ?? {}) };
+    let command = (automatic?.command ?? "").trim();
+    let args = normalizeInitArgs(automatic?.args);
+    let workingDir = (automatic?.workingDir ?? "").trim();
+    if (explicit !== undefined) {
+        const explicitWorkingDir = (explicit.workingDir ?? "").trim();
+        if (explicitWorkingDir) {
+            workingDir = explicitWorkingDir;
+        }
+        const explicitArgs = normalizeInitArgs(explicit.args);
+        if (explicitArgs.length > 0) {
+            args = explicitArgs;
+            command = "";
+        }
+        const explicitCommand = (explicit.command ?? "").trim();
+        if (explicitCommand) {
+            command = explicitCommand;
+            args = [];
+        }
+    }
+    if (Object.keys(env).length === 0 && !command && args.length === 0 && !workingDir) {
+        return undefined;
+    }
+    const merged = {};
+    if (Object.keys(env).length > 0) {
+        merged.env = env;
+    }
+    if (command) {
+        merged.command = command;
+    }
+    if (args.length > 0) {
+        merged.args = args;
+    }
+    if (workingDir) {
+        merged.workingDir = workingDir;
+    }
+    return merged;
+};
+exports.mergeImageInit = mergeImageInit;

package/dist/sandbox/image-build/index.d.ts

@@ -0,0 +1,13 @@
+export { CONTEXT_MANIFEST_INPUT_FORMAT, DOCKER_IMAGE_MANIFEST_INPUT_FORMAT, IMAGE_BUILD_INPUT_FORMAT, IMAGE_BUILD_SOURCE_PLATFORM, } from "./artifacts";
+export type { DockerImageBuildArtifact } from "./artifacts";
+export { DockerBuildContextChangedError, dockerBuildContextFingerprint, packageDockerBuildContextManifest, } from "./context";
+export type { DockerBuildContextOptions, PackageDockerBuildContextOptions, PackagedDockerBuildContext, } from "./context";
+export { DockerCommandError, dockerImageDigest, packageDockerImageManifest, prepareDockerImageManifestSource, } from "./docker-image";
+export type { DockerImageManifestSource, PackagedDockerImage, PackageDockerImageManifestOptions, } from "./docker-image";
+export { DockerIgnoreMatcher } from "./dockerignore";
+export { analyzeDockerfileSources } from "./dockerfile-analysis";
+export { deriveAutoImageInit, mergeImageInit } from "./image-init";
+export { buildDockerImageFromDockerfile, makeTempDockerTag, removeDockerImage, } from "./local-docker";
+export { completedImageId, imageBuildName, isTerminalImageBuildStatus, matchingImageBuild, } from "./resolution";
+export type { ImageBuildNameOptions, ImageBuildSource } from "./resolution";
+export { uploadImageBuildArtifact, uploadMissingImageBuildArtifacts } from "./upload";

package/dist/sandbox/image-build/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadMissingImageBuildArtifacts = exports.uploadImageBuildArtifact = exports.matchingImageBuild = exports.isTerminalImageBuildStatus = exports.imageBuildName = exports.completedImageId = exports.removeDockerImage = exports.makeTempDockerTag = exports.buildDockerImageFromDockerfile = exports.mergeImageInit = exports.deriveAutoImageInit = exports.analyzeDockerfileSources = exports.DockerIgnoreMatcher = exports.prepareDockerImageManifestSource = exports.packageDockerImageManifest = exports.dockerImageDigest = exports.DockerCommandError = exports.packageDockerBuildContextManifest = exports.dockerBuildContextFingerprint = exports.DockerBuildContextChangedError = exports.IMAGE_BUILD_SOURCE_PLATFORM = exports.IMAGE_BUILD_INPUT_FORMAT = exports.DOCKER_IMAGE_MANIFEST_INPUT_FORMAT = exports.CONTEXT_MANIFEST_INPUT_FORMAT = void 0;
+var artifacts_1 = require("./artifacts");
+Object.defineProperty(exports, "CONTEXT_MANIFEST_INPUT_FORMAT", { enumerable: true, get: function () { return artifacts_1.CONTEXT_MANIFEST_INPUT_FORMAT; } });
+Object.defineProperty(exports, "DOCKER_IMAGE_MANIFEST_INPUT_FORMAT", { enumerable: true, get: function () { return artifacts_1.DOCKER_IMAGE_MANIFEST_INPUT_FORMAT; } });
+Object.defineProperty(exports, "IMAGE_BUILD_INPUT_FORMAT", { enumerable: true, get: function () { return artifacts_1.IMAGE_BUILD_INPUT_FORMAT; } });
+Object.defineProperty(exports, "IMAGE_BUILD_SOURCE_PLATFORM", { enumerable: true, get: function () { return artifacts_1.IMAGE_BUILD_SOURCE_PLATFORM; } });
+var context_1 = require("./context");
+Object.defineProperty(exports, "DockerBuildContextChangedError", { enumerable: true, get: function () { return context_1.DockerBuildContextChangedError; } });
+Object.defineProperty(exports, "dockerBuildContextFingerprint", { enumerable: true, get: function () { return context_1.dockerBuildContextFingerprint; } });
+Object.defineProperty(exports, "packageDockerBuildContextManifest", { enumerable: true, get: function () { return context_1.packageDockerBuildContextManifest; } });
+var docker_image_1 = require("./docker-image");
+Object.defineProperty(exports, "DockerCommandError", { enumerable: true, get: function () { return docker_image_1.DockerCommandError; } });
+Object.defineProperty(exports, "dockerImageDigest", { enumerable: true, get: function () { return docker_image_1.dockerImageDigest; } });
+Object.defineProperty(exports, "packageDockerImageManifest", { enumerable: true, get: function () { return docker_image_1.packageDockerImageManifest; } });
+Object.defineProperty(exports, "prepareDockerImageManifestSource", { enumerable: true, get: function () { return docker_image_1.prepareDockerImageManifestSource; } });
+var dockerignore_1 = require("./dockerignore");
+Object.defineProperty(exports, "DockerIgnoreMatcher", { enumerable: true, get: function () { return dockerignore_1.DockerIgnoreMatcher; } });
+var dockerfile_analysis_1 = require("./dockerfile-analysis");
+Object.defineProperty(exports, "analyzeDockerfileSources", { enumerable: true, get: function () { return dockerfile_analysis_1.analyzeDockerfileSources; } });
+var image_init_1 = require("./image-init");
+Object.defineProperty(exports, "deriveAutoImageInit", { enumerable: true, get: function () { return image_init_1.deriveAutoImageInit; } });
+Object.defineProperty(exports, "mergeImageInit", { enumerable: true, get: function () { return image_init_1.mergeImageInit; } });
+var local_docker_1 = require("./local-docker");
+Object.defineProperty(exports, "buildDockerImageFromDockerfile", { enumerable: true, get: function () { return local_docker_1.buildDockerImageFromDockerfile; } });
+Object.defineProperty(exports, "makeTempDockerTag", { enumerable: true, get: function () { return local_docker_1.makeTempDockerTag; } });
+Object.defineProperty(exports, "removeDockerImage", { enumerable: true, get: function () { return local_docker_1.removeDockerImage; } });
+var resolution_1 = require("./resolution");
+Object.defineProperty(exports, "completedImageId", { enumerable: true, get: function () { return resolution_1.completedImageId; } });
+Object.defineProperty(exports, "imageBuildName", { enumerable: true, get: function () { return resolution_1.imageBuildName; } });
+Object.defineProperty(exports, "isTerminalImageBuildStatus", { enumerable: true, get: function () { return resolution_1.isTerminalImageBuildStatus; } });
+Object.defineProperty(exports, "matchingImageBuild", { enumerable: true, get: function () { return resolution_1.matchingImageBuild; } });
+var upload_1 = require("./upload");
+Object.defineProperty(exports, "uploadImageBuildArtifact", { enumerable: true, get: function () { return upload_1.uploadImageBuildArtifact; } });
+Object.defineProperty(exports, "uploadMissingImageBuildArtifacts", { enumerable: true, get: function () { return upload_1.uploadMissingImageBuildArtifacts; } });

package/dist/sandbox/image-build/local-docker.d.ts

@@ -0,0 +1,11 @@
+export declare const makeTempDockerTag: (prefix?: string) => string;
+export declare const removeDockerImage: (image: string) => Promise<void>;
+export interface LocalDockerBuildOptions {
+    contextPath: string;
+    dockerfile?: string;
+    tag: string;
+    platform?: string;
+    buildArgs?: Record<string, string>;
+}
+/** Build a Dockerfile locally with `docker buildx build --load`. */
+export declare const buildDockerImageFromDockerfile: (options: LocalDockerBuildOptions) => Promise<void>;

package/dist/sandbox/image-build/local-docker.js

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDockerImageFromDockerfile = exports.removeDockerImage = exports.makeTempDockerTag = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const artifacts_1 = require("./artifacts");
+const docker_image_1 = require("./docker-image");
+const makeTempDockerTag = (prefix = "hyperbrowser-sdk-build") => `${prefix}:${(0, crypto_1.randomUUID)().replace(/-/g, "")}`;
+exports.makeTempDockerTag = makeTempDockerTag;
+const removeDockerImage = async (image) => {
+    try {
+        await (0, docker_image_1.runDockerCommand)(["image", "rm", image]);
+    }
+    catch (error) {
+        if (!(error instanceof docker_image_1.DockerCommandError)) {
+            throw error;
+        }
+    }
+};
+exports.removeDockerImage = removeDockerImage;
+/** Build a Dockerfile locally with `docker buildx build --load`. */
+const buildDockerImageFromDockerfile = async (options) => {
+    const context = options.contextPath;
+    if (!(0, fs_1.existsSync)(context)) {
+        throw new Error(`Docker build context not found: ${context}`);
+    }
+    let dockerfilePath = options.dockerfile ?? "Dockerfile";
+    if (!path.isAbsolute(dockerfilePath)) {
+        dockerfilePath = path.join(context, dockerfilePath);
+    }
+    const args = [
+        "buildx",
+        "build",
+        "--platform",
+        options.platform ?? artifacts_1.IMAGE_BUILD_SOURCE_PLATFORM,
+        "-t",
+        options.tag,
+        "-f",
+        dockerfilePath,
+        "--load",
+    ];
+    for (const [key, value] of Object.entries(options.buildArgs ?? {})) {
+        args.push("--build-arg", `${key}=${value}`);
+    }
+    args.push(context);
+    await (0, docker_image_1.runDockerCommand)(args);
+};
+exports.buildDockerImageFromDockerfile = buildDockerImageFromDockerfile;

package/dist/sandbox/image-build/resolution.d.ts

@@ -0,0 +1,27 @@
+/** Shared identity and validation for opt-in image resolution. */
+import { HyperbrowserError } from "../../error";
+import { SandboxImageBuild, SandboxImageInit } from "../../types/sandbox";
+export type ImageBuildSource = "dockerfile" | "prebuilt";
+export interface ImageBuildNameOptions {
+    source: ImageBuildSource;
+    fingerprint: string;
+    namePrefix?: string;
+    platform?: string;
+    imageInit?: SandboxImageInit;
+    imageConfigUser?: string;
+}
+/** Drop undefined/null fields so identity matches `exclude_none` serialization. */
+export declare const normalizeImageInit: (imageInit: SandboxImageInit | undefined) => SandboxImageInit | undefined;
+/**
+ * Name an immutable input identity without packaging or uploading it.
+ *
+ * Fingerprints identify effective Dockerfile contexts or platform-specific
+ * Docker image digests. Builder resources and wait policies do not change the
+ * image contents and are excluded. Mutable external inputs (base tags, network
+ * downloads) require an explicit `forceBuild` to request another build.
+ */
+export declare const imageBuildName: (options: ImageBuildNameOptions) => string;
+/** Return the compatible in-progress build described by a 409 conflict, if any. */
+export declare const matchingImageBuild: (error: HyperbrowserError, imageName: string, inputFormat: string) => SandboxImageBuild | null;
+export declare const completedImageId: (build: SandboxImageBuild) => string | undefined;
+export declare const isTerminalImageBuildStatus: (status: SandboxImageBuild["status"]) => boolean;

package/dist/sandbox/image-build/resolution.js

@@ -0,0 +1,137 @@
+"use strict";
+/** Shared identity and validation for opt-in image resolution. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTerminalImageBuildStatus = exports.completedImageId = exports.matchingImageBuild = exports.imageBuildName = exports.normalizeImageInit = void 0;
+const blake2b_1 = require("./blake2b");
+const common_1 = require("./common");
+const normalizeInitEnv = (env) => env === undefined ? undefined : env;
+/** Drop undefined/null fields so identity matches `exclude_none` serialization. */
+const normalizeImageInit = (imageInit) => {
+    if (imageInit === undefined) {
+        return undefined;
+    }
+    const normalized = {};
+    const env = normalizeInitEnv(imageInit.env);
+    if (env !== undefined && env !== null) {
+        normalized.env = env;
+    }
+    if (imageInit.command !== undefined && imageInit.command !== null) {
+        normalized.command = imageInit.command;
+    }
+    if (imageInit.args !== undefined && imageInit.args !== null) {
+        normalized.args = imageInit.args;
+    }
+    if (imageInit.workingDir !== undefined && imageInit.workingDir !== null) {
+        normalized.workingDir = imageInit.workingDir;
+    }
+    return normalized;
+};
+exports.normalizeImageInit = normalizeImageInit;
+/**
+ * Name an immutable input identity without packaging or uploading it.
+ *
+ * Fingerprints identify effective Dockerfile contexts or platform-specific
+ * Docker image digests. Builder resources and wait policies do not change the
+ * image contents and are excluded. Mutable external inputs (base tags, network
+ * downloads) require an explicit `forceBuild` to request another build.
+ */
+const imageBuildName = (options) => {
+    const platform = (options.platform ?? "linux/amd64").trim().toLowerCase();
+    const namePrefix = options.namePrefix ?? "hb";
+    if (!/^[a-z0-9]+\/[a-z0-9]+(?:\/[a-z0-9]+)?$/.test(platform)) {
+        throw new Error("platform must be an OCI platform such as 'linux/amd64'");
+    }
+    if (!/^[A-Za-z0-9_-]{1,21}$/.test(namePrefix)) {
+        throw new Error("imageNamePrefix must be 1-21 letters, digits, '_' or '-'");
+    }
+    let payload;
+    if (options.source === "prebuilt") {
+        const fingerprint = options.fingerprint.toLowerCase();
+        if (!/^sha256:[0-9a-f]{64}$/.test(fingerprint)) {
+            throw new Error("expectedImageDigest must be a sha256: Docker digest");
+        }
+        payload = `docker_image\0${fingerprint}\0platform\0${platform}`;
+    }
+    else if (options.source === "dockerfile") {
+        if (!/^[0-9a-f]{64}$/.test(options.fingerprint)) {
+            throw new Error("expectedContextFingerprint must be a SHA-256 hex digest");
+        }
+        payload = `dockerfile-context-v3\0${options.fingerprint}\0platform\0${platform}`;
+    }
+    else {
+        throw new Error("source must be 'dockerfile' or 'prebuilt'");
+    }
+    const identityOptions = {};
+    const initialization = (0, exports.normalizeImageInit)(options.imageInit);
+    if (initialization !== undefined && Object.keys(initialization).length > 0) {
+        identityOptions.imageInit = initialization;
+    }
+    if (options.imageConfigUser !== undefined) {
+        identityOptions.imageConfigUser = options.imageConfigUser.trim();
+    }
+    if (Object.keys(identityOptions).length > 0) {
+        payload += "\0options\0" + (0, common_1.compactJson)(identityOptions, { sortKeys: true });
+    }
+    const digest = (0, blake2b_1.blake2b)(Buffer.from(payload, "utf8"), 8).toString("hex");
+    const name = `${namePrefix}__${options.source}__${digest}__${platform.replace(/\//g, "-")}`;
+    if (name.length > 64) {
+        throw new Error("imageNamePrefix and platform produce a name longer than 64 characters");
+    }
+    return name;
+};
+exports.imageBuildName = imageBuildName;
+const IMAGE_BUILD_STATUSES = new Set([
+    "awaiting_upload",
+    "upload_verified",
+    "dispatching",
+    "building",
+    "verifying",
+    "completed",
+    "failed",
+    "canceled",
+]);
+/** Return the compatible in-progress build described by a 409 conflict, if any. */
+const matchingImageBuild = (error, imageName, inputFormat) => {
+    if (error.statusCode !== 409 || error.code !== "image_build_in_progress") {
+        return null;
+    }
+    if (!(0, common_1.isRecord)(error.details)) {
+        return null;
+    }
+    const data = error.details.build;
+    if (!(0, common_1.isRecord)(data)) {
+        return null;
+    }
+    const metadata = data.metadata;
+    if (!(0, common_1.isRecord)(metadata) || metadata.inputFormat !== inputFormat) {
+        return null;
+    }
+    if ((metadata.sourcePlatform ?? "linux/amd64") !== "linux/amd64") {
+        return null;
+    }
+    if (typeof data.id !== "string" ||
+        !data.id ||
+        typeof data.imageName !== "string" ||
+        typeof data.status !== "string" ||
+        !IMAGE_BUILD_STATUSES.has(data.status)) {
+        return null;
+    }
+    const build = data;
+    if (build.imageName !== imageName) {
+        return null;
+    }
+    return build;
+};
+exports.matchingImageBuild = matchingImageBuild;
+const completedImageId = (build) => {
+    if (build.status !== "completed") {
+        return undefined;
+    }
+    if (!build.imageId) {
+        throw new Error("Completed image build did not return an image ID");
+    }
+    return build.imageId;
+};
+exports.completedImageId = completedImageId;
+const isTerminalImageBuildStatus = (status) => status === "completed" || status === "failed" || status === "canceled";
+exports.isTerminalImageBuildStatus = isTerminalImageBuildStatus;

package/dist/sandbox/image-build/tar.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal tar support: a PAX-format writer that mirrors CPython's `tarfile`
+ * output for the normalized entries used in build contexts, and a streaming
+ * reader for `docker image save` archives.
+ */
+import type { Readable } from "stream";
+export type TarEntryType = "file" | "directory" | "symlink";
+export interface TarEntryInfo {
+    /** Archive path; directories carry a trailing slash. */
+    name: string;
+    type: TarEntryType;
+    mode: number;
+    size: number;
+    linkname: string;
+}
+export declare const createTarEntryHeader: (info: TarEntryInfo) => Buffer;
+export type TarSink = (chunk: Buffer) => Promise<void>;
+/** Sequential PAX tar writer; `close` writes the end-of-archive blocks. */
+export declare class PaxTarWriter {
+    private readonly sink;
+    private written;
+    constructor(sink: TarSink);
+    private emit;
+    addEntry(info: TarEntryInfo, content?: AsyncIterable<Buffer>): Promise<void>;
+    close(): Promise<void>;
+}
+export interface TarStreamEntry {
+    name: string;
+    size: number;
+    typeflag: string;
+    mode: number;
+    linkname: string;
+    isFile: boolean;
+    /** Stream the entry contents. Must be consumed before advancing. */
+    content(): AsyncGenerator<Buffer>;
+}
+/**
+ * Iterate over tar entries from a stream. Callers must fully consume an
+ * entry's content before advancing; unread content is skipped.
+ */
+export declare function readTarEntries(source: Readable): AsyncGenerator<TarStreamEntry>;