start-command 0.20.4 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # start-command
 
+## 0.22.0
+
+### Minor Changes
+
+- 694d85e: feat: Add shell auto-detection and --shell option for isolation environments
+
+  In docker/ssh and other applicable isolation environments, the shell is now
+  automatically detected in order of preference: `bash` → `zsh` → `sh`.
+
+  Previously, `/bin/sh` was hardcoded in Docker and SSH isolation, which prevented
+  access to tools like `nvm` that require bash. Now, the most feature-complete
+  available shell is used automatically.
+
+  Key features:
+  - Auto-detect best available shell in Docker containers and SSH hosts (`bash > zsh > sh`)
+  - New `--shell` option to force a specific shell (`auto`, `bash`, `zsh`, `sh`)
+  - Default mode is `auto` — no need to specify `--shell` for automatic detection
+  - `--shell` is passed through in isolation stacking
+
+  Example usage:
+
+  ```bash
+  # Auto-detect best shell (default behavior, no option needed)
+  $ --isolated docker --image node:20 -- nvm use 20
+
+  # Force bash explicitly
+  $ --isolated docker --image ubuntu:22.04 --shell bash -- echo $BASH_VERSION
+
+  # Use sh specifically
+  $ --isolated ssh --endpoint user@host --shell sh -- echo hello
+  ```
+
+## 0.21.0
+
+### Minor Changes
+
+- bd8fc93: feat: Add isolation stacking support
+
+  Added support for stacking multiple isolation environments in sequence,
+  allowing complex isolation chains like:
+
+  ```bash
+  $ echo hi --isolated "screen ssh tmux docker"
+  ```
+
+  Key features:
+  - Space-separated sequences for `--isolated`, `--image`, and `--endpoint` options
+  - Underscore (`_`) placeholder for "default/skip" values in option sequences
+  - Recursive execution where each level invokes `$` with remaining levels
+  - Maximum isolation depth of 7 levels (prevents infinite recursion)
+
+  Example usage:
+
+  ```bash
+  # SSH to remote host, then run in Docker
+  $ cmd --isolated "ssh docker" --endpoint "user@host _" --image "_ node:20"
+
+  # Create screen session, SSH to host, start tmux, run in Docker
+  $ cmd --isolated "screen ssh tmux docker" --endpoint "_ user@host _ _" --image "_ _ _ node:20"
+  ```
+
+  Backward compatible: All existing single-level isolation commands work unchanged.
+
+  Fixes #77
+
 ## 0.20.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.20.4",
+  "version": "0.22.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/lib/args-parser.js

@@ -16,6 +16,7 @@
  * --keep-user                      Keep isolated user after command completes (don't delete)
  * --keep-alive, -k                 Keep isolation environment alive after command exits
  * --auto-remove-docker-container   Automatically remove docker container after exit (disabled by default)
+ * --shell <shell>                  Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --status <uuid>                  Show status of a previous command execution by UUID
  * --output-format <format>         Output format for status (links-notation, json, text)
@@ -24,6 +25,7 @@
  */
 
 const { getDefaultDockerImage } = require('./docker-utils');
+const { parseSequence, isSequence } = require('./sequence-parser');
 
 // Debug mode from environment
 const DEBUG =
@@ -34,6 +36,16 @@ const DEBUG =
  */
 const VALID_BACKENDS = ['screen', 'tmux', 'docker', 'ssh'];
 
+/**
+ * Valid shell options for --shell
+ */
+const VALID_SHELLS = ['auto', 'bash', 'zsh', 'sh'];
+
+/**
+ * Maximum depth for isolation stacking
+ */
+const MAX_ISOLATION_DEPTH = 7;
+
 /**
  * Valid output formats for --status
  */
@@ -73,6 +85,63 @@ function generateUUID() {
   }
 }
 
+/**
+ * Parse --isolated value, handling both single values and sequences
+ * @param {string} value - Isolation value (e.g., "docker" or "screen ssh docker")
+ * @param {object} options - Options object to populate
+ */
+function parseIsolatedValue(value, options) {
+  if (isSequence(value)) {
+    // Multi-value sequence (e.g., "screen ssh docker")
+    const backends = parseSequence(value).map((v) =>
+      v ? v.toLowerCase() : null
+    );
+    options.isolatedStack = backends;
+    options.isolated = backends[0]; // Current level
+  } else {
+    // Single value (backward compatible)
+    const backend = value.toLowerCase();
+    options.isolated = backend;
+    options.isolatedStack = [backend];
+  }
+}
+
+/**
+ * Parse --image value, handling both single values and sequences
+ * @param {string} value - Image value (e.g., "ubuntu:22.04" or "_ _ ubuntu:22.04")
+ * @param {object} options - Options object to populate
+ */
+function parseImageValue(value, options) {
+  if (isSequence(value)) {
+    // Multi-value sequence with placeholders
+    const images = parseSequence(value);
+    options.imageStack = images;
+    options.image = images[0]; // Current level
+  } else {
+    // Single value - will be distributed later during validation
+    options.image = value;
+    options.imageStack = null; // Will be populated during validation
+  }
+}
+
+/**
+ * Parse --endpoint value, handling both single values and sequences
+ * @param {string} value - Endpoint value (e.g., "user@host" or "_ user@host1 _ user@host2")
+ * @param {object} options - Options object to populate
+ */
+function parseEndpointValue(value, options) {
+  if (isSequence(value)) {
+    // Multi-value sequence with placeholders
+    const endpoints = parseSequence(value);
+    options.endpointStack = endpoints;
+    options.endpoint = endpoints[0]; // Current level
+  } else {
+    // Single value - will be distributed later during validation
+    options.endpoint = value;
+    options.endpointStack = null; // Will be populated during validation
+  }
+}
+
 /**
  * Parse command line arguments into wrapper options and command
  * @param {string[]} args - Array of command line arguments
@@ -80,18 +149,23 @@ function generateUUID() {
  */
 function parseArgs(args) {
   const wrapperOptions = {
-    isolated: null, // Isolation environment: screen, tmux, docker, ssh
+    isolated: null, // Isolation environment: screen, tmux, docker, ssh (current level)
+    isolatedStack: null, // Full isolation stack for multi-level isolation (e.g., ["screen", "ssh", "docker"])
     attached: false, // Run in attached mode
     detached: false, // Run in detached mode
-    session: null, // Session name
+    session: null, // Session name (current level)
+    sessionStack: null, // Session names for each level
     sessionId: null, // Session ID (UUID) for tracking - auto-generated if not provided
-    image: null, // Docker image
-    endpoint: null, // SSH endpoint (e.g., user@host)
+    image: null, // Docker image (current level)
+    imageStack: null, // Docker images for each level (with nulls for non-docker levels)
+    endpoint: null, // SSH endpoint (current level, e.g., user@host)
+    endpointStack: null, // SSH endpoints for each level (with nulls for non-ssh levels)
     user: false, // Create isolated user
     userName: null, // Optional custom username for isolated user
     keepUser: false, // Keep isolated user after command completes (don't delete)
     keepAlive: false, // Keep environment alive after command exits
     autoRemoveDockerContainer: false, // Auto-remove docker container after exit
+    shell: 'auto', // Shell to use in isolation environments: auto, bash, zsh, sh
     useCommandStream: false, // Use command-stream library for command execution
     status: null, // UUID to show status for
     outputFormat: null, // Output format for status (links-notation, json, text)
@@ -175,18 +249,20 @@ function parseOption(args, index, options) {
   // --isolated or -i
   if (arg === '--isolated' || arg === '-i') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.isolated = args[index + 1].toLowerCase();
+      const value = args[index + 1];
+      parseIsolatedValue(value, options);
       return 2;
     } else {
       throw new Error(
-        `Option ${arg} requires a backend argument (screen, tmux, docker)`
+        `Option ${arg} requires a backend argument (screen, tmux, docker, ssh)`
       );
     }
   }
 
   // --isolated=<value>
   if (arg.startsWith('--isolated=')) {
-    options.isolated = arg.split('=')[1].toLowerCase();
+    const value = arg.split('=')[1];
+    parseIsolatedValue(value, options);
     return 1;
   }
 
@@ -218,10 +294,11 @@ function parseOption(args, index, options) {
     return 1;
   }
 
-  // --image (for docker)
+  // --image (for docker) - supports sequence for stacked isolation
   if (arg === '--image') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.image = args[index + 1];
+      const value = args[index + 1];
+      parseImageValue(value, options);
       return 2;
     } else {
       throw new Error(`Option ${arg} requires an image name argument`);
@@ -230,14 +307,16 @@ function parseOption(args, index, options) {
 
   // --image=<value>
   if (arg.startsWith('--image=')) {
-    options.image = arg.split('=')[1];
+    const value = arg.split('=')[1];
+    parseImageValue(value, options);
     return 1;
   }
 
-  // --endpoint (for ssh)
+  // --endpoint (for ssh) - supports sequence for stacked isolation
   if (arg === '--endpoint') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.endpoint = args[index + 1];
+      const value = args[index + 1];
+      parseEndpointValue(value, options);
       return 2;
     } else {
       throw new Error(`Option ${arg} requires an endpoint argument`);
@@ -246,7 +325,8 @@ function parseOption(args, index, options) {
 
   // --endpoint=<value>
   if (arg.startsWith('--endpoint=')) {
-    options.endpoint = arg.split('=')[1];
+    const value = arg.split('=')[1];
+    parseEndpointValue(value, options);
     return 1;
   }
 
@@ -291,6 +371,24 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --shell <shell>
+  if (arg === '--shell') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.shell = args[index + 1].toLowerCase();
+      return 2;
+    } else {
+      throw new Error(
+        `Option ${arg} requires a shell argument (auto, bash, zsh, sh)`
+      );
+    }
+  }
+
+  // --shell=<value>
+  if (arg.startsWith('--shell=')) {
+    options.shell = arg.split('=')[1].toLowerCase();
+    return 1;
+  }
+
   // --use-command-stream
   if (arg === '--use-command-stream') {
     options.useCommandStream = true;
@@ -375,23 +473,137 @@ function validateOptions(options) {
     );
   }
 
-  // Validate isolation environment
+  // Validate isolation environment (with stacking support)
   if (options.isolated !== null) {
-    if (!VALID_BACKENDS.includes(options.isolated)) {
+    const stack = options.isolatedStack || [options.isolated];
+    const stackDepth = stack.length;
+
+    // Check depth limit
+    if (stackDepth > MAX_ISOLATION_DEPTH) {
       throw new Error(
-        `Invalid isolation environment: "${options.isolated}". Valid options are: ${VALID_BACKENDS.join(', ')}`
+        `Isolation stack too deep: ${stackDepth} levels (max: ${MAX_ISOLATION_DEPTH})`
       );
     }
 
-    // Docker uses --image or defaults to OS-matched image
-    if (options.isolated === 'docker' && !options.image) {
-      options.image = getDefaultDockerImage();
+    // Validate each backend in the stack
+    for (const backend of stack) {
+      if (backend && !VALID_BACKENDS.includes(backend)) {
+        throw new Error(
+          `Invalid isolation environment: "${backend}". Valid options are: ${VALID_BACKENDS.join(', ')}`
+        );
+      }
+    }
+
+    // Distribute single option values across stack if needed
+    if (options.image && !options.imageStack) {
+      // Single image value - replicate for all levels
+      options.imageStack = Array(stackDepth).fill(options.image);
     }
 
-    // SSH requires --endpoint
-    if (options.isolated === 'ssh' && !options.endpoint) {
+    if (options.endpoint && !options.endpointStack) {
+      // Single endpoint value - replicate for all levels
+      options.endpointStack = Array(stackDepth).fill(options.endpoint);
+    }
+
+    // Validate stack lengths match
+    if (options.imageStack && options.imageStack.length !== stackDepth) {
       throw new Error(
-        'SSH isolation requires --endpoint option to specify the remote server (e.g., user@host)'
+        `--image has ${options.imageStack.length} value(s) but isolation stack has ${stackDepth} level(s). ` +
+          `Use underscores (_) as placeholders for levels that don't need this option.`
+      );
+    }
+
+    if (options.endpointStack && options.endpointStack.length !== stackDepth) {
+      throw new Error(
+        `--endpoint has ${options.endpointStack.length} value(s) but isolation stack has ${stackDepth} level(s). ` +
+          `Use underscores (_) as placeholders for levels that don't need this option.`
+      );
+    }
+
+    // Validate each level has required options
+    for (let i = 0; i < stackDepth; i++) {
+      const backend = stack[i];
+
+      // Docker uses --image or defaults to OS-matched image
+      if (backend === 'docker') {
+        const image = options.imageStack
+          ? options.imageStack[i]
+          : options.image;
+        if (!image) {
+          // Apply default image
+          if (!options.imageStack) {
+            options.imageStack = Array(stackDepth).fill(null);
+          }
+          options.imageStack[i] = getDefaultDockerImage();
+        }
+      }
+
+      // SSH requires --endpoint
+      if (backend === 'ssh') {
+        const endpoint = options.endpointStack
+          ? options.endpointStack[i]
+          : options.endpoint;
+        if (!endpoint) {
+          throw new Error(
+            `SSH isolation at level ${i + 1} requires --endpoint option. ` +
+              `Use a sequence like --endpoint "_ user@host _" to specify endpoints for specific levels.`
+          );
+        }
+      }
+    }
+
+    // Set current level values for backward compatibility
+    options.image = options.imageStack ? options.imageStack[0] : options.image;
+    options.endpoint = options.endpointStack
+      ? options.endpointStack[0]
+      : options.endpoint;
+
+    // Validate option compatibility with current level (for backward compatible error messages)
+    const currentBackend = stack[0];
+
+    // Image is only valid if stack contains docker
+    if (options.image && !stack.includes('docker')) {
+      throw new Error(
+        '--image option is only valid when isolation stack includes docker'
+      );
+    }
+
+    // Endpoint is only valid if stack contains ssh
+    if (options.endpoint && !stack.includes('ssh')) {
+      throw new Error(
+        '--endpoint option is only valid when isolation stack includes ssh'
+      );
+    }
+
+    // Auto-remove-docker-container is only valid with docker in stack
+    if (options.autoRemoveDockerContainer && !stack.includes('docker')) {
+      throw new Error(
+        '--auto-remove-docker-container option is only valid when isolation stack includes docker'
+      );
+    }
+
+    // User isolation is not supported with Docker as first level
+    if (options.user && currentBackend === 'docker') {
+      throw new Error(
+        '--isolated-user is not supported with Docker as the first isolation level. ' +
+          'Docker uses its own user namespace for isolation.'
+      );
+    }
+  } else {
+    // Validate options that require isolation when no isolation is specified
+    if (options.autoRemoveDockerContainer) {
+      throw new Error(
+        '--auto-remove-docker-container option is only valid when isolation stack includes docker'
+      );
+    }
+    if (options.image) {
+      throw new Error(
+        '--image option is only valid when isolation stack includes docker'
+      );
+    }
+    if (options.endpoint) {
+      throw new Error(
+        '--endpoint option is only valid when isolation stack includes ssh'
       );
     }
   }
@@ -401,36 +613,13 @@ function validateOptions(options) {
     throw new Error('--session option is only valid with --isolated');
   }
 
-  // Image is only valid with docker
-  if (options.image && options.isolated !== 'docker') {
-    throw new Error('--image option is only valid with --isolated docker');
-  }
-
-  // Endpoint is only valid with ssh
-  if (options.endpoint && options.isolated !== 'ssh') {
-    throw new Error('--endpoint option is only valid with --isolated ssh');
-  }
-
   // Keep-alive is only valid with isolation
   if (options.keepAlive && !options.isolated) {
     throw new Error('--keep-alive option is only valid with --isolated');
   }
 
-  // Auto-remove-docker-container is only valid with docker isolation
-  if (options.autoRemoveDockerContainer && options.isolated !== 'docker') {
-    throw new Error(
-      '--auto-remove-docker-container option is only valid with --isolated docker'
-    );
-  }
-
   // User isolation validation
   if (options.user) {
-    // User isolation is not supported with Docker (Docker has its own user mechanism)
-    if (options.isolated === 'docker') {
-      throw new Error(
-        '--isolated-user is not supported with Docker isolation. Docker uses its own user namespace for isolation.'
-      );
-    }
     // Validate custom username if provided
     if (options.userName) {
       if (!/^[a-zA-Z0-9_-]+$/.test(options.userName)) {
@@ -465,6 +654,15 @@ function validateOptions(options) {
     throw new Error('--output-format option is only valid with --status');
   }
 
+  // Validate shell option
+  if (options.shell !== null && options.shell !== undefined) {
+    if (!VALID_SHELLS.includes(options.shell)) {
+      throw new Error(
+        `Invalid shell: "${options.shell}". Valid options are: ${VALID_SHELLS.join(', ')}`
+      );
+    }
+  }
+
   // Validate session ID is a valid UUID if provided
   if (options.sessionId !== null && options.sessionId !== undefined) {
     if (!isValidUUID(options.sessionId)) {
@@ -509,14 +707,26 @@ function getEffectiveMode(options) {
   return 'attached';
 }
 
+/**
+ * Check if isolation stack has multiple levels
+ * @param {object} options - Parsed wrapper options
+ * @returns {boolean} True if multiple isolation levels
+ */
+function hasStackedIsolation(options) {
+  return options.isolatedStack && options.isolatedStack.length > 1;
+}
+
 module.exports = {
   parseArgs,
   validateOptions,
   generateSessionName,
   hasIsolation,
+  hasStackedIsolation,
   getEffectiveMode,
   isValidUUID,
   generateUUID,
   VALID_BACKENDS,
   VALID_OUTPUT_FORMATS,
+  VALID_SHELLS,
+  MAX_ISOLATION_DEPTH,
 };

package/src/lib/command-builder.js

@@ -0,0 +1,134 @@
+/**
+ * Command Builder for Isolation Stacking
+ *
+ * Builds the command to execute at each isolation level,
+ * including the recursive $ invocation for nested levels.
+ */
+
+const { formatSequence } = require('./sequence-parser');
+
+/**
+ * Build command for next isolation level
+ * If more levels remain, builds a recursive $ command
+ * If this is the last level, returns the actual command
+ *
+ * @param {object} options - Current wrapper options
+ * @param {string} command - User command to execute
+ * @returns {string} Command to execute at current level
+ */
+function buildNextLevelCommand(options, command) {
+  // If no more isolation levels, execute actual command
+  if (!options.isolatedStack || options.isolatedStack.length <= 1) {
+    return command;
+  }
+
+  // Build recursive $ command for remaining levels
+  const parts = ['$'];
+
+  // Remaining isolation stack (skip first which is current level)
+  const remainingStack = options.isolatedStack.slice(1);
+  parts.push(`--isolated "${remainingStack.join(' ')}"`);
+
+  // Shift option values and add if non-empty
+  if (options.imageStack && options.imageStack.length > 1) {
+    const remainingImages = options.imageStack.slice(1);
+    const imageStr = formatSequence(remainingImages);
+    if (imageStr && imageStr !== '_'.repeat(remainingImages.length)) {
+      parts.push(`--image "${imageStr}"`);
+    }
+  }
+
+  if (options.endpointStack && options.endpointStack.length > 1) {
+    const remainingEndpoints = options.endpointStack.slice(1);
+    const endpointStr = formatSequence(remainingEndpoints);
+    if (endpointStr) {
+      parts.push(`--endpoint "${endpointStr}"`);
+    }
+  }
+
+  if (options.sessionStack && options.sessionStack.length > 1) {
+    const remainingSessions = options.sessionStack.slice(1);
+    const sessionStr = formatSequence(remainingSessions);
+    if (sessionStr && sessionStr !== '_'.repeat(remainingSessions.length)) {
+      parts.push(`--session "${sessionStr}"`);
+    }
+  }
+
+  // Pass through global flags
+  if (options.detached) {
+    parts.push('--detached');
+  }
+
+  if (options.keepAlive) {
+    parts.push('--keep-alive');
+  }
+
+  if (options.sessionId) {
+    parts.push(`--session-id ${options.sessionId}`);
+  }
+
+  if (options.autoRemoveDockerContainer) {
+    parts.push('--auto-remove-docker-container');
+  }
+
+  if (options.shell && options.shell !== 'auto') {
+    parts.push(`--shell ${options.shell}`);
+  }
+
+  // Separator and command
+  parts.push('--');
+  parts.push(command);
+
+  return parts.join(' ');
+}
+
+/**
+ * Escape a command for safe execution in a shell context
+ * @param {string} cmd - Command to escape
+ * @returns {string} Escaped command
+ */
+function escapeForShell(cmd) {
+  // For now, simple escaping - could be enhanced
+  return cmd.replace(/'/g, "'\\''");
+}
+
+/**
+ * Check if we're at the last isolation level
+ * @param {object} options - Wrapper options
+ * @returns {boolean} True if this is the last level
+ */
+function isLastLevel(options) {
+  return !options.isolatedStack || options.isolatedStack.length <= 1;
+}
+
+/**
+ * Get current isolation backend from options
+ * @param {object} options - Wrapper options
+ * @returns {string|null} Current backend or null
+ */
+function getCurrentBackend(options) {
+  if (options.isolatedStack && options.isolatedStack.length > 0) {
+    return options.isolatedStack[0];
+  }
+  return options.isolated;
+}
+
+/**
+ * Get option value for current level
+ * @param {(string|null)[]} stack - Option value stack
+ * @returns {string|null} Value for current level
+ */
+function getCurrentValue(stack) {
+  if (Array.isArray(stack) && stack.length > 0) {
+    return stack[0];
+  }
+  return null;
+}
+
+module.exports = {
+  buildNextLevelCommand,
+  escapeForShell,
+  isLastLevel,
+  getCurrentBackend,
+  getCurrentValue,
+};