@pablozaiden/devbox 0.1.1 → 0.1.3

package/README.md

@@ -6,7 +6,7 @@ It does not modify the original `devcontainer.json`. Instead, it generates a der
 
 ## What it does
 
-- Discovers `.devcontainer/devcontainer.json` or `.devcontainer.json` in the current directory.
+- Discovers `.devcontainer/devcontainer.json` or `.devcontainer.json` in the current directory, and can target `.devcontainer/<subpath>/devcontainer.json` with a flag.
 - Reuses or creates the devcontainer with Docker + Dev Container CLI.
 - Names the managed container as `devbox-<project>-<port>`.
 - Publishes the same TCP port on host and container.
@@ -31,6 +31,8 @@ npm install -g @pablozaiden/devbox
 
 After either install, `devbox` is available in any directory.
 
+Run `devbox` with no arguments to see the CLI help.
+
 ## Requirements
 
 - macOS or Linux
@@ -45,23 +47,34 @@ After either install, `devbox` is available in any directory.
 ## Commands
 
 ```bash
-# Start or reuse the devcontainer on port 5001
-devbox 5001
+# Show CLI help
+devbox
 
-# Same as above
-devbox up 5001
+# Start or reuse the devcontainer on a chosen port
+devbox up <port>
 
 # Continue even if SSH agent sharing is unavailable
-devbox up 5001 --allow-missing-ssh
+devbox up <port> --allow-missing-ssh
+
+# Use a specific devcontainer under .devcontainer/services/api
+devbox up <port> --devcontainer-subpath services/api
 
 # Rebuild/recreate the managed devcontainer
-devbox rebuild 5001
+devbox rebuild <port>
+
+# Reuse the last stored port for this workspace
+devbox up
+
+# Open an interactive shell in the running managed devcontainer for this workspace
+devbox shell
 
 # Stop and remove the managed container while preserving the workspace-mounted SSH credentials
 devbox down
 ```
 
-If you omit the port for `up` or `rebuild`, `devbox` will reuse the last port stored for the current workspace.
+There is no default port. If you omit the port for `up` or `rebuild`, `devbox` will reuse the last port stored for the current workspace; otherwise pass a port explicitly.
+
+`devbox shell` requires an already running managed container for the current workspace. If none is running, use `devbox up` first.
 
 ## Development
 
@@ -82,14 +95,16 @@ For a quick smoke test, this repository includes `examples/smoke-workspace/.devc
 
 ```bash
 cd examples/smoke-workspace
-../../dist/devbox.js up 5001 --allow-missing-ssh
+../../dist/devbox.js up <port> --allow-missing-ssh
 ```
 
 ## Notes
 
 - The generated config is written next to the original devcontainer config, using the alternate accepted devcontainer filename so relative Dockerfile paths keep working.
+- `--devcontainer-subpath services/api` tells `devbox` to use `.devcontainer/services/api/devcontainer.json`.
+- `devbox shell` opens an interactive shell inside the running managed container for the current workspace.
 - `down` removes managed containers but does not delete the workspace `.sshcred` or `.devbox-ssh-host-keys/`, so the SSH password and SSH host identity survive rebuilds.
-- Re-running `devbox` after a host restart recreates the desired state: container up, port published, SSH runner started again.
+- Re-running `devbox up` after a host restart recreates the desired state: container up, port published, SSH runner started again.
 - When Docker Desktop host services are available, `devbox` can share the SSH agent without relying on a host-shell `SSH_AUTH_SOCK`.
 - On Docker Desktop, `devbox` prefers the Docker-provided SSH agent socket over the host `SSH_AUTH_SOCK`, which avoids macOS launchd socket mount issues.
 - `--allow-missing-ssh` starts the workspace without mounting an SSH agent and prints a warning instead of failing.

package/dist/devbox.js

@@ -839,33 +839,54 @@ function helpText() {
   return `${CLI_NAME} - manage a devcontainer plus ssh-server-runner
 
 Usage:
-  ${CLI_NAME} [port] [--allow-missing-ssh]
-  ${CLI_NAME} up [port] [--allow-missing-ssh]
-  ${CLI_NAME} rebuild [port] [--allow-missing-ssh]
-  ${CLI_NAME} down
+  ${CLI_NAME}
+  ${CLI_NAME} up [port] [--allow-missing-ssh] [--devcontainer-subpath <subpath>]
+  ${CLI_NAME} rebuild [port] [--allow-missing-ssh] [--devcontainer-subpath <subpath>]
+  ${CLI_NAME} shell
+  ${CLI_NAME} down [--devcontainer-subpath <subpath>]
+  ${CLI_NAME} help
   ${CLI_NAME} --help
 
+Commands:
+  up       Start or reuse the managed devcontainer.
+  rebuild  Recreate the managed devcontainer.
+  shell    Open an interactive shell in the running managed container.
+  down     Stop and remove the managed container for this workspace.
+  help     Show this help.
+
+Options:
+  -p, --port <port>             Publish the same port on host and container.
+  --allow-missing-ssh           Continue without SSH agent sharing when unavailable.
+  --devcontainer-subpath <path> Use .devcontainer/<path>/devcontainer.json.
+  -h, --help                    Show this help.
+
 Notes:
+  - Running ${CLI_NAME} with no arguments shows this help.
   - The same port is published on host and container.
-  - If no port is provided for up/rebuild, the last stored port for this workspace is reused.
-  - Pass --allow-missing-ssh to continue without SSH agent sharing when no usable SSH agent socket is available.
+  - There is no default port. Pass one explicitly the first time, or reuse the last stored port with \`${CLI_NAME} up\` / \`${CLI_NAME} rebuild\`.
+  - ${CLI_NAME} shell opens an interactive shell in the running managed container for this workspace.
   - Only image/Dockerfile-based devcontainers are supported in v1.`;
 }
 function parseArgs(argv) {
   const args = [...argv];
   if (args.length === 0) {
-    return { command: "up", allowMissingSsh: false };
+    return { command: "help", allowMissingSsh: false };
   }
-  let command = "up";
+  let command;
   const first = args[0];
-  if (first === "up" || first === "down" || first === "rebuild" || first === "help") {
+  if (first === "up" || first === "down" || first === "rebuild" || first === "shell") {
     command = first;
     args.shift();
+  } else if (first === "help") {
+    return { command: "help", allowMissingSsh: false };
   } else if (first === "--help" || first === "-h") {
     return { command: "help", allowMissingSsh: false };
+  } else {
+    throw new UserError(`A command is required. Run \`${CLI_NAME} --help\` for usage.`);
   }
   let port;
   let allowMissingSsh = false;
+  let devcontainerSubpath;
   const positionals = [];
   for (let index = 0;index < args.length; index += 1) {
     const arg = args[index];
@@ -876,6 +897,19 @@ function parseArgs(argv) {
       allowMissingSsh = true;
       continue;
     }
+    if (arg === "--devcontainer-subpath") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new UserError("Expected a value after --devcontainer-subpath.");
+      }
+      devcontainerSubpath = parseDevcontainerSubpath(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--devcontainer-subpath=")) {
+      devcontainerSubpath = parseDevcontainerSubpath(arg.slice("--devcontainer-subpath=".length));
+      continue;
+    }
     if (arg === "--port" || arg === "-p") {
       const value = args[index + 1];
       if (!value) {
@@ -901,11 +935,23 @@ function parseArgs(argv) {
     if (command === "down") {
       throw new UserError("The down command does not accept a port.");
     }
+    if (command === "shell") {
+      throw new UserError("The shell command does not accept a port.");
+    }
     port = parsePort(positionals[0]);
   }
   if (command === "down" && port !== undefined) {
     throw new UserError("The down command does not accept a port.");
   }
+  if (command === "shell" && port !== undefined) {
+    throw new UserError("The shell command does not accept a port.");
+  }
+  if (command === "shell" && devcontainerSubpath !== undefined) {
+    throw new UserError("The shell command does not accept --devcontainer-subpath.");
+  }
+  if (devcontainerSubpath) {
+    return { command, port, allowMissingSsh, devcontainerSubpath };
+  }
   return { command, port, allowMissingSsh };
 }
 function parsePort(raw) {
@@ -977,7 +1023,7 @@ async function deleteWorkspaceState(workspacePath) {
   await rm(getWorkspaceStateDir(workspacePath), { recursive: true, force: true });
 }
 function resolvePort(command, explicitPort, state) {
-  if (command === "down" || command === "help") {
+  if (command === "down" || command === "shell" || command === "help") {
     throw new UserError(`resolvePort cannot be used for ${command}.`);
   }
   if (explicitPort !== undefined) {
@@ -986,13 +1032,10 @@ function resolvePort(command, explicitPort, state) {
   if (state) {
     return state.port;
   }
-  throw new UserError(`No port was provided and no previous port is stored for this workspace. Run \`${CLI_NAME} <port>\` first.`);
+  throw new UserError(`No port was provided and no previous port is stored for this workspace. Run \`${CLI_NAME} up <port>\` first.`);
 }
-async function discoverDevcontainerConfig(workspacePath) {
-  const candidates = [
-    path.join(workspacePath, ".devcontainer", "devcontainer.json"),
-    path.join(workspacePath, ".devcontainer.json")
-  ];
+async function discoverDevcontainerConfig(workspacePath, devcontainerSubpath) {
+  const candidates = getDevcontainerCandidates(workspacePath, devcontainerSubpath);
   for (const candidate of candidates) {
     if (!existsSync(candidate)) {
       continue;
@@ -1014,7 +1057,8 @@ async function discoverDevcontainerConfig(workspacePath) {
     validateSupportedDevcontainerConfig(config);
     return { path: candidate, config };
   }
-  throw new UserError(`No devcontainer definition was found in ${workspacePath}. Expected .devcontainer/devcontainer.json or .devcontainer.json.`);
+  const expectedLocations = devcontainerSubpath ? `.devcontainer/${formatDevcontainerSubpath(devcontainerSubpath)}/devcontainer.json` : ".devcontainer/devcontainer.json or .devcontainer.json";
+  throw new UserError(`No devcontainer definition was found in ${workspacePath}. Expected ${expectedLocations}.`);
 }
 function validateSupportedDevcontainerConfig(config) {
   if (config.dockerComposeFile !== undefined) {
@@ -1056,17 +1100,18 @@ function buildManagedConfig(baseConfig, options) {
     runArgs.push("-p", `${options.port}:${options.port}`);
   }
   managedConfig.runArgs = runArgs;
+  const containerSshAuthSock = getContainerSshAuthSockPath(options.sshAuthSock);
   const mounts = getStringArray(managedConfig.mounts, "mounts");
-  if (options.sshAuthSock) {
-    mounts.push(`type=bind,source=${options.sshAuthSock},target=${SSH_AUTH_SOCK_TARGET}`);
+  if (options.sshAuthSock && containerSshAuthSock) {
+    mounts.push(`type=bind,source=${options.sshAuthSock},target=${containerSshAuthSock}`);
   }
   if (options.knownHostsPath) {
     mounts.push(`type=bind,source=${options.knownHostsPath},target=${KNOWN_HOSTS_TARGET},readonly`);
   }
   managedConfig.mounts = dedupe(mounts);
   const containerEnv = getStringRecord(managedConfig.containerEnv, "containerEnv");
-  if (options.sshAuthSock) {
-    containerEnv.SSH_AUTH_SOCK = SSH_AUTH_SOCK_TARGET;
+  if (containerSshAuthSock) {
+    containerEnv.SSH_AUTH_SOCK = containerSshAuthSock;
   }
   managedConfig.containerEnv = containerEnv;
   return managedConfig;
@@ -1097,6 +1142,38 @@ async function getKnownHostsPath() {
 function quoteShell(value) {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
+function getContainerSshAuthSockPath(sshAuthSock) {
+  if (!sshAuthSock) {
+    return null;
+  }
+  return sshAuthSock === DOCKER_DESKTOP_SSH_AUTH_SOCK_SOURCE ? DOCKER_DESKTOP_SSH_AUTH_SOCK_SOURCE : SSH_AUTH_SOCK_TARGET;
+}
+function parseDevcontainerSubpath(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new UserError("Devcontainer subpath cannot be empty.");
+  }
+  if (path.isAbsolute(trimmed) || trimmed.startsWith("\\")) {
+    throw new UserError(`Devcontainer subpath must stay inside .devcontainer. Received: ${raw}`);
+  }
+  const segments = trimmed.split(/[\\/]+/u).filter((segment) => segment.length > 0);
+  if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+    throw new UserError(`Devcontainer subpath must stay inside .devcontainer. Received: ${raw}`);
+  }
+  return path.join(...segments);
+}
+function getDevcontainerCandidates(workspacePath, devcontainerSubpath) {
+  if (devcontainerSubpath) {
+    return [path.join(workspacePath, ".devcontainer", devcontainerSubpath, "devcontainer.json")];
+  }
+  return [
+    path.join(workspacePath, ".devcontainer", "devcontainer.json"),
+    path.join(workspacePath, ".devcontainer.json")
+  ];
+}
+function formatDevcontainerSubpath(subpath) {
+  return subpath.split(path.sep).join("/");
+}
 function dedupe(values) {
   return [...new Set(values)];
 }
@@ -1201,6 +1278,9 @@ function formatDevcontainerProgressLine(line) {
   if (!cleaned) {
     return null;
   }
+  if (looksLikeDevcontainerUserEnvProbeDump(cleaned) || cleaned.startsWith("bash: cannot set terminal process group") || cleaned === "bash: no job control in this shell") {
+    return null;
+  }
   try {
     const parsed = JSON.parse(cleaned);
     const text = typeof parsed.text === "string" ? stripAnsi(parsed.text).trim() : "";
@@ -1244,8 +1324,30 @@ function formatDevcontainerProgressLine(line) {
 function requiresSshAuthSockPermissionFix(sshAuthSockSource) {
   return sshAuthSockSource === DOCKER_DESKTOP_SSH_AUTH_SOCK_SOURCE;
 }
-function buildEnsureSshAuthSockAccessibleScript() {
-  return `if [ -S ${quoteShell(SSH_AUTH_SOCK_TARGET)} ]; then chmod 666 ${quoteShell(SSH_AUTH_SOCK_TARGET)}; fi`;
+function buildEnsureSshAuthSockAccessibleScript(containerSshAuthSock) {
+  return `if [ -S ${quoteShell(containerSshAuthSock)} ]; then chmod 666 ${quoteShell(containerSshAuthSock)}; fi`;
+}
+function buildAssertConfiguredSshAuthSockScript() {
+  return [
+    'if [ -z "${SSH_AUTH_SOCK:-}" ]; then',
+    "  exit 0",
+    "fi",
+    'if [ -S "$SSH_AUTH_SOCK" ]; then',
+    "  exit 0",
+    "fi",
+    `printf '%s\\n' "SSH_AUTH_SOCK points to a missing socket inside the container: $SSH_AUTH_SOCK. Run devbox rebuild to refresh SSH agent sharing." >&2`,
+    "exit 1"
+  ].join(`
+`);
+}
+function buildInteractiveShellScript() {
+  return [
+    "if command -v bash >/dev/null 2>&1; then",
+    "  exec bash -l",
+    "fi",
+    "exec sh"
+  ].join(`
+`);
 }
 function getRunnerHostKeysDir(remoteWorkspaceFolder) {
   const trimmed = remoteWorkspaceFolder.endsWith("/") ? remoteWorkspaceFolder.slice(0, -1) : remoteWorkspaceFolder;
@@ -1418,12 +1520,21 @@ async function copyKnownHosts(containerId) {
 async function stopManagedSshd(containerId) {
   await devcontainerExec(containerId, buildStopManagedSshdScript(), { quiet: true });
 }
-async function ensureSshAuthSockAccessible(containerId) {
-  await dockerExec(containerId, buildEnsureSshAuthSockAccessibleScript(), {
+async function ensureSshAuthSockAccessible(containerId, sshAuthSockSource) {
+  const containerSshAuthSock = getContainerSshAuthSockPath(sshAuthSockSource);
+  if (!containerSshAuthSock) {
+    throw new UserError("Cannot adjust SSH agent socket permissions when SSH sharing is disabled.");
+  }
+  await dockerExec(containerId, buildEnsureSshAuthSockAccessibleScript(containerSshAuthSock), {
     quiet: true,
     user: "root"
   });
 }
+async function assertConfiguredSshAuthSockAvailable(containerId) {
+  await dockerExec(containerId, buildAssertConfiguredSshAuthSockScript(), {
+    quiet: true
+  });
+}
 async function restoreRunnerHostKeys(containerId, remoteWorkspaceFolder) {
   await dockerExec(containerId, buildRestoreRunnerHostKeysScript(remoteWorkspaceFolder), {
     quiet: true,
@@ -1453,6 +1564,39 @@ async function persistRunnerHostKeys(containerId, remoteWorkspaceFolder) {
     user: "root"
   });
 }
+function resolveShellContainerId(input) {
+  const running = input.containers.filter((container) => container.State?.Running);
+  if (input.preferredContainerId) {
+    const preferred = running.find((container) => container.Id === input.preferredContainerId);
+    if (preferred) {
+      return preferred.Id;
+    }
+  }
+  if (running.length === 1) {
+    return running[0].Id;
+  }
+  if (running.length === 0) {
+    throw new UserError("No running managed container was found for this workspace. Run `devbox up` first.");
+  }
+  throw new UserError("More than one managed container is running for this workspace. Run `devbox down` first.");
+}
+function buildDevcontainerShellCommand(containerId, terminalSize) {
+  const args = ["devcontainer", "exec", "--container-id", containerId];
+  if (terminalSize?.columns && terminalSize.columns > 0) {
+    args.push("--terminal-columns", String(terminalSize.columns));
+  }
+  if (terminalSize?.rows && terminalSize.rows > 0) {
+    args.push("--terminal-rows", String(terminalSize.rows));
+  }
+  args.push("sh", "-lc", buildInteractiveShellScript());
+  return args;
+}
+async function openInteractiveShell(containerId) {
+  return executeInteractive(buildDevcontainerShellCommand(containerId, {
+    columns: process.stdout.isTTY ? process.stdout.columns : undefined,
+    rows: process.stdout.isTTY ? process.stdout.rows : undefined
+  }));
+}
 async function hasDockerDesktopHostService() {
   const result = await execute(["docker", "info", "--format", "{{.OperatingSystem}}"], {
     stdoutMode: "capture",
@@ -1542,6 +1686,25 @@ async function execute(command, options) {
   }
   return result;
 }
+async function executeInteractive(command, options) {
+  const env = { ...process.env, ...options?.env ?? {} };
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) {
+      delete env[key];
+    }
+  }
+  const subprocess = spawn(command[0], command.slice(1), {
+    cwd: options?.cwd,
+    env,
+    stdio: "inherit"
+  });
+  return new Promise((resolve, reject) => {
+    subprocess.once("error", reject);
+    subprocess.once("close", (exitCode) => {
+      resolve(exitCode ?? 0);
+    });
+  });
+}
 async function consumeStream(stream, mode, useStderr) {
   if (!stream) {
     return "";
@@ -1643,6 +1806,13 @@ ${details}`;
 function stripAnsi(text) {
   return text.replace(/\u001B\[[0-9;]*m/g, "");
 }
+function looksLikeDevcontainerUserEnvProbeDump(text) {
+  const match = text.match(/^([0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12})([\s\S]*)\1$/i);
+  if (!match) {
+    return false;
+  }
+  return /\b(?:HOME|HOSTNAME|PATH|PWD|SHLVL|SSH_AUTH_SOCK|USER)=/.test(match[2]);
+}
 function labelsForWorkspaceHash(workspaceHash) {
   return {
     [MANAGED_LABEL_KEY]: "true",
@@ -1659,17 +1829,21 @@ async function main() {
   }
   const workspacePath = await realpath(process.cwd());
   const state = await loadWorkspaceState(workspacePath);
+  if (parsed.command === "shell") {
+    await handleShell(workspacePath, state);
+    return;
+  }
   if (parsed.command === "down") {
-    await handleDown(workspacePath, state);
+    await handleDown(workspacePath, state, parsed.devcontainerSubpath);
     return;
   }
-  await handleUpLike(parsed.command, workspacePath, state, parsed.port, parsed.allowMissingSsh);
+  await handleUpLike(parsed.command, workspacePath, state, parsed.port, parsed.allowMissingSsh, parsed.devcontainerSubpath);
 }
-async function handleUpLike(command, workspacePath, state, explicitPort, allowMissingSsh) {
+async function handleUpLike(command, workspacePath, state, explicitPort, allowMissingSsh, devcontainerSubpath) {
   const environment = await ensureHostEnvironment({ allowMissingSsh });
   const port = resolvePort(command, explicitPort, state);
   const knownHostsPath = await getKnownHostsPath();
-  const discovered = await discoverDevcontainerConfig(workspacePath);
+  const discovered = await discoverDevcontainerConfig(workspacePath, devcontainerSubpath);
   const generatedConfigPath = getGeneratedConfigPath(discovered.path);
   const legacyGeneratedConfigPath = getLegacyGeneratedConfigPath(discovered.path);
   const workspaceHash = hashWorkspacePath(workspacePath);
@@ -1719,7 +1893,10 @@ async function handleUpLike(command, workspacePath, state, explicitPort, allowMi
   await ensurePathIgnored(workspacePath, path3.join(workspacePath, RUNNER_HOST_KEYS_DIRNAME));
   if (requiresSshAuthSockPermissionFix(environment.sshAuthSock)) {
     console.log("Making the forwarded SSH agent socket accessible to the container user...");
-    await ensureSshAuthSockAccessible(upResult.containerId);
+    await ensureSshAuthSockAccessible(upResult.containerId, environment.sshAuthSock);
+  }
+  if (environment.sshAuthSock) {
+    await assertConfiguredSshAuthSockAvailable(upResult.containerId);
   }
   await copyKnownHosts(upResult.containerId);
   await stopManagedSshd(upResult.containerId);
@@ -1743,7 +1920,25 @@ Ready. ${upResult.containerId.slice(0, 12)} is available on port ${port}.`);
     console.log("Host known_hosts was not found, so only SSH agent sharing was configured.");
   }
 }
-async function handleDown(workspacePath, state) {
+async function handleShell(workspacePath, state) {
+  if (!isExecutableAvailable("docker")) {
+    throw new UserError("Docker is required but was not found in PATH.");
+  }
+  if (!isExecutableAvailable("devcontainer")) {
+    throw new UserError("Dev Container CLI is required but was not found in PATH.");
+  }
+  const labels = labelsForWorkspaceHash(hashWorkspacePath(workspacePath));
+  const containerIds = await listManagedContainers(labels);
+  const containers = await inspectContainers(containerIds);
+  const containerId = resolveShellContainerId({
+    containers,
+    preferredContainerId: state?.lastContainerId
+  });
+  await assertConfiguredSshAuthSockAvailable(containerId);
+  console.log(`Opening shell inside ${containerId.slice(0, 12)}...`);
+  process.exitCode = await openInteractiveShell(containerId);
+}
+async function handleDown(workspacePath, state, devcontainerSubpath) {
   if (!isExecutableAvailable("docker")) {
     throw new UserError("Docker is required but was not found in PATH.");
   }
@@ -1755,7 +1950,7 @@ async function handleDown(workspacePath, state) {
     generatedConfigPaths.add(state.generatedConfigPath);
   }
   try {
-    const discovered = await discoverDevcontainerConfig(workspacePath);
+    const discovered = await discoverDevcontainerConfig(workspacePath, devcontainerSubpath);
     generatedConfigPaths.add(getGeneratedConfigPath(discovered.path));
     generatedConfigPaths.add(getLegacyGeneratedConfigPath(discovered.path));
   } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/devbox",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "CLI to run and expose a devcontainer with SSH agent sharing and a forwarded ssh-server-runner port.",
   "repository": {