start-command 0.9.0 → 0.11.0

package/src/lib/args-parser.js

@@ -6,11 +6,14 @@
  * 2. $ [wrapper-options] command [command-options]
  *
  * Wrapper Options:
- * --isolated, -i <backend>         Run in isolated environment (screen, tmux, docker)
+ * --isolated, -i <backend>         Run in isolated environment (screen, tmux, docker, ssh)
  * --attached, -a                   Run in attached mode (foreground)
  * --detached, -d                   Run in detached mode (background)
  * --session, -s <name>             Session name for isolation
  * --image <image>                  Docker image (required for docker isolation)
+ * --endpoint <endpoint>            SSH endpoint (required for ssh isolation, e.g., user@host)
+ * --isolated-user, -u [username]   Create isolated user with same permissions (auto-generated name if not specified)
+ * --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)
  */
@@ -22,7 +25,7 @@ const DEBUG =
 /**
  * Valid isolation backends
  */
-const VALID_BACKENDS = ['screen', 'tmux', 'docker'];
+const VALID_BACKENDS = ['screen', 'tmux', 'docker', 'ssh'];
 
 /**
  * Parse command line arguments into wrapper options and command
@@ -31,11 +34,15 @@ const VALID_BACKENDS = ['screen', 'tmux', 'docker'];
  */
 function parseArgs(args) {
   const wrapperOptions = {
-    isolated: null, // Isolation backend: screen, tmux, docker
+    isolated: null, // Isolation backend: screen, tmux, docker, ssh
     attached: false, // Run in attached mode
     detached: false, // Run in detached mode
     session: null, // Session name
     image: null, // Docker image
+    endpoint: null, // SSH endpoint (e.g., user@host)
+    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
   };
@@ -175,6 +182,51 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --endpoint (for ssh)
+  if (arg === '--endpoint') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.endpoint = args[index + 1];
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires an endpoint argument`);
+    }
+  }
+
+  // --endpoint=<value>
+  if (arg.startsWith('--endpoint=')) {
+    options.endpoint = arg.split('=')[1];
+    return 1;
+  }
+
+  // --isolated-user or -u [optional-username] - creates isolated user with same permissions
+  if (arg === '--isolated-user' || arg === '-u') {
+    options.user = true;
+    // Check if next arg is an optional username (not starting with -)
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      // Check if next arg looks like a username (not a command)
+      const nextArg = args[index + 1];
+      // If next arg matches username format, consume it
+      if (/^[a-zA-Z0-9_-]+$/.test(nextArg) && nextArg.length <= 32) {
+        options.userName = nextArg;
+        return 2;
+      }
+    }
+    return 1;
+  }
+
+  // --isolated-user=<value>
+  if (arg.startsWith('--isolated-user=')) {
+    options.user = true;
+    options.userName = arg.split('=')[1];
+    return 1;
+  }
+
+  // --keep-user - keep isolated user after command completes
+  if (arg === '--keep-user') {
+    options.keepUser = true;
+    return 1;
+  }
+
   // --keep-alive or -k
   if (arg === '--keep-alive' || arg === '-k') {
     options.keepAlive = true;
@@ -218,6 +270,13 @@ function validateOptions(options) {
         'Docker isolation requires --image option to specify the container image'
       );
     }
+
+    // SSH requires --endpoint
+    if (options.isolated === 'ssh' && !options.endpoint) {
+      throw new Error(
+        'SSH isolation requires --endpoint option to specify the remote server (e.g., user@host)'
+      );
+    }
   }
 
   // Session name is only valid with isolation
@@ -230,6 +289,11 @@ function validateOptions(options) {
     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');
@@ -241,6 +305,34 @@ function validateOptions(options) {
       '--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)) {
+        throw new Error(
+          `Invalid username format for --isolated-user: "${options.userName}". Username should contain only letters, numbers, hyphens, and underscores.`
+        );
+      }
+      if (options.userName.length > 32) {
+        throw new Error(
+          `Username too long for --isolated-user: "${options.userName}". Maximum length is 32 characters.`
+        );
+      }
+    }
+  }
+
+  // Keep-user validation
+  if (options.keepUser && !options.user) {
+    throw new Error('--keep-user option is only valid with --isolated-user');
+  }
 }
 
 /**

package/src/lib/isolation.js

@@ -131,6 +131,22 @@ function hasTTY() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
+/**
+ * Wrap command with sudo -u if user option is specified
+ * @param {string} command - Original command
+ * @param {string|null} user - Username to run as (or null)
+ * @returns {string} Wrapped command
+ */
+function wrapCommandWithUser(command, user) {
+  if (!user) {
+    return command;
+  }
+  // Use sudo -u to run command as specified user
+  // -E preserves environment variables
+  // -n ensures non-interactive (fails if password required)
+  return `sudo -n -u ${user} sh -c '${command.replace(/'/g, "'\\''")}'`;
+}
+
 /**
  * Run command in GNU Screen using detached mode with log capture
  * This is a workaround for environments without TTY
@@ -142,9 +158,10 @@ function hasTTY() {
  * @param {string} command - Command to execute
  * @param {string} sessionName - Session name
  * @param {object} shellInfo - Shell info from getShell()
+ * @param {string|null} user - Username to run command as (optional)
  * @returns {Promise<{success: boolean, sessionName: string, message: string, output: string}>}
  */
-function runScreenWithLogCapture(command, sessionName, shellInfo) {
+function runScreenWithLogCapture(command, sessionName, shellInfo, user = null) {
   const { shell, shellArg } = shellInfo;
   const logFile = path.join(os.tmpdir(), `screen-output-${sessionName}.log`);
 
@@ -154,7 +171,8 @@ function runScreenWithLogCapture(command, sessionName, shellInfo) {
   return new Promise((resolve) => {
     try {
       let screenArgs;
-      let effectiveCommand = command;
+      // Wrap command with user switch if specified
+      let effectiveCommand = wrapCommandWithUser(command, user);
 
       if (useNativeLogging) {
         // Modern screen (>= 4.5.1): Use -L -Logfile option for native log capture
@@ -167,7 +185,7 @@ function runScreenWithLogCapture(command, sessionName, shellInfo) {
           logFile,
           shell,
           shellArg,
-          command,
+          effectiveCommand,
         ];
 
         if (DEBUG) {
@@ -179,7 +197,7 @@ function runScreenWithLogCapture(command, sessionName, shellInfo) {
         // Older screen (< 4.5.1, e.g., macOS bundled 4.0.3): Use tee fallback
         // Wrap the command to capture output using tee
         // The parentheses ensure proper grouping of the command and its stderr
-        effectiveCommand = `(${command}) 2>&1 | tee "${logFile}"`;
+        effectiveCommand = `(${effectiveCommand}) 2>&1 | tee "${logFile}"`;
         screenArgs = ['-dmS', sessionName, shell, shellArg, effectiveCommand];
 
         if (DEBUG) {
@@ -299,7 +317,7 @@ function runScreenWithLogCapture(command, sessionName, shellInfo) {
 /**
  * Run command in GNU Screen
  * @param {string} command - Command to execute
- * @param {object} options - Options (session, detached, keepAlive)
+ * @param {object} options - Options (session, detached, user, keepAlive)
  * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
  */
 function runInScreen(command, options = {}) {
@@ -317,16 +335,17 @@ function runInScreen(command, options = {}) {
   const { shell, shellArg } = shellInfo;
 
   try {
+    // Wrap command with user switch if specified
+    let effectiveCommand = wrapCommandWithUser(command, options.user);
+
     if (options.detached) {
       // Detached mode: screen -dmS <session> <shell> -c '<command>'
       // By default (keepAlive=false), the session will exit after command completes
       // With keepAlive=true, we start a shell that runs the command but stays alive
-      let effectiveCommand = command;
 
       if (options.keepAlive) {
         // With keep-alive: run command, then keep shell open
-        // Use exec to replace the shell, but first run command
-        effectiveCommand = `${command}; exec ${shell}`;
+        effectiveCommand = `${effectiveCommand}; exec ${shell}`;
       }
       // Without keep-alive: command runs and session exits naturally when done
 
@@ -383,7 +402,12 @@ function runInScreen(command, options = {}) {
         );
       }
 
-      return runScreenWithLogCapture(command, sessionName, shellInfo);
+      return runScreenWithLogCapture(
+        command,
+        sessionName,
+        shellInfo,
+        options.user
+      );
     }
   } catch (err) {
     return Promise.resolve({
@@ -397,7 +421,7 @@ function runInScreen(command, options = {}) {
 /**
  * Run command in tmux
  * @param {string} command - Command to execute
- * @param {object} options - Options (session, detached, keepAlive)
+ * @param {object} options - Options (session, detached, user, keepAlive)
  * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
  */
 function runInTmux(command, options = {}) {
@@ -414,16 +438,18 @@ function runInTmux(command, options = {}) {
   const shellInfo = getShell();
   const { shell } = shellInfo;
 
+  // Wrap command with user switch if specified
+  let effectiveCommand = wrapCommandWithUser(command, options.user);
+
   try {
     if (options.detached) {
       // Detached mode: tmux new-session -d -s <session> '<command>'
       // By default (keepAlive=false), the session will exit after command completes
       // With keepAlive=true, we keep the shell alive after the command
-      let effectiveCommand = command;
 
       if (options.keepAlive) {
         // With keep-alive: run command, then keep shell open
-        effectiveCommand = `${command}; exec ${shell}`;
+        effectiveCommand = `${effectiveCommand}; exec ${shell}`;
       }
       // Without keep-alive: command runs and session exits naturally when done
 
@@ -458,14 +484,14 @@ function runInTmux(command, options = {}) {
       // Attached mode: tmux new-session -s <session> '<command>'
       if (DEBUG) {
         console.log(
-          `[DEBUG] Running: tmux new-session -s "${sessionName}" "${command}"`
+          `[DEBUG] Running: tmux new-session -s "${sessionName}" "${effectiveCommand}"`
         );
       }
 
       return new Promise((resolve) => {
         const child = spawn(
           'tmux',
-          ['new-session', '-s', sessionName, command],
+          ['new-session', '-s', sessionName, effectiveCommand],
           {
             stdio: 'inherit',
           }
@@ -498,10 +524,103 @@ function runInTmux(command, options = {}) {
   }
 }
 
+/**
+ * Run command over SSH on a remote server
+ * @param {string} command - Command to execute
+ * @param {object} options - Options (endpoint, session, detached)
+ * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
+ */
+function runInSsh(command, options = {}) {
+  if (!isCommandAvailable('ssh')) {
+    return Promise.resolve({
+      success: false,
+      sessionName: null,
+      message:
+        'ssh is not installed. Install it with: sudo apt-get install openssh-client (Debian/Ubuntu) or brew install openssh (macOS)',
+    });
+  }
+
+  if (!options.endpoint) {
+    return Promise.resolve({
+      success: false,
+      sessionName: null,
+      message:
+        'SSH isolation requires --endpoint option to specify the remote server (e.g., user@host)',
+    });
+  }
+
+  const sessionName = options.session || generateSessionName('ssh');
+  const sshTarget = options.endpoint;
+
+  try {
+    if (options.detached) {
+      // Detached mode: Run command in background on remote server using nohup
+      // The command will continue running even after SSH connection closes
+      const remoteCommand = `nohup ${command} > /tmp/${sessionName}.log 2>&1 &`;
+      const sshArgs = [sshTarget, remoteCommand];
+
+      if (DEBUG) {
+        console.log(`[DEBUG] Running: ssh ${sshArgs.join(' ')}`);
+      }
+
+      const result = spawnSync('ssh', sshArgs, {
+        stdio: 'inherit',
+      });
+
+      if (result.error) {
+        throw result.error;
+      }
+
+      return Promise.resolve({
+        success: true,
+        sessionName,
+        message: `Command started in detached SSH session on ${sshTarget}\nSession: ${sessionName}\nView logs: ssh ${sshTarget} "tail -f /tmp/${sessionName}.log"`,
+      });
+    } else {
+      // Attached mode: Run command interactively over SSH
+      // This creates a direct SSH connection and runs the command
+      const sshArgs = [sshTarget, command];
+
+      if (DEBUG) {
+        console.log(`[DEBUG] Running: ssh ${sshArgs.join(' ')}`);
+      }
+
+      return new Promise((resolve) => {
+        const child = spawn('ssh', sshArgs, {
+          stdio: 'inherit',
+        });
+
+        child.on('exit', (code) => {
+          resolve({
+            success: code === 0,
+            sessionName,
+            message: `SSH session "${sessionName}" on ${sshTarget} exited with code ${code}`,
+            exitCode: code,
+          });
+        });
+
+        child.on('error', (err) => {
+          resolve({
+            success: false,
+            sessionName,
+            message: `Failed to start SSH: ${err.message}`,
+          });
+        });
+      });
+    }
+  } catch (err) {
+    return Promise.resolve({
+      success: false,
+      sessionName,
+      message: `Failed to run over SSH: ${err.message}`,
+    });
+  }
+}
+
 /**
  * Run command in Docker container
  * @param {string} command - Command to execute
- * @param {object} options - Options (image, session/name, detached, keepAlive, autoRemoveDockerContainer)
+ * @param {object} options - Options (image, session/name, detached, user, keepAlive, autoRemoveDockerContainer)
  * @returns {Promise<{success: boolean, containerName: string, message: string}>}
  */
 function runInDocker(command, options = {}) {
@@ -526,7 +645,7 @@ function runInDocker(command, options = {}) {
 
   try {
     if (options.detached) {
-      // Detached mode: docker run -d --name <name> <image> <shell> -c '<command>'
+      // Detached mode: docker run -d --name <name> [--user <user>] <image> <shell> -c '<command>'
       // By default (keepAlive=false), the container exits after command completes
       // With keepAlive=true, we keep the container running with a shell
       let effectiveCommand = command;
@@ -537,16 +656,7 @@ function runInDocker(command, options = {}) {
       }
       // Without keep-alive: container exits naturally when command completes
 
-      const dockerArgs = [
-        'run',
-        '-d',
-        '--name',
-        containerName,
-        options.image,
-        '/bin/sh',
-        '-c',
-        effectiveCommand,
-      ];
+      const dockerArgs = ['run', '-d', '--name', containerName];
 
       // Add --rm flag if autoRemoveDockerContainer is true
       // Note: --rm must come before the image name
@@ -554,6 +664,13 @@ function runInDocker(command, options = {}) {
         dockerArgs.splice(2, 0, '--rm');
       }
 
+      // Add --user flag if specified
+      if (options.user) {
+        dockerArgs.push('--user', options.user);
+      }
+
+      dockerArgs.push(options.image, '/bin/sh', '-c', effectiveCommand);
+
       if (DEBUG) {
         console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
         console.log(`[DEBUG] keepAlive: ${options.keepAlive || false}`);
@@ -588,18 +705,15 @@ function runInDocker(command, options = {}) {
         message,
       });
     } else {
-      // Attached mode: docker run -it --name <name> <image> <shell> -c '<command>'
-      const dockerArgs = [
-        'run',
-        '-it',
-        '--rm',
-        '--name',
-        containerName,
-        options.image,
-        '/bin/sh',
-        '-c',
-        command,
-      ];
+      // Attached mode: docker run -it --name <name> [--user <user>] <image> <shell> -c '<command>'
+      const dockerArgs = ['run', '-it', '--rm', '--name', containerName];
+
+      // Add --user flag if specified
+      if (options.user) {
+        dockerArgs.push('--user', options.user);
+      }
+
+      dockerArgs.push(options.image, '/bin/sh', '-c', command);
 
       if (DEBUG) {
         console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
@@ -639,7 +753,7 @@ function runInDocker(command, options = {}) {
 
 /**
  * Run command in the specified isolation backend
- * @param {string} backend - Isolation backend (screen, tmux, docker)
+ * @param {string} backend - Isolation backend (screen, tmux, docker, ssh)
  * @param {string} command - Command to execute
  * @param {object} options - Options
  * @returns {Promise<{success: boolean, message: string}>}
@@ -652,6 +766,8 @@ function runIsolated(backend, command, options = {}) {
       return runInTmux(command, options);
     case 'docker':
       return runInDocker(command, options);
+    case 'ssh':
+      return runInSsh(command, options);
     default:
       return Promise.resolve({
         success: false,
@@ -687,6 +803,7 @@ function generateLogFilename(environment) {
  * @param {string} params.mode - attached or detached
  * @param {string} params.sessionName - Session/container name
  * @param {string} [params.image] - Docker image (for docker environment)
+ * @param {string} [params.user] - User to run command as (optional)
  * @param {string} params.startTime - Start timestamp
  * @returns {string} Log header content
  */
@@ -700,6 +817,9 @@ function createLogHeader(params) {
   if (params.image) {
     content += `Image: ${params.image}\n`;
   }
+  if (params.user) {
+    content += `User: ${params.user}\n`;
+  }
   content += `Platform: ${process.platform}\n`;
   content += `Node Version: ${process.version}\n`;
   content += `Working Directory: ${process.cwd()}\n`;
@@ -763,14 +883,47 @@ function resetScreenVersionCache() {
   screenVersionChecked = false;
 }
 
+/**
+ * Run command as an isolated user (without isolation backend)
+ * Uses sudo -u to switch users
+ * @param {string} cmd - Command to execute
+ * @param {string} username - User to run as
+ * @returns {Promise<{success: boolean, message: string, exitCode: number}>}
+ */
+function runAsIsolatedUser(cmd, username) {
+  return new Promise((resolve) => {
+    const child = spawn('sudo', ['-n', '-u', username, 'sh', '-c', cmd], {
+      stdio: 'inherit',
+    });
+
+    child.on('exit', (code) => {
+      resolve({
+        success: code === 0,
+        message: `Command completed as user "${username}" with exit code ${code}`,
+        exitCode: code || 0,
+      });
+    });
+
+    child.on('error', (err) => {
+      resolve({
+        success: false,
+        message: `Failed to run as user "${username}": ${err.message}`,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
 module.exports = {
   isCommandAvailable,
   hasTTY,
   runInScreen,
   runInTmux,
   runInDocker,
+  runInSsh,
   runIsolated,
-  // Export logging utilities for unified experience
+  runAsIsolatedUser,
+  wrapCommandWithUser,
   getTimestamp,
   generateLogFilename,
   createLogHeader,
@@ -778,7 +931,6 @@ module.exports = {
   writeLogFile,
   getLogDir,
   createLogPath,
-  // Export screen version utilities for testing and debugging
   getScreenVersion,
   supportsLogfileOption,
   resetScreenVersionCache,