@ycs77/devbox 0.1.0 → 0.2.0

package/dist/cli.mjs

@@ -0,0 +1,1835 @@
+import { cac } from "cac";
+import * as p from "@clack/prompts";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, relative, sep } from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { parse as parse$1, parseDocument, stringify } from "yaml";
+import { once } from "node:events";
+//#region src/catalog/index.ts
+const NODE_RELEASE_KEYS = [
+	"5BE8A3F6C8A5C01D106C0AD820B1A390B168D356",
+	"DD792F5973C6DE52C432CBDAC77ABFA00DDBF2B7",
+	"CC68F5A3106FF448322E48ED27F5E38D5B0A215F",
+	"8FCCA13FEF1D0C2E91008E09770F7A9A5AE15600",
+	"890C08DB8579162FEE0DF9DB8BEAB4DFCF555EF4",
+	"C82FA3AE1CBEDC6BE46B9360C43CEC45C17AB93C",
+	"108F52B48DB57BB0CC439B2997B01419BD92F80A",
+	"A363A499291CBBC940DD62E41F10027AF002F8B0",
+	"655F3B5C1FB3FA8D1A0CA6BDE4A7D232B936D2FD"
+];
+const PACKAGED_NODE_RECIPES = {
+	"24": {
+		releaseLine: "24",
+		version: "24.19.0",
+		runtimeRoot: "/opt/devbox/runtimes/node/24",
+		trustedReleaseKeys: NODE_RELEASE_KEYS
+	},
+	"22": {
+		releaseLine: "22",
+		version: "22.23.2",
+		runtimeRoot: "/opt/devbox/runtimes/node/22",
+		trustedReleaseKeys: NODE_RELEASE_KEYS
+	}
+};
+const PACKAGED_NODE_RELEASE_LINES = ["24", "22"];
+const PACKAGED_AGENTS = {
+	"claude-code": {
+		home: {
+			volumeName: "devbox-claude",
+			target: "/home/devbox/.claude"
+		},
+		installation: {
+			url: "https://claude.ai/install.sh",
+			shell: "bash"
+		},
+		supportsNotifications: true,
+		supportsSkillInstallation: true
+	},
+	codex: {
+		home: {
+			volumeName: "devbox-codex",
+			target: "/home/devbox/.codex"
+		},
+		installation: {
+			url: "https://chatgpt.com/codex/install.sh",
+			shell: "sh"
+		},
+		supportsNotifications: true,
+		supportsSkillInstallation: true
+	},
+	agy: {
+		home: {
+			volumeName: "devbox-agy",
+			target: "/home/devbox/.gemini"
+		},
+		installation: {
+			url: "https://antigravity.google/cli/install.sh",
+			shell: "bash"
+		},
+		supportsNotifications: false,
+		supportsSkillInstallation: false
+	},
+	omp: {
+		home: {
+			volumeName: "devbox-omp",
+			target: "/home/devbox/.omp"
+		},
+		installation: {
+			url: "https://omp.sh/install",
+			shell: "sh"
+		},
+		supportsNotifications: true,
+		supportsSkillInstallation: false
+	}
+};
+const PACKAGED_RUNTIME_CATALOG = {
+	runtimes: { node: PACKAGED_NODE_RELEASE_LINES },
+	agents: Object.keys(PACKAGED_AGENTS)
+};
+//#endregion
+//#region src/result.ts
+function success(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function failure(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+//#endregion
+//#region src/host.ts
+const execFile$1 = promisify(execFile);
+var HostCommandError = class extends Error {
+	exitCode;
+	constructor(file, args, exitCode) {
+		super(`${file} ${args.join(" ")} exited with status ${exitCode}.`);
+		this.exitCode = exitCode;
+		this.name = "HostCommandError";
+	}
+};
+const supportedHostAction = "Start Docker Desktop and ensure Docker Compose is available.";
+function currentHostEnvironment() {
+	return {
+		run: async (file, args) => {
+			await execFile$1(file, args);
+		},
+		runDirect: async (file, args) => new Promise((resolve, reject) => {
+			const command = spawn(file, args, { stdio: "inherit" });
+			command.once("error", reject);
+			command.once("close", (code) => {
+				if (code === 0) {
+					resolve();
+					return;
+				}
+				reject(new HostCommandError(file, args, code ?? 1));
+			});
+		})
+	};
+}
+async function validateSupportedHost(environment = currentHostEnvironment()) {
+	for (const [file, args, description] of [[
+		"docker",
+		["--version"],
+		"Docker"
+	], [
+		"docker",
+		["compose", "version"],
+		"Docker Compose"
+	]]) try {
+		await environment.run(file, args);
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "missing-host-prerequisite",
+			observed: `${description} is unavailable.`,
+			nextAction: supportedHostAction
+		});
+	}
+	return success(void 0);
+}
+//#endregion
+//#region src/agent/volumes.ts
+async function ensureSharedAgentVolumes(configuredAgents, environment = currentHostEnvironment()) {
+	for (const configuredAgent of configuredAgents) {
+		const volumeName = PACKAGED_AGENTS[configuredAgent]?.home.volumeName;
+		if (volumeName !== void 0) await environment.run("docker", [
+			"volume",
+			"create",
+			"--driver",
+			"local",
+			volumeName
+		]);
+	}
+}
+//#endregion
+//#region src/configuration/index.ts
+function normalizeCatalog(catalog = PACKAGED_RUNTIME_CATALOG) {
+	if (!isRecord(catalog.runtimes) || !Array.isArray(catalog.agents)) return invalid$1("invalid-runtime-catalog", "The packaged Runtime catalog is invalid.");
+	const runtimes = {};
+	for (const [family, entries] of Object.entries(catalog.runtimes)) {
+		if (!isCatalogName(family) || !Array.isArray(entries) || entries.length === 0) return invalid$1("invalid-runtime-catalog", "The packaged Runtime catalog is invalid.");
+		const normalizedEntries = [];
+		for (const entry of entries) {
+			if (typeof entry !== "string" || entry.length === 0 || normalizedEntries.includes(entry)) return invalid$1("invalid-runtime-catalog", "The packaged Runtime catalog is invalid.");
+			normalizedEntries.push(entry);
+		}
+		runtimes[family] = normalizedEntries;
+	}
+	const agents = [];
+	for (const agent of catalog.agents) {
+		if (typeof agent !== "string" || !isCatalogName(agent) || agents.includes(agent)) return invalid$1("invalid-runtime-catalog", "The packaged Agent catalog is invalid.");
+		agents.push(agent);
+	}
+	return success({
+		runtimes,
+		agents
+	});
+}
+function defaultGlobalConfiguration(catalog = PACKAGED_RUNTIME_CATALOG) {
+	return {
+		version: 1,
+		node: catalog.runtimes.node?.[0] === void 0 ? [] : [catalog.runtimes.node[0]],
+		agent: [],
+		agent_notifications: true
+	};
+}
+function defaultLocalConfiguration(globalConfiguration) {
+	return {
+		version: 1,
+		node: globalConfiguration.node[0] ?? null
+	};
+}
+function parseGlobalConfiguration(source, catalog = PACKAGED_RUNTIME_CATALOG) {
+	const parsed = parseYaml(source);
+	if (!parsed.ok) return invalid$1("invalid-global-configuration", parsed.observed);
+	const document = parsed.value;
+	if (!isRecord(document) || !hasExactKeys$1(document, [
+		"version",
+		"node",
+		"agent",
+		"agent_notifications"
+	])) return invalid$1("invalid-global-configuration", "Global configuration contains unknown or missing fields.");
+	if (document.version !== 1) return invalid$1("invalid-global-configuration", "Global configuration must use version: 1.");
+	if (!Array.isArray(document.node) || !Array.isArray(document.agent)) return invalid$1("invalid-global-configuration", "Global configuration has invalid values.");
+	if (typeof document.agent_notifications !== "boolean") return invalid$1("invalid-global-configuration", "Global configuration agent_notifications must be true or false.");
+	const node = [];
+	for (const rawEntry of document.node) {
+		const entry = runtimeLine(rawEntry);
+		if (entry === void 0 || !catalog.runtimes.node?.includes(entry)) return invalid$1("invalid-global-configuration", `Node Runtime is not in the packaged catalog: ${String(rawEntry)}.`);
+		if (node.includes(entry)) return invalid$1("invalid-global-configuration", `Node Runtime is duplicated: ${entry}.`);
+		node.push(entry);
+	}
+	const agent = [];
+	for (const rawAgent of document.agent) {
+		if (typeof rawAgent !== "string" || !catalog.agents.includes(rawAgent)) return invalid$1("invalid-global-configuration", `Agent is not in the packaged catalog: ${String(rawAgent)}.`);
+		if (agent.includes(rawAgent)) return invalid$1("invalid-global-configuration", `Agent is duplicated: ${rawAgent}.`);
+		agent.push(rawAgent);
+	}
+	return success({
+		version: 1,
+		node,
+		agent,
+		agent_notifications: document.agent_notifications
+	});
+}
+function parseLocalConfiguration(source, globalConfiguration, catalog = PACKAGED_RUNTIME_CATALOG) {
+	const parsed = parseYaml(source);
+	if (!parsed.ok) return invalid$1("invalid-local-configuration", parsed.observed);
+	const document = parsed.value;
+	if (!isRecord(document) || !hasExactKeys$1(document, ["version", "node"])) return invalid$1("invalid-local-configuration", "Local configuration contains unknown or missing fields.");
+	if (document.version !== 1) return invalid$1("invalid-local-configuration", "Local configuration must use version: 1.");
+	const node = runtimeLineOrNull(document.node);
+	if (node === void 0) return invalid$1("invalid-local-configuration", `Node Runtime is invalid: ${String(document.node)}.`);
+	if (node !== null && !catalog.runtimes.node?.includes(node)) return invalid$1("invalid-local-configuration", `Node Runtime is not in the packaged catalog: ${String(document.node)}.`);
+	if (node !== null && !globalConfiguration.node.includes(node)) return invalid$1("unconfigured-runtime-selection", `Local configuration selects a Node Runtime that is not configured globally: ${node}.`);
+	return success({
+		version: 1,
+		node
+	});
+}
+function serializeGlobalConfiguration(configuration) {
+	return stringify({
+		version: 1,
+		node: [...configuration.node],
+		agent: [...configuration.agent],
+		agent_notifications: configuration.agent_notifications
+	});
+}
+function serializeLocalConfiguration(configuration) {
+	return stringify({
+		version: 1,
+		node: configuration.node
+	});
+}
+function configurationsEqual(left, right) {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+function parseYaml(source) {
+	try {
+		const document = parseDocument(source, {
+			strict: true,
+			uniqueKeys: true,
+			version: "1.2"
+		});
+		if (document.errors.length > 0) return {
+			ok: false,
+			observed: document.errors[0]?.message ?? "YAML is invalid."
+		};
+		return {
+			ok: true,
+			value: document.toJS()
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			observed: error instanceof Error ? error.message : "YAML is invalid."
+		};
+	}
+}
+function runtimeLine(value) {
+	if (typeof value === "string" && value.length > 0) return value;
+	if (typeof value === "number" && Number.isInteger(value)) return String(value);
+}
+function runtimeLineOrNull(value) {
+	if (value === null) return null;
+	return runtimeLine(value);
+}
+function isRecord(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys$1(value, keys) {
+	const expected = new Set(keys);
+	const actual = Object.keys(value);
+	return actual.length === expected.size && actual.every((key) => expected.has(key));
+}
+function isCatalogName(value) {
+	return /^[a-z][a-z0-9-]*$/.test(value);
+}
+function invalid$1(code, observed) {
+	return failure({
+		kind: "validation",
+		code,
+		observed,
+		nextAction: "Edit the supported version-1 YAML configuration and try again."
+	});
+}
+//#endregion
+//#region src/state-lock/index.ts
+var StateLockInterruptedError = class extends Error {
+	constructor() {
+		super("State lock acquisition interrupted.");
+		this.name = "StateLockInterruptedError";
+	}
+};
+var StateLockBusyError = class extends Error {
+	scope;
+	projectRoot;
+	constructor(scope, projectRoot) {
+		super("A required Devbox command marker is already present.");
+		this.name = "StateLockBusyError";
+		this.scope = scope;
+		this.projectRoot = projectRoot;
+	}
+};
+async function withStateLocks(input, operation) {
+	const lockRoot = join(input.devboxHome, "locks");
+	const targets = input.global ? [{
+		path: join(lockRoot, "global"),
+		scope: "global"
+	}] : [];
+	targets.push(...projectLockTargets(lockRoot, input.projectRoots));
+	let devboxHomeExisted = true;
+	try {
+		await lstat(input.devboxHome);
+	} catch (error) {
+		if (isMissingFileError$1(error)) devboxHomeExisted = false;
+		else throw error;
+	}
+	const acquired = [];
+	const acquireTargets = async (targetsToAcquire) => {
+		for (const target of targetsToAcquire) {
+			if (input.signal?.aborted) throw new StateLockInterruptedError();
+			await acquireLock(target);
+			acquired.push(target.path);
+		}
+	};
+	try {
+		if (input.signal?.aborted) throw new StateLockInterruptedError();
+		await mkdir(lockRoot, {
+			recursive: true,
+			mode: 448
+		});
+		await acquireTargets(targets);
+		if (input.signal?.aborted) throw new StateLockInterruptedError();
+		return await operation({ acquireProjectScopes: async (projectRoots) => {
+			await acquireTargets(projectLockTargets(lockRoot, projectRoots));
+		} });
+	} catch (error) {
+		if (error instanceof StateLockBusyError) return failure({
+			kind: "operational",
+			code: "command-lock-busy",
+			observed: error.scope === "global" ? "The Global command marker is already occupied." : `The Project command marker is already occupied for ${error.projectRoot}.`,
+			nextAction: `Wait for the other Devbox command to finish and try again. If no Devbox process is running, remove the residual marker under ${input.devboxHome}/locks/ and try again.`
+		});
+		throw error;
+	} finally {
+		for (const lockPath of acquired.reverse()) await rm(lockPath, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		await rmdir(lockRoot).catch(() => void 0);
+		if (!devboxHomeExisted) await rmdir(input.devboxHome).catch(() => void 0);
+	}
+}
+function projectLockTargets(lockRoot, projectRoots) {
+	const targets = [];
+	const sortedRoots = [...new Set(projectRoots)].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+	for (const projectRoot of sortedRoots) {
+		const hash = createHash("sha256").update(projectRoot).digest("hex");
+		targets.push({
+			path: join(lockRoot, `project-${hash}`),
+			scope: "project",
+			projectRoot
+		});
+	}
+	return targets;
+}
+async function acquireLock(target) {
+	try {
+		await mkdir(target.path, { mode: 448 });
+	} catch (error) {
+		if (isFileExistsError(error)) throw new StateLockBusyError(target.scope, target.projectRoot);
+		throw error;
+	}
+}
+function isFileExistsError(error) {
+	return typeof error === "object" && error !== null && error.code === "EEXIST";
+}
+function isMissingFileError$1(error) {
+	return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+//#endregion
+//#region src/workspace/image.ts
+const WORKSPACE_IMAGE = "devbox-workspace:latest";
+//#endregion
+//#region src/project/compose-fragments.ts
+const NOTIFICATION_FRAGMENT = {
+	environment: { PULSE_SERVER: "unix:/tmp/pulse-socket" },
+	volume: {
+		source: "/mnt/wslg/runtime-dir/pulse/native",
+		target: "/tmp/pulse-socket",
+		readOnly: true
+	}
+};
+function selectComposeFragments({ selectedNode, configuredAgents, agentNotifications }) {
+	const agents = [];
+	let hasNotificationAgent = false;
+	for (const agent of configuredAgents) {
+		const packagedAgent = PACKAGED_AGENTS[agent];
+		if (packagedAgent !== void 0) {
+			agents.push({
+				agent,
+				volume: {
+					name: packagedAgent.home.volumeName,
+					target: packagedAgent.home.target,
+					external: true
+				}
+			});
+			hasNotificationAgent ||= packagedAgent.supportsNotifications;
+		}
+	}
+	return {
+		node: selectedNode === null ? void 0 : { environment: { NODE_VERSION: selectedNode } },
+		agents,
+		notification: agentNotifications && hasNotificationAgent ? NOTIFICATION_FRAGMENT : void 0
+	};
+}
+//#endregion
+//#region src/project/compose.ts
+function renderProjectCompose(input) {
+	const fragments = selectComposeFragments(input);
+	const environment = {
+		...fragments.node?.environment,
+		...fragments.notification?.environment
+	};
+	const volumes = [
+		{
+			type: "bind",
+			source: input.projectRoot,
+			target: `/workspace/${input.sandboxName}`
+		},
+		...fragments.agents.map((fragment) => ({
+			type: "volume",
+			source: fragment.volume.name,
+			target: fragment.volume.target
+		})),
+		...input.claudeHostConfiguration === void 0 ? [] : [{
+			type: "bind",
+			source: input.claudeHostConfiguration,
+			target: "/home/devbox/.claude.json"
+		}],
+		...fragments.notification === void 0 ? [] : [{
+			type: "bind",
+			source: fragments.notification.volume.source,
+			target: fragments.notification.volume.target,
+			read_only: fragments.notification.volume.readOnly
+		}]
+	];
+	const definition = {
+		name: input.sandboxName,
+		"x-devbox": {
+			version: 1,
+			project_root: input.projectRoot,
+			compose_name: input.sandboxName,
+			sandbox_service: "devbox"
+		},
+		services: { devbox: {
+			image: WORKSPACE_IMAGE,
+			container_name: input.sandboxName,
+			working_dir: `/workspace/${input.sandboxName}`,
+			...Object.keys(environment).length === 0 ? {} : { environment },
+			volumes
+		} },
+		...fragments.agents.length === 0 ? {} : { volumes: Object.fromEntries(fragments.agents.map((fragment) => [fragment.volume.name, {
+			name: fragment.volume.name,
+			external: fragment.volume.external
+		}])) }
+	};
+	const source = stringify(definition);
+	return validatesProjectCompose(source, input) ? success(source) : failure({
+		kind: "operational",
+		code: "invalid-project-compose",
+		observed: `Devbox generated an invalid Compose definition for Project ${input.projectRoot}.`,
+		nextAction: "Run the command again. If the problem continues, report it as a Devbox bug."
+	});
+}
+function validatesProjectCompose(source, input) {
+	try {
+		const definition = parse$1(source);
+		if (definition.name !== input.sandboxName) return false;
+		const metadata = definition["x-devbox"];
+		if (metadata.version !== 1 || metadata.project_root !== input.projectRoot || metadata.compose_name !== input.sandboxName || metadata.sandbox_service !== "devbox") return false;
+		const service = definition.services.devbox;
+		if (service.image !== "devbox-workspace:latest" || service.container_name !== input.sandboxName || service.working_dir !== `/workspace/${input.sandboxName}` || "build" in service) return false;
+		return input.selectedNode === null && service.environment?.NODE_VERSION === void 0 || input.selectedNode !== null && service.environment?.NODE_VERSION === input.selectedNode;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/project/registry.ts
+function parseProjectRegistry(source) {
+	let document;
+	try {
+		const parsed = parseDocument(source, {
+			strict: true,
+			uniqueKeys: true,
+			version: "1.2"
+		});
+		if (parsed.errors.length > 0) return invalid(parsed.errors[0]?.message ?? "Project registry YAML is invalid.");
+		document = parsed.toJS();
+	} catch (error) {
+		return invalid(error instanceof Error ? error.message : "Project registry YAML is invalid.");
+	}
+	if (!isPlainObject(document) || !hasExactKeys(document, ["version", "projects"]) || document.version !== 1 || !isPlainObject(document.projects)) return invalid("Project registry must contain only version: 1 and projects.");
+	const projects = {};
+	const assignedIdentities = /* @__PURE__ */ new Set();
+	const assignedNames = /* @__PURE__ */ new Set();
+	for (const [root, registration] of Object.entries(document.projects)) {
+		if (!isAbsolute(root)) return invalid(`Project root must be an exact absolute path: ${root}.`);
+		if (!isPlainObject(registration) || !hasExactKeys(registration, ["identity", "name"]) || typeof registration.identity !== "string" || !isSafeStateDirectoryName(registration.identity) || assignedIdentities.has(registration.identity)) return invalid("Sandbox identity assignment is invalid.");
+		if (typeof registration.name !== "string" || !isSafeSandboxName(registration.name) || assignedNames.has(registration.name)) return invalid("Sandbox name assignment is invalid.");
+		assignedIdentities.add(registration.identity);
+		assignedNames.add(registration.name);
+		projects[root] = {
+			identity: registration.identity,
+			name: registration.name
+		};
+	}
+	return success({
+		version: 1,
+		projects
+	});
+}
+function serializeProjectRegistry(registry) {
+	const projects = Object.fromEntries(Object.entries(registry.projects).sort(([left], [right]) => {
+		if (left < right) return -1;
+		if (left > right) return 1;
+		return 0;
+	}));
+	return stringify({
+		version: 1,
+		projects
+	});
+}
+function isSafeStateDirectoryName(name) {
+	return /^(?:[A-Za-z0-9_%~-]+)(?:-[2-9][0-9]*)?$/.test(name) && name !== "." && name !== "..";
+}
+function isSafeSandboxName(name) {
+	return /^[a-z0-9][a-z0-9_-]+$/.test(name);
+}
+function hasExactKeys(value, keys) {
+	const expected = new Set(keys);
+	const actual = Object.keys(value);
+	return actual.length === expected.size && actual.every((key) => expected.has(key));
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function invalid(observed) {
+	return failure({
+		kind: "validation",
+		code: "invalid-project-registry",
+		observed,
+		nextAction: "Repair ~/.devbox/projects.yaml using the supported version-1 registry schema."
+	});
+}
+//#endregion
+//#region src/project/index.ts
+function devboxPaths(devboxHome = join(homedir(), ".devbox")) {
+	return {
+		home: devboxHome,
+		globalConfiguration: join(devboxHome, "config.yaml"),
+		projectRegistry: join(devboxHome, "projects.yaml"),
+		projects: join(devboxHome, "projects"),
+		buildContext: join(devboxHome, "build"),
+		claudeHostConfiguration: join(devboxHome, "agents", "claude", ".claude.json")
+	};
+}
+function sandboxIdentity(projectRoot) {
+	const root = parse(projectRoot).root;
+	const pathWithinRoot = relative(root, projectRoot);
+	if (!isAbsolute(projectRoot) || pathWithinRoot === ".." || pathWithinRoot.startsWith(`..${sep}`)) throw new TypeError("Project root must be an absolute path.");
+	return pathWithinRoot === "" ? "root" : pathWithinRoot.split(sep).map(escapePathSegment).join("-");
+}
+function projectStateDirectory(sandboxIdentity, devboxHome) {
+	if (!isSafeStateDirectoryName(sandboxIdentity)) throw new TypeError("Sandbox identity must be a safe state directory name.");
+	return join(devboxHome, "projects", sandboxIdentity);
+}
+function sandboxName(projectRoot) {
+	const normalized = basename(projectRoot).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^[^a-z0-9]+/, "").replace(/-+$/, "");
+	return normalized.length < 2 ? `project-${normalized || "root"}` : normalized;
+}
+function escapePathSegment(segment) {
+	const bytes = new TextEncoder().encode(segment);
+	let escaped = "";
+	for (const byte of bytes) if (byte >= 65 && byte <= 90 || byte >= 97 && byte <= 122 || byte >= 48 && byte <= 57 || byte === 45 || byte === 95) escaped += String.fromCharCode(byte);
+	else escaped += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+	return escaped;
+}
+async function initializeProject(input = {}) {
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: true,
+		projectRoots: [input.root ?? process.cwd()],
+		signal: input.signal
+	}, () => initializeProjectUnlocked(input));
+}
+async function initializeProjectUnlocked(input = {}) {
+	const projectRoot = input.root ?? process.cwd();
+	const rootCheck = await validateProjectRoot(projectRoot);
+	if (!rootCheck.ok) return rootCheck;
+	if (input.signal?.aborted) throw new InterruptedError();
+	const hostCheck = await (input.validateHost ?? validateSupportedHost)();
+	if (!hostCheck.ok) return hostCheck;
+	if (input.signal?.aborted) throw new InterruptedError();
+	const catalogCheck = normalizeCatalog(input.catalog);
+	if (!catalogCheck.ok) return catalogCheck;
+	const catalog = catalogCheck.value;
+	const paths = devboxPaths(input.devboxHome);
+	const registryState = await readOptionalFile(paths.projectRegistry);
+	if (!registryState.ok) return registryState;
+	const registryCheck = registryState.value.exists ? parseProjectRegistry(registryState.value.content) : success({
+		version: 1,
+		projects: {}
+	});
+	if (!registryCheck.ok) return registryCheck;
+	const registry = registryCheck.value;
+	const registration = registry.projects[projectRoot];
+	let identity;
+	let name;
+	if (registration !== void 0) {
+		identity = registration.identity;
+		name = registration.name;
+	} else {
+		const allocatedIdentity = await allocateSandboxIdentity(projectRoot, paths, registry);
+		if (!allocatedIdentity.ok) return allocatedIdentity;
+		const allocatedName = allocateSandboxName(projectRoot, registry);
+		if (!allocatedName.ok) return allocatedName;
+		identity = allocatedIdentity.value;
+		name = allocatedName.value;
+	}
+	const stateDirectory = projectStateDirectory(identity, paths.home);
+	const registered = registration !== void 0;
+	const globalState = await readOptionalFile(paths.globalConfiguration);
+	if (!globalState.ok) return globalState;
+	if (registered && !globalState.value.exists) return missingConfiguration("global", paths.globalConfiguration);
+	let globalConfiguration;
+	let globalChanged = false;
+	if (globalState.value.exists) {
+		const parsedGlobal = parseGlobalConfiguration(globalState.value.content, catalog);
+		if (!parsedGlobal.ok) return parsedGlobal;
+		globalConfiguration = parsedGlobal.value;
+	} else if (input.initialGlobalConfiguration !== void 0) {
+		const initialGlobal = validateGlobalObject(input.initialGlobalConfiguration, catalog);
+		if (!initialGlobal.ok) return initialGlobal;
+		globalConfiguration = initialGlobal.value;
+		globalChanged = true;
+	} else {
+		globalConfiguration = defaultGlobalConfiguration(catalog);
+		if (input.prompt?.editGlobal) {
+			const checkedGlobal = validateGlobalObject(await input.prompt.editGlobal(globalConfiguration, catalog), catalog);
+			if (!checkedGlobal.ok) return checkedGlobal;
+			globalConfiguration = checkedGlobal.value;
+		}
+		globalChanged = true;
+	}
+	const localPath = join(stateDirectory, "config.yaml");
+	const localState = registered ? await readOptionalFile(localPath) : success({
+		exists: false,
+		content: ""
+	});
+	if (!localState.ok) return localState;
+	if (registered && !localState.value.exists) return missingConfiguration("local", localPath);
+	let localConfiguration;
+	let localChanged = false;
+	if (localState.value.exists) {
+		const parsedLocal = parseLocalConfiguration(localState.value.content, globalConfiguration, catalog);
+		if (!parsedLocal.ok) return parsedLocal;
+		localConfiguration = parsedLocal.value;
+	} else if (input.initialLocalConfiguration !== void 0) {
+		const initialLocal = validateLocalObject(input.initialLocalConfiguration, globalConfiguration, catalog);
+		if (!initialLocal.ok) return initialLocal;
+		localConfiguration = initialLocal.value;
+		localChanged = true;
+	} else {
+		localConfiguration = defaultLocalConfiguration(globalConfiguration);
+		if (input.prompt?.editLocal) {
+			const checkedLocal = validateLocalObject(await input.prompt.editLocal(localConfiguration, catalog, globalConfiguration), globalConfiguration, catalog);
+			if (!checkedLocal.ok) return checkedLocal;
+			localConfiguration = checkedLocal.value;
+		}
+		localChanged = true;
+	}
+	const composeWrite = await composeStateWrite({
+		projectRoot,
+		sandboxName: name,
+		stateDirectory,
+		devboxHome: paths.home,
+		globalConfiguration,
+		localConfiguration
+	});
+	if (!composeWrite.ok) return composeWrite;
+	if (registered) {
+		if (!composeWrite.value.previous.exists || composeWrite.value.content !== composeWrite.value.previous.content) {
+			const written = await writeStateTransaction([composeWrite.value]);
+			if (!written.ok) return written;
+		}
+		return success({
+			root: projectRoot,
+			stateDirectory,
+			sandboxName: name,
+			created: false,
+			confirmed: true
+		});
+	}
+	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))(`Register Project ${projectRoot} and write its configuration?`)) return success({
+		root: projectRoot,
+		stateDirectory,
+		sandboxName: name,
+		created: false,
+		confirmed: false
+	});
+	const nextRegistry = {
+		version: 1,
+		projects: {
+			...registry.projects,
+			[projectRoot]: {
+				identity,
+				name
+			}
+		}
+	};
+	const written = await writeStateTransaction([
+		...globalChanged ? [{
+			path: paths.globalConfiguration,
+			content: serializeGlobalConfiguration(globalConfiguration),
+			previous: globalState.value
+		}] : [],
+		...localChanged ? [{
+			path: localPath,
+			content: serializeLocalConfiguration(localConfiguration),
+			previous: localState.value
+		}] : [],
+		{
+			path: paths.projectRegistry,
+			content: serializeProjectRegistry(nextRegistry),
+			previous: registryState.value
+		},
+		composeWrite.value
+	]);
+	if (!written.ok) return written;
+	return success({
+		root: projectRoot,
+		stateDirectory,
+		sandboxName: name,
+		created: true,
+		confirmed: true
+	});
+}
+async function configureLocalProject(input = {}) {
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: true,
+		projectRoots: [input.root ?? process.cwd()],
+		signal: input.signal
+	}, () => configureLocalProjectUnlocked(input));
+}
+async function configureLocalProjectUnlocked(input = {}) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	const catalogCheck = normalizeCatalog(input.catalog);
+	if (!catalogCheck.ok) return catalogCheck;
+	const catalog = catalogCheck.value;
+	const projectRoot = input.root ?? process.cwd();
+	const paths = devboxPaths(input.devboxHome);
+	const registryCheck = await readRegistry(paths.projectRegistry);
+	if (!registryCheck.ok) return registryCheck;
+	const registration = registryCheck.value.projects[projectRoot];
+	if (registration === void 0) return notRegistered(projectRoot);
+	const globalState = await readOptionalFile(paths.globalConfiguration);
+	if (!globalState.ok) return globalState;
+	if (!globalState.value.exists) return missingConfiguration("global", paths.globalConfiguration);
+	const globalCheck = parseGlobalConfiguration(globalState.value.content, catalog);
+	if (!globalCheck.ok) return globalCheck;
+	const stateDirectory = projectStateDirectory(registration.identity, paths.home);
+	const localPath = join(stateDirectory, "config.yaml");
+	const localState = await readOptionalFile(localPath);
+	if (!localState.ok) return localState;
+	if (!localState.value.exists) return missingConfiguration("local", localPath);
+	const localCheck = parseLocalConfiguration(localState.value.content, globalCheck.value, catalog);
+	if (!localCheck.ok) return localCheck;
+	let nextConfiguration = input.nextConfiguration ?? localCheck.value;
+	if (input.nextConfiguration === void 0 && input.prompt?.editLocal) nextConfiguration = await input.prompt.editLocal(localCheck.value, catalog, globalCheck.value);
+	const nextCheck = validateLocalObject(nextConfiguration, globalCheck.value, catalog);
+	if (!nextCheck.ok) return nextCheck;
+	if (configurationsEqual(localCheck.value, nextCheck.value)) return success({
+		scope: "local",
+		root: projectRoot,
+		changed: false
+	});
+	const confirm = input.confirm ?? input.prompt?.confirm ?? (async () => true);
+	const changeSummary = `Current: ${serializeLocalConfiguration(localCheck.value).trim()}\nNext: ${serializeLocalConfiguration(nextCheck.value).trim()}`;
+	if (!await confirm(`Save Local configuration for ${projectRoot}?`, {
+		title: "Local configuration changes",
+		content: changeSummary
+	})) return success({
+		scope: "local",
+		root: projectRoot,
+		changed: false
+	});
+	if (input.signal?.aborted) throw new InterruptedError();
+	const composeWrite = await composeStateWrite({
+		projectRoot,
+		sandboxName: registration.name,
+		stateDirectory,
+		devboxHome: paths.home,
+		globalConfiguration: globalCheck.value,
+		localConfiguration: nextCheck.value
+	});
+	if (!composeWrite.ok) return composeWrite;
+	const written = await writeStateTransaction([{
+		path: localPath,
+		content: serializeLocalConfiguration(nextCheck.value),
+		previous: localState.value
+	}, composeWrite.value]);
+	if (!written.ok) return written;
+	return success({
+		scope: "local",
+		root: projectRoot,
+		changed: true
+	});
+}
+async function configureGlobal(input = {}) {
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: true,
+		projectRoots: [],
+		signal: input.signal
+	}, (context) => configureGlobalUnlocked(input, context));
+}
+async function configureGlobalUnlocked(input = {}, locks) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	const catalogCheck = normalizeCatalog(input.catalog);
+	if (!catalogCheck.ok) return catalogCheck;
+	const catalog = catalogCheck.value;
+	const paths = devboxPaths(input.devboxHome);
+	const globalState = await readOptionalFile(paths.globalConfiguration);
+	if (!globalState.ok) return globalState;
+	let currentConfiguration;
+	if (globalState.value.exists) {
+		const currentCheck = parseGlobalConfiguration(globalState.value.content, catalog);
+		if (!currentCheck.ok) return currentCheck;
+		currentConfiguration = currentCheck.value;
+	} else currentConfiguration = defaultGlobalConfiguration(catalog);
+	const registryState = await readOptionalFile(paths.projectRegistry);
+	if (!registryState.ok) return registryState;
+	const registryCheck = registryState.value.exists ? parseProjectRegistry(registryState.value.content) : success({
+		version: 1,
+		projects: {}
+	});
+	if (!registryCheck.ok) return registryCheck;
+	await locks.acquireProjectScopes(Object.keys(registryCheck.value.projects));
+	let nextConfiguration = input.nextConfiguration ?? currentConfiguration;
+	if (input.nextConfiguration === void 0 && input.prompt?.editGlobal) nextConfiguration = await input.prompt.editGlobal(currentConfiguration, catalog);
+	const nextCheck = validateGlobalObject(nextConfiguration, catalog);
+	if (!nextCheck.ok) return nextCheck;
+	const localConfigurations = /* @__PURE__ */ new Map();
+	const localConfigurationSources = /* @__PURE__ */ new Map();
+	for (const [root, registration] of Object.entries(registryCheck.value.projects)) {
+		const localPath = join(paths.projects, registration.identity, "config.yaml");
+		const localState = await readOptionalFile(localPath);
+		if (!localState.ok) return localState;
+		if (!localState.value.exists) return missingConfiguration("local", localPath);
+		const localCheck = parseLocalConfiguration(localState.value.content, currentConfiguration, catalog);
+		if (!localCheck.ok) return localCheck;
+		localConfigurations.set(root, localCheck.value);
+		localConfigurationSources.set(root, localState.value.content);
+	}
+	const removedNode = new Set(currentConfiguration.node.filter((entry) => !nextCheck.value.node.includes(entry)));
+	const replacementConfigurations = /* @__PURE__ */ new Map();
+	for (const [root, localConfiguration] of localConfigurations) {
+		if (localConfiguration.node === null || !removedNode.has(localConfiguration.node)) continue;
+		let replacement = input.nextLocalConfigurations?.[root];
+		if (replacement === void 0 && input.prompt?.editLocal) replacement = await input.prompt.editLocal(localConfiguration, catalog, nextCheck.value);
+		if (replacement === void 0) return failure({
+			kind: "validation",
+			code: "node-replacement-required",
+			observed: `Global Node Runtime ${localConfiguration.node} is selected by Project ${root}.`,
+			nextAction: `Select a replacement Node Runtime or none for Project ${root}.`
+		});
+		const replacementCheck = validateLocalObject(replacement, nextCheck.value, catalog);
+		if (!replacementCheck.ok) return replacementCheck;
+		replacementConfigurations.set(root, replacementCheck.value);
+	}
+	if (!(!globalState.value.exists || !configurationsEqual(currentConfiguration, nextCheck.value)) && replacementConfigurations.size === 0) return success({
+		scope: "global",
+		changed: false
+	});
+	const confirm = input.confirm ?? input.prompt?.confirm ?? (async () => true);
+	const localChangeSummary = [...replacementConfigurations].map(([root, configuration]) => `Project ${root}:\nCurrent: ${serializeLocalConfiguration(localConfigurations.get(root)).trim()}\nNext: ${serializeLocalConfiguration(configuration).trim()}`).join("\n\n");
+	if (!await confirm("Save Global configuration?", {
+		title: "Global configuration changes",
+		content: [
+			`Current Global:\n${serializeGlobalConfiguration(currentConfiguration).trim()}`,
+			`Next Global:\n${serializeGlobalConfiguration(nextCheck.value).trim()}`,
+			localChangeSummary
+		].filter(Boolean).join("\n\n")
+	})) return success({
+		scope: "global",
+		changed: false
+	});
+	if (input.signal?.aborted) throw new InterruptedError();
+	const composeWrites = [];
+	for (const [root, registration] of Object.entries(registryCheck.value.projects)) {
+		const composeWrite = await composeStateWrite({
+			projectRoot: root,
+			sandboxName: registration.name,
+			stateDirectory: projectStateDirectory(registration.identity, paths.home),
+			devboxHome: paths.home,
+			globalConfiguration: nextCheck.value,
+			localConfiguration: replacementConfigurations.get(root) ?? localConfigurations.get(root)
+		});
+		if (!composeWrite.ok) return composeWrite;
+		if (!composeWrite.value.previous.exists || composeWrite.value.content !== composeWrite.value.previous.content) composeWrites.push(composeWrite.value);
+	}
+	const written = await writeStateTransaction([
+		{
+			path: paths.globalConfiguration,
+			content: serializeGlobalConfiguration(nextCheck.value),
+			previous: globalState.value
+		},
+		...[...replacementConfigurations].map(([root, configuration]) => ({
+			path: join(paths.projects, registryCheck.value.projects[root].identity, "config.yaml"),
+			content: serializeLocalConfiguration(configuration),
+			previous: {
+				exists: true,
+				content: localConfigurationSources.get(root)
+			}
+		})),
+		...composeWrites
+	]);
+	if (!written.ok) return written;
+	return success({
+		scope: "global",
+		changed: true
+	});
+}
+async function removeProject(input = {}) {
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: true,
+		projectRoots: [input.root ?? process.cwd()],
+		signal: input.signal
+	}, () => removeProjectUnlocked(input));
+}
+async function removeProjectUnlocked(input = {}) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	const projectRoot = input.root ?? process.cwd();
+	const rootCheck = await validateProjectRoot(projectRoot);
+	if (!rootCheck.ok) return rootCheck;
+	const paths = devboxPaths(input.devboxHome);
+	const registryCheck = await readRegistry(paths.projectRegistry);
+	if (!registryCheck.ok) return registryCheck;
+	const registration = registryCheck.value.projects[projectRoot];
+	if (registration === void 0) return notRegistered(projectRoot);
+	if (!input.yes) {
+		if (!await (input.confirm ?? (async () => false))(`Remove Project ${projectRoot} and its Devbox state?`)) return success({
+			root: projectRoot,
+			removed: false
+		});
+	}
+	if (input.signal?.aborted) throw new InterruptedError();
+	const stateDirectory = projectStateDirectory(registration.identity, paths.home);
+	try {
+		await rm(stateDirectory, {
+			recursive: true,
+			force: true
+		});
+	} catch {
+		return failure({
+			kind: "operational",
+			code: "project-state-removal-failed",
+			observed: `Devbox could not remove Project state: ${stateDirectory}.`,
+			nextAction: "Check write access to ~/.devbox and run devbox rm --yes again."
+		});
+	}
+	const projects = { ...registryCheck.value.projects };
+	delete projects[projectRoot];
+	const written = await writeAtomically(paths.projectRegistry, serializeProjectRegistry({
+		version: 1,
+		projects
+	}));
+	if (!written.ok) return written;
+	return success({
+		root: projectRoot,
+		removed: true
+	});
+}
+async function cleanupMissingProjects(input = {}) {
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: true,
+		projectRoots: [],
+		signal: input.signal
+	}, async (locks) => {
+		const discovery = await discoverMissingProjects(input);
+		if (!discovery.ok) return discovery;
+		await locks.acquireProjectScopes(discovery.value.missingRoots);
+		return cleanupMissingProjectsUnlocked(input, discovery.value);
+	});
+}
+async function discoverMissingProjects(input) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	const paths = devboxPaths(input.devboxHome);
+	const registryState = await readOptionalFile(paths.projectRegistry);
+	if (!registryState.ok) return registryState;
+	if (!registryState.value.exists) return success({
+		paths,
+		registry: {
+			version: 1,
+			projects: {}
+		},
+		missingRoots: []
+	});
+	const registryCheck = parseProjectRegistry(registryState.value.content);
+	if (!registryCheck.ok) return registryCheck;
+	const missingRoots = [];
+	for (const root of Object.keys(registryCheck.value.projects)) {
+		if (input.signal?.aborted) throw new InterruptedError();
+		const exists = await projectRootExists(root);
+		if (exists === void 0) return failure({
+			kind: "operational",
+			code: "project-root-observation-failed",
+			observed: `Devbox could not inspect Project root: ${root}.`,
+			nextAction: "Check access to the registered Project root and try cleanup again."
+		});
+		if (!exists) missingRoots.push(root);
+	}
+	return success({
+		paths,
+		registry: registryCheck.value,
+		missingRoots
+	});
+}
+async function cleanupMissingProjectsUnlocked(input, discovery) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	if (discovery.missingRoots.length === 0) return success({
+		roots: [],
+		removed: false
+	});
+	if (!input.yes) {
+		if (!await (input.confirm ?? (async () => false))(`Remove Missing-root Project registrations?\n${discovery.missingRoots.map((root) => `- ${root}`).join("\n")}`)) return success({
+			roots: [],
+			removed: false
+		});
+	}
+	const removedRoots = [];
+	const projects = { ...discovery.registry.projects };
+	for (const root of discovery.missingRoots) {
+		const rootExists = await projectRootExists(root);
+		if (rootExists === void 0) return failure({
+			kind: "operational",
+			code: "project-root-observation-failed",
+			observed: `Devbox could not recheck Project root: ${root}.`,
+			nextAction: "Check access to the registered Project root and try cleanup again."
+		});
+		if (rootExists) continue;
+		const registration = projects[root];
+		if (registration === void 0) continue;
+		try {
+			await rm(projectStateDirectory(registration.identity, discovery.paths.home), {
+				recursive: true,
+				force: true
+			});
+		} catch {
+			return failure({
+				kind: "operational",
+				code: "missing-project-state-removal-failed",
+				observed: `Devbox could not remove Missing-root Project state for ${root}.`,
+				nextAction: "Check write access to ~/.devbox and try cleanup again."
+			});
+		}
+		delete projects[root];
+		removedRoots.push(root);
+	}
+	if (removedRoots.length === 0) return success({
+		roots: [],
+		removed: false
+	});
+	const written = await writeAtomically(discovery.paths.projectRegistry, serializeProjectRegistry({
+		version: 1,
+		projects
+	}));
+	if (!written.ok) return written;
+	return success({
+		roots: removedRoots,
+		removed: true
+	});
+}
+async function runSandboxLifecycle(command, input = {}) {
+	const projectRoot = input.root ?? process.cwd();
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: false,
+		projectRoots: [projectRoot],
+		signal: input.signal
+	}, () => runSandboxLifecycleUnlocked(command, input, projectRoot));
+}
+async function runSandboxLifecycleUnlocked(command, input, projectRoot) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	const rootCheck = await validateProjectRoot(projectRoot);
+	if (!rootCheck.ok) return rootCheck;
+	const paths = devboxPaths(input.devboxHome);
+	const registryCheck = await readRegistry(paths.projectRegistry);
+	if (!registryCheck.ok) return registryCheck;
+	const registration = registryCheck.value.projects[projectRoot];
+	if (registration === void 0) return notRegistered(projectRoot);
+	const environment = input.environment ?? currentHostEnvironment();
+	if (command === "up") {
+		const globalState = await readOptionalFile(paths.globalConfiguration);
+		if (!globalState.ok) return globalState;
+		if (!globalState.value.exists) return missingConfiguration("global", paths.globalConfiguration);
+		const globalCheck = parseGlobalConfiguration(globalState.value.content);
+		if (!globalCheck.ok) return globalCheck;
+		await ensureSharedAgentVolumes(globalCheck.value.agent, environment);
+	}
+	const composePath = join(projectStateDirectory(registration.identity, paths.home), "compose.yaml");
+	const operation = command === "up" ? ["up", "-d"] : command === "sh" ? [
+		"exec",
+		"--user",
+		"devbox",
+		"devbox",
+		"bash"
+	] : [command];
+	await (environment.runDirect ?? environment.run)("docker", [
+		"compose",
+		"--file",
+		composePath,
+		...operation
+	]);
+	return success(void 0);
+}
+async function validateProjectRoot(projectRoot) {
+	if (!isAbsolute(projectRoot)) return failure({
+		kind: "validation",
+		code: "invalid-project-root",
+		observed: `The current Project directory is not absolute: ${projectRoot}.`,
+		nextAction: "Run the command from an existing directory."
+	});
+	try {
+		if (!(await lstat(projectRoot)).isDirectory()) return failure({
+			kind: "validation",
+			code: "invalid-project-root",
+			observed: `The current Project path is not a directory: ${projectRoot}.`,
+			nextAction: "Run the command from an existing directory."
+		});
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "missing-project-root",
+			observed: `The current Project directory does not exist: ${projectRoot}.`,
+			nextAction: "Change to an existing directory and run the command again."
+		});
+	}
+	return success(void 0);
+}
+async function readRegistry(path) {
+	const state = await readOptionalFile(path);
+	if (!state.ok) return state;
+	if (!state.value.exists) return failure({
+		kind: "validation",
+		code: "project-not-registered",
+		observed: "No Project registry exists for this Devbox installation.",
+		nextAction: "Run devbox init from the exact Project directory first."
+	});
+	return parseProjectRegistry(state.value.content);
+}
+async function allocateSandboxIdentity(projectRoot, paths, registry) {
+	const identity = sandboxIdentity(projectRoot);
+	for (let suffix = 1; suffix < 1e6; suffix += 1) {
+		const candidate = suffix === 1 ? identity : `${identity}-${suffix}`;
+		if (!isSafeStateDirectoryName(candidate) || Object.values(registry.projects).some((entry) => entry.identity === candidate)) continue;
+		try {
+			await lstat(projectStateDirectory(candidate, paths.home));
+		} catch (error) {
+			if (isMissingFileError(error)) return success(candidate);
+			return failure({
+				kind: "operational",
+				code: "state-directory-observation-failed",
+				observed: `Devbox could not inspect Project state directory: ${projectStateDirectory(candidate, paths.home)}.`,
+				nextAction: "Check write access to ~/.devbox and run devbox init again."
+			});
+		}
+	}
+	return failure({
+		kind: "operational",
+		code: "state-directory-allocation-failed",
+		observed: `Devbox could not allocate a unique Project state directory for ${projectRoot}.`,
+		nextAction: "Remove stale Devbox state only through its supported command and try again."
+	});
+}
+function allocateSandboxName(projectRoot, registry) {
+	const name = sandboxName(projectRoot);
+	for (let suffix = 1; suffix < 1e6; suffix += 1) {
+		const candidate = suffix === 1 ? name : `${name}-${suffix}`;
+		if (isSafeSandboxName(candidate) && !Object.values(registry.projects).some((entry) => entry.name === candidate)) return success(candidate);
+	}
+	return failure({
+		kind: "operational",
+		code: "sandbox-name-allocation-failed",
+		observed: `Devbox could not allocate a unique Sandbox name for ${projectRoot}.`,
+		nextAction: "Remove stale Devbox state only through its supported command and try again."
+	});
+}
+async function projectRootExists(projectRoot) {
+	try {
+		return (await lstat(projectRoot)).isDirectory();
+	} catch (error) {
+		if (isMissingFileError(error)) return false;
+		return;
+	}
+}
+async function readOptionalFile(path) {
+	try {
+		return success({
+			exists: true,
+			content: await readFile(path, "utf8")
+		});
+	} catch (error) {
+		if (isMissingFileError(error)) return success({
+			exists: false,
+			content: ""
+		});
+		return failure({
+			kind: "operational",
+			code: "state-read-failed",
+			observed: `Devbox could not read state file: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and try again."
+		});
+	}
+}
+async function writeAtomically(path, content) {
+	const staged = await stageStateWrite(path, content, "tmp");
+	if (!staged.ok) return staged;
+	try {
+		await rename(staged.value, path);
+		return success(void 0);
+	} catch {
+		await rm(staged.value, { force: true }).catch(() => void 0);
+		return failure({
+			kind: "operational",
+			code: "state-write-failed",
+			observed: `Devbox could not atomically write state file: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+async function stageStateWrite(path, content, suffix) {
+	const directory = dirname(path);
+	const temporaryPath = join(directory, `.${basename(path)}-${process.pid}-${randomUUID()}.${suffix}`);
+	try {
+		await mkdir(directory, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(temporaryPath, content, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+		return success(temporaryPath);
+	} catch {
+		await rm(temporaryPath, { force: true }).catch(() => void 0);
+		return failure({
+			kind: "operational",
+			code: "state-write-failed",
+			observed: `Devbox could not atomically write state file: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+async function composeStateWrite(input) {
+	const claudeHostConfiguration = await ensureClaudeHostConfiguration(input.devboxHome, input.globalConfiguration);
+	if (!claudeHostConfiguration.ok) return claudeHostConfiguration;
+	const rendered = renderProjectCompose({
+		projectRoot: input.projectRoot,
+		sandboxName: input.sandboxName,
+		selectedNode: input.localConfiguration.node,
+		configuredAgents: input.globalConfiguration.agent,
+		agentNotifications: input.globalConfiguration.agent_notifications,
+		claudeHostConfiguration: claudeHostConfiguration.value
+	});
+	if (!rendered.ok) return rendered;
+	const path = join(input.stateDirectory, "compose.yaml");
+	const previous = await readOptionalFile(path);
+	if (!previous.ok) return previous;
+	return success({
+		path,
+		content: rendered.value,
+		previous: previous.value
+	});
+}
+async function ensureClaudeHostConfiguration(devboxHome, globalConfiguration) {
+	if (!globalConfiguration.agent.includes("claude-code")) return success(void 0);
+	const path = devboxPaths(devboxHome).claudeHostConfiguration;
+	try {
+		if ((await lstat(path)).isFile()) return success(path);
+		return failure({
+			kind: "operational",
+			code: "claude-host-configuration-invalid",
+			observed: `Claude host configuration is not a regular file: ${path}.`,
+			nextAction: "Replace it with a regular file, then run the command again."
+		});
+	} catch (error) {
+		if (!isMissingFileError(error)) return failure({
+			kind: "operational",
+			code: "claude-host-configuration-unreadable",
+			observed: `Devbox could not inspect Claude host configuration: ${path}.`,
+			nextAction: "Check access to ~/.devbox and run the command again."
+		});
+	}
+	try {
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(path, "{}\n", {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+		return success(path);
+	} catch (error) {
+		if (error.code === "EEXIST") return ensureClaudeHostConfiguration(devboxHome, globalConfiguration);
+		return failure({
+			kind: "operational",
+			code: "claude-host-configuration-write-failed",
+			observed: `Devbox could not create Claude host configuration: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+async function writeStateTransaction(writes) {
+	const staged = [];
+	for (const write of writes) {
+		const stagedWrite = await stageStateWrite(write.path, write.content, "transaction.tmp");
+		if (!stagedWrite.ok) {
+			await Promise.all(staged.map((stage) => rm(stage.path, { force: true }).catch(() => void 0)));
+			return stagedWrite;
+		}
+		staged.push({
+			write,
+			path: stagedWrite.value
+		});
+	}
+	const published = [];
+	try {
+		for (const stage of staged) {
+			await rename(stage.path, stage.write.path);
+			published.push(stage.write);
+		}
+		return success(void 0);
+	} catch {
+		let restored = true;
+		for (const write of published.reverse()) if (write.previous.exists) {
+			const restoredWrite = await writeAtomically(write.path, write.previous.content);
+			restored &&= restoredWrite.ok;
+		} else try {
+			await rm(write.path, { force: true });
+		} catch {
+			restored = false;
+		}
+		await Promise.all(staged.map((stage) => rm(stage.path, { force: true }).catch(() => void 0)));
+		return failure({
+			kind: "operational",
+			code: "state-write-failed",
+			observed: restored ? "Devbox could not publish Project state; the previous state was restored." : "Devbox could not publish Project state or restore the previous state.",
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+function validateGlobalObject(configuration, catalog) {
+	try {
+		return parseGlobalConfiguration(serializeGlobalConfiguration(configuration), catalog);
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "invalid-global-configuration",
+			observed: "Global configuration has invalid values.",
+			nextAction: "Edit the supported version-1 Global YAML configuration and try again."
+		});
+	}
+}
+function validateLocalObject(configuration, globalConfiguration, catalog) {
+	try {
+		return parseLocalConfiguration(serializeLocalConfiguration(configuration), globalConfiguration, catalog);
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "invalid-local-configuration",
+			observed: "Local configuration has invalid values.",
+			nextAction: "Edit the supported version-1 Local YAML configuration and try again."
+		});
+	}
+}
+function notRegistered(projectRoot) {
+	return failure({
+		kind: "validation",
+		code: "project-not-registered",
+		observed: `The exact Project directory is not registered: ${projectRoot}.`,
+		nextAction: "Run devbox init from this exact existing directory first."
+	});
+}
+function missingConfiguration(scope, path) {
+	return failure({
+		kind: "validation",
+		code: `missing-${scope}-configuration`,
+		observed: `Devbox could not find the ${scope} configuration: ${path}.`,
+		nextAction: `Restore the supported version-1 ${scope} YAML configuration and try again.`
+	});
+}
+function isMissingFileError(error) {
+	return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+var InterruptedError = class extends Error {
+	constructor() {
+		super("Devbox command interrupted.");
+	}
+};
+//#endregion
+//#region src/configuration/prompter.ts
+function createConfigurationPrompter({ signal, input, output }) {
+	const common = {
+		signal,
+		input,
+		output
+	};
+	return {
+		confirm: async (message, details) => {
+			if (details !== void 0) p.note(details.content, details.title, common);
+			return promptValue(p.confirm({
+				message,
+				...common
+			}));
+		},
+		selectConfigurationScope: async () => promptValue(p.select({
+			message: "Configuration scope",
+			options: [{
+				value: "local",
+				label: "Current Project"
+			}, {
+				value: "global",
+				label: "Global"
+			}],
+			...common
+		})),
+		editGlobal: async (configuration, catalog) => {
+			return {
+				version: 1,
+				node: await promptValue(p.multiselect({
+					message: "Configured Node release lines",
+					options: (catalog.runtimes.node ?? []).map((value) => ({ value })),
+					initialValues: [...configuration.node],
+					required: false,
+					...common
+				})),
+				agent: await promptValue(p.multiselect({
+					message: "Configured Agents",
+					options: catalog.agents.map((value) => ({ value })),
+					initialValues: [...configuration.agent],
+					required: false,
+					...common
+				})),
+				agent_notifications: await promptValue(p.confirm({
+					message: "Enable Agent notifications",
+					initialValue: configuration.agent_notifications,
+					...common
+				}))
+			};
+		},
+		editLocal: async (configuration, catalog, globalConfiguration) => {
+			return {
+				version: 1,
+				node: await promptValue(p.select({
+					message: "Selected Node release line",
+					options: [{
+						value: null,
+						label: "None"
+					}, ...(globalConfiguration.node ?? []).map((value) => ({
+						value,
+						label: value
+					}))],
+					initialValue: configuration.node,
+					...common
+				}))
+			};
+		}
+	};
+}
+async function promptValue(prompt) {
+	const value = await prompt;
+	if (p.isCancel(value)) throw new InterruptedError();
+	return value;
+}
+//#endregion
+//#region src/workspace/build.ts
+async function buildWorkspace(input = {}) {
+	return withStateLocks({
+		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
+		global: true,
+		projectRoots: [],
+		signal: input.signal
+	}, () => buildWorkspaceUnlocked(input));
+}
+async function buildWorkspaceUnlocked(input) {
+	if (input.signal?.aborted) throw new InterruptedError();
+	const catalogCheck = normalizeCatalog();
+	if (!catalogCheck.ok) return catalogCheck;
+	const paths = devboxPaths(input.devboxHome);
+	let globalSource;
+	try {
+		globalSource = await readFile(paths.globalConfiguration, "utf8");
+	} catch {
+		return failure({
+			kind: "operational",
+			code: "global-configuration-missing",
+			observed: "Global configuration is required before building the Workspace image.",
+			nextAction: "Run devbox config to commit Global configuration before devbox build."
+		});
+	}
+	const parsedGlobal = parseGlobalConfiguration(globalSource, catalogCheck.value);
+	if (!parsedGlobal.ok) return parsedGlobal;
+	const globalConfiguration = parsedGlobal.value;
+	const dockerfile = renderBuildDockerfile({
+		nodeRuntimes: globalConfiguration.node.map((releaseLine) => PACKAGED_NODE_RECIPES[releaseLine]),
+		buildNodeRuntime: buildNodeRuntimeRecipe(globalConfiguration),
+		agents: globalConfiguration.agent.map((name) => ({
+			name,
+			recipe: PACKAGED_AGENTS[name]
+		})),
+		skillAgents: globalConfiguration.agent.filter((agent) => PACKAGED_AGENTS[agent]?.supportsSkillInstallation === true)
+	});
+	await rm(paths.buildContext, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(paths.buildContext, { recursive: true });
+	await writeFile(join(paths.buildContext, "Dockerfile"), dockerfile);
+	await writeFile(join(paths.buildContext, ".dockerignore"), "# Machine-owned Workspace build context\n*\n!Dockerfile\n");
+	if (input.signal?.aborted) throw new InterruptedError();
+	const buildResult = await (input.executeDockerBuild ?? runDockerBuild)({
+		context: paths.buildContext,
+		image: WORKSPACE_IMAGE,
+		noCache: input.noCache === true
+	});
+	if (!buildResult.ok) return buildResult;
+	return success({ image: WORKSPACE_IMAGE });
+}
+function buildNodeRuntimeRecipe(globalConfiguration) {
+	let buildNodeRuntime;
+	for (const releaseLine of globalConfiguration.node) {
+		const recipe = PACKAGED_NODE_RECIPES[releaseLine];
+		if (buildNodeRuntime === void 0 || Number.parseFloat(releaseLine) > Number.parseFloat(buildNodeRuntime.releaseLine)) buildNodeRuntime = recipe;
+	}
+	return buildNodeRuntime;
+}
+function renderBuildDockerfile(input) {
+	const lines = [
+		"# Generated by devbox build. Machine-owned Workspace build context.",
+		"FROM ubuntu:24.04",
+		"",
+		"ENV DEBIAN_FRONTEND=noninteractive",
+		"ENV TZ=UTC",
+		"ENV LANG=C.UTF-8",
+		"",
+		"RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone",
+		"",
+		"# Install the Base profile packages and build tools",
+		"RUN set -eux \\",
+		"    && apt-get update && apt-get upgrade -y \\",
+		"    && apt-get install -y --no-install-recommends \\",
+		"      ca-certificates curl wget git supervisor openssh-client \\",
+		"      zip unzip jq less vim ripgrep fd-find procps lsof iproute2 \\",
+		"      dnsutils netcat-openbsd rsync tree tzdata bubblewrap \\",
+		"      build-essential python3 python-is-python3 pkg-config \\",
+		"      gnupg dirmngr xz-utils pulseaudio-utils sudo gosu \\",
+		"    && apt-get -y autoremove \\",
+		"    && apt-get clean \\",
+		"    && rm -rf /var/lib/apt/lists/*",
+		"",
+		"# Create the devbox user and group",
+		"RUN userdel -r ubuntu \\",
+		"    && groupadd -f -g 1000 devbox \\",
+		"    && useradd -m -s /bin/bash -N -g 1000 -u 1000 devbox \\",
+		"    && echo \"devbox ALL=(ALL) NOPASSWD:ALL\" > /etc/sudoers.d/devbox \\",
+		"    && chmod 0440 /etc/sudoers.d/devbox",
+		""
+	];
+	for (const recipe of input.nodeRuntimes) lines.push(...renderNodeRuntimeStage(recipe));
+	lines.push("WORKDIR /workspace", "USER devbox", "");
+	if (input.buildNodeRuntime !== void 0) lines.push("# Configure pnpm for the non-root Sandbox user", "RUN mkdir -p /home/devbox/.config/pnpm /home/devbox/.pnpm-store \\", "    && printf 'storeDir: /home/devbox/.pnpm-store\\n' > /home/devbox/.config/pnpm/config.yaml \\", "    && chown devbox:devbox /home/devbox/.config/pnpm/config.yaml", "");
+	for (const agent of input.agents) lines.push(`# Install ${agent.name}`, `RUN mkdir -p ${agent.recipe.home.target} \\`, `    && curl -fsSL ${agent.recipe.installation.url} | ${agent.recipe.installation.shell}`, "");
+	if (input.agents.length > 0) lines.push("# Set the PATH to include AI tools", "ENV PATH=\"/home/devbox/.local/bin:${PATH}\"", "");
+	if (input.buildNodeRuntime !== void 0 && input.skillAgents.length > 0) {
+		const skillAgentArguments = input.skillAgents.map((agent) => `-a ${agent}`).join(" ");
+		lines.push("# Install Agent Skills", "RUN set -eux \\", "    && mkdir -p /home/devbox/.agents/skills \\", `    && export PATH="${input.buildNodeRuntime.runtimeRoot}/bin:$PATH" \\`, `    && npx -y skills add ycs77/skills -g ${skillAgentArguments} -s '*' -y`, "");
+	}
+	lines.push("USER root");
+	return `${lines.join("\n")}\n`;
+}
+function renderNodeRuntimeStage(recipe) {
+	const keys = recipe.trustedReleaseKeys.map((key) => `      ${key}`).join(" \\\n");
+	return [
+		`# Install Node.js ${recipe.releaseLine}`,
+		"RUN ARCH= OPENSSL_ARCH= && dpkgArch=\"$(dpkg --print-architecture)\" \\",
+		"    && case \"${dpkgArch##*-}\" in \\",
+		"      amd64) ARCH='x64' OPENSSL_ARCH='linux-x86_64';; \\",
+		"      ppc64el) ARCH='ppc64le' OPENSSL_ARCH='linux-ppc64le';; \\",
+		"      s390x) ARCH='s390x' OPENSSL_ARCH='linux*-s390x';; \\",
+		"      arm64) ARCH='arm64' OPENSSL_ARCH='linux-aarch64';; \\",
+		"      *) echo \"unsupported architecture\"; exit 1 ;; \\",
+		"    esac \\",
+		"    && set -eux \\",
+		`    && NODE_RUNTIME_VERSION=${recipe.version} \\`,
+		`    && NODE_RUNTIME_ROOT=${recipe.runtimeRoot} \\`,
+		`    && NODE_ARCHIVE_URL="https://nodejs.org/dist/v\${NODE_RUNTIME_VERSION}/node-v\${NODE_RUNTIME_VERSION}-linux-\${ARCH}.tar.xz" \\`,
+		`    && NODE_CHECKSUMS_URL="https://nodejs.org/dist/v\${NODE_RUNTIME_VERSION}/SHASUMS256.txt.asc" \\`,
+		"    && mkdir -p \"$NODE_RUNTIME_ROOT\" /tmp/node-source \\",
+		"    && cd /tmp/node-source \\",
+		"    && export GNUPGHOME=\"$(mktemp -d)\" \\",
+		"    && for key in \\",
+		`${keys} \\`,
+		"    ; do \\",
+		"      { gpg --batch --no-options --keyserver hkps://keys.openpgp.org --recv-keys \"$key\" && gpg --batch --no-options --fingerprint \"$key\"; } || \\",
+		"      { gpg --batch --no-options --keyserver keyserver.ubuntu.com --recv-keys \"$key\" && gpg --batch --no-options --fingerprint \"$key\"; }; \\",
+		"    done \\",
+		"    && archive=\"node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\" \\",
+		"    && curl -fsSL --retry 3 -o \"$archive\" \"$NODE_ARCHIVE_URL\" \\",
+		"    && curl -fsSL --retry 3 -o SHASUMS256.txt.asc \"$NODE_CHECKSUMS_URL\" \\",
+		"    && gpg --batch --no-options --decrypt --output SHASUMS256.txt SHASUMS256.txt.asc \\",
+		"    && gpgconf --kill all \\",
+		"    && rm -rf \"$GNUPGHOME\" \\",
+		"    && awk -v archive=\"$archive\" \\",
+		"      '$2 == archive { print; found = 1; exit } END { if (!found) exit 1 }' \\",
+		"      SHASUMS256.txt > \"$archive.sha256\" \\",
+		"    && sha256sum --check \"$archive.sha256\" \\",
+		"    && tar --extract --xz --file \"$archive\" --directory \"$NODE_RUNTIME_ROOT\" \\",
+		"      --strip-components=1 --no-same-owner \\",
+		"    && rm \"$archive\" SHASUMS256.txt.asc SHASUMS256.txt \"$archive.sha256\" \\",
+		"    && find \"$NODE_RUNTIME_ROOT/include/node/openssl/archs\" -mindepth 1 -maxdepth 1 ! -name \"$OPENSSL_ARCH\" -exec rm -rf {} \\; \\",
+		"    && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \\",
+		"    && export PATH=\"$NODE_RUNTIME_ROOT/bin:$PATH\" \\",
+		"    && npm install -g npm \\",
+		"    && npm uninstall -g corepack \\",
+		"    && npm install -g yarn pnpm @antfu/ni \\",
+		"    && \"$NODE_RUNTIME_ROOT/bin/node\" --version \\",
+		"    && \"$NODE_RUNTIME_ROOT/bin/npm\" --version \\",
+		"    && rm -rf /tmp/node-source",
+		""
+	];
+}
+async function runDockerBuild(invocation, signal) {
+	const build = spawn("docker", [
+		"build",
+		...invocation.noCache ? ["--no-cache"] : [],
+		"--tag",
+		invocation.image,
+		"--file",
+		join(invocation.context, "Dockerfile"),
+		invocation.context
+	], { stdio: "inherit" });
+	const interrupt = () => build.kill("SIGINT");
+	signal?.addEventListener("abort", interrupt, { once: true });
+	let spawnFailed = false;
+	build.on("error", () => {
+		spawnFailed = true;
+	});
+	const [exitCode] = await once(build, "close");
+	signal?.removeEventListener("abort", interrupt);
+	if (signal?.aborted) throw new InterruptedError();
+	if (spawnFailed || exitCode !== 0) return failure({
+		kind: "operational",
+		code: "docker-build-failed",
+		observed: `Docker failed to build ${invocation.image}.`,
+		nextAction: "Inspect the Docker output above; the prior Workspace image is unchanged."
+	});
+	return success(void 0);
+}
+//#endregion
+//#region src/cli.ts
+function createCli(signal, interactive) {
+	const prompt = createConfigurationPrompter({ signal });
+	const cli = cac("devbox");
+	cli.command("").action(() => cli.outputHelp());
+	cli.command("init", "Register the current directory as a Devbox Project.").action(async () => {
+		if (!interactive) return interactiveFailure("devbox init requires an interactive terminal.", "Run devbox init from a TTY before it writes Project state.");
+		const result = await initializeProject({
+			signal,
+			prompt
+		});
+		if (!result.ok) return result;
+		return success({ message: result.value.created ? `Registered Project: ${result.value.root}` : result.value.confirmed === false ? "Project registration was not changed." : `Project is already registered: ${result.value.root}` });
+	});
+	cli.command("config", "Edit Global or Local configuration for the current Project.").action(async () => {
+		if (!interactive) return interactiveFailure("devbox config requires an interactive terminal.", "Run devbox config from a TTY, or edit the supported Global or Local YAML directly.");
+		if (await prompt.selectConfigurationScope() === "global") {
+			const result = await configureGlobal({
+				signal,
+				prompt
+			});
+			if (!result.ok) return result;
+			return success({ message: result.value.changed ? "Global configuration updated." : "Global configuration was not changed." });
+		}
+		const result = await configureLocalProject({
+			signal,
+			prompt
+		});
+		if (!result.ok) return result;
+		return success({ message: result.value.changed ? "Local configuration updated." : "Local configuration was not changed." });
+	});
+	cli.command("build", "Build the shared Workspace image from Global configuration.").option("--cache, --no-cache", "Use Docker layer cache.", { default: true }).action(async (options = {}) => {
+		const result = await buildWorkspace({
+			signal,
+			noCache: options.cache === false
+		});
+		if (!result.ok) return result;
+		return success({ message: `Built Workspace image: ${result.value.image}` });
+	});
+	cli.command("rm", "Remove the current registered Project and its state.").option("--yes", "Skip the confirmation prompt.").action(async (options = {}) => {
+		if (!interactive && !options.yes) return interactiveFailure("devbox rm requires a TTY or --yes.", "Run devbox rm from a TTY, or pass --yes to confirm removal.");
+		const result = await removeProject({
+			signal,
+			confirm: prompt.confirm,
+			yes: options.yes
+		});
+		if (!result.ok) return result;
+		return success({ message: result.value.removed ? `Removed Project: ${result.value.root}` : "Project removal was not changed." });
+	});
+	cli.command("cleanup", "Remove explicitly selected disposable Devbox state.").option("--missing-projects", "Remove Missing-root Project registrations.").option("--yes", "Skip the confirmation prompt.").action(async (options = {}) => {
+		if (!options.missingProjects) return failure({
+			kind: "usage",
+			code: "cleanup-mode-required",
+			observed: "cleanup requires --missing-projects.",
+			nextAction: "Run devbox cleanup --missing-projects."
+		});
+		if (!interactive && !options.yes) return interactiveFailure("devbox cleanup --missing-projects requires a TTY or --yes.", "Run devbox cleanup --missing-projects from a TTY, or pass --yes to confirm removal.");
+		const result = await cleanupMissingProjects({
+			signal,
+			confirm: prompt.confirm,
+			yes: options.yes
+		});
+		if (!result.ok) return result;
+		return success({ message: result.value.removed ? `Removed Missing-root Projects: ${result.value.roots.join(", ")}` : "No Missing-root Projects were removed." });
+	});
+	for (const [command, description] of [
+		["up", "Start the current Project Sandbox."],
+		["down", "Stop and remove the current Project Sandbox."],
+		["stop", "Stop the current Project Sandbox."],
+		["sh", "Open a shell in the current Project Sandbox."]
+	]) cli.command(command, description).action(async () => {
+		const result = await runSandboxLifecycle(command, { signal });
+		return result.ok ? success({}) : result;
+	});
+	cli.help();
+	return cli;
+}
+function present(result) {
+	if (!result.ok) {
+		process.stderr.write(`${result.error.observed}\n${result.error.nextAction}\n`);
+		return result.error.kind === "usage" ? 2 : 1;
+	}
+	if (result.value.message !== void 0) process.stdout.write(`${result.value.message}\n`);
+	return 0;
+}
+async function main() {
+	const abortController = new AbortController();
+	const interrupt = () => abortController.abort();
+	process.once("SIGINT", interrupt);
+	const cli = createCli(abortController.signal, process.stdin.isTTY === true && process.stdout.isTTY === true);
+	try {
+		cli.parse(process.argv, { run: false });
+		const result = await cli.runMatchedCommand();
+		return result === void 0 ? 0 : present(result);
+	} catch (error) {
+		if (error instanceof InterruptedError || abortController.signal.aborted) {
+			process.stderr.write("Devbox command interrupted.\n");
+			return 130;
+		}
+		if (error instanceof HostCommandError) return error.exitCode;
+		throw error;
+	} finally {
+		process.off("SIGINT", interrupt);
+	}
+}
+function interactiveFailure(observed, nextAction) {
+	return failure({
+		kind: "usage",
+		code: "interactive-terminal-required",
+		observed,
+		nextAction
+	});
+}
+process.exitCode = await main();
+//#endregion
+export {};