@ycs77/devbox 0.4.0 → 0.5.1

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

@@ -209,7 +209,8 @@ function defaultGlobalConfiguration(catalog = PACKAGED_RUNTIME_CATALOG) {
 function defaultLocalConfiguration(globalConfiguration) {
 	return {
 		version: 1,
-		node: globalConfiguration.node[0] ?? null
+		node: globalConfiguration.node[0] ?? null,
+		ports: ["APP_PORT:5173:5173"]
 	};
 }
 function parseGlobalConfiguration(source, catalog = PACKAGED_RUNTIME_CATALOG) {
@@ -249,15 +250,22 @@ function parseLocalConfiguration(source, globalConfiguration, catalog = PACKAGED
 	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 (!isRecord(document) || !hasExactKeys$1(document, ["version", "node"]) && !hasExactKeys$1(document, [
+		"version",
+		"node",
+		"ports"
+	])) 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}.`);
+	const ports = document.ports === void 0 ? success([]) : normalizePortMappings(document.ports);
+	if (!ports.ok) return ports;
 	return success({
 		version: 1,
-		node
+		node,
+		ports: ports.value
 	});
 }
 function serializeGlobalConfiguration(configuration) {
@@ -271,12 +279,31 @@ function serializeGlobalConfiguration(configuration) {
 function serializeLocalConfiguration(configuration) {
 	return stringify({
 		version: 1,
-		node: configuration.node
+		node: configuration.node,
+		ports: [...configuration.ports]
 	});
 }
 function configurationsEqual(left, right) {
 	return JSON.stringify(left) === JSON.stringify(right);
 }
+function renderComposePortMapping(mapping) {
+	return parsePortMapping(mapping)?.compose ?? mapping;
+}
+function normalizePortMappings(values) {
+	if (!Array.isArray(values) || !values.every((value) => typeof value === "string")) return invalid$1("invalid-local-configuration", "Ports must be a list of port mappings.");
+	const mappings = [];
+	const hostPorts = /* @__PURE__ */ new Set();
+	for (const input of values) {
+		const mapping = input.trim();
+		if (mapping.length === 0) continue;
+		const parsed = parsePortMapping(mapping);
+		if (parsed === void 0) return invalid$1("invalid-local-configuration", `Port mapping is invalid: ${mapping}.`);
+		if (hostPorts.has(parsed.hostPort)) return invalid$1("invalid-local-configuration", `Host port is configured more than once: ${parsed.hostPort}.`);
+		hostPorts.add(parsed.hostPort);
+		mappings.push(mapping);
+	}
+	return success(mappings);
+}
 function parseYaml(source) {
 	try {
 		const document = parseDocument(source, {
@@ -307,6 +334,22 @@ function runtimeLineOrNull(value) {
 	if (value === null) return null;
 	return runtimeLine(value);
 }
+function parsePortMapping(mapping) {
+	const literal = /^(\d+):(\d+)$/.exec(mapping);
+	if (literal !== null) return validPort(literal[1]) && validPort(literal[2]) ? {
+		hostPort: String(Number(literal[1])),
+		compose: mapping
+	} : void 0;
+	const environment = /^([A-Za-z_][A-Za-z0-9_]*):(\d+):(\d+)$/.exec(mapping);
+	if (environment !== null) return validPort(environment[2]) && validPort(environment[3]) ? {
+		hostPort: String(Number(environment[2])),
+		compose: `\${${environment[1]}:-${environment[2]}}:${environment[3]}`
+	} : void 0;
+}
+function validPort(value) {
+	const port = Number(value);
+	return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
 function isRecord(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const prototype = Object.getPrototypeOf(value);
@@ -464,7 +507,6 @@ function selectComposeFragments({ selectedNode, configuredAgents, agentNotificat
 function renderProjectCompose(input) {
 	const fragments = selectComposeFragments(input);
 	const environment = {
-		TERM: "xterm-256color",
 		...fragments.node?.environment,
 		...fragments.notification?.environment
 	};
@@ -501,8 +543,10 @@ function renderProjectCompose(input) {
 		},
 		services: { devbox: {
 			image: WORKSPACE_IMAGE,
+			hostname: "devbox",
 			container_name: `devbox-${input.sandboxName}`,
 			working_dir: `/workspace/${input.sandboxName}`,
+			...input.ports.length === 0 ? {} : { ports: input.ports.map((port) => renderComposePortMapping(port)) },
 			...Object.keys(environment).length === 0 ? {} : { environment },
 			volumes
 		} },
@@ -527,7 +571,8 @@ function validatesProjectCompose(source, input) {
 		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 !== `devbox-${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;
+		const ports = input.ports.map((port) => renderComposePortMapping(port));
+		return JSON.stringify(service.ports ?? []) === JSON.stringify(ports) && (input.selectedNode === null && service.environment?.NODE_VERSION === void 0 || input.selectedNode !== null && service.environment?.NODE_VERSION === input.selectedNode);
 	} catch {
 		return false;
 	}
@@ -920,7 +965,7 @@ async function configureGlobalUnlocked(input = {}, locks) {
 	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 && input.prompt?.editLocal) replacement = await input.prompt.editLocal(localConfiguration, catalog, nextCheck.value, false);
 		if (replacement === void 0) return failure({
 			kind: "validation",
 			code: "node-replacement-required",
@@ -1145,9 +1190,12 @@ async function runSandboxLifecycle(command, input = {}) {
 		global: false,
 		projectRoots: [projectRoot],
 		signal: input.signal
-	}, () => runSandboxLifecycleUnlocked(command, input, projectRoot));
+	}, () => runSandboxCommandUnlocked(command, input, projectRoot));
+}
+async function runSandboxShell(input = {}) {
+	return runSandboxCommandUnlocked("sh", input, input.root ?? process.cwd());
 }
-async function runSandboxLifecycleUnlocked(command, input, projectRoot) {
+async function runSandboxCommandUnlocked(command, input, projectRoot) {
 	if (input.signal?.aborted) throw new InterruptedError();
 	const rootCheck = await validateProjectRoot(projectRoot);
 	if (!rootCheck.ok) return rootCheck;
@@ -1329,7 +1377,8 @@ async function composeStateWrite(input) {
 		selectedNode: input.localConfiguration.node,
 		configuredAgents: input.globalConfiguration.agent,
 		agentNotifications: input.globalConfiguration.agent_notifications,
-		claudeHostConfiguration: claudeHostConfiguration.value
+		claudeHostConfiguration: claudeHostConfiguration.value,
+		ports: input.localConfiguration.ports
 	});
 	if (!rendered.ok) return rendered;
 	const path = join(input.stateDirectory, "compose.yaml");
@@ -1485,18 +1534,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({
@@ -1520,22 +1571,38 @@ function createConfigurationPrompter({ signal, input, output }) {
 				}))
 			};
 		},
-		editLocal: async (configuration, catalog, globalConfiguration) => {
-			p.log.step(`${c.bold(c.cyan("Project configuration"))}\n${c.dim("Choose the runtime for this Project.")}`, common);
+		editLocal: async (configuration, catalog, globalConfiguration, editPorts = true) => {
+			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: [{
+					value: null,
+					label: "None"
+				}, ...(globalConfiguration.node ?? []).map((value) => ({
+					value,
+					label: value
+				}))],
+				initialValue: configuration.node,
+				...common
+			}));
+			if (!editPorts) return {
+				...configuration,
+				node
+			};
+			const ports = normalizePortMappings((await promptValue(p.multiline({
+				message: "Published ports",
+				initialValue: configuration.ports.join("\n"),
+				validate: (value) => {
+					const ports = normalizePortMappings((value ?? "").split("\n"));
+					return ports.ok ? void 0 : ports.error.observed;
+				},
+				...common
+			}))).split("\n"));
+			if (!ports.ok) throw new Error(ports.error.observed);
 			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
-				}))
+				node,
+				ports: ports.value
 			};
 		}
 	};
@@ -1630,6 +1697,8 @@ async function buildWorkspaceUnlocked(input) {
 	const parsedGlobal = parseGlobalConfiguration(globalSource, catalogCheck.value);
 	if (!parsedGlobal.ok) return parsedGlobal;
 	const globalConfiguration = parsedGlobal.value;
+	const hostIdentity = currentHostIdentity();
+	if (!hostIdentity.ok) return hostIdentity;
 	const agents = globalConfiguration.agent.map((name) => ({
 		name,
 		recipe: PACKAGED_AGENTS[name]
@@ -1658,7 +1727,8 @@ async function buildWorkspaceUnlocked(input) {
 	const buildResult = await (input.executeDockerBuild ?? runDockerBuild)({
 		context: paths.buildContext,
 		image: WORKSPACE_IMAGE,
-		noCache: input.noCache === true
+		noCache: input.noCache === true,
+		buildArgs: hostIdentity.value
 	});
 	if (!buildResult.ok) return buildResult;
 	return success({ image: WORKSPACE_IMAGE });
@@ -1671,17 +1741,41 @@ function buildNodeRuntimeRecipe(globalConfiguration) {
 	}
 	return buildNodeRuntime;
 }
+function currentHostIdentity() {
+	const userId = typeof process.getuid === "function" ? process.getuid() : void 0;
+	const groupId = typeof process.getgid === "function" ? process.getgid() : void 0;
+	if (typeof userId !== "number" || typeof groupId !== "number" || !Number.isSafeInteger(userId) || !Number.isSafeInteger(groupId) || userId <= 0 || groupId <= 0) return failure({
+		kind: "validation",
+		code: "invalid-host-identity",
+		observed: "The invoking host process must have a non-root POSIX numeric UID and GID.",
+		nextAction: "Run devbox build as the intended non-root host user."
+	});
+	return success({
+		USER_ID: String(userId),
+		GROUP_ID: String(groupId)
+	});
+}
 function renderBuildDockerfile(input) {
 	const lines = [
 		"# Generated by devbox build. Machine-owned Workspace build context.",
 		"FROM ubuntu:24.04",
 		"",
+		"ARG USER_ID",
+		"ARG GROUP_ID",
+		"",
 		"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",
 		"",
+		"RUN echo \"Acquire::http::Pipeline-Depth 0;\" > /etc/apt/apt.conf.d/99custom && \\",
+		"    echo \"Acquire::http::No-Cache true;\" >> /etc/apt/apt.conf.d/99custom && \\",
+		"    echo \"Acquire::BrokenProxy    true;\" >> /etc/apt/apt.conf.d/99custom",
+		"",
 		"# Install the Base profile packages and build tools",
 		"RUN set -eux \\",
 		"    && apt-get update && apt-get upgrade -y \\",
@@ -1697,8 +1791,8 @@ function renderBuildDockerfile(input) {
 		"",
 		"# 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 \\",
+		"    && groupadd -g \"$GROUP_ID\" devbox \\",
+		"    && useradd -m -s /bin/bash -N -g \"$GROUP_ID\" -u \"$USER_ID\" devbox \\",
 		"    && echo \"devbox ALL=(ALL) NOPASSWD:ALL\" > /etc/sudoers.d/devbox \\",
 		"    && chmod 0440 /etc/sudoers.d/devbox",
 		""
@@ -1767,11 +1861,7 @@ function selectBuildContextAssets(agents) {
 	return assets;
 }
 function renderEntrypoint(input) {
-	const lines = [
-		"#!/bin/sh",
-		"set -eu",
-		""
-	];
+	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");
@@ -1834,7 +1924,7 @@ function renderNodeRuntimeStage(recipe) {
 		"    && export PATH=\"$NODE_RUNTIME_ROOT/bin:$PATH\" \\",
 		"    && npm install -g npm \\",
 		"    && npm uninstall -g corepack \\",
-		"    && npm install -g yarn pnpm @antfu/ni \\",
+		"    && 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",
@@ -1845,6 +1935,10 @@ async function runDockerBuild(invocation, signal) {
 	const build = spawn("docker", [
 		"build",
 		...invocation.noCache ? ["--no-cache"] : [],
+		"--build-arg",
+		`USER_ID=${invocation.buildArgs.USER_ID}`,
+		"--build-arg",
+		`GROUP_ID=${invocation.buildArgs.GROUP_ID}`,
 		"--tag",
 		invocation.image,
 		"--file",
@@ -1953,12 +2047,15 @@ 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.help();
 	return cli;
 }
@@ -1985,11 +2082,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.4.0",
+  "version": "0.5.1",
   "description": "A Lucas Yang's opinionated devbox for AI agents",
   "keywords": [
     "agent",