@pablozaiden/devbox 0.1.0 → 0.1.2

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.
@@ -54,15 +54,23 @@ devbox up 5001
 # Continue even if SSH agent sharing is unavailable
 devbox up 5001 --allow-missing-ssh
 
+# Use a specific devcontainer under .devcontainer/services/api
+devbox up 5001 --devcontainer-subpath services/api
+
 # Rebuild/recreate the managed devcontainer
 devbox rebuild 5001
 
+# 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.
 
+`devbox shell` requires an already running managed container for the current workspace. If none is running, use `devbox up` first.
+
 ## Development
 
 ```bash
@@ -88,6 +96,8 @@ cd examples/smoke-workspace
 ## 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.
 - When Docker Desktop host services are available, `devbox` can share the SSH agent without relying on a host-shell `SSH_AUTH_SOCK`.

package/dist/devbox.js

@@ -839,16 +839,19 @@ 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} [port] [--allow-missing-ssh] [--devcontainer-subpath <subpath>]
+  ${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
 
 Notes:
   - 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.
+  - Pass --devcontainer-subpath to use .devcontainer/<subpath>/devcontainer.json.
+  - ${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) {
@@ -858,7 +861,7 @@ function parseArgs(argv) {
   }
   let command = "up";
   const first = args[0];
-  if (first === "up" || first === "down" || first === "rebuild" || first === "help") {
+  if (first === "up" || first === "down" || first === "rebuild" || first === "shell" || first === "help") {
     command = first;
     args.shift();
   } else if (first === "--help" || first === "-h") {
@@ -866,6 +869,7 @@ function parseArgs(argv) {
   }
   let port;
   let allowMissingSsh = false;
+  let devcontainerSubpath;
   const positionals = [];
   for (let index = 0;index < args.length; index += 1) {
     const arg = args[index];
@@ -876,6 +880,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 +918,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 +1006,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) {
@@ -988,11 +1017,8 @@ function resolvePort(command, explicitPort, state) {
   }
   throw new UserError(`No port was provided and no previous port is stored for this workspace. Run \`${CLI_NAME} <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 +1040,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) {
@@ -1097,6 +1124,32 @@ async function getKnownHostsPath() {
 function quoteShell(value) {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
+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)];
 }
@@ -1247,6 +1300,15 @@ function requiresSshAuthSockPermissionFix(sshAuthSockSource) {
 function buildEnsureSshAuthSockAccessibleScript() {
   return `if [ -S ${quoteShell(SSH_AUTH_SOCK_TARGET)} ]; then chmod 666 ${quoteShell(SSH_AUTH_SOCK_TARGET)}; fi`;
 }
+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;
   return `${trimmed}/${RUNNER_HOST_KEYS_DIRNAME}`;
@@ -1453,6 +1515,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 +1637,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 "";
@@ -1659,17 +1773,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);
@@ -1743,7 +1861,24 @@ 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
+  });
+  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 +1890,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.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "CLI to run and expose a devcontainer with SSH agent sharing and a forwarded ssh-server-runner port.",
   "repository": {