spawnfile 0.1.13 → 0.1.17

package/dist/target/dockerCommandExecutor.d.ts

@@ -0,0 +1,38 @@
+import { type DockerOrganizationAttachmentExecutor } from "./organizationAttachmentProvider.js";
+import { type DockerArtifactExecutor } from "./dockerArtifactsProvider.js";
+import { type DockerResourceExecutor } from "./dockerResourcesProvider.js";
+import { type DockerSecretExecutor } from "./dockerSecretsProvider.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import type { DockerEvidenceExportExecutor } from "./evidenceExportProvider.js";
+import { type DockerCommandSpawn } from "./dockerCommandExecutorCore.js";
+export declare const PUBLIC_ARTIFACT_READER_PROGRAM: string;
+/** Private control signal emitted only for an exact missing public path probe. */
+export declare class DockerPublicArtifactNotPresentError extends Error {
+    readonly kind: "not_present";
+    constructor();
+}
+export interface DockerTargetExecutors {
+    readonly artifact: DockerArtifactExecutor;
+    readonly attachment: DockerOrganizationAttachmentExecutor;
+    readonly evidenceExport: DockerEvidenceExportExecutor;
+    readonly publicArtifact: (file: string, args: readonly string[], options: {
+        readonly signal?: AbortSignal;
+        readonly timeout: number;
+    }) => Promise<{
+        readonly bytes: Uint8Array;
+    }>;
+    readonly resource: DockerResourceExecutor;
+    readonly secret: DockerSecretExecutor;
+    readonly world: DockerWorldServiceExecutor;
+}
+export declare const createPublicArtifactReadCommand: (input: {
+    readonly containerId: string;
+    readonly context: string;
+    readonly path: string;
+}) => string[];
+export interface CreateDockerTargetExecutorsOptions {
+    readonly dockerCommand?: string;
+    readonly spawn?: DockerCommandSpawn;
+}
+export declare const createDockerTargetExecutors: (options?: CreateDockerTargetExecutorsOptions) => DockerTargetExecutors;
+export type { DockerCommandSpawn } from "./dockerCommandExecutorCore.js";

package/dist/target/dockerCommandExecutor.js

@@ -0,0 +1,251 @@
+import { spawn } from "node:child_process";
+import { types as nodeTypes } from "node:util";
+import { DockerOrganizationAttachmentProviderError } from "./organizationAttachmentProvider.js";
+import { DockerArtifactProviderError } from "./dockerArtifactsProvider.js";
+import { DockerResourceProviderError } from "./dockerResourcesProvider.js";
+import { DockerSecretProviderError } from "./dockerSecretsProvider.js";
+import { DockerWorldServiceProviderError } from "./dockerWorldServiceProvider.js";
+import { MAX_TARGET_PUBLIC_ARTIFACT_BYTES, isTargetPublicArtifactPath } from "./publicArtifactSnapshot.js";
+import { DOCKER_COMMAND_ERROR, DockerCommandFailure, executeDockerCommandCore } from "./dockerCommandExecutorCore.js";
+const PUBLIC_ARTIFACT_NOT_PRESENT_EXIT = 42;
+// The public directory is a separately mounted tmpfs and paths are restricted
+// to direct children.  Open the leaf exactly once with O_NOFOLLOW: no path
+// preflight is permitted because it would turn a replacement into a TOCTOU
+// disclosure.  Only ENOENT from that open denotes the terminal absence state.
+export const PUBLIC_ARTIFACT_READER_PROGRAM = [
+    "import fs from 'node:fs';",
+    "const path = process.argv[1];",
+    "let fd;",
+    "try { fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); }",
+    "catch (error) { process.exitCode = error?.code === 'ENOENT' ? 42 : 43; }",
+    "if (fd !== undefined) {",
+    "  try {",
+    "    if (!fs.fstatSync(fd).isFile()) process.exitCode = 43;",
+    "    else { const chunks = []; let bytes; do { const chunk = Buffer.allocUnsafe(65536); bytes = fs.readSync(fd, chunk); if (bytes) chunks.push(chunk.subarray(0, bytes)); } while (bytes); process.stdout.write(Buffer.concat(chunks)); }",
+    "  } catch { process.exitCode = 43; } finally { fs.closeSync(fd); }",
+    "}"
+].join(" ");
+/** Private control signal emitted only for an exact missing public path probe. */
+export class DockerPublicArtifactNotPresentError extends Error {
+    kind = "not_present";
+    constructor() {
+        super("Target public artifact is not present");
+        this.name = "DockerPublicArtifactNotPresentError";
+    }
+}
+const role = (args) => {
+    if (args[0] === "--context") {
+        return args.length >= 3 && /^[a-z][a-z0-9_-]{0,63}$/u.test(args[1]) ? args.slice(2) : [];
+    }
+    if (args[0] === "--config") {
+        return args.length >= 5 && typeof args[1] === "string" && args[1].startsWith("/")
+            && args[1].length <= 4_096 && !/\s/u.test(args[1])
+            && args[2] === "--context" && /^[a-z][a-z0-9_-]{0,63}$/u.test(args[3])
+            ? args.slice(4) : [];
+    }
+    return args;
+};
+const exactPublicArtifactAbsence = (args, error) => {
+    if (!(error instanceof DockerCommandFailure)
+        || error.code !== PUBLIC_ARTIFACT_NOT_PRESENT_EXIT || error.stderr !== ""
+        || error.stdoutBytes !== 0)
+        return undefined;
+    const command = role(args);
+    const path = command[8];
+    if (command.length !== 9
+        || command[0] !== "container" || command[1] !== "exec"
+        || !/^[a-f0-9]{64}$/u.test(command[2])
+        || command[3] !== "/usr/local/bin/node" || command[4] !== "--input-type=module"
+        || command[5] !== "-e" || command[6] !== PUBLIC_ARTIFACT_READER_PROGRAM
+        || command[7] !== "spawnfile-public-artifact-read"
+        || !isTargetPublicArtifactPath(path))
+        return undefined;
+    return new DockerPublicArtifactNotPresentError();
+};
+const exactMissingImageReference = (requested, reported) => {
+    if (requested === undefined || reported === requested)
+        return reported === requested;
+    const lastSlash = requested.lastIndexOf("/");
+    const lastColon = requested.lastIndexOf(":");
+    const hasExplicitTagOrDigest = requested.includes("@") || lastColon > lastSlash;
+    return !hasExplicitTagOrDigest && reported === `${requested}:latest`;
+};
+const exactVolumeAbsence = (kind, command, message) => {
+    if (kind !== "resource" && kind !== "secret")
+        return undefined;
+    const inspect = command.length === 3 && command[0] === "volume" && command[1] === "inspect"
+        || command.length === 5 && command[0] === "volume" && command[1] === "inspect"
+            && command[2] === "--format" && typeof command[3] === "string" && command[3].length > 0;
+    const remove = command.length === 3 && command[0] === "volume" && command[1] === "rm";
+    if (!inspect && !remove)
+        return undefined;
+    const oldForm = /^(?:Error response from daemon: )?No such volume: ([A-Za-z0-9_.:-]+)$/u.exec(message);
+    const docker29Form = /^Error response from daemon: get ([A-Za-z0-9_.:-]+): no such volume$/u.exec(message);
+    const reported = oldForm?.[1] ?? docker29Form?.[1];
+    if (reported === undefined || reported !== command.at(-1))
+        return undefined;
+    return kind === "resource"
+        ? new DockerResourceProviderError("not_found")
+        : new DockerSecretProviderError("not_found");
+};
+const classify = (kind, args, error) => {
+    if (!(error instanceof DockerCommandFailure)
+        || !Number.isInteger(error.code) || error.code <= 0)
+        return new Error(DOCKER_COMMAND_ERROR);
+    const command = role(args);
+    const message = error.stderr.trim();
+    const missingImage = /^(?:Error response from daemon: )?No such image: ([A-Za-z0-9_.:@/-]+)$/u.exec(message);
+    if (kind === "artifact" && command[0] === "image" && command[1] === "inspect"
+        && missingImage && exactMissingImageReference(command.at(-1), missingImage[1])) {
+        return new DockerArtifactProviderError("image_not_found");
+    }
+    const missingVolume = exactVolumeAbsence(kind, command, message);
+    if (missingVolume)
+        return missingVolume;
+    const docker29MissingNetwork = /^Error response from daemon: network ([A-Za-z0-9_.:-]+) not found$/u.exec(message);
+    if (kind === "resource" && command[0] === "network"
+        && (command[1] === "inspect" || command[1] === "rm")
+        && docker29MissingNetwork?.[1] === command.at(-1)) {
+        return new DockerResourceProviderError("not_found");
+    }
+    let collisionNoun;
+    if (/^(?:Error response from daemon: )?network with name [A-Za-z0-9_.:-]+ already exists$/u.test(message))
+        collisionNoun = "network";
+    else if (/^(?:Error response from daemon: )?volume [A-Za-z0-9_.:-]+ already exists$/u.test(message))
+        collisionNoun = "volume";
+    else if (/^(?:Error response from daemon: )?Conflict\. The container name "[A-Za-z0-9_.:/-]+" is already in use by container "[a-f0-9]{12,64}"\.$/u.test(message))
+        collisionNoun = "container";
+    const createNoun = command[0] === "run" ? "container"
+        : command[1] === "create" && ["container", "network", "volume"].includes(command[0])
+            ? command[0] : undefined;
+    if (collisionNoun && collisionNoun === createNoun) {
+        if (kind === "resource" && collisionNoun !== "container")
+            return new DockerResourceProviderError("collision");
+        if (kind === "secret" && (collisionNoun === "volume" || collisionNoun === "container"))
+            return new DockerSecretProviderError("collision");
+        if (kind === "world" && collisionNoun === "container")
+            return new DockerWorldServiceProviderError("collision");
+    }
+    const missing = /^(?:Error response from daemon: )?No such (container|network): [A-Za-z0-9_.:/-]+$/u.exec(message);
+    const noun = command[0];
+    const mutation = command[1];
+    const roleEligible = kind === "resource"
+        ? (noun === "network" || noun === "volume")
+            && (mutation === "inspect" || mutation === "rm")
+        : kind === "secret"
+            ? noun === "volume" && (mutation === "inspect" || mutation === "rm")
+                || noun === "container" && ["inspect", "rm", "wait", "stop"].includes(mutation)
+            : kind === "attachment"
+                ? noun === "container" && mutation === "inspect"
+                    || noun === "network" && ["inspect", "connect", "disconnect"].includes(mutation)
+                : noun === "container" && ["inspect", "rm", "stop"].includes(mutation);
+    const nounMatches = Boolean(missing) && (missing[1] === command[0]
+        || kind === "attachment" && command[0] === "network"
+            && (mutation === "connect" || mutation === "disconnect")
+            && (missing[1] === "network" || missing[1] === "container"));
+    if (roleEligible && nounMatches) {
+        if (kind === "resource" && missing[1] === "network")
+            return new DockerResourceProviderError("not_found");
+        if (kind === "secret" && missing[1] === "container")
+            return new DockerSecretProviderError("not_found");
+        if (kind === "attachment")
+            return new DockerOrganizationAttachmentProviderError("not_found");
+        if (kind === "world" && missing[1] === "container")
+            return new DockerWorldServiceProviderError("not_found");
+    }
+    return new Error(DOCKER_COMMAND_ERROR);
+};
+export const createPublicArtifactReadCommand = (input) => [
+    "--context", input.context, "container", "exec", input.containerId,
+    "/usr/local/bin/node", "--input-type=module", "-e", PUBLIC_ARTIFACT_READER_PROGRAM,
+    "spawnfile-public-artifact-read", input.path
+];
+const normalizeCommandOptions = (raw, allowStdin) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || nodeTypes.isProxy(raw)
+        || Object.getPrototypeOf(raw) !== Object.prototype)
+        throw new Error(DOCKER_COMMAND_ERROR);
+    const keys = Reflect.ownKeys(raw);
+    const allowed = allowStdin ? ["signal", "stdin", "timeout"] : ["signal", "timeout"];
+    if (keys.some((key) => typeof key !== "string" || !allowed.includes(key))
+        || !keys.includes("timeout"))
+        throw new Error(DOCKER_COMMAND_ERROR);
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    if (Object.values(descriptors).some((descriptor) => !descriptor.enumerable || !("value" in descriptor)))
+        throw new Error(DOCKER_COMMAND_ERROR);
+    return {
+        signal: descriptors.signal?.value,
+        stdin: descriptors.stdin?.value,
+        timeout: descriptors.timeout.value
+    };
+};
+export const createDockerTargetExecutors = (options = {}) => {
+    if (!options || typeof options !== "object" || Array.isArray(options)
+        || nodeTypes.isProxy(options) || Object.getPrototypeOf(options) !== Object.prototype) {
+        throw new Error(DOCKER_COMMAND_ERROR);
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(options);
+    if (Reflect.ownKeys(options).some((key) => typeof key !== "string"
+        || !["dockerCommand", "spawn"].includes(key))
+        || Object.values(descriptors).some((descriptor) => !("value" in descriptor))) {
+        throw new Error(DOCKER_COMMAND_ERROR);
+    }
+    const spawnCommand = descriptors.spawn?.value
+        ?? spawn;
+    const dockerCommand = descriptors.dockerCommand?.value ?? "docker";
+    if (typeof spawnCommand !== "function")
+        throw new Error(DOCKER_COMMAND_ERROR);
+    const text = (kind) => async (file, args, commandOptions) => {
+        try {
+            if (file !== "docker")
+                throw new Error(DOCKER_COMMAND_ERROR);
+            const normalized = normalizeCommandOptions(commandOptions, true);
+            const result = await executeDockerCommandCore(spawnCommand, dockerCommand, args, {
+                ...normalized, binary: false
+            });
+            return { stderr: result.stderr, stdout: result.stdout };
+        }
+        catch (error) {
+            throw kind ? classify(kind, args, error) : new Error(DOCKER_COMMAND_ERROR);
+        }
+    };
+    return Object.freeze({
+        artifact: text("artifact"),
+        attachment: text("attachment"),
+        evidenceExport: async (file, args, commandOptions) => {
+            try {
+                if (file !== "docker")
+                    throw new Error(DOCKER_COMMAND_ERROR);
+                const normalized = normalizeCommandOptions(commandOptions, false);
+                const result = await executeDockerCommandCore(spawnCommand, dockerCommand, args, {
+                    ...normalized, binary: true
+                });
+                return { bytes: result.stdout };
+            }
+            catch {
+                throw new Error(DOCKER_COMMAND_ERROR);
+            }
+        },
+        publicArtifact: async (file, args, commandOptions) => {
+            try {
+                if (file !== "docker")
+                    throw new Error(DOCKER_COMMAND_ERROR);
+                const normalized = normalizeCommandOptions(commandOptions, false);
+                const result = await executeDockerCommandCore(spawnCommand, dockerCommand, args, {
+                    ...normalized,
+                    binary: true,
+                    stdoutCap: MAX_TARGET_PUBLIC_ARTIFACT_BYTES
+                });
+                return { bytes: Uint8Array.from(result.stdout) };
+            }
+            catch (error) {
+                const absence = exactPublicArtifactAbsence(args, error);
+                if (absence)
+                    throw absence;
+                throw new Error(DOCKER_COMMAND_ERROR);
+            }
+        },
+        resource: text("resource"),
+        secret: text("secret"),
+        world: text("world")
+    });
+};

package/dist/target/dockerCommandExecutorCore.d.ts

@@ -0,0 +1,35 @@
+import type { Readable, Writable } from "node:stream";
+export declare const DOCKER_COMMAND_ERROR = "Docker command failed";
+export declare const DOCKER_TEXT_CAP = 32768;
+export declare const DOCKER_BINARY_CAP = 67108864;
+export interface SpawnedDockerCommand {
+    readonly stderr: Readable;
+    readonly stdin: Writable;
+    readonly stdout: Readable;
+    kill(signal?: NodeJS.Signals): boolean;
+    off(event: string, listener: (...args: never[]) => void): this;
+    on(event: string, listener: (...args: never[]) => void): this;
+    once(event: string, listener: (...args: never[]) => void): this;
+}
+export type DockerCommandSpawn = (file: string, args: readonly string[], options: {
+    readonly shell: false;
+    readonly stdio: ["pipe", "pipe", "pipe"];
+}) => SpawnedDockerCommand;
+export declare class DockerCommandFailure extends Error {
+    readonly code: number;
+    readonly stderr: string;
+    readonly stdoutBytes: number;
+    constructor(code: number, stderr: string, stdoutBytes: number);
+}
+export interface DockerCommandCoreOptions {
+    readonly binary: boolean;
+    readonly signal?: AbortSignal;
+    readonly stdin?: Uint8Array;
+    readonly stdoutCap?: number;
+    readonly timeout: number;
+}
+export interface DockerCommandCoreResult {
+    readonly stderr: string;
+    readonly stdout: string | Uint8Array;
+}
+export declare const executeDockerCommandCore: (spawnCommand: DockerCommandSpawn, file: string, args: readonly string[], rawOptions: DockerCommandCoreOptions) => Promise<DockerCommandCoreResult>;

package/dist/target/dockerCommandExecutorCore.js

@@ -0,0 +1,275 @@
+import { Buffer } from "node:buffer";
+import { types as nodeTypes } from "node:util";
+export const DOCKER_COMMAND_ERROR = "Docker command failed";
+export const DOCKER_TEXT_CAP = 32_768;
+export const DOCKER_BINARY_CAP = 67_108_864;
+const FALLBACK_MS = 50;
+export class DockerCommandFailure extends Error {
+    code;
+    stderr;
+    stdoutBytes;
+    constructor(code, stderr, stdoutBytes) {
+        super(DOCKER_COMMAND_ERROR);
+        this.code = code;
+        this.stderr = stderr;
+        this.stdoutBytes = stdoutBytes;
+    }
+}
+const ordinaryOptions = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || nodeTypes.isProxy(raw)
+        || Object.getPrototypeOf(raw) !== Object.prototype)
+        return false;
+    const value = raw;
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== "string"))
+        return false;
+    const names = keys.sort();
+    const data = Object.fromEntries(names.map((key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return [key, descriptor && "value" in descriptor && descriptor.enumerable
+                ? descriptor.value : Symbol("invalid")];
+    }));
+    if (!names.every((key) => ["binary", "signal", "stdin", "stdoutCap", "timeout"].includes(key))
+        || !names.includes("binary") || !names.includes("timeout")
+        || typeof data.binary !== "boolean"
+        || data.stdoutCap !== undefined && (!Number.isSafeInteger(data.stdoutCap)
+            || data.stdoutCap < 1
+            || data.stdoutCap > (data.binary ? DOCKER_BINARY_CAP : DOCKER_TEXT_CAP))
+        || !Number.isSafeInteger(data.timeout) || data.timeout < 1
+        || data.timeout > 120_000
+        || data.signal !== undefined && !(data.signal instanceof AbortSignal)
+        || data.stdin !== undefined && (!(data.stdin instanceof Uint8Array)
+            || nodeTypes.isProxy(data.stdin)))
+        return false;
+    return true;
+};
+const validate = (file, args, options) => {
+    if (typeof file !== "string" || file.length < 1 || file.length > 128 || file.includes("\0")
+        || Buffer.from(file, "utf8").toString("utf8") !== file
+        || !Array.isArray(args) || nodeTypes.isProxy(args)
+        || Object.getPrototypeOf(args) !== Array.prototype || args.length > 1_024
+        || !ordinaryOptions(options))
+        throw new Error(DOCKER_COMMAND_ERROR);
+    const ownKeys = Reflect.ownKeys(args);
+    if (ownKeys.length !== args.length + 1 || !ownKeys.includes("length")) {
+        throw new Error(DOCKER_COMMAND_ERROR);
+    }
+    let total = 0;
+    for (let index = 0; index < args.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(args, String(index));
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+            throw new Error(DOCKER_COMMAND_ERROR);
+        }
+        const arg = descriptor.value;
+        if (typeof arg !== "string" || arg.includes("\0")
+            || Buffer.from(arg, "utf8").toString("utf8") !== arg)
+            throw new Error(DOCKER_COMMAND_ERROR);
+        total += Buffer.byteLength(arg, "utf8");
+        if (total > 262_144)
+            throw new Error(DOCKER_COMMAND_ERROR);
+    }
+};
+const decode = (chunks) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new Error(DOCKER_COMMAND_ERROR);
+    }
+};
+export const executeDockerCommandCore = (spawnCommand, file, args, rawOptions) => {
+    validate(file, args, rawOptions);
+    const options = rawOptions;
+    if (options.signal?.aborted)
+        return Promise.reject(new Error(DOCKER_COMMAND_ERROR));
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnCommand(file, args, { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+        }
+        catch {
+            reject(new Error(DOCKER_COMMAND_ERROR));
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdin = options.stdin;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let childClosed = false;
+        let stdoutClosed = false;
+        let stderrClosed = false;
+        let stdinDone = false;
+        let stdinClosed = false;
+        let closeCode = null;
+        let terminal;
+        let settled = false;
+        let killed = false;
+        let fallback;
+        const swallow = () => undefined;
+        const clearBuffers = () => {
+            stdoutChunks.splice(0);
+            stderrChunks.splice(0);
+            stdin = undefined;
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            if (fallback)
+                clearTimeout(fallback);
+            options.signal?.removeEventListener("abort", onAbort);
+            child.off("error", onChildError);
+            child.off("close", onChildClose);
+            child.stdout.off("data", onStdoutData);
+            child.stderr.off("data", onStderrData);
+            child.stdout.off("error", onStreamError);
+            child.stderr.off("error", onStreamError);
+            child.stdin.off("error", onStreamError);
+            child.stdout.off("close", onStdoutClose);
+            child.stderr.off("close", onStderrClose);
+            child.stdin.off("close", onStdinClose);
+            clearBuffers();
+        };
+        const absorbUntilClose = (stream, alreadyClosed) => {
+            if (alreadyClosed)
+                return;
+            const release = () => { stream.off("error", swallow); };
+            stream.on("error", swallow);
+            stream.once("close", release);
+        };
+        const absorbLateErrors = () => {
+            if (!childClosed) {
+                const release = () => { child.off("error", swallow); };
+                child.on("error", swallow);
+                child.once("close", release);
+            }
+            absorbUntilClose(child.stdout, stdoutClosed);
+            absorbUntilClose(child.stderr, stderrClosed);
+            absorbUntilClose(child.stdin, stdinClosed);
+        };
+        const settle = (error, result, absorbLate = true) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (absorbLate)
+                absorbLateErrors();
+            if (error)
+                reject(error);
+            else
+                resolve(result);
+        };
+        const settleTerminated = () => settle(terminal ?? new Error(DOCKER_COMMAND_ERROR), undefined, true);
+        const requestTermination = (error) => {
+            if (settled || terminal)
+                return;
+            terminal = error;
+            if (!killed) {
+                killed = true;
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* bounded fallback settles safely */ }
+            }
+            fallback = setTimeout(settleTerminated, FALLBACK_MS);
+        };
+        const maybeSettle = () => {
+            if (settled)
+                return;
+            if (terminal) {
+                if (childClosed)
+                    settleTerminated();
+                return;
+            }
+            if (!childClosed || !stdoutClosed || !stderrClosed || !stdinDone)
+                return;
+            if (!Number.isInteger(closeCode) || closeCode === null || closeCode < 0) {
+                settle(new Error(DOCKER_COMMAND_ERROR));
+                return;
+            }
+            let stderr;
+            let stdout;
+            try {
+                stderr = decode(stderrChunks);
+                stdout = options.binary
+                    ? Uint8Array.from(Buffer.concat(stdoutChunks))
+                    : decode(stdoutChunks);
+            }
+            catch {
+                settle(new Error(DOCKER_COMMAND_ERROR));
+                return;
+            }
+            if (closeCode !== 0) {
+                settle(new DockerCommandFailure(closeCode, stderr, typeof stdout === "string" ? Buffer.byteLength(stdout, "utf8") : stdout.byteLength));
+                return;
+            }
+            settle(undefined, { stderr, stdout });
+        };
+        const append = (target, chunk, current, cap) => {
+            let value;
+            try {
+                value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            }
+            catch {
+                requestTermination(new Error(DOCKER_COMMAND_ERROR));
+                return current;
+            }
+            const next = current + value.byteLength;
+            if (next > cap) {
+                requestTermination(new Error(DOCKER_COMMAND_ERROR));
+                return next;
+            }
+            target.push(Buffer.from(value));
+            return next;
+        };
+        function onStdoutData(chunk) {
+            stdoutBytes = append(stdoutChunks, chunk, stdoutBytes, options.stdoutCap ?? (options.binary ? DOCKER_BINARY_CAP : DOCKER_TEXT_CAP));
+        }
+        function onStderrData(chunk) {
+            stderrBytes = append(stderrChunks, chunk, stderrBytes, DOCKER_TEXT_CAP);
+        }
+        function onChildError() { requestTermination(new Error(DOCKER_COMMAND_ERROR)); }
+        function onStreamError() { requestTermination(new Error(DOCKER_COMMAND_ERROR)); }
+        function onChildClose(code) {
+            childClosed = true;
+            closeCode = code;
+            maybeSettle();
+        }
+        function onStdoutClose() { stdoutClosed = true; maybeSettle(); }
+        function onStderrClose() { stderrClosed = true; maybeSettle(); }
+        function onStdinClose() { stdinClosed = true; }
+        function onAbort() { requestTermination(new Error(DOCKER_COMMAND_ERROR)); }
+        child.stdout.on("data", onStdoutData);
+        child.stderr.on("data", onStderrData);
+        child.on("error", onChildError);
+        child.on("close", onChildClose);
+        child.stdout.on("error", onStreamError);
+        child.stderr.on("error", onStreamError);
+        child.stdin.on("error", onStreamError);
+        child.stdout.on("close", onStdoutClose);
+        child.stderr.on("close", onStderrClose);
+        child.stdin.on("close", onStdinClose);
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const timeout = setTimeout(() => requestTermination(new Error(DOCKER_COMMAND_ERROR)), options.timeout);
+        if (options.signal?.aborted)
+            requestTermination(new Error(DOCKER_COMMAND_ERROR));
+        if (settled || terminal)
+            return;
+        try {
+            const view = stdin
+                ? Buffer.from(stdin.buffer, stdin.byteOffset, stdin.byteLength)
+                : undefined;
+            child.stdin.end(view, (error) => {
+                if (error) {
+                    requestTermination(new Error(DOCKER_COMMAND_ERROR));
+                    return;
+                }
+                stdinDone = true;
+                stdin = undefined;
+                maybeSettle();
+            });
+        }
+        catch {
+            requestTermination(new Error(DOCKER_COMMAND_ERROR));
+        }
+    });
+};

package/dist/target/dockerContainerBundleBuilder.d.ts

@@ -0,0 +1,8 @@
+import { type DockerArtifactExecutor } from "./dockerArtifactsProvider.js";
+import type { DockerTargetLocalBundleBuilder } from "./containerBundle.js";
+/** Private Docker lowering. It refuses tag adoption; durable post-build recovery uses inspect() instead. */
+export declare const createDockerTargetLocalBundleBuilder: (input: {
+    readonly context: string;
+    readonly executor: DockerArtifactExecutor;
+    readonly timeoutMs?: number;
+}) => DockerTargetLocalBundleBuilder;