@pablozaiden/devbox 0.1.2 → 0.1.4

package/README.md

@@ -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,20 +47,23 @@ 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 5001 --devcontainer-subpath 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
@@ -67,7 +72,7 @@ devbox shell
 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.
 
@@ -90,7 +95,7 @@ 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
@@ -99,7 +104,7 @@ cd examples/smoke-workspace
 - `--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,50 @@ function helpText() {
   return `${CLI_NAME} - manage a devcontainer plus ssh-server-runner
 
 Usage:
-  ${CLI_NAME} [port] [--allow-missing-ssh] [--devcontainer-subpath <subpath>]
+  ${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.
-  - Pass --devcontainer-subpath to use .devcontainer/<subpath>/devcontainer.json.
+  - 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 === "shell" || 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;
@@ -1015,7 +1032,7 @@ 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, devcontainerSubpath) {
   const candidates = getDevcontainerCandidates(workspacePath, devcontainerSubpath);
@@ -1083,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;
@@ -1124,6 +1142,12 @@ 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) {
@@ -1254,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() : "";
@@ -1278,12 +1305,22 @@ function formatDevcontainerProgressLine(line) {
       return null;
     }
     if (type === "raw" && text === "Container started") {
-      return "Container started.";
+      return "Container started. Finishing devcontainer setup...";
     }
     if (text.startsWith("workspace root: ")) {
       return `Workspace: ${text.slice("workspace root: ".length)}`;
     }
-    if (text === "No user features to update" || text === "Inspecting container" || text.startsWith("Run: ") || text.startsWith("Run in container: ") || text.startsWith("userEnvProbe") || text.startsWith("LifecycleCommandExecutionMap:") || text.startsWith("Exit code ")) {
+    if (text === "Inspecting container") {
+      return "Inspecting container...";
+    }
+    if (text.startsWith("userEnvProbe")) {
+      return "Checking container environment...";
+    }
+    const lifecycleProgress = formatDevcontainerLifecycleProgress(text);
+    if (lifecycleProgress) {
+      return lifecycleProgress;
+    }
+    if (text === "No user features to update" || text.startsWith("Run: ") || text.startsWith("Run in container: ") || text.startsWith("Exit code ")) {
       return null;
     }
     if (level !== undefined && level >= 2) {
@@ -1297,8 +1334,21 @@ 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 [
@@ -1480,12 +1530,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,
@@ -1664,6 +1723,7 @@ async function consumeStream(stream, mode, useStderr) {
   stream.setEncoding("utf8");
   let captured = "";
   let buffered = "";
+  let lastRenderedProgressLine = null;
   for await (const chunk of stream) {
     const text = typeof chunk === "string" ? chunk : String(chunk);
     captured += text;
@@ -1680,13 +1740,13 @@ async function consumeStream(stream, mode, useStderr) {
     while (newlineIndex >= 0) {
       const line = buffered.slice(0, newlineIndex);
       buffered = buffered.slice(newlineIndex + 1);
-      renderDevcontainerJsonLine(line, writer);
+      lastRenderedProgressLine = renderDevcontainerJsonLine(line, writer, lastRenderedProgressLine);
       newlineIndex = buffered.indexOf(`
 `);
     }
   }
   if (mode === "devcontainer-json" && buffered.length > 0) {
-    renderDevcontainerJsonLine(buffered, writer);
+    renderDevcontainerJsonLine(buffered, writer, lastRenderedProgressLine);
   }
   return captured;
 }
@@ -1722,12 +1782,14 @@ function isExecutablePath(candidate) {
     return false;
   }
 }
-function renderDevcontainerJsonLine(line, writer) {
+function renderDevcontainerJsonLine(line, writer, previousLine) {
   const formatted = formatDevcontainerProgressLine(line);
-  if (formatted) {
+  if (formatted && formatted !== previousLine) {
     writer.write(`${formatted}
 `);
+    return formatted;
   }
+  return previousLine;
 }
 function parseDevcontainerOutcome(stdout) {
   const lines = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
@@ -1757,6 +1819,23 @@ ${details}`;
 function stripAnsi(text) {
   return text.replace(/\u001B\[[0-9;]*m/g, "");
 }
+function formatDevcontainerLifecycleProgress(text) {
+  if (!text.startsWith("LifecycleCommandExecutionMap:")) {
+    return null;
+  }
+  const commandMatch = text.match(/\b(initializeCommand|onCreateCommand|updateContentCommand|postCreateCommand|postStartCommand|postAttachCommand)\b/);
+  if (commandMatch) {
+    return `Running ${commandMatch[1]}...`;
+  }
+  return "Running devcontainer lifecycle commands...";
+}
+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",
@@ -1837,7 +1916,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);
@@ -1875,6 +1957,7 @@ async function handleShell(workspacePath, state) {
     containers,
     preferredContainerId: state?.lastContainerId
   });
+  await assertConfiguredSshAuthSockAvailable(containerId);
   console.log(`Opening shell inside ${containerId.slice(0, 12)}...`);
   process.exitCode = await openInteractiveShell(containerId);
 }

package/package.json

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