@ycs77/devbox 0.3.1 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @ycs77/devbox
 
-**A containerized devbox for AI agents.**
+**A opinionated devbox for AI agents.**
 
 [![NPM version][ico-version]][link-npm]
 [![Software License][ico-license]](LICENSE)
@@ -79,8 +79,7 @@ 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 current project's Node.js selection. |
-| `devbox config -g` | Change the globally configured Node.js versions or AI agents. |
+| `devbox config` | Change the globally configured or current project's Node.js selection. |
 
 ## Troubleshooting
 

package/dist/cli.mjs

@@ -45,9 +45,11 @@ const PACKAGED_AGENTS = {
 		},
 		installation: {
 			url: "https://claude.ai/install.sh",
-			shell: "bash"
+			shell: "bash",
+			preInstallCommands: ["echo '{}' > /home/devbox/.claude.json"]
 		},
 		supportsNotifications: true,
+		notificationInstallationCommands: ["claude plugin marketplace add ycs77/claude-code-notifications", "claude plugin install notification-basic-wsl@ycs77-notifications"],
 		supportsSkillInstallation: true
 	},
 	codex: {
@@ -60,7 +62,8 @@ const PACKAGED_AGENTS = {
 			shell: "sh"
 		},
 		supportsNotifications: true,
-		supportsSkillInstallation: true
+		supportsSkillInstallation: true,
+		notificationInstallationCommands: ["codex plugin marketplace add ycs77/codex-notifications", "codex plugin add notification-basic-wsl@ycs77-notifications"]
 	},
 	agy: {
 		home: {
@@ -84,7 +87,8 @@ const PACKAGED_AGENTS = {
 			shell: "sh"
 		},
 		supportsNotifications: true,
-		supportsSkillInstallation: false
+		supportsSkillInstallation: false,
+		notificationInstallationCommands: ["omp plugin marketplace add ycs77/omp-notifications", "omp plugin install notification-basic@ycs77-notifications"]
 	}
 };
 const PACKAGED_RUNTIME_CATALOG = {
@@ -205,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) {
@@ -245,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) {
@@ -267,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, {
@@ -303,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);
@@ -460,6 +507,7 @@ function selectComposeFragments({ selectedNode, configuredAgents, agentNotificat
 function renderProjectCompose(input) {
 	const fragments = selectComposeFragments(input);
 	const environment = {
+		TERM: "xterm-256color",
 		...fragments.node?.environment,
 		...fragments.notification?.environment
 	};
@@ -496,8 +544,10 @@ function renderProjectCompose(input) {
 		},
 		services: { devbox: {
 			image: WORKSPACE_IMAGE,
-			container_name: input.sandboxName,
+			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
 		} },
@@ -521,8 +571,9 @@ function validatesProjectCompose(source, input) {
 		const metadata = definition["x-devbox"];
 		if (metadata.version !== 1 || metadata.project_root !== input.projectRoot || metadata.compose_name !== input.sandboxName || metadata.sandbox_service !== "devbox") return false;
 		const service = definition.services.devbox;
-		if (service.image !== "devbox-workspace:latest" || service.container_name !== input.sandboxName || service.working_dir !== `/workspace/${input.sandboxName}` || "build" in service) return false;
-		return input.selectedNode === null && service.environment?.NODE_VERSION === void 0 || input.selectedNode !== null && service.environment?.NODE_VERSION === input.selectedNode;
+		if (service.image !== "devbox-workspace:latest" || service.container_name !== `devbox-${input.sandboxName}` || service.working_dir !== `/workspace/${input.sandboxName}` || "build" in service) return false;
+		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;
 	}
@@ -915,7 +966,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",
@@ -1324,7 +1375,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");
@@ -1515,22 +1567,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 runtime and published ports for this Project." : "Choose the replacement runtime for this Project.")}`, 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
 			};
 		}
 	};
@@ -1625,6 +1693,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]
@@ -1635,6 +1705,7 @@ async function buildWorkspaceUnlocked(input) {
 		nodeRuntimes,
 		buildNodeRuntime: buildNodeRuntimeRecipe(globalConfiguration),
 		agents,
+		agentNotifications: globalConfiguration.agent_notifications,
 		skillAgents: globalConfiguration.agent.filter((agent) => PACKAGED_AGENTS[agent]?.supportsSkillInstallation === true)
 	});
 	await mkdir(paths.buildContext, { recursive: true });
@@ -1652,7 +1723,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 });
@@ -1665,17 +1737,38 @@ 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",
 		"",
 		"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 \\",
@@ -1691,8 +1784,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",
 		""
@@ -1700,7 +1793,10 @@ function renderBuildDockerfile(input) {
 	for (const recipe of input.nodeRuntimes) lines.push(...renderNodeRuntimeStage(recipe));
 	lines.push("WORKDIR /workspace", "USER devbox", "");
 	if (input.buildNodeRuntime !== void 0) lines.push("# Configure pnpm for the non-root Sandbox user", "RUN mkdir -p /home/devbox/.config/pnpm /home/devbox/.pnpm-store \\", "    && printf 'storeDir: /home/devbox/.pnpm-store\\n' > /home/devbox/.config/pnpm/config.yaml \\", "    && chown devbox:devbox /home/devbox/.config/pnpm/config.yaml", "");
-	for (const agent of input.agents) lines.push(`# Install ${agent.name}`, `RUN mkdir -p ${agent.recipe.home.target} \\`, `    && curl -fsSL ${agent.recipe.installation.url} | ${agent.recipe.installation.shell}`, "");
+	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(" ");
@@ -1722,6 +1818,8 @@ function renderBuildDockerfile(input) {
 		}
 		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("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`;
 }
@@ -1756,12 +1854,8 @@ function selectBuildContextAssets(agents) {
 	return assets;
 }
 function renderEntrypoint(input) {
-	const lines = [
-		"#!/bin/sh",
-		"set -eu",
-		""
-	];
-	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", "", "  export NODE_RUNTIME_ROOT", "  export PATH=\"$NODE_RUNTIME_ROOT/bin:$PATH\"", "fi", "");
+	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`;
@@ -1823,7 +1917,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",
@@ -1834,6 +1928,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",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ycs77/devbox",
-  "version": "0.3.1",
-  "description": "A containerized devbox for AI agents",
+  "version": "0.5.0",
+  "description": "A Lucas Yang's opinionated devbox for AI agents",
   "keywords": [
     "agent",
     "agentic",
@@ -40,6 +40,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
+    "actionspack": "^0.1.5",
     "bumpp": "^12.2.0",
     "memfs": "^4.68.1",
     "oxfmt": "^0.63.0",
@@ -60,7 +61,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "check": "pnpm lint && pnpm fmt --check && pnpm typecheck && pnpm test --run",
-    "smoke:cli": "node scripts/package-devbox-smoke.mjs",
+    "smoke": "node scripts/package-devbox-smoke.mjs",
+    "update-actions": "actionspack update",
     "release": "bumpp --commit \"Release v%s\""
   }
 }