boxdown 1.2.1 → 1.3.0

package/dist/{main-J4_2Up3o.mjs → main-O__JaiXe.mjs}

@@ -3,6 +3,7 @@ import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtemp
 import { createHash, randomUUID } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, isAbsolute, join, parse, relative, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
@@ -970,41 +971,12 @@ function publishContainerPortFromConfig(config) {
 	return config.runArgs?.find((arg) => /^[0-9.]+::[0-9]+$/.test(arg))?.split("::")[1];
 }
 
-//#endregion
-//#region src/devcontainer-cli.ts
-function devcontainerBinFromPackageJson(packageJson) {
-	return typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.devcontainer;
-}
-function resolveDevcontainerCli(context) {
-	const requireFromBoxdown = createRequire(join(context.packageRoot, "package.json"));
-	let packageJsonPath;
-	try {
-		packageJsonPath = requireFromBoxdown.resolve("@devcontainers/cli/package.json");
-	} catch (error) {
-		throw new Error(`Boxdown's packaged @devcontainers/cli dependency is missing. Reinstall boxdown so @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} is available.`, { cause: error });
-	}
-	const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-	const bin = devcontainerBinFromPackageJson(packageJson);
-	if (packageJson.version !== "0.84.1") {
-		throw new Error(`Boxdown expected @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} but resolved ${packageJson.version ?? "an unknown version"}.`);
-	}
-	if (bin === undefined) {
-		throw new Error("Boxdown resolved @devcontainers/cli, but the package does not expose a devcontainer binary.");
-	}
-	const cliPath = resolve(dirname(packageJsonPath), bin);
-	if (!existsSync(cliPath)) {
-		throw new Error(`Boxdown resolved @devcontainers/cli, but its devcontainer binary is missing: ${cliPath}`);
-	}
-	return {
-		command: process.execPath,
-		argsPrefix: [cliPath],
-		path: cliPath,
-		version: packageJson.version
-	};
-}
-
 //#endregion
 //#region src/process.ts
+const realTimeoutControl = {
+	schedule: (callback, milliseconds) => setTimeout(callback, milliseconds),
+	cancel: (handle) => clearTimeout(handle)
+};
 function mergedEnv(env) {
 	const baseEnv = {
 		...process.env,
@@ -1057,6 +1029,9 @@ function writeChunk(target, chunk) {
 	}
 }
 function runBuffered(command, args, options = {}) {
+	if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+		throw new Error("timeoutMs must be a finite non-negative number");
+	}
 	return new Promise((resolve) => {
 		const loggedCommand = options.logger?.startCommand(command, args, { cwd: options.cwd });
 		const child = spawn(command, args, {
@@ -1070,24 +1045,28 @@ function runBuffered(command, args, options = {}) {
 		});
 		const stdoutChunks = [];
 		const stderrChunks = [];
+		let settled = false;
+		let timeoutHandle;
+		let timeoutScheduled = false;
+		const timeoutControl = options.timeoutControl ?? realTimeoutControl;
 		child.stdout.on("data", (chunk) => {
+			if (settled) return;
 			stdoutChunks.push(chunk);
 			loggedCommand?.stream("stdout", chunk);
 			options.onStdout?.(chunk);
 			writeChunk(options.mirrorStdout ?? "stdout", chunk);
 		});
 		child.stderr.on("data", (chunk) => {
+			if (settled) return;
 			stderrChunks.push(chunk);
 			loggedCommand?.stream("stderr", chunk);
 			options.onStderr?.(chunk);
 			writeChunk(options.mirrorStderr ?? "stderr", chunk);
 		});
-		let resolved = false;
 		child.on("error", (error) => {
-			if (resolved) {
-				return;
-			}
-			resolved = true;
+			if (settled) return;
+			settled = true;
+			if (timeoutScheduled) timeoutControl.cancel(timeoutHandle);
 			loggedCommand?.error(error);
 			loggedCommand?.finish(127);
 			resolve({
@@ -1097,10 +1076,9 @@ function runBuffered(command, args, options = {}) {
 			});
 		});
 		child.on("close", (code) => {
-			if (resolved) {
-				return;
-			}
-			resolved = true;
+			if (settled) return;
+			settled = true;
+			if (timeoutScheduled) timeoutControl.cancel(timeoutHandle);
 			loggedCommand?.finish(code ?? 1);
 			resolve({
 				code: code ?? 1,
@@ -1108,6 +1086,25 @@ function runBuffered(command, args, options = {}) {
 				stderr: Buffer.concat(stderrChunks).toString("utf8")
 			});
 		});
+		if (options.timeoutMs !== undefined) {
+			timeoutHandle = timeoutControl.schedule(() => {
+				if (settled) return;
+				settled = true;
+				const message = `Command timed out after ${options.timeoutMs} milliseconds.`;
+				const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+				const stderr = Buffer.concat(stderrChunks).toString("utf8");
+				loggedCommand?.error(new Error(message));
+				loggedCommand?.finish(124);
+				child.kill("SIGKILL");
+				resolve({
+					code: 124,
+					stdout,
+					stderr: `${stderr}${stderr.length > 0 && !stderr.endsWith("\n") ? "\n" : ""}${message}\n`,
+					timedOut: true
+				});
+			}, options.timeoutMs);
+			timeoutScheduled = true;
+		}
 		if (options.input !== undefined) {
 			child.stdin.end(options.input);
 		} else {
@@ -1136,6 +1133,250 @@ function runInteractive(command, args, options = {}) {
 	});
 }
 
+//#endregion
+//#region src/container-runtime.ts
+const BUILDX_FALLBACK_WARNING = "Docker Buildx is unavailable; the Dev Containers CLI will use its classic-build fallback.";
+async function runContainerRuntimeCommand(command, args, timeoutMs) {
+	return runBuffered(command, args, {
+		mirrorStdout: false,
+		mirrorStderr: false,
+		timeoutMs
+	});
+}
+function compactCommandOutput(result) {
+	const output = result.stderr.trim().length > 0 ? result.stderr : result.stdout;
+	const compact = output.trim().replace(/\s+/gu, " ").slice(0, 500);
+	return compact.length > 0 ? compact : `Command exited with code ${result.code}`;
+}
+function failure(reason, command, result) {
+	return {
+		reason,
+		command,
+		detail: compactCommandOutput(result),
+		...result.timedOut === true ? { timedOut: true } : {}
+	};
+}
+async function probeContainerRuntime(runCommand = runContainerRuntimeCommand) {
+	const dockerVersionCommand = ["docker", "--version"];
+	const dockerVersion = await runCommand(dockerVersionCommand[0], dockerVersionCommand.slice(1));
+	if (dockerVersion.code !== 0) {
+		return {
+			state: "failed",
+			failure: failure("docker-cli-unavailable", dockerVersionCommand, dockerVersion)
+		};
+	}
+	const dockerInfoCommand = ["docker", "info"];
+	const dockerInfo = await runCommand(dockerInfoCommand[0], dockerInfoCommand.slice(1));
+	if (dockerInfo.code !== 0) {
+		return {
+			state: "waiting",
+			failure: failure("docker-daemon-unavailable", dockerInfoCommand, dockerInfo)
+		};
+	}
+	const buildxVersionCommand = [
+		"docker",
+		"buildx",
+		"version"
+	];
+	const buildxVersion = await runCommand(buildxVersionCommand[0], buildxVersionCommand.slice(1));
+	if (buildxVersion.timedOut === true) {
+		return {
+			state: "waiting",
+			failure: failure("buildx-builder-unavailable", buildxVersionCommand, buildxVersion)
+		};
+	}
+	if (buildxVersion.code !== 0) {
+		return {
+			state: "ready",
+			mode: "fallback",
+			warnings: [BUILDX_FALLBACK_WARNING]
+		};
+	}
+	const buildxInspectCommand = [
+		"docker",
+		"buildx",
+		"inspect",
+		"--bootstrap"
+	];
+	const buildxInspect = await runCommand(buildxInspectCommand[0], buildxInspectCommand.slice(1));
+	if (buildxInspect.code !== 0) {
+		return {
+			state: "waiting",
+			failure: failure("buildx-builder-unavailable", buildxInspectCommand, buildxInspect)
+		};
+	}
+	return {
+		state: "ready",
+		mode: "buildx",
+		warnings: []
+	};
+}
+function defaultSleep(milliseconds) {
+	return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function transitionKey(probe) {
+	return probe.state === "ready" ? "ready" : `${probe.state}:${probe.failure.reason}`;
+}
+var ContainerRuntimeDeadlineError = class extends Error {
+	command;
+	constructor(command) {
+		super(`Container runtime deadline expired before ${command.join(" ")}`);
+		this.command = command;
+	}
+};
+function deadlineFailure(command) {
+	const reason = command[1] === "info" ? "docker-daemon-unavailable" : command[1] === "buildx" ? "buildx-builder-unavailable" : "docker-cli-unavailable";
+	return {
+		reason,
+		command,
+		detail: `Readiness deadline expired before ${command.join(" ")} could start.`,
+		timedOut: true
+	};
+}
+/** @internal */
+async function waitForContainerRuntimeInternal(options = {}) {
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+	if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 6e4) {
+		throw new Error("timeoutMs must be a finite number between 0 and 60000 milliseconds");
+	}
+	if (pollIntervalMs !== 1e3) {
+		throw new Error("pollIntervalMs must be exactly 1000 milliseconds");
+	}
+	const now = options.now ?? Date.now;
+	const sleep = options.sleep ?? defaultSleep;
+	const deadline = now() + timeoutMs;
+	let lastTransition;
+	let lastWaitingFailure;
+	while (true) {
+		if (lastWaitingFailure !== undefined && deadline - now() <= 0) {
+			return {
+				state: "failed",
+				failure: lastWaitingFailure,
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		const runCommand = options.runCommand ?? runContainerRuntimeCommand;
+		let lastStartedCommand;
+		let probe;
+		try {
+			probe = await probeContainerRuntime(async (command, args) => {
+				const commandArgs = [command, ...args];
+				const remainingMs = Math.floor(deadline - now());
+				if (remainingMs <= 0) throw new ContainerRuntimeDeadlineError(commandArgs);
+				lastStartedCommand = commandArgs;
+				return runCommand(command, args, remainingMs);
+			});
+		} catch (error) {
+			if (!(error instanceof ContainerRuntimeDeadlineError)) throw error;
+			return {
+				state: "failed",
+				failure: lastWaitingFailure ?? deadlineFailure(error.command),
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		if (deadline - now() <= 0) {
+			const currentFailure = probe.state === "ready" ? deadlineFailure(lastStartedCommand ?? ["docker", "--version"]) : probe.failure;
+			return {
+				state: "failed",
+				failure: lastWaitingFailure ?? currentFailure,
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		if (probe.state === "ready") return probe;
+		const currentTransition = transitionKey(probe);
+		if (currentTransition !== lastTransition) {
+			options.onTransition?.(probe);
+			lastTransition = currentTransition;
+		}
+		if (probe.state === "failed") {
+			return {
+				state: "failed",
+				failure: probe.failure,
+				timedOut: probe.failure.timedOut === true,
+				timeoutMs
+			};
+		}
+		lastWaitingFailure = probe.failure;
+		const remainingMs = deadline - now();
+		if (remainingMs <= 0) {
+			return {
+				state: "failed",
+				failure: probe.failure,
+				timedOut: true,
+				timeoutMs
+			};
+		}
+		await sleep(Math.min(pollIntervalMs, remainingMs));
+	}
+}
+async function waitForContainerRuntime(options = {}) {
+	return waitForContainerRuntimeInternal({
+		runCommand: options.runCommand,
+		onTransition: options.onTransition,
+		timeoutMs: 6e4,
+		pollIntervalMs: 1e3,
+		now: () => performance.now(),
+		sleep: defaultSleep
+	});
+}
+function commandText(command) {
+	return command.join(" ");
+}
+function formatContainerRuntimeFailure(result, options = {}) {
+	const seconds = result.timeoutMs / 1e3;
+	const descriptions = {
+		"docker-cli-unavailable": "Docker CLI is required but was not available.",
+		"docker-daemon-unavailable": result.timedOut ? `Docker daemon did not become ready within ${seconds} seconds.` : "Docker daemon is required but was not reachable.",
+		"buildx-builder-unavailable": result.timedOut ? `Docker Buildx builder did not become ready within ${seconds} seconds.` : "Docker Buildx builder was not operational."
+	};
+	const manualCheck = result.failure.reason === "buildx-builder-unavailable" ? "docker buildx inspect" : result.failure.reason === "docker-daemon-unavailable" ? "docker info" : "docker --version";
+	const lines = [
+		descriptions[result.failure.reason],
+		`Last check: ${commandText(result.failure.command)}`,
+		`Detail: ${result.failure.detail}`,
+		`Check ${result.failure.reason === "buildx-builder-unavailable" ? "Buildx" : "Docker"} with: ${manualCheck}`
+	];
+	if (options.logPath !== undefined) lines.push(`Command log: ${options.logPath}`);
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/devcontainer-cli.ts
+function devcontainerBinFromPackageJson(packageJson) {
+	return typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.devcontainer;
+}
+function resolveDevcontainerCli(context) {
+	const requireFromBoxdown = createRequire(join(context.packageRoot, "package.json"));
+	let packageJsonPath;
+	try {
+		packageJsonPath = requireFromBoxdown.resolve("@devcontainers/cli/package.json");
+	} catch (error) {
+		throw new Error(`Boxdown's packaged @devcontainers/cli dependency is missing. Reinstall boxdown so @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} is available.`, { cause: error });
+	}
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	const bin = devcontainerBinFromPackageJson(packageJson);
+	if (packageJson.version !== "0.84.1") {
+		throw new Error(`Boxdown expected @devcontainers/cli@${DEVCONTAINER_CLI_VERSION} but resolved ${packageJson.version ?? "an unknown version"}.`);
+	}
+	if (bin === undefined) {
+		throw new Error("Boxdown resolved @devcontainers/cli, but the package does not expose a devcontainer binary.");
+	}
+	const cliPath = resolve(dirname(packageJsonPath), bin);
+	if (!existsSync(cliPath)) {
+		throw new Error(`Boxdown resolved @devcontainers/cli, but its devcontainer binary is missing: ${cliPath}`);
+	}
+	return {
+		command: process.execPath,
+		argsPrefix: [cliPath],
+		path: cliPath,
+		version: packageJson.version
+	};
+}
+
 //#endregion
 //#region src/git-signing.ts
 const GIT_SIGNING_REASON_MESSAGES = {
@@ -1516,10 +1757,40 @@ async function runDoctorChecks(context, options = {}) {
 		message: sshAgent.code !== 0 ? signingMessages["agent-unavailable"] : selected.key === undefined ? signingMessages[selected.reason ?? "ambiguous-identities"] : selectedByConfiguration ? "Configured SSH signing key is loaded in the agent" : selectedByGithub ? "GitHub authentication keys identify one SSH agent identity for Boxdown commit signing" : "One SSH agent identity is available for Boxdown commit signing"
 	});
 	checks.push(check("devcontainers-cli", await packagedDevcontainerCliWorks(context, runCommand), "Packaged @devcontainers/cli is available", "Packaged @devcontainers/cli is required but was not available"));
-	const dockerCliWorks = await commandWorks(runCommand, "docker", ["--version"]);
-	checks.push(check("docker-cli", dockerCliWorks, "Docker CLI is available", "Docker CLI is required but was not available"));
-	const dockerDaemonWorks = await commandWorks(runCommand, "docker", ["info"]);
-	checks.push(check("docker-daemon", dockerDaemonWorks, "Docker daemon is reachable", "Docker daemon is required but was not reachable"));
+	let dockerCliWorks = options.containerRuntimeReady === true;
+	let dockerDaemonWorks = options.containerRuntimeReady === true;
+	if (options.containerRuntimeReady !== true) {
+		const runtime = await probeContainerRuntime(runCommand);
+		dockerCliWorks = runtime.state === "ready" || runtime.failure.reason !== "docker-cli-unavailable";
+		dockerDaemonWorks = runtime.state === "ready" || runtime.state === "waiting" && runtime.failure.reason === "buildx-builder-unavailable";
+		checks.push(check("docker-cli", dockerCliWorks, "Docker CLI is available", "Docker CLI is required but was not available"));
+		checks.push(check("docker-daemon", dockerDaemonWorks, "Docker daemon is reachable", "Docker daemon is required but was not reachable"));
+		if (!dockerCliWorks || !dockerDaemonWorks) {
+			checks.push({
+				name: "docker-buildx",
+				level: "warn",
+				message: "Docker Buildx was not checked because the Docker runtime is unavailable"
+			});
+		} else if (runtime.state === "ready" && runtime.mode === "fallback") {
+			checks.push({
+				name: "docker-buildx",
+				level: "warn",
+				message: runtime.warnings[0]
+			});
+		} else if (runtime.state === "waiting") {
+			checks.push({
+				name: "docker-buildx",
+				level: "fail",
+				message: `Docker Buildx builder was not operational: ${runtime.failure.detail}`
+			});
+		} else {
+			checks.push({
+				name: "docker-buildx",
+				level: "ok",
+				message: "Docker Buildx builder is operational"
+			});
+		}
+	}
 	checks.push(check("ssh", await commandExists(runCommand, "ssh", ["-V"]), "ssh is available", "ssh is required but was not available"));
 	if (options.includeDockerMountProbe ?? true) {
 		checks.push(await checkDockerBindMounts(context, runCommand, dockerCliWorks && dockerDaemonWorks));
@@ -2077,6 +2348,14 @@ var ProgressReporter = class {
 		}
 		this.#writeLine(`${promptRail()}  ${color$1(message, "dim")}`);
 	}
+	status(message) {
+		if (this.mode === "none") return;
+		if (this.mode === "verbose") {
+			this.#write(this.target, message);
+			return;
+		}
+		this.#writeInteractiveLine(`${promptRail()}  ${color$1(message, "dim")}`);
+	}
 	warn(message) {
 		if (this.mode === "none") {
 			return;
@@ -2085,7 +2364,7 @@ var ProgressReporter = class {
 			this.#write(this.target, `Warning: ${message}`);
 			return;
 		}
-		this.#writeLine(`${promptRail()}  ${color$1("!", "dim")} ${message}`);
+		this.#writeInteractiveLine(`${promptRail()}  ${color$1("!", "dim")} ${message}`);
 	}
 	marker(message) {
 		if (this.#steps.length > 0) {
@@ -2198,6 +2477,16 @@ var ProgressReporter = class {
 		}
 		this.#write(this.target, message);
 	}
+	#writeInteractiveLine(message) {
+		if (this.#isTTY && this.#renderedStepLineCount > 0) {
+			this.#writeRaw(this.target, `\u001B[${this.#renderedStepLineCount}A\r\u001B[2K`);
+			this.#write(this.target, message);
+			this.#renderedStepLineCount = 0;
+			this.#renderChecklist();
+			return;
+		}
+		this.#writeLine(message);
+	}
 	#renderSpinner() {
 		const spinner = this.#spinner;
 		if (spinner === undefined) {
@@ -2330,13 +2619,27 @@ function createMarkerSink(progress) {
 function outputWithoutProgressMarkers(output) {
 	return output.split(/\r?\n/u).filter((line) => !isProgressMarkerLine(line)).join("\n");
 }
-function tailLines(output, maxLines) {
-	return output.split(/\r?\n/u).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0).slice(-maxLines);
+function outputLines(output) {
+	return output.split(/\r?\n/u).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0);
+}
+function isDevcontainerErrorEnvelope(line) {
+	try {
+		const value = JSON.parse(line);
+		return value !== null && typeof value === "object" && value.outcome === "error" && typeof value.message === "string";
+	} catch {
+		return false;
+	}
 }
 function formatCommandFailure(label, result, options = {}) {
 	const maxLines = options.tailLines ?? DEFAULT_FAILURE_TAIL_LINES;
-	const stderrTail = tailLines(outputWithoutProgressMarkers(result.stderr), maxLines);
-	const stdoutTail = tailLines(outputWithoutProgressMarkers(result.stdout), Math.max(0, maxLines - stderrTail.length));
+	const stderrLines = outputLines(outputWithoutProgressMarkers(result.stderr));
+	const stderrTail = maxLines <= 0 ? [] : stderrLines.slice(-maxLines);
+	const stdoutLines = outputLines(outputWithoutProgressMarkers(result.stdout));
+	const wrapperPresent = stdoutLines.some(isDevcontainerErrorEnvelope);
+	const specificStdout = stdoutLines.filter((line) => !isDevcontainerErrorEnvelope(line));
+	const hasSpecificDiagnostic = stderrLines.length > 0 || specificStdout.length > 0;
+	const stdoutBudget = Math.max(0, maxLines - stderrTail.length);
+	const stdoutTail = stdoutBudget === 0 ? [] : specificStdout.slice(-stdoutBudget);
 	const lines = [`${label} failed with exit code ${result.code}.`, "Rerun with --verbose to see full command output."];
 	if (stderrTail.length > 0) {
 		lines.push("", "stderr tail:", ...stderrTail.map((line) => `  ${line}`));
@@ -2344,6 +2647,12 @@ function formatCommandFailure(label, result, options = {}) {
 	if (stdoutTail.length > 0) {
 		lines.push("", "stdout tail:", ...stdoutTail.map((line) => `  ${line}`));
 	}
+	if (wrapperPresent && !hasSpecificDiagnostic) {
+		lines.push("", "The Dev Containers CLI reported a nested command failure without diagnostic output.");
+	}
+	if (options.logPath !== undefined) {
+		lines.push("", `Command log: ${options.logPath}`);
+	}
 	return lines.join("\n");
 }
 async function runProgressCommand(label, command, args, options = {}) {
@@ -2388,9 +2697,9 @@ async function runProgressCommand(label, command, args, options = {}) {
 		throw error;
 	}
 }
-function assertProgressCommandSucceeded(label, result, message) {
+function assertProgressCommandSucceeded(label, result, message, options = {}) {
 	if (result.code !== 0) {
-		throw new Error(`${message}\n${formatCommandFailure(label, result)}`);
+		throw new Error(`${message}\n${formatCommandFailure(label, result, options)}`);
 	}
 }
 
@@ -3123,7 +3432,7 @@ async function startDevcontainer(context, options = {}) {
 		mirrorStdout: proxyMode ? "stderr" : "stdout",
 		mirrorStderr: "stderr",
 		logger: options.logger
-	}) : await runProgressCommand("devcontainer up", cli.command, [...cli.argsPrefix, ...args], {
+	}) : await (options.runDevcontainerUp ?? runProgressCommand)("devcontainer up", cli.command, [...cli.argsPrefix, ...args], {
 		progress,
 		spinnerLabel: "Starting devcontainer",
 		stepId: "devcontainer-start",
@@ -3135,7 +3444,7 @@ async function startDevcontainer(context, options = {}) {
 		throw new Error(`devcontainer up failed for ${context.workspaceFolder}`);
 	}
 	if (progress !== undefined) {
-		assertProgressCommandSucceeded("devcontainer up", result, `devcontainer up failed for ${context.workspaceFolder}`);
+		assertProgressCommandSucceeded("devcontainer up", result, `devcontainer up failed for ${context.workspaceFolder}`, { logPath: options.logger?.logPath });
 	}
 	const containerId = parseContainerIdFromUpOutput(`${result.stdout}\n${result.stderr}`) ?? await findRunningContainerId(context, { logger: options.logger });
 	if (containerId === undefined) {
@@ -3233,7 +3542,7 @@ async function ensureContainerSshRuntime(context, options = {}) {
 		throw new Error("Failed to prepare devcontainer SSH runtime");
 	}
 	if (options.progress !== undefined) {
-		assertProgressCommandSucceeded("prepare SSH runtime", result, "Failed to prepare devcontainer SSH runtime");
+		assertProgressCommandSucceeded("prepare SSH runtime", result, "Failed to prepare devcontainer SSH runtime", { logPath: options.logger?.logPath });
 	}
 }
 async function refreshContainerCodingAgentClis(context, proxyMode = false, agents = [], options = {}) {
@@ -3300,7 +3609,7 @@ async function ensureContainerCodingAgentCli(context, agent, options = {}) {
 		throw new Error(`Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`);
 	}
 	if (options.progress !== undefined) {
-		assertProgressCommandSucceeded(`prepare ${codingAgentBinary(agent)}`, result, `Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`);
+		assertProgressCommandSucceeded(`prepare ${codingAgentBinary(agent)}`, result, `Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`, { logPath: options.logger?.logPath });
 	}
 }
 async function runSshdProxy(containerId, options = {}) {
@@ -4613,10 +4922,12 @@ function commandWritesWorkspaceMetadata(command) {
 		"ssh-proxy",
 		"tunnel",
 		"refresh-gh-token",
-		"refresh-gh-token-running",
 		"coding-agent"
 	].includes(command);
 }
+function commandRequiresContainerRuntime(command) {
+	return command === "setup" || command === "start" || command === "ssh-proxy" || command === "tunnel" || command === "refresh-gh-token" || command === "coding-agent";
+}
 function parseCliArgs(argv) {
 	const args = [...argv];
 	const workspaces = [];
@@ -5312,7 +5623,7 @@ function createCliProgress(parsed, target = "stdout", options = {}) {
 		target
 	});
 }
-function startProgressSteps() {
+function devcontainerStartProgressSteps() {
 	return [
 		{
 			id: "ssh-identity",
@@ -5328,13 +5639,19 @@ function startProgressSteps() {
 		}
 	];
 }
+function startProgressSteps() {
+	return [{
+		id: "container-runtime",
+		label: "Checking container runtime"
+	}, ...devcontainerStartProgressSteps()];
+}
 function sshTargetProgressLabel(target) {
 	const label = SSH_INSTALL_TARGETS.find((candidate) => candidate.value === target)?.label ?? target;
 	return `Installing ${label} SSH target`;
 }
 function setupProgressSteps(targets) {
 	return [
-		...startProgressSteps(),
+		...devcontainerStartProgressSteps(),
 		{
 			id: "ssh-alias",
 			label: "Installing SSH alias"
@@ -5347,6 +5664,9 @@ function setupProgressSteps(targets) {
 }
 function setupPreflightProgressSteps() {
 	return [{
+		id: "container-runtime",
+		label: "Checking container runtime"
+	}, {
 		id: "setup-preflight",
 		label: "Checking host readiness"
 	}];
@@ -5355,13 +5675,55 @@ function setupPreflightFailureMessage(checks) {
 	const failures = checks.filter((check) => check.level === "fail").map((check) => `- ${check.name}: ${check.message}`);
 	return `Setup preflight failed:\n${failures.join("\n")}`;
 }
+function runtimeTransitionMessage(probe) {
+	if (probe.state === "waiting" && probe.failure.reason === "docker-daemon-unavailable") {
+		return "Waiting for Docker daemon";
+	}
+	if (probe.state === "waiting" && probe.failure.reason === "buildx-builder-unavailable") {
+		return "Waiting for Docker Buildx builder";
+	}
+	return undefined;
+}
+async function runContainerRuntimePreflight(context, progress, options, logger) {
+	const wait = options.waitForContainerRuntime ?? waitForContainerRuntime;
+	progress.startStep("container-runtime");
+	const result = await wait({
+		runCommand: async (command, args, timeoutMs) => runBuffered(command, args, {
+			env: options.env,
+			logger,
+			mirrorStdout: false,
+			mirrorStderr: false,
+			timeoutMs
+		}),
+		onTransition: (probe) => {
+			const message = runtimeTransitionMessage(probe);
+			if (message !== undefined) progress.status(message);
+		}
+	});
+	if (result.state === "failed") {
+		progress.failStep("container-runtime");
+		throw new Error(formatContainerRuntimeFailure(result, { logPath: logger === undefined ? undefined : context.workspaceLogPath }));
+	}
+	for (const warning of result.warnings) progress.warn(warning);
+	if (progress.mode === "verbose") progress.status("Container runtime ready");
+	progress.completeStep("container-runtime");
+}
+async function prepareContainerLifecycle(context, alias, progress, options, logger) {
+	await runContainerRuntimePreflight(context, progress, options, logger);
+	const writeMetadata = options.writeWorkspaceMetadata ?? writeWorkspaceMetadata;
+	writeMetadata(context, alias);
+}
 async function runSetupPreflight(context, alias, parsed, options) {
 	const progress = createCliProgress(parsed, "stdout", { env: options.env });
 	const doctor = options.runDoctorChecks ?? runDoctorChecks;
 	await withProgressSection(progress, "Boxdown setup", [`Workspace: ${context.workspaceFolder}`, `SSH alias: ${alias}`], async () => {
 		progress.setSteps(setupPreflightProgressSteps());
+		await runContainerRuntimePreflight(context, progress, options);
 		progress.startStep("setup-preflight");
-		const checks = await doctor(context, { includeOptional: false });
+		const checks = await doctor(context, {
+			includeOptional: false,
+			containerRuntimeReady: true
+		});
 		for (const check of checks.filter((item) => item.level === "warn")) {
 			progress.warn(`${check.name}: ${check.message}`);
 		}
@@ -5473,9 +5835,6 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 		const context = createWorkspaceContext({ workspace: parsed.workspace });
 		const alias = parsed.alias ?? defaultSshAlias(context.workspaceBasename);
 		const aliasSource = parsed.alias === undefined ? "default" : "provided";
-		if (parsed.command !== "ssh-install" && parsed.command !== "setup" && parsed.command !== "tunnel" && commandWritesWorkspaceMetadata(parsed.command)) {
-			writeWorkspaceMetadata(context, alias);
-		}
 		if (parsed.command === "ssh-install") {
 			const resolvedTargets = await resolveSshInstallTargets(parsed, options);
 			if (resolvedTargets.cancelled) {
@@ -5572,6 +5931,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 				const progress = createCliProgress(parsed, "stderr", { env: options.env });
 				const containerId = await withProgressSection(progress, "Boxdown SSH proxy", [`Workspace: ${context.workspaceFolder}`, `SSH alias: ${alias}`], async () => {
 					progress.setSteps(sshProxyProgressSteps());
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					progress.startStep("ssh-alias");
 					try {
 						await installSshConfig(context, alias, { quiet: true });
@@ -5610,11 +5970,11 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 			if (tunnelPorts.length === 0) {
 				throw new Error("tunnel requires at least one --port value");
 			}
-			writeWorkspaceMetadata(context, alias);
 			return runLoggedLifecycle(context, "tunnel", argv, async (logger) => {
 				const progress = createCliProgress(parsed, "stdout", { env: options.env });
 				await withProgressSection(progress, "Boxdown tunnel", [`Workspace: ${context.workspaceFolder}`, `SSH alias: ${alias}`], async () => {
 					progress.setSteps(tunnelProgressSteps());
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					progress.startStep("ssh-alias");
 					try {
 						await installSshConfig(context, alias, { quiet: true });
@@ -5638,7 +5998,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 		}
 		if (parsed.command === "refresh-gh-token-running") {
 			return runLoggedLifecycle(context, "refresh-gh-token-running", argv, async (logger) => {
-				const containerId = await findRunningContainerId(context, { logger });
+				const containerId = await (options.findRunningContainerId ?? findRunningContainerId)(context, { logger });
 				if (containerId === undefined) {
 					throw new Error(`No running devcontainer found for: ${context.workspaceFolder}`);
 				}
@@ -5660,6 +6020,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 				const progress = createCliProgress(parsed, "stdout", { env: options.env });
 				await withProgressSection(progress, "Boxdown GitHub auth refresh", [`Workspace: ${context.workspaceFolder}`], async () => {
 					progress.setSteps(ghAuthProgressSteps(true));
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					await startDevcontainer(context, {
 						progress,
 						logger
@@ -5681,6 +6042,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 				const progress = createCliProgress(parsed, "stdout", { env: options.env });
 				await withProgressSection(progress, `Boxdown ${agent}`, [`Workspace: ${context.workspaceFolder}`], async () => {
 					progress.setSteps(codingAgentProgressSteps(agent));
+					await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 					await startDevcontainer(context, {
 						recreate: parsed.recreate,
 						progress,
@@ -5698,6 +6060,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 			const progress = createCliProgress(parsed, "stdout", { env: options.env });
 			const containerId = await withProgressSection(progress, "Boxdown start", [`Workspace: ${context.workspaceFolder}`], async () => {
 				progress.setSteps(startProgressSteps());
+				await (options.prepareContainerLifecycle ?? prepareContainerLifecycle)(context, alias, progress, options, logger);
 				return await startDevcontainer(context, {
 					recreate: parsed.recreate,
 					progress,
@@ -5714,5 +6077,5 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
 }
 
 //#endregion
-export { parseTunnelPortList as a, parseTunnelPort as i, commandWritesWorkspaceMetadata as n, runCli as o, parseCliArgs as r, setupWorkspace as s, USAGE as t };
-//# sourceMappingURL=main-J4_2Up3o.mjs.map
+export { parseTunnelPort as a, runCli as c, parseCliArgs as i, runContainerRuntimePreflight as l, commandRequiresContainerRuntime as n, parseTunnelPortList as o, commandWritesWorkspaceMetadata as r, prepareContainerLifecycle as s, USAGE as t, setupWorkspace as u };
+//# sourceMappingURL=main-O__JaiXe.mjs.map