@ycs77/devbox 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @ycs77/devbox
 
-**A opinionated devbox for AI agents.**
+**An opinionated devbox for AI agents.**
 
 [![NPM version][ico-version]][link-npm]
 [![Software License][ico-license]](LICENSE)
@@ -17,20 +17,20 @@ English | [繁體中文](README-zh-TW.md)
 
 ## Overview
 
-Devbox gives each project an isolated Docker sandbox designed for AI agents, with Lucas's opinionated development setup. Choose the Node.js release lines and AI agents you use, then work from a consistent container without configuring it yourself.
+Devbox gives each project an isolated Docker sandbox for AI agents, preconfigured with Lucas's development preferences.
 
 ## Features
 
 - **Container environment for AI agents:** choose Claude Code, Codex, and more during setup, then use them inside the sandbox.
-- **Simple setup and project lifecycle:** initialize, start, enter, stop, and remove a sandbox with a few commands.
-- **Flexible Node.js environments:** configure Node.js 22 and 24, then select a version for each project.
+- **Simple project sandbox management:** initialize, start, enter, stop, and remove a sandbox with a few commands.
+- **Flexible Node.js versions:** choose the versions to include, then select one for each project.
 - **Selective builds:** build only the Node.js versions and AI agents you choose.
 - **No project configuration files:** keep Devbox configuration local to your machine, not in your repository.
 
 ## Requirements
 
-- **Node.js 22 or later:** installs and runs the CLI with npm.
-- **Docker with Docker Compose:** runs the development sandbox.
+- **Node.js 22 or later:** required to install and run the CLI with npm.
+- **Docker with Docker Compose:** required to run the development sandbox.
 - **Windows:** use Devbox from a **WSL2** Linux distribution with Docker Desktop integration enabled.
 
 ## Getting started
@@ -47,9 +47,11 @@ From your project directory, initialize Devbox:
 devbox init
 ```
 
-The interactive setup lets you choose the Node.js release lines and AI agents to configure, then select the Node.js version for the current project.
+The interactive setup lets you choose the Node.js versions and AI agents to include, then select a Node.js version for the current project.
 
-Build the shared workspace image once after setup or after changing global configuration:
+Global configuration controls what goes into the shared Workspace Image. Each Node.js version or AI agent you add makes the image larger and uses more disk space. Projects can use only the Node.js versions included in the image.
+
+Build the shared Workspace Image once after setup or whenever you change global configuration:
 
 ```bash
 devbox build
@@ -67,9 +69,9 @@ Open a shell inside the running sandbox and start working with your AI agent:
 devbox sh
 ```
 
-For example, run `claude`, `codex`, `agy`, or `omp` after opening the shell when that agent was selected during setup.
+If you selected an agent during setup, run `claude`, `codex`, `agy`, or `omp` inside the shell.
 
-## Everyday commands
+## Commands
 
 Run these commands from the initialized project directory:
 
@@ -79,23 +81,24 @@ Run these commands from the initialized project directory:
 | `devbox sh` | Open a Bash shell in the running sandbox. |
 | `devbox stop` | Stop the sandbox and preserve it for a later restart. |
 | `devbox down` | Stop and remove the sandbox container. |
-| `devbox config` | Change the globally configured or current project's Node.js selection. |
+| `devbox config` | Change global settings or this project's configuration. |
+| `devbox cleanup --missing-projects` | Remove registrations for projects whose root directory no longer exists. |
 
 ## Troubleshooting
 
-### A command says a Devbox marker is occupied
+### Devbox reports that a command marker is in use
 
-An interrupted process or sudden system shutdown can leave a command marker behind. First confirm that no Devbox process is still running, then remove only the stale marker and retry:
+An interrupted command or sudden system shutdown can leave a command marker behind. First confirm that no other Devbox command is still running, then remove the stale marker and retry:
 
 ```bash
 rm -rf ~/.devbox/locks/<marker>
 ```
 
-Markers are directories named `global` or `project-<hash>`. Do not remove a marker while its Devbox command is still running.
+A marker is a directory named `global` or `project-<hash>`. Do not remove a marker while its Devbox command is still running.
 
 ## Sponsor
 
-If you think this package has helped you, please consider [Becoming a sponsor](https://www.patreon.com/ycs77) to support my work~ and your avatar will be visible on my major projects.
+If Devbox has helped you, consider sponsoring my work on Patreon. Your avatar will appear on my major projects.
 
 <p align="center">
   <a href="https://www.patreon.com/ycs77">

package/dist/cli.mjs

@@ -10,6 +10,9 @@ 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 package.json
+var version = "0.6.0";
+//#endregion
 //#region src/catalog/index.ts
 const NODE_RELEASE_KEYS = [
 	"5BE8A3F6C8A5C01D106C0AD820B1A390B168D356",
@@ -27,12 +30,14 @@ const PACKAGED_NODE_RECIPES = {
 		releaseLine: "24",
 		version: "24.19.0",
 		runtimeRoot: "/opt/devbox/runtimes/node/24",
+		distributionBaseUrl: "https://nodejs.org/dist",
 		trustedReleaseKeys: NODE_RELEASE_KEYS
 	},
 	"22": {
 		releaseLine: "22",
 		version: "22.23.2",
 		runtimeRoot: "/opt/devbox/runtimes/node/22",
+		distributionBaseUrl: "https://nodejs.org/dist",
 		trustedReleaseKeys: NODE_RELEASE_KEYS
 	}
 };
@@ -467,10 +472,7 @@ 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
+//#region src/agent/compose.ts
 const NOTIFICATION_FRAGMENT = {
 	environment: { PULSE_SERVER: "unix:/tmp/pulse-socket" },
 	volume: {
@@ -479,7 +481,7 @@ const NOTIFICATION_FRAGMENT = {
 		readOnly: true
 	}
 };
-function selectComposeFragments({ selectedNode, configuredAgents, agentNotifications }) {
+function selectAgentComposeFragments(configuredAgents, notificationsEnabled) {
 	const agents = [];
 	let hasNotificationAgent = false;
 	for (const agent of configuredAgents) {
@@ -497,19 +499,26 @@ function selectComposeFragments({ selectedNode, configuredAgents, agentNotificat
 		}
 	}
 	return {
-		node: selectedNode === null ? void 0 : { environment: { NODE_VERSION: selectedNode } },
 		agents,
-		notification: agentNotifications && hasNotificationAgent ? NOTIFICATION_FRAGMENT : void 0
+		notification: notificationsEnabled && hasNotificationAgent ? NOTIFICATION_FRAGMENT : void 0
 	};
 }
 //#endregion
+//#region src/runtimes/node/compose.ts
+function selectNodeComposeFragment(selectedNode) {
+	return selectedNode === null ? void 0 : { environment: { NODE_VERSION: selectedNode } };
+}
+//#endregion
+//#region src/workspace/image.ts
+const WORKSPACE_IMAGE = "devbox-workspace:latest";
+//#endregion
 //#region src/project/compose.ts
 function renderProjectCompose(input) {
-	const fragments = selectComposeFragments(input);
+	const node = selectNodeComposeFragment(input.selectedNode);
+	const agent = selectAgentComposeFragments(input.configuredAgents, input.agentNotifications);
 	const environment = {
-		TERM: "xterm-256color",
-		...fragments.node?.environment,
-		...fragments.notification?.environment
+		...node?.environment,
+		...agent.notification?.environment
 	};
 	const volumes = [
 		{
@@ -517,7 +526,7 @@ function renderProjectCompose(input) {
 			source: input.projectRoot,
 			target: `/workspace/${input.sandboxName}`
 		},
-		...fragments.agents.map((fragment) => ({
+		...agent.agents.map((fragment) => ({
 			type: "volume",
 			source: fragment.volume.name,
 			target: fragment.volume.target
@@ -527,11 +536,11 @@ function renderProjectCompose(input) {
 			source: input.claudeHostConfiguration,
 			target: "/home/devbox/.claude.json"
 		}],
-		...fragments.notification === void 0 ? [] : [{
+		...agent.notification === void 0 ? [] : [{
 			type: "bind",
-			source: fragments.notification.volume.source,
-			target: fragments.notification.volume.target,
-			read_only: fragments.notification.volume.readOnly
+			source: agent.notification.volume.source,
+			target: agent.notification.volume.target,
+			read_only: agent.notification.volume.readOnly
 		}]
 	];
 	const definition = {
@@ -551,7 +560,7 @@ function renderProjectCompose(input) {
 			...Object.keys(environment).length === 0 ? {} : { environment },
 			volumes
 		} },
-		...fragments.agents.length === 0 ? {} : { volumes: Object.fromEntries(fragments.agents.map((fragment) => [fragment.volume.name, {
+		...agent.agents.length === 0 ? {} : { volumes: Object.fromEntries(agent.agents.map((fragment) => [fragment.volume.name, {
 			name: fragment.volume.name,
 			external: fragment.volume.external
 		}])) }
@@ -1191,9 +1200,12 @@ async function runSandboxLifecycle(command, input = {}) {
 		global: false,
 		projectRoots: [projectRoot],
 		signal: input.signal
-	}, () => runSandboxLifecycleUnlocked(command, input, projectRoot));
+	}, () => runSandboxCommandUnlocked(command, input, projectRoot));
 }
-async function runSandboxLifecycleUnlocked(command, input, projectRoot) {
+async function runSandboxShell(input = {}) {
+	return runSandboxCommandUnlocked("sh", input, input.root ?? process.cwd());
+}
+async function runSandboxCommandUnlocked(command, input, projectRoot) {
 	if (input.signal?.aborted) throw new InterruptedError();
 	const rootCheck = await validateProjectRoot(projectRoot);
 	if (!rootCheck.ok) return rootCheck;
@@ -1532,18 +1544,20 @@ function createConfigurationPrompter({ signal, input, output }) {
 			}));
 		},
 		selectConfigurationScope: async () => promptValue(p.select({
-			message: "Configuration scope",
+			message: "Where should this configuration apply?",
 			options: [{
 				value: "local",
-				label: "Current Project"
+				label: "Current project",
+				hint: "Enabled when this project’s container starts."
 			}, {
 				value: "global",
-				label: "Global"
+				label: "Workspace Docker image",
+				hint: "Built into the shared image. It affects image size and disk usage."
 			}],
 			...common
 		})),
 		editGlobal: async (configuration, catalog) => {
-			p.log.step(`${c.bold(c.cyan("Global configuration"))}\n${c.dim("Choose the runtimes and agents available to every Project.")}`, common);
+			p.log.step(`${c.bold(c.cyan("Workspace Docker image"))}\n${c.dim("Add runtimes and agents to the shared image. They are available to every project and increase the image size.")}`, common);
 			return {
 				version: 1,
 				node: await promptValue(p.multiselect({
@@ -1568,7 +1582,7 @@ function createConfigurationPrompter({ signal, input, output }) {
 			};
 		},
 		editLocal: async (configuration, catalog, globalConfiguration, editPorts = true) => {
-			p.log.step(`${c.bold(c.cyan("Project configuration"))}\n${c.dim(editPorts ? "Choose the runtime and published ports for this Project." : "Choose the replacement runtime for this Project.")}`, common);
+			p.log.step(`${c.bold(c.cyan("Project configuration"))}\n${c.dim(editPorts ? "Choose the Node version and ports to use when this project’s container starts." : "Choose the Node version to use when this project’s container starts.")}`, common);
 			const node = await promptValue(p.select({
 				message: "Selected Node release line",
 				options: [{
@@ -1638,34 +1652,205 @@ function showLogo() {
 	for (let i = 0; i < ASCII_ART.length; i++) console.log(`${COLORS[i]}${ASCII_ART[i]}${REST}`);
 }
 //#endregion
-//#region \0devbox-workspace-image-default:.bash_aliases.mjs
-var _devbox_workspace_image_default__bash_aliases_default = "alias ..='cd ..'\nalias ...='cd ../..'\nalias c='clear'\nalias g='git'\nalias ccc='claude --dangerously-skip-permissions'\nalias ccx='codex --sandbox workspace-write --ask-for-approval never'\nalias ggg='agy --dangerously-skip-permissions'\n\nfunction mkcd() {\n  mkdir \"$1\"\n  cd \"$1\"\n}\n\n# Laravel Artisan\nalias pa='php artisan'\nalias pav='php artisan serve'\nalias pam='php artisan migrate'\nalias pams='php artisan migrate --seed'\nalias pamr='php artisan migrate:rollback'\nalias pamf='php artisan migrate:fresh'\nalias pamfs='php artisan migrate:fresh --seed'\nalias pas='php artisan db:seed'\nalias par='php artisan route:list'\nalias paq='php artisan queue:work'\nalias pah='php artisan horizon'\nalias pat='php artisan tinker'\nalias phpunit='./vendor/bin/phpunit --colors=always'\nalias pu='phpunit'\nalias pest='./vendor/bin/pest --colors=always'\nalias p='pest'\nalias pint='./vendor/bin/pint'\nalias phpstan='./vendor/bin/phpstan analyse --ansi'\nalias rector='./vendor/bin/rector'\n\n# NPM (requires @antfu/ni)\nalias nv='nr dev' # nd exists in @antfu/ni\nalias nb='nr build'\nalias nll='nr lint' # nl is a Linux command\nalias nlf='nr lint --fix'\nalias nf='nr fmt'\nalias nfc='nr fmt --check'\nalias nc='nr check'\nalias nt='nr test'\nalias ntr='nr test --run'\n";
-//#endregion
-//#region \0devbox-workspace-image-default:.claude/settings.json.mjs
+//#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-workspace-image-default:.gitconfig.mjs
-var _devbox_workspace_image_default__gitconfig_default = "[core]\n	autocrlf = input\n	fileMode = false\n	pager = less -r\n	quotepath = false\n[init]\n	defaultBranch = main\n[color]\n	diff = auto\n	status = auto\n	branch = auto\n[alias]\n	cf = config\n	cfl = config --list\n	s = status\n	a = add .\n	l = log --oneline --graph\n	la = log --oneline --graph --all\n	last = log -1 HEAD\n	c = commit\n	cm = commit -m\n	ca = commit --amend -m\n	can = commit --amend --no-edit\n	co = checkout\n	cp = cherry-pick\n	b = branch\n	m = merge\n	mnf = merge --no-ff\n	rs = reset\n	rs0h = reset HEAD --hard\n	rs1 = reset HEAD~1\n	rs1h = reset HEAD~1 --hard\n	rb = rebase\n	rbo = rebase --onto\n	rbi = rebase -i\n	rbc = rebase --continue\n	rba = rebase --abort\n	rm = remote\n	r = remote -v\n	ra = remote add\n	rr = remote remove\n	rp = remote prune\n	f = fetch\n	fp = fetch --prune\n	p = push\n	pl = pull\n";
-//#endregion
-//#region \0devbox-workspace-image-default:.omp/agent/config.yml.mjs
+//#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 src/agent/build.ts
+function createAgentWorkspaceContribution(input) {
+	const agents = input.configuredAgents.map((name) => ({
+		name,
+		recipe: PACKAGED_AGENTS[name]
+	}));
+	const buildContextAssets = selectBuildContextAssets(agents);
+	const skillAgents = agents.filter((agent) => agent.recipe.supportsSkillInstallation).map((agent) => agent.name);
+	return {
+		buildContextAssets,
+		dockerignoreEntries: selectDockerignoreEntries(buildContextAssets),
+		installationDockerfileLines: renderAgentInstallations(agents, input.buildNodeRuntimeRoot, skillAgents),
+		assetDockerfileLines: renderAgentAssets(agents),
+		notificationDockerfileLines: renderAgentNotifications(agents, input.notificationsEnabled),
+		entrypointSetup: renderAgentEntrypointSetup(agents)
+	};
+}
+function renderAgentInstallations(agents, buildNodeRuntimeRoot, skillAgents) {
+	const lines = [];
+	for (const agent of agents) {
+		const preInstallCommands = agent.recipe.installation.preInstallCommands ?? [];
+		lines.push(`# Install ${agent.name}`, `RUN mkdir -p ${agent.recipe.home.target} \\`, ...preInstallCommands.map((command) => `    && ${command} \\`), `    && curl -fsSL ${agent.recipe.installation.url} | ${agent.recipe.installation.shell}`, "");
+	}
+	if (agents.length > 0) lines.push("# Set the PATH to include AI tools", "ENV PATH=\"/home/devbox/.local/bin:${PATH}\"", "");
+	if (buildNodeRuntimeRoot !== void 0 && skillAgents.length > 0) {
+		const skillAgentArguments = skillAgents.map((agent) => `-a ${agent}`).join(" ");
+		lines.push("# Install Agent Skills", "RUN set -eux \\", "    && mkdir -p /home/devbox/.agents/skills \\", `    && export PATH="${buildNodeRuntimeRoot}/bin:$PATH" \\`, `    && npx -y skills add ycs77/skills -g ${skillAgentArguments} -s '*' -y`, "");
+	}
+	return lines;
+}
+function selectDockerignoreEntries(assets) {
+	const entries = [];
+	if (assets.some((asset) => asset.relativePath === ".claude/settings.json")) entries.push("!.claude", "!.claude/settings.json");
+	if (assets.some((asset) => asset.relativePath === ".omp/agent/config.yml")) entries.push("!.omp", "!.omp/agent", "!.omp/agent/config.yml");
+	return entries;
+}
+function selectBuildContextAssets(agents) {
+	const assets = [];
+	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
+	});
+	return assets;
+}
+function renderAgentAssets(agents) {
+	const hasClaudeCode = agents.some((agent) => agent.name === "claude-code");
+	const hasOmp = agents.some((agent) => agent.name === "omp");
+	if (!hasClaudeCode && !hasOmp) return [];
+	const ownershipCommands = [];
+	const lines = ["# Copy AI dotfiles"];
+	if (hasClaudeCode) {
+		lines.push("COPY .claude/settings.json /home/devbox/.claude/settings.json");
+		ownershipCommands.push("chown devbox:devbox /home/devbox/.claude/settings.json");
+	}
+	if (hasOmp) {
+		lines.push("COPY .omp/agent/config.yml /home/devbox/.omp/agent/config.yml");
+		ownershipCommands.push("chown devbox:devbox /home/devbox/.omp/agent", "chown devbox:devbox /home/devbox/.omp/agent/config.yml");
+	}
+	lines.push(`RUN ${ownershipCommands.join(" \\\n    && ")}`, "");
+	return lines;
+}
+function renderAgentNotifications(agents, notificationsEnabled) {
+	const commands = notificationsEnabled ? agents.flatMap((agent) => agent.recipe.supportsNotifications ? agent.recipe.notificationInstallationCommands : []) : [];
+	if (commands.length === 0) return [];
+	return [
+		"# Install Agent Notification Plugins",
+		"USER devbox",
+		"RUN set -eux \\",
+		...commands.map((command, index) => `    && ${command}${index < commands.length - 1 ? " \\" : ""}`),
+		"USER root",
+		""
+	];
+}
+function renderAgentEntrypointSetup(agents) {
+	if (!agents.some((agent) => agent.name === "agy")) return [];
+	return [
+		"# Link shared Agent Skills",
+		"if [ ! -L \"/home/devbox/.gemini/skills\" ]; then",
+		"  ln -sfn /home/devbox/.agents/skills /home/devbox/.gemini/skills",
+		"  chown -h devbox:devbox /home/devbox/.gemini/skills",
+		"fi",
+		""
+	];
+}
+//#endregion
+//#region src/runtimes/node/build.ts
+function createNodeWorkspaceContribution(configuredReleaseLines) {
+	const runtimes = configuredReleaseLines.map((releaseLine) => PACKAGED_NODE_RECIPES[releaseLine]);
+	const buildRuntime = selectBuildNodeRuntime(runtimes);
+	return {
+		buildNodeRuntimeRoot: buildRuntime?.runtimeRoot,
+		runtimeInstallations: runtimes.flatMap(renderNodeRuntimeStage),
+		sandboxUserSetup: buildRuntime === void 0 ? [] : [
+			"# 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",
+			""
+		],
+		entrypointSetup: renderNodeEntrypointSetup(runtimes)
+	};
+}
+function selectBuildNodeRuntime(runtimes) {
+	let buildRuntime;
+	for (const runtime of runtimes) if (buildRuntime === void 0 || Number.parseFloat(runtime.releaseLine) > Number.parseFloat(buildRuntime.releaseLine)) buildRuntime = runtime;
+	return buildRuntime;
+}
+function renderNodeEntrypointSetup(runtimes) {
+	if (runtimes.length === 0) return [];
+	return [
+		"# Set the Node.js release line to use",
+		"NODE_VERSION=\"${NODE_VERSION:-}\"",
+		"if [ -n \"$NODE_VERSION\" ]; then",
+		"  case \"$NODE_VERSION\" in",
+		"    *[!0-9]*)",
+		"      echo \"NODE_VERSION must be a numeric release line: $NODE_VERSION\" >&2",
+		"      exit 1",
+		"      ;;",
+		"  esac",
+		"",
+		"  NODE_RUNTIME_ROOT=\"/opt/devbox/runtimes/node/$NODE_VERSION\"",
+		"  if [ ! -x \"$NODE_RUNTIME_ROOT/bin/node\" ]; then",
+		"    echo \"Node.js release line $NODE_VERSION is not installed.\" >&2",
+		"    exit 1",
+		"  fi",
+		"",
+		"  if ! grep -q \"# Devbox\" /etc/bash.bashrc; then",
+		"    printf \"\\n# Devbox\\nexport PATH=\\\"$NODE_RUNTIME_ROOT/bin:\\$PATH\\\"\\n\" >> /etc/bash.bashrc",
+		"  fi",
+		"",
+		"  export PATH=\"$NODE_RUNTIME_ROOT/bin:$PATH\"",
+		"fi",
+		""
+	];
+}
+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} \\`,
+		"    && 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 -fsSLO --compressed "${recipe.distributionBaseUrl}/v\${NODE_RUNTIME_VERSION}/node-v\${NODE_RUNTIME_VERSION}-linux-\${ARCH}.tar.xz" \\`,
+		`    && curl -fsSLO --compressed "${recipe.distributionBaseUrl}/v\${NODE_RUNTIME_VERSION}/SHASUMS256.txt.asc" \\`,
+		"    && gpg --batch --no-options --decrypt --output SHASUMS256.txt SHASUMS256.txt.asc \\",
+		"    && gpgconf --kill all \\",
+		"    && rm -rf \"$GNUPGHOME\" \\",
+		"    && grep \" node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\\$\" SHASUMS256.txt | sha256sum -c - \\",
+		"    && tar -xJf \"node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\" -C \"$NODE_RUNTIME_ROOT\" --strip-components=1 --no-same-owner \\",
+		"    && rm \"node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\" SHASUMS256.txt.asc SHASUMS256.txt \\",
+		"    && 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 --allow-scripts=pnpm,yarn \\",
+		"    && \"$NODE_RUNTIME_ROOT/bin/node\" --version \\",
+		"    && \"$NODE_RUNTIME_ROOT/bin/npm\" --version \\",
+		"    && rm -rf /tmp/node-source",
+		""
+	];
+}
+//#endregion
 //#region src/workspace/build.ts
 const BASE_WORKSPACE_IMAGE_DEFAULTS = [{
 	relativePath: ".bash_aliases",
-	content: _devbox_workspace_image_default__bash_aliases_default
+	content: "alias ..='cd ..'\nalias ...='cd ../..'\nalias c='clear'\nalias g='git'\nalias ccc='claude --dangerously-skip-permissions'\nalias ccx='codex --sandbox workspace-write --ask-for-approval never'\nalias ggg='agy --dangerously-skip-permissions'\n\nfunction mkcd() {\n  mkdir \"$1\"\n  cd \"$1\"\n}\n\n# Laravel Artisan\nalias pa='php artisan'\nalias pav='php artisan serve'\nalias pam='php artisan migrate'\nalias pams='php artisan migrate --seed'\nalias pamr='php artisan migrate:rollback'\nalias pamf='php artisan migrate:fresh'\nalias pamfs='php artisan migrate:fresh --seed'\nalias pas='php artisan db:seed'\nalias par='php artisan route:list'\nalias paq='php artisan queue:work'\nalias pah='php artisan horizon'\nalias pat='php artisan tinker'\nalias phpunit='./vendor/bin/phpunit --colors=always'\nalias pu='phpunit'\nalias pest='./vendor/bin/pest --colors=always'\nalias p='pest'\nalias pint='./vendor/bin/pint'\nalias phpstan='./vendor/bin/phpstan analyse --ansi'\nalias rector='./vendor/bin/rector'\n\n# NPM (requires @antfu/ni)\nalias nv='nr dev' # nd exists in @antfu/ni\nalias nb='nr build'\nalias nll='nr lint' # nl is a Linux command\nalias nlf='nr lint --fix'\nalias nf='nr fmt'\nalias nfc='nr fmt --check'\nalias nc='nr check'\nalias nt='nr test'\nalias ntr='nr test --run'\n"
 }, {
 	relativePath: ".gitconfig",
-	content: _devbox_workspace_image_default__gitconfig_default
+	content: "[core]\n	autocrlf = input\n	fileMode = false\n	pager = less -r\n	quotepath = false\n[init]\n	defaultBranch = main\n[color]\n	diff = auto\n	status = auto\n	branch = auto\n[alias]\n	cf = config\n	cfl = config --list\n	s = status\n	a = add .\n	l = log --oneline --graph\n	la = log --oneline --graph --all\n	last = log -1 HEAD\n	c = commit\n	cm = commit -m\n	ca = commit --amend -m\n	can = commit --amend --no-edit\n	co = checkout\n	cp = cherry-pick\n	b = branch\n	m = merge\n	mnf = merge --no-ff\n	rs = reset\n	rs0h = reset HEAD --hard\n	rs1 = reset HEAD~1\n	rs1h = reset HEAD~1 --hard\n	rb = rebase\n	rbo = rebase --onto\n	rbi = rebase -i\n	rbc = rebase --continue\n	rba = rebase --abort\n	rm = remote\n	r = remote -v\n	ra = remote add\n	rr = remote remove\n	rp = remote prune\n	f = fetch\n	fp = fetch --prune\n	p = push\n	pl = pull\n"
 }];
-const CLAUDE_SETTINGS_DEFAULT = {
-	relativePath: ".claude/settings.json",
-	content: settings_json_default
-};
-const OMP_AGENT_CONFIG_DEFAULT = {
-	relativePath: ".omp/agent/config.yml",
-	content: config_yml_default
-};
 async function buildWorkspace(input = {}) {
 	return withStateLocks({
 		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
@@ -1695,27 +1880,25 @@ async function buildWorkspaceUnlocked(input) {
 	const globalConfiguration = parsedGlobal.value;
 	const hostIdentity = currentHostIdentity();
 	if (!hostIdentity.ok) return hostIdentity;
-	const agents = globalConfiguration.agent.map((name) => ({
-		name,
-		recipe: PACKAGED_AGENTS[name]
-	}));
-	const buildContextAssets = selectBuildContextAssets(agents);
-	const nodeRuntimes = globalConfiguration.node.map((releaseLine) => PACKAGED_NODE_RECIPES[releaseLine]);
+	const node = createNodeWorkspaceContribution(globalConfiguration.node);
+	const agent = createAgentWorkspaceContribution({
+		configuredAgents: globalConfiguration.agent,
+		notificationsEnabled: globalConfiguration.agent_notifications,
+		buildNodeRuntimeRoot: node.buildNodeRuntimeRoot
+	});
+	const buildContextAssets = [...BASE_WORKSPACE_IMAGE_DEFAULTS, ...agent.buildContextAssets];
 	const dockerfile = renderBuildDockerfile({
-		nodeRuntimes,
-		buildNodeRuntime: buildNodeRuntimeRecipe(globalConfiguration),
-		agents,
-		agentNotifications: globalConfiguration.agent_notifications,
-		skillAgents: globalConfiguration.agent.filter((agent) => PACKAGED_AGENTS[agent]?.supportsSkillInstallation === true)
+		node,
+		agent
 	});
 	await mkdir(paths.buildContext, { recursive: true });
 	await seedBuildContextAssets(paths.buildContext, buildContextAssets);
 	await Promise.all([
 		writeFile(join(paths.buildContext, "Dockerfile"), dockerfile),
-		writeFile(join(paths.buildContext, ".dockerignore"), renderDockerignore(buildContextAssets)),
+		writeFile(join(paths.buildContext, ".dockerignore"), renderDockerignore(buildContextAssets, agent.dockerignoreEntries)),
 		writeFile(join(paths.buildContext, "entrypoint.sh"), renderEntrypoint({
-			nodeRuntimes,
-			agents
+			node,
+			agent
 		})),
 		writeFile(join(paths.buildContext, "supervisord.conf"), renderSupervisorConfiguration())
 	]);
@@ -1729,14 +1912,6 @@ async function buildWorkspaceUnlocked(input) {
 	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 currentHostIdentity() {
 	const userId = typeof process.getuid === "function" ? process.getuid() : void 0;
 	const groupId = typeof process.getgid === "function" ? process.getgid() : void 0;
@@ -1762,6 +1937,9 @@ function renderBuildDockerfile(input) {
 		"ENV DEBIAN_FRONTEND=noninteractive",
 		"ENV TZ=UTC",
 		"ENV LANG=C.UTF-8",
+		"ENV TERM=xterm-256color",
+		"ENV EDITOR=vim",
+		"ENV VISUAL=vim",
 		"",
 		"RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone",
 		"",
@@ -1790,51 +1968,26 @@ function renderBuildDockerfile(input) {
 		"    && chmod 0440 /etc/sudoers.d/devbox",
 		""
 	];
-	for (const recipe of input.nodeRuntimes) lines.push(...renderNodeRuntimeStage(recipe));
+	lines.push(...input.node.runtimeInstallations);
 	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) {
-		const preInstallCommands = agent.recipe.installation.preInstallCommands ?? [];
-		lines.push(`# Install ${agent.name}`, `RUN mkdir -p ${agent.recipe.home.target} \\`, ...preInstallCommands.map((command) => `    && ${command} \\`), `    && 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(...input.node.sandboxUserSetup);
+	lines.push(...input.agent.installationDockerfileLines);
 	lines.push("USER root", "", "# Copy dotfiles", "COPY .bash_aliases /home/devbox/.bash_aliases", "COPY .gitconfig /home/devbox/.gitconfig", "RUN chown devbox:devbox /home/devbox/.bash_aliases \\", "    && chown devbox:devbox /home/devbox/.gitconfig", "");
-	const hasClaudeCode = input.agents.some((agent) => agent.name === "claude-code");
-	const hasOmp = input.agents.some((agent) => agent.name === "omp");
-	if (hasClaudeCode || hasOmp) {
-		const ownershipCommands = [];
-		lines.push("# Copy AI dotfiles");
-		if (hasClaudeCode) {
-			lines.push("COPY .claude/settings.json /home/devbox/.claude/settings.json");
-			ownershipCommands.push("chown devbox:devbox /home/devbox/.claude/settings.json");
-		}
-		if (hasOmp) {
-			lines.push("COPY .omp/agent/config.yml /home/devbox/.omp/agent/config.yml");
-			ownershipCommands.push("chown devbox:devbox /home/devbox/.omp/agent", "chown devbox:devbox /home/devbox/.omp/agent/config.yml");
-		}
-		lines.push(`RUN ${ownershipCommands.join(" \\\n    && ")}`, "");
-	}
-	const notificationInstallationCommands = input.agentNotifications ? input.agents.flatMap((agent) => agent.recipe.supportsNotifications ? agent.recipe.notificationInstallationCommands : []) : [];
-	if (notificationInstallationCommands.length > 0) lines.push("# Install Agent Notification Plugins", "USER devbox", "RUN set -eux \\", ...notificationInstallationCommands.map((command, index) => `    && ${command}${index < notificationInstallationCommands.length - 1 ? " \\" : ""}`), "USER root", "");
+	lines.push(...input.agent.assetDockerfileLines);
+	lines.push(...input.agent.notificationDockerfileLines);
 	lines.push("COPY entrypoint.sh /usr/local/bin/entrypoint.sh", "COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf", "RUN chmod +x /usr/local/bin/entrypoint.sh", "", "ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]");
 	return `${lines.join("\n")}\n`;
 }
-function renderDockerignore(assets) {
-	const lines = [
+function renderDockerignore(assets, additionalEntries) {
+	return `${[
 		"# Machine-owned Workspace build context",
 		"*",
 		"!Dockerfile",
 		"!entrypoint.sh",
 		"!supervisord.conf",
-		...assets.map((asset) => `!${asset.relativePath}`)
-	];
-	if (assets.some((asset) => asset.relativePath === ".claude/settings.json")) lines.push("!.claude", "!.claude/settings.json");
-	if (assets.some((asset) => asset.relativePath === ".omp/agent/config.yml")) lines.push("!.omp", "!.omp/agent", "!.omp/agent/config.yml");
-	return `${lines.join("\n")}\n`;
+		...assets.map((asset) => `!${asset.relativePath}`),
+		...additionalEntries
+	].join("\n")}\n`;
 }
 async function seedBuildContextAssets(buildContext, assets) {
 	await Promise.all(assets.map(async (asset) => {
@@ -1847,18 +2000,18 @@ async function seedBuildContextAssets(buildContext, assets) {
 		}
 	}));
 }
-function selectBuildContextAssets(agents) {
-	const assets = [...BASE_WORKSPACE_IMAGE_DEFAULTS];
-	if (agents.some((agent) => agent.name === "claude-code")) assets.push(CLAUDE_SETTINGS_DEFAULT);
-	if (agents.some((agent) => agent.name === "omp")) assets.push(OMP_AGENT_CONFIG_DEFAULT);
-	return assets;
-}
 function renderEntrypoint(input) {
-	const lines = ["#!/usr/bin/env bash", ""];
-	if (input.nodeRuntimes.length > 0) lines.push("# Set the Node.js release line to use", "NODE_VERSION=\"${NODE_VERSION:-}\"", "if [ -n \"$NODE_VERSION\" ]; then", "  case \"$NODE_VERSION\" in", "    *[!0-9]*)", "      echo \"NODE_VERSION must be a numeric release line: $NODE_VERSION\" >&2", "      exit 1", "      ;;", "  esac", "", "  NODE_RUNTIME_ROOT=\"/opt/devbox/runtimes/node/$NODE_VERSION\"", "  if [ ! -x \"$NODE_RUNTIME_ROOT/bin/node\" ]; then", "    echo \"Node.js release line $NODE_VERSION is not installed.\" >&2", "    exit 1", "  fi", "", "  if ! grep -q \"# Devbox\" /etc/bash.bashrc; then", "    printf \"\\n# Devbox\\nexport PATH=\\\"$NODE_RUNTIME_ROOT/bin:\\$PATH\\\"\\n\" >> /etc/bash.bashrc", "  fi", "", "  export PATH=\"$NODE_RUNTIME_ROOT/bin:$PATH\"", "fi", "");
-	if (input.agents.some((agent) => agent.name === "agy")) lines.push("# Link shared Agent Skills", "if [ ! -L \"/home/devbox/.gemini/skills\" ]; then", "  ln -sfn /home/devbox/.agents/skills /home/devbox/.gemini/skills", "  chown -h devbox:devbox /home/devbox/.gemini/skills", "fi", "");
-	lines.push("if [ $# -gt 0 ]; then", "  exec gosu devbox \"$@\"", "else", "  exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf", "fi");
-	return `${lines.join("\n")}\n`;
+	return `${[
+		"#!/usr/bin/env bash",
+		"",
+		...input.node.entrypointSetup,
+		...input.agent.entrypointSetup,
+		"if [ $# -gt 0 ]; then",
+		"  exec gosu devbox \"$@\"",
+		"else",
+		"  exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf",
+		"fi"
+	].join("\n")}\n`;
 }
 function renderSupervisorConfiguration() {
 	return `${[
@@ -1879,51 +2032,6 @@ function renderSupervisorConfiguration() {
 		"stderr_logfile=/dev/null"
 	].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} \\`,
-		"    && 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 -fsSLO --compressed \"https://nodejs.org/dist/v${NODE_RUNTIME_VERSION}/node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\" \\",
-		"    && curl -fsSLO --compressed \"https://nodejs.org/dist/v${NODE_RUNTIME_VERSION}/SHASUMS256.txt.asc\" \\",
-		"    && gpg --batch --no-options --decrypt --output SHASUMS256.txt SHASUMS256.txt.asc \\",
-		"    && gpgconf --kill all \\",
-		"    && rm -rf \"$GNUPGHOME\" \\",
-		"    && grep \" node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\\$\" SHASUMS256.txt | sha256sum -c - \\",
-		"    && tar -xJf \"node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\" -C \"$NODE_RUNTIME_ROOT\" --strip-components=1 --no-same-owner \\",
-		"    && rm \"node-v${NODE_RUNTIME_VERSION}-linux-${ARCH}.tar.xz\" SHASUMS256.txt.asc SHASUMS256.txt \\",
-		"    && 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 --allow-scripts=pnpm,yarn \\",
-		"    && \"$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",
@@ -2040,12 +2148,16 @@ function createCli(signal, interactive) {
 	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."]
+		["stop", "Stop the current Project Sandbox."]
 	]) cli.command(command, description).action(async () => {
 		const result = await runSandboxLifecycle(command, { signal });
 		return result.ok ? success({}) : result;
 	});
+	cli.command("sh", "Open a shell in the current Project Sandbox.").action(async () => {
+		const result = await runSandboxShell({ signal });
+		return result.ok ? success({}) : result;
+	});
+	cli.version(version);
 	cli.help();
 	return cli;
 }
@@ -2072,11 +2184,18 @@ async function main() {
 			return 130;
 		}
 		if (error instanceof HostCommandError) return error.exitCode;
+		if (isCacError(error)) {
+			process.stderr.write(`${error.message}\n`);
+			return 2;
+		}
 		throw error;
 	} finally {
 		process.off("SIGINT", interrupt);
 	}
 }
+function isCacError(error) {
+	return error instanceof Error && error.name === "CACError";
+}
 function interactiveFailure(observed, nextAction) {
 	return failure({
 		kind: "usage",

package/package.json

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