@ycs77/devbox 0.7.0 → 0.7.1

package/README.md

@@ -56,7 +56,7 @@ Published ports accept one mapping per line. The following are the supported por
 - `5173:5173` maps host port `5173` to container port `5173`.
 - `APP_PORT:5173:5173` maps the host port from the `APP_PORT` environment variable (default port: `5173`) to container port `5173`.
 
-Build the shared Workspace image once after setup or whenever you change global configuration:
+Build the shared Workspace image after setup, changes to global configuration, or a Devbox package upgrade:
 
 ```bash
 devbox build

package/dist/cli.mjs

@@ -2,16 +2,120 @@ import * as p from "@clack/prompts";
 import { intro, outro } from "@clack/prompts";
 import { cac } from "cac";
 import c from "picocolors";
-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 { parse as parse$1, parseDocument, stringify } from "yaml";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { parse as parse$1, parseDocument, stringify } from "yaml";
+import { createHash, randomUUID } from "node:crypto";
 import { once } from "node:events";
 //#region package.json
-var version = "0.7.0";
+var version = "0.7.1";
+//#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(composeSource, environment = currentHostEnvironment()) {
+	const volumeNames = /* @__PURE__ */ new Set();
+	try {
+		const definition = parse$1(composeSource);
+		if (!isMapping(definition)) throw new Error("Expected a Compose mapping.");
+		const volumes = definition.volumes;
+		if (volumes !== void 0) {
+			if (!isMapping(volumes)) throw new Error("Expected a volume mapping.");
+			for (const [key, volume] of Object.entries(volumes)) {
+				if (volume === null) continue;
+				if (!isMapping(volume)) throw new Error("Expected a volume definition.");
+				if (volume.external !== true) continue;
+				const name = volume.name ?? key;
+				if (typeof name !== "string" || name.length === 0) throw new Error("Expected an external volume name.");
+				volumeNames.add(name);
+			}
+		}
+	} catch {
+		return failure({
+			kind: "operational",
+			code: "invalid-project-compose",
+			observed: "Devbox could not read external volumes from the retained Sandbox definition.",
+			nextAction: "Run devbox config to publish the Sandbox definition, then retry devbox up."
+		});
+	}
+	for (const volumeName of volumeNames) await environment.run("docker", [
+		"volume",
+		"create",
+		"--driver",
+		"local",
+		volumeName
+	]);
+	return success(void 0);
+}
+function isMapping(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 //#endregion
 //#region src/catalog/index.ts
 const NODE_RELEASE_KEYS = [
@@ -100,85 +204,6 @@ const PACKAGED_RUNTIME_CATALOG = {
 	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.");
@@ -404,7 +429,7 @@ async function withStateLocks(input, operation) {
 	try {
 		await lstat(input.devboxHome);
 	} catch (error) {
-		if (isMissingFileError$1(error)) devboxHomeExisted = false;
+		if (isMissingFileError$2(error)) devboxHomeExisted = false;
 		else throw error;
 	}
 	const acquired = [];
@@ -467,7 +492,7 @@ async function acquireLock(target) {
 function isFileExistsError(error) {
 	return typeof error === "object" && error !== null && error.code === "EEXIST";
 }
-function isMissingFileError$1(error) {
+function isMissingFileError$2(error) {
 	return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
 //#endregion
@@ -649,13 +674,207 @@ function isPlainObject(value) {
 	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."
-	});
+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/publication.ts
+async function publishProjectState(input) {
+	const definitions = [];
+	for (const project of input.projects) {
+		const prepared = project.preparedDefinition === void 0 ? await prepareSandboxDefinition(input.devboxHome, input.globalConfiguration, project) : success(project.preparedDefinition);
+		if (!prepared.ok) return prepared;
+		definitions.push(prepared.value);
+	}
+	const claudeHostConfiguration = await ensureClaudeHostConfiguration(input.devboxHome, input.globalConfiguration);
+	if (!claudeHostConfiguration.ok) return claudeHostConfiguration;
+	const writes = [
+		...input.globalPrevious === void 0 ? [] : [{
+			path: join(input.devboxHome, "config.yaml"),
+			content: serializeGlobalConfiguration(input.globalConfiguration),
+			previous: input.globalPrevious
+		}],
+		...input.projects.flatMap((project) => project.localPrevious === void 0 ? [] : [{
+			path: join(project.stateDirectory, "config.yaml"),
+			content: serializeLocalConfiguration(project.localConfiguration),
+			previous: project.localPrevious
+		}]),
+		...input.registry === void 0 ? [] : [{
+			path: join(input.devboxHome, "projects.yaml"),
+			content: serializeProjectRegistry(input.registry.value),
+			previous: input.registry.previous
+		}],
+		...definitions
+	].filter((write) => !write.previous.exists || write.content !== write.previous.content);
+	const written = await writeStateTransaction(writes);
+	return written.ok ? success(writes.length > 0) : written;
+}
+async function prepareSandboxDefinition(devboxHome, globalConfiguration, project) {
+	const claudeHostConfiguration = globalConfiguration.agent.includes("claude-code") ? join(devboxHome, "agents", "claude", ".claude.json") : void 0;
+	const rendered = renderProjectCompose({
+		projectRoot: project.root,
+		sandboxName: project.name,
+		selectedNode: project.localConfiguration.node,
+		configuredAgents: globalConfiguration.agent,
+		agentNotifications: globalConfiguration.agent_notifications,
+		claudeHostConfiguration,
+		ports: project.localConfiguration.ports
+	});
+	if (!rendered.ok) return rendered;
+	const path = join(project.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 = join(devboxHome, "agents", "claude", ".claude.json");
+	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$1(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 readOptionalFile(path) {
+	try {
+		return success({
+			exists: true,
+			content: await readFile(path, "utf8")
+		});
+	} catch (error) {
+		if (isMissingFileError$1(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 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 isMissingFileError$1(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 //#endregion
 //#region src/project/index.ts
@@ -719,24 +938,22 @@ async function initializeProjectUnlocked(input = {}) {
 	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;
-	}
+	if (registration !== void 0) return success({
+		root: projectRoot,
+		stateDirectory: projectStateDirectory(registration.identity, paths.home),
+		sandboxName: registration.name,
+		created: false,
+		globalConfigurationCreated: false
+	});
+	const allocatedIdentity = await allocateSandboxIdentity(projectRoot, paths, registry);
+	if (!allocatedIdentity.ok) return allocatedIdentity;
+	const allocatedName = allocateSandboxName(projectRoot, registry);
+	if (!allocatedName.ok) return allocatedName;
+	const identity = allocatedIdentity.value;
+	const 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) {
@@ -757,24 +974,11 @@ async function initializeProjectUnlocked(input = {}) {
 		}
 		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) {
+	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) {
@@ -782,35 +986,20 @@ async function initializeProjectUnlocked(input = {}) {
 			if (!checkedLocal.ok) return checkedLocal;
 			localConfiguration = checkedLocal.value;
 		}
-		localChanged = true;
 	}
-	const composeWrite = await composeStateWrite({
-		projectRoot,
-		sandboxName: name,
+	const definition = await prepareSandboxDefinition(paths.home, globalConfiguration, {
+		root: projectRoot,
+		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 (!definition.ok) return definition;
 	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))("Save configuration?")) return success({
 		root: projectRoot,
 		stateDirectory,
 		sandboxName: name,
 		created: false,
+		globalConfigurationCreated: false,
 		confirmed: false
 	});
 	const nextRegistry = {
@@ -823,30 +1012,33 @@ async function initializeProjectUnlocked(input = {}) {
 			}
 		}
 	};
-	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),
+	const written = await publishProjectState({
+		devboxHome: paths.home,
+		globalConfiguration,
+		globalPrevious: globalChanged ? globalState.value : void 0,
+		registry: {
+			value: nextRegistry,
 			previous: registryState.value
 		},
-		composeWrite.value
-	]);
+		projects: [{
+			root: projectRoot,
+			name,
+			stateDirectory,
+			localConfiguration,
+			localPrevious: {
+				exists: false,
+				content: ""
+			},
+			preparedDefinition: definition.value
+		}]
+	});
 	if (!written.ok) return written;
 	return success({
 		root: projectRoot,
 		stateDirectory,
 		sandboxName: name,
 		created: true,
+		globalConfigurationCreated: globalChanged,
 		confirmed: true
 	});
 }
@@ -885,11 +1077,7 @@ async function configureLocalProjectUnlocked(input = {}) {
 	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 localChanged = !configurationsEqual(localCheck.value, nextCheck.value);
 	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))("Save Project configuration?", {
 		title: "Review configuration",
 		sections: [{
@@ -903,25 +1091,22 @@ async function configureLocalProjectUnlocked(input = {}) {
 		changed: false
 	});
 	if (input.signal?.aborted) throw new InterruptedError();
-	const composeWrite = await composeStateWrite({
-		projectRoot,
-		sandboxName: registration.name,
-		stateDirectory,
+	const written = await publishProjectState({
 		devboxHome: paths.home,
 		globalConfiguration: globalCheck.value,
-		localConfiguration: nextCheck.value
+		projects: [{
+			root: projectRoot,
+			name: registration.name,
+			stateDirectory,
+			localConfiguration: nextCheck.value,
+			localPrevious: localChanged ? localState.value : void 0
+		}]
 	});
-	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
+		changed: written.value
 	});
 }
 async function configureGlobal(input = {}) {
@@ -986,10 +1171,7 @@ async function configureGlobalUnlocked(input = {}, locks) {
 		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 globalChanged = !globalState.value.exists || !configurationsEqual(currentConfiguration, nextCheck.value);
 	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))("Save Global configuration?", {
 		title: "Review configuration",
 		sections: [{
@@ -1006,39 +1188,25 @@ async function configureGlobalUnlocked(input = {}, locks) {
 		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,
+	const written = await publishProjectState({
+		devboxHome: paths.home,
+		globalConfiguration: nextCheck.value,
+		globalPrevious: globalChanged ? globalState.value : void 0,
+		projects: Object.entries(registryCheck.value.projects).map(([root, registration]) => ({
+			root,
+			name: 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: {
+			localConfiguration: replacementConfigurations.get(root) ?? localConfigurations.get(root),
+			localPrevious: replacementConfigurations.has(root) ? {
 				exists: true,
 				content: localConfigurationSources.get(root)
-			}
-		})),
-		...composeWrites
-	]);
+			} : void 0
+		}))
+	});
 	if (!written.ok) return written;
 	return success({
 		scope: "global",
-		changed: true
+		changed: written.value
 	});
 }
 async function removeProject(input = {}) {
@@ -1121,15 +1289,19 @@ async function runSandboxCommandUnlocked(command, input, projectRoot) {
 	const registration = registryCheck.value.projects[projectRoot];
 	if (registration === void 0) return notRegistered(projectRoot);
 	const environment = input.environment ?? currentHostEnvironment();
+	const composePath = join(projectStateDirectory(registration.identity, paths.home), "compose.yaml");
 	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 composeState = await readOptionalFile(composePath);
+		if (!composeState.ok) return composeState;
+		if (!composeState.value.exists) return failure({
+			kind: "operational",
+			code: "missing-project-compose",
+			observed: `Sandbox definition is missing: ${composePath}.`,
+			nextAction: "Run devbox config to publish the Sandbox definition, then retry devbox up."
+		});
+		const volumes = await ensureSharedAgentVolumes(composeState.value.content, environment);
+		if (!volumes.ok) return volumes;
 	}
-	const composePath = join(projectStateDirectory(registration.identity, paths.home), "compose.yaml");
 	const operation = command === "up" ? ["up", "-d"] : command === "sh" ? [
 		"exec",
 		"--user",
@@ -1217,166 +1389,6 @@ function allocateSandboxName(projectRoot, registry) {
 		nextAction: "Remove stale Devbox state only through its supported command and try again."
 	});
 }
-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,
-		ports: input.localConfiguration.ports
-	});
-	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);
@@ -1548,16 +1560,21 @@ function showLogo() {
 	for (let i = 0; i < ASCII_ART.length; i++) console.log(`${COLORS[i]}${ASCII_ART[i]}${REST}`);
 }
 //#endregion
-//#region \0devbox-image-default:/home/runner/work/devbox/devbox/src/agent/image-defaults/.claude/settings.json.mjs
-var settings_json_default = "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"env\": {\n    \"CLAUDE_CODE_USE_POWERSHELL_TOOL\": \"0\"\n  },\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"includeGitInstructions\": false,\n  \"autoMemoryEnabled\": false\n}\n";
-//#endregion
-//#region \0devbox-image-default:/home/runner/work/devbox/devbox/src/agent/image-defaults/.omp/agent/config.yml.mjs
-var config_yml_default = "setupVersion: 2\n\n# Basic\nmodelRoles:\n  default: openai-codex/gpt-5.6-terra:high\n  smol: openai-codex/gpt-5.6-luna:high\n  slow: openai-codex/gpt-5.6-sol:max\n  plan: openai-codex/gpt-5.6-sol:max\nsymbolPreset: unicode\n\n# Theme\ntheme:\n  dark: titanium\n  light: light\ncomposer:\n  shape: claude\n\n# Auto QA\ndev:\n  autoqa: false\n  autoqaConsent: denied\n";
-//#endregion
-//#region \0devbox-image-default:/home/runner/work/devbox/devbox/src/agent/image-defaults/AGENTS.md.mjs
-var AGENTS_md_default = "# 協作規範\n\n## 語言\n\n- 一律使用繁體中文台灣用語產生對話及結果\n- 嚴禁使用簡體字，或是繁體字但中國大陸用語\n- 用詞要口語、常見，避免生硬或翻譯腔的詞彙；例如「根因」改用「原因」、「根本原因」、「主要原因」\n\n## 開發規範\n\n### 共用原則\n\n- 優先遵循專案既有的 `AGENTS.md`、文件、設定檔、lockfile、指令與程式碼慣例；專案沒有既有規範時，才使用本文件的預設選擇\n- 優先使用目前環境提供的專用工具；只有在專用工具無法完成工作或需要執行專案指令時，才使用適合的 CLI 工具\n- 執行會修改檔案、安裝套件或變更環境的指令前，確認目前位於預期的工作目錄\n- 可以在目前 workspace 內存取所需的上層目錄；存取 workspace 以外的檔案或目錄前，必須先取得使用者同意\n- 嚴禁執行任何會遞迴刪除根目錄的指令（例如 `rm -rf /`），也不得改寫或規避為效果相同的形式\n- 執行其他可能造成不可逆資料遺失的操作前，必須說明影響並取得使用者明確同意\n\n### JavaScript / TypeScript\n\n- 優先使用專案既有的 Node.js 版本設定與套件管理器\n- 專案未指定套件管理器且不存在 lockfile 時，使用 npm\n- 需要執行專案套件提供的 CLI 時，使用專案既有套件管理器對應的執行方式；使用 npm 時使用 npx\n- 不得擅自更換套件管理器、刪除 lockfile 或產生不同格式的 lockfile\n- TypeScript 格式規則\n  - 陣列型別優先使用 `T[]`，避免使用 `Array<T>`\n  - 字典型物件優先使用 `Record<string, T>`，避免使用 `{ [key: string]: T }`\n- Vue 3 程式碼變更前，先讀取 `/ycs77-vue` skill\n\n### PHP\n\n- 優先使用專案既有的 Composer scripts\n\n### 常見 CLI 工具\n\n- 版本控制操作使用 `git`\n- 所有 Git 操作都必須直接執行 `git` CLI\n- 禁止透過 Eval、JavaScript、Bun、Node.js、Python 或臨時程式碼間接包裝或呼叫 Git 指令\n- GitHub 相關操作優先使用 `gh` CLI\n\n## 安全\n\n- 在任何對話、指令輸出或程式碼中，不得揭露密碼、金鑰、Access Token、API Key 等機密資料\n- 不得讀取或輸出 `.env`、`.env.*` 等可能包含機密資料的檔案；不含真實機密的範本檔案（例如 `.env.example`）除外\n- 開發時需要使用機密資料，應以環境變數名稱或假值代稱，不得嘗試取得實際值\n";
-//#endregion
 //#region src/agent/build.ts
+const AGENT_BUILD_CONTEXT_ASSETS = {
+	instructions: {
+		relativePath: "AGENTS.md",
+		content: "# 協作規範\n\n## 語言\n\n- 一律使用繁體中文台灣用語產生對話及結果\n- 嚴禁使用簡體字，或是繁體字但中國大陸用語\n- 用詞要口語、常見，避免生硬或翻譯腔的詞彙；例如「根因」改用「原因」、「根本原因」、「主要原因」\n\n## 開發規範\n\n### 共用原則\n\n- 優先遵循專案既有的 `AGENTS.md`、文件、設定檔、lockfile、指令與程式碼慣例；專案沒有既有規範時，才使用本文件的預設選擇\n- 優先使用目前環境提供的專用工具；只有在專用工具無法完成工作或需要執行專案指令時，才使用適合的 CLI 工具\n- 執行會修改檔案、安裝套件或變更環境的指令前，確認目前位於預期的工作目錄\n- 可以在目前 workspace 內存取所需的上層目錄；存取 workspace 以外的檔案或目錄前，必須先取得使用者同意\n- 嚴禁執行任何會遞迴刪除根目錄的指令（例如 `rm -rf /`），也不得改寫或規避為效果相同的形式\n- 執行其他可能造成不可逆資料遺失的操作前，必須說明影響並取得使用者明確同意\n\n### JavaScript / TypeScript\n\n- 優先使用專案既有的 Node.js 版本設定與套件管理器\n- 專案未指定套件管理器且不存在 lockfile 時，使用 npm\n- 需要執行專案套件提供的 CLI 時，使用專案既有套件管理器對應的執行方式；使用 npm 時使用 npx\n- 不得擅自更換套件管理器、刪除 lockfile 或產生不同格式的 lockfile\n- TypeScript 格式規則\n  - 陣列型別優先使用 `T[]`，避免使用 `Array<T>`\n  - 字典型物件優先使用 `Record<string, T>`，避免使用 `{ [key: string]: T }`\n- Vue 3 程式碼變更前，先讀取 `/ycs77-vue` skill\n\n### PHP\n\n- 優先使用專案既有的 Composer scripts\n\n### 常見 CLI 工具\n\n- 版本控制操作使用 `git`\n- 所有 Git 操作都必須直接執行 `git` CLI\n- 禁止透過 Eval、JavaScript、Bun、Node.js、Python 或臨時程式碼間接包裝或呼叫 Git 指令\n- GitHub 相關操作優先使用 `gh` CLI\n\n## 安全\n\n- 在任何對話、指令輸出或程式碼中，不得揭露密碼、金鑰、Access Token、API Key 等機密資料\n- 不得讀取或輸出 `.env`、`.env.*` 等可能包含機密資料的檔案；不含真實機密的範本檔案（例如 `.env.example`）除外\n- 開發時需要使用機密資料，應以環境變數名稱或假值代稱，不得嘗試取得實際值\n"
+	},
+	claude: {
+		relativePath: ".claude/settings.json",
+		content: "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"env\": {\n    \"CLAUDE_CODE_USE_POWERSHELL_TOOL\": \"0\"\n  },\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"includeGitInstructions\": false,\n  \"autoMemoryEnabled\": false\n}\n"
+	},
+	omp: {
+		relativePath: ".omp/agent/config.yml",
+		content: "setupVersion: 2\n\n# Basic\nmodelRoles:\n  default: openai-codex/gpt-5.6-terra:high\n  smol: openai-codex/gpt-5.6-luna:high\n  slow: openai-codex/gpt-5.6-sol:max\n  plan: openai-codex/gpt-5.6-sol:max\nsymbolPreset: unicode\n\n# Theme\ntheme:\n  dark: titanium\n  light: light\ncomposer:\n  shape: claude\n\n# Auto QA\ndev:\n  autoqa: false\n  autoqaConsent: denied\n"
+	}
+};
 function createAgentWorkspaceContribution(input) {
 	const agents = input.configuredAgents.map((name) => ({
 		name,
@@ -1596,18 +1613,9 @@ function selectDockerignoreEntries(assets) {
 }
 function selectBuildContextAssets(agents) {
 	const assets = [];
-	if (agents.length > 0) assets.push({
-		relativePath: "AGENTS.md",
-		content: AGENTS_md_default
-	});
-	if (agents.some((agent) => agent.name === "claude-code")) assets.push({
-		relativePath: ".claude/settings.json",
-		content: settings_json_default
-	});
-	if (agents.some((agent) => agent.name === "omp")) assets.push({
-		relativePath: ".omp/agent/config.yml",
-		content: config_yml_default
-	});
+	if (agents.length > 0) assets.push(AGENT_BUILD_CONTEXT_ASSETS.instructions);
+	if (agents.some((agent) => agent.name === "claude-code")) assets.push(AGENT_BUILD_CONTEXT_ASSETS.claude);
+	if (agents.some((agent) => agent.name === "omp")) assets.push(AGENT_BUILD_CONTEXT_ASSETS.omp);
 	return assets;
 }
 function renderAgentAssets(agents) {
@@ -1793,7 +1801,7 @@ async function buildWorkspaceUnlocked(input) {
 		agent
 	});
 	await mkdir(paths.buildContext, { recursive: true });
-	await seedBuildContextAssets(paths.buildContext, buildContextAssets);
+	await refreshBuildContextAssets(paths.buildContext, buildContextAssets);
 	await Promise.all([
 		writeFile(join(paths.buildContext, "Dockerfile"), dockerfile),
 		writeFile(join(paths.buildContext, ".dockerignore"), renderDockerignore(buildContextAssets, agent.dockerignoreEntries)),
@@ -1890,15 +1898,13 @@ function renderDockerignore(assets, additionalEntries) {
 		...additionalEntries
 	].join("\n")}\n`;
 }
-async function seedBuildContextAssets(buildContext, assets) {
+async function refreshBuildContextAssets(buildContext, assets) {
+	const requiredPaths = new Set(assets.map((asset) => asset.relativePath));
+	for (const asset of Object.values(AGENT_BUILD_CONTEXT_ASSETS)) if (!requiredPaths.has(asset.relativePath)) await rm(join(buildContext, asset.relativePath), { force: true });
 	await Promise.all(assets.map(async (asset) => {
 		const destination = join(buildContext, asset.relativePath);
 		await mkdir(dirname(destination), { recursive: true });
-		try {
-			await writeFile(destination, asset.content, { flag: "wx" });
-		} catch (error) {
-			if (typeof error !== "object" || error === null || !("code" in error) || error.code !== "EEXIST") throw error;
-		}
+		await writeFile(destination, asset.content);
 	}));
 }
 function renderEntrypoint(input) {
@@ -1989,7 +1995,7 @@ function createCli(signal, interactive) {
 			outro("Project is already registered.");
 			return success({});
 		}
-		outro(`Next: run ${command("devbox build")} to prepare your workspace, then ${command("devbox up")} to start it.`);
+		outro(result.value.globalConfigurationCreated ? `Next: run ${command("devbox build")} to prepare your workspace, then ${command("devbox up")} to start it.` : `Next: run ${command("devbox up")} to start it.`);
 		return success({});
 	});
 	cli.command("config", "Edit Global or Local configuration for the current Project.").action(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycs77/devbox",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "A Lucas Yang's opinionated devbox for AI agents",
   "keywords": [
     "agent",