start-command 0.3.1

package/src/lib/args-parser.js

@@ -0,0 +1,259 @@
+/**
+ * Argument Parser for start-command wrapper options
+ *
+ * Supports two syntax patterns:
+ * 1. $ [wrapper-options] -- [command-options]
+ * 2. $ [wrapper-options] command [command-options]
+ *
+ * Wrapper Options:
+ * --isolated, -i <backend>  Run in isolated environment (screen, tmux, docker, zellij)
+ * --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)
+ */
+
+// Debug mode from environment
+const DEBUG =
+  process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
+
+/**
+ * Valid isolation backends
+ */
+const VALID_BACKENDS = ['screen', 'tmux', 'docker', 'zellij'];
+
+/**
+ * Parse command line arguments into wrapper options and command
+ * @param {string[]} args - Array of command line arguments
+ * @returns {{wrapperOptions: object, command: string, rawCommand: string[]}}
+ */
+function parseArgs(args) {
+  const wrapperOptions = {
+    isolated: null, // Isolation backend: screen, tmux, docker, zellij
+    attached: false, // Run in attached mode
+    detached: false, // Run in detached mode
+    session: null, // Session name
+    image: null, // Docker image
+  };
+
+  let commandArgs = [];
+  let i = 0;
+
+  // Find the separator '--' or detect where command starts
+  const separatorIndex = args.indexOf('--');
+
+  if (separatorIndex !== -1) {
+    // Pattern 1: explicit separator
+    const wrapperArgs = args.slice(0, separatorIndex);
+    commandArgs = args.slice(separatorIndex + 1);
+
+    parseWrapperArgs(wrapperArgs, wrapperOptions);
+  } else {
+    // Pattern 2: parse until we hit a non-option argument
+    while (i < args.length) {
+      const arg = args[i];
+
+      if (arg.startsWith('-')) {
+        const consumed = parseOption(args, i, wrapperOptions);
+        if (consumed === 0) {
+          // Unknown option, treat rest as command
+          commandArgs = args.slice(i);
+          break;
+        }
+        i += consumed;
+      } else {
+        // Non-option argument, rest is command
+        commandArgs = args.slice(i);
+        break;
+      }
+    }
+  }
+
+  // Validate options
+  validateOptions(wrapperOptions);
+
+  return {
+    wrapperOptions,
+    command: commandArgs.join(' '),
+    rawCommand: commandArgs,
+  };
+}
+
+/**
+ * Parse wrapper arguments
+ * @param {string[]} args - Wrapper arguments
+ * @param {object} options - Options object to populate
+ */
+function parseWrapperArgs(args, options) {
+  let i = 0;
+  while (i < args.length) {
+    const consumed = parseOption(args, i, options);
+    if (consumed === 0) {
+      if (DEBUG) {
+        console.warn(`Unknown wrapper option: ${args[i]}`);
+      }
+      i++;
+    } else {
+      i += consumed;
+    }
+  }
+}
+
+/**
+ * Parse a single option from args array
+ * @param {string[]} args - Arguments array
+ * @param {number} index - Current index
+ * @param {object} options - Options object to populate
+ * @returns {number} Number of arguments consumed (0 if not recognized)
+ */
+function parseOption(args, index, options) {
+  const arg = args[index];
+
+  // --isolated or -i
+  if (arg === '--isolated' || arg === '-i') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.isolated = args[index + 1].toLowerCase();
+      return 2;
+    } else {
+      throw new Error(
+        `Option ${arg} requires a backend argument (screen, tmux, docker, zellij)`
+      );
+    }
+  }
+
+  // --isolated=<value>
+  if (arg.startsWith('--isolated=')) {
+    options.isolated = arg.split('=')[1].toLowerCase();
+    return 1;
+  }
+
+  // --attached or -a
+  if (arg === '--attached' || arg === '-a') {
+    options.attached = true;
+    return 1;
+  }
+
+  // --detached or -d
+  if (arg === '--detached' || arg === '-d') {
+    options.detached = true;
+    return 1;
+  }
+
+  // --session or -s
+  if (arg === '--session' || arg === '-s') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.session = args[index + 1];
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires a session name argument`);
+    }
+  }
+
+  // --session=<value>
+  if (arg.startsWith('--session=')) {
+    options.session = arg.split('=')[1];
+    return 1;
+  }
+
+  // --image (for docker)
+  if (arg === '--image') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.image = args[index + 1];
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires an image name argument`);
+    }
+  }
+
+  // --image=<value>
+  if (arg.startsWith('--image=')) {
+    options.image = arg.split('=')[1];
+    return 1;
+  }
+
+  // Not a recognized wrapper option
+  return 0;
+}
+
+/**
+ * Validate parsed options
+ * @param {object} options - Parsed options
+ * @throws {Error} If options are invalid
+ */
+function validateOptions(options) {
+  // Check attached and detached conflict
+  if (options.attached && options.detached) {
+    throw new Error(
+      'Cannot use both --attached and --detached at the same time. Please choose only one mode.'
+    );
+  }
+
+  // Validate isolation backend
+  if (options.isolated !== null) {
+    if (!VALID_BACKENDS.includes(options.isolated)) {
+      throw new Error(
+        `Invalid isolation backend: "${options.isolated}". Valid options are: ${VALID_BACKENDS.join(', ')}`
+      );
+    }
+
+    // Docker requires --image
+    if (options.isolated === 'docker' && !options.image) {
+      throw new Error(
+        'Docker isolation requires --image option to specify the container image'
+      );
+    }
+  }
+
+  // Session name is only valid with isolation
+  if (options.session && !options.isolated) {
+    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');
+  }
+}
+
+/**
+ * Generate a unique session name
+ * @param {string} [prefix='start'] - Prefix for the session name
+ * @returns {string} Generated session name
+ */
+function generateSessionName(prefix = 'start') {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 8);
+  return `${prefix}-${timestamp}-${random}`;
+}
+
+/**
+ * Check if any isolation options are present
+ * @param {object} options - Parsed wrapper options
+ * @returns {boolean} True if isolation is requested
+ */
+function hasIsolation(options) {
+  return options.isolated !== null;
+}
+
+/**
+ * Get the effective mode for isolation
+ * Multiplexers default to attached, docker defaults to attached
+ * @param {object} options - Parsed wrapper options
+ * @returns {'attached'|'detached'} The effective mode
+ */
+function getEffectiveMode(options) {
+  if (options.detached) {
+    return 'detached';
+  }
+  // Default to attached for all backends
+  return 'attached';
+}
+
+module.exports = {
+  parseArgs,
+  validateOptions,
+  generateSessionName,
+  hasIsolation,
+  getEffectiveMode,
+  VALID_BACKENDS,
+};

package/src/lib/isolation.js

@@ -0,0 +1,419 @@
+/**
+ * Isolation Runners for start-command
+ *
+ * Provides execution of commands in various isolated environments:
+ * - screen: GNU Screen terminal multiplexer
+ * - tmux: tmux terminal multiplexer
+ * - zellij: Modern terminal workspace
+ * - docker: Docker containers
+ */
+
+const { execSync, spawn } = require('child_process');
+const { generateSessionName } = require('./args-parser');
+
+// Debug mode from environment
+const DEBUG =
+  process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
+
+/**
+ * Check if a command is available on the system
+ * @param {string} command - Command to check
+ * @returns {boolean} True if command is available
+ */
+function isCommandAvailable(command) {
+  try {
+    const isWindows = process.platform === 'win32';
+    const checkCmd = isWindows ? 'where' : 'which';
+    execSync(`${checkCmd} ${command}`, { stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the shell to use for command execution
+ * @returns {{shell: string, shellArgs: string[]}} Shell path and args
+ */
+function getShell() {
+  const isWindows = process.platform === 'win32';
+  const shell = isWindows ? 'cmd.exe' : process.env.SHELL || '/bin/sh';
+  const shellArg = isWindows ? '/c' : '-c';
+  return { shell, shellArg };
+}
+
+/**
+ * Run command in GNU Screen
+ * @param {string} command - Command to execute
+ * @param {object} options - Options (session, detached)
+ * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
+ */
+function runInScreen(command, options = {}) {
+  if (!isCommandAvailable('screen')) {
+    return Promise.resolve({
+      success: false,
+      sessionName: null,
+      message:
+        'screen is not installed. Install it with: sudo apt-get install screen (Debian/Ubuntu) or brew install screen (macOS)',
+    });
+  }
+
+  const sessionName = options.session || generateSessionName('screen');
+  const { shell, shellArg } = getShell();
+
+  try {
+    if (options.detached) {
+      // Detached mode: screen -dmS <session> <shell> -c '<command>'
+      const screenArgs = ['-dmS', sessionName, shell, shellArg, command];
+
+      if (DEBUG) {
+        console.log(`[DEBUG] Running: screen ${screenArgs.join(' ')}`);
+      }
+
+      execSync(`screen ${screenArgs.map((a) => `"${a}"`).join(' ')}`, {
+        stdio: 'inherit',
+      });
+
+      return Promise.resolve({
+        success: true,
+        sessionName,
+        message: `Command started in detached screen session: ${sessionName}\nReattach with: screen -r ${sessionName}`,
+      });
+    } else {
+      // Attached mode: screen -S <session> <shell> -c '<command>'
+      const screenArgs = ['-S', sessionName, shell, shellArg, command];
+
+      if (DEBUG) {
+        console.log(`[DEBUG] Running: screen ${screenArgs.join(' ')}`);
+      }
+
+      return new Promise((resolve) => {
+        const child = spawn('screen', screenArgs, {
+          stdio: 'inherit',
+        });
+
+        child.on('exit', (code) => {
+          resolve({
+            success: code === 0,
+            sessionName,
+            message: `Screen session "${sessionName}" exited with code ${code}`,
+            exitCode: code,
+          });
+        });
+
+        child.on('error', (err) => {
+          resolve({
+            success: false,
+            sessionName,
+            message: `Failed to start screen: ${err.message}`,
+          });
+        });
+      });
+    }
+  } catch (err) {
+    return Promise.resolve({
+      success: false,
+      sessionName,
+      message: `Failed to run in screen: ${err.message}`,
+    });
+  }
+}
+
+/**
+ * Run command in tmux
+ * @param {string} command - Command to execute
+ * @param {object} options - Options (session, detached)
+ * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
+ */
+function runInTmux(command, options = {}) {
+  if (!isCommandAvailable('tmux')) {
+    return Promise.resolve({
+      success: false,
+      sessionName: null,
+      message:
+        'tmux is not installed. Install it with: sudo apt-get install tmux (Debian/Ubuntu) or brew install tmux (macOS)',
+    });
+  }
+
+  const sessionName = options.session || generateSessionName('tmux');
+
+  try {
+    if (options.detached) {
+      // Detached mode: tmux new-session -d -s <session> '<command>'
+      if (DEBUG) {
+        console.log(
+          `[DEBUG] Running: tmux new-session -d -s "${sessionName}" "${command}"`
+        );
+      }
+
+      execSync(`tmux new-session -d -s "${sessionName}" "${command}"`, {
+        stdio: 'inherit',
+      });
+
+      return Promise.resolve({
+        success: true,
+        sessionName,
+        message: `Command started in detached tmux session: ${sessionName}\nReattach with: tmux attach -t ${sessionName}`,
+      });
+    } else {
+      // Attached mode: tmux new-session -s <session> '<command>'
+      if (DEBUG) {
+        console.log(
+          `[DEBUG] Running: tmux new-session -s "${sessionName}" "${command}"`
+        );
+      }
+
+      return new Promise((resolve) => {
+        const child = spawn(
+          'tmux',
+          ['new-session', '-s', sessionName, command],
+          {
+            stdio: 'inherit',
+          }
+        );
+
+        child.on('exit', (code) => {
+          resolve({
+            success: code === 0,
+            sessionName,
+            message: `Tmux session "${sessionName}" exited with code ${code}`,
+            exitCode: code,
+          });
+        });
+
+        child.on('error', (err) => {
+          resolve({
+            success: false,
+            sessionName,
+            message: `Failed to start tmux: ${err.message}`,
+          });
+        });
+      });
+    }
+  } catch (err) {
+    return Promise.resolve({
+      success: false,
+      sessionName,
+      message: `Failed to run in tmux: ${err.message}`,
+    });
+  }
+}
+
+/**
+ * Run command in Zellij
+ * @param {string} command - Command to execute
+ * @param {object} options - Options (session, detached)
+ * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
+ */
+function runInZellij(command, options = {}) {
+  if (!isCommandAvailable('zellij')) {
+    return Promise.resolve({
+      success: false,
+      sessionName: null,
+      message:
+        'zellij is not installed. Install it with: cargo install zellij or brew install zellij (macOS)',
+    });
+  }
+
+  const sessionName = options.session || generateSessionName('zellij');
+  const { shell, shellArg } = getShell();
+
+  try {
+    if (options.detached) {
+      // Detached mode for zellij
+      if (DEBUG) {
+        console.log(`[DEBUG] Creating detached zellij session: ${sessionName}`);
+      }
+
+      // Create the session in background
+      execSync(
+        `zellij -s "${sessionName}" action new-tab -- ${shell} ${shellArg} "${command}" &`,
+        { stdio: 'inherit', shell: true }
+      );
+
+      return Promise.resolve({
+        success: true,
+        sessionName,
+        message: `Command started in detached zellij session: ${sessionName}\nReattach with: zellij attach ${sessionName}`,
+      });
+    } else {
+      // Attached mode: zellij -s <session> -- <shell> -c <command>
+      if (DEBUG) {
+        console.log(
+          `[DEBUG] Running: zellij -s "${sessionName}" -- ${shell} ${shellArg} "${command}"`
+        );
+      }
+
+      return new Promise((resolve) => {
+        const child = spawn(
+          'zellij',
+          ['-s', sessionName, '--', shell, shellArg, command],
+          {
+            stdio: 'inherit',
+          }
+        );
+
+        child.on('exit', (code) => {
+          resolve({
+            success: code === 0,
+            sessionName,
+            message: `Zellij session "${sessionName}" exited with code ${code}`,
+            exitCode: code,
+          });
+        });
+
+        child.on('error', (err) => {
+          resolve({
+            success: false,
+            sessionName,
+            message: `Failed to start zellij: ${err.message}`,
+          });
+        });
+      });
+    }
+  } catch (err) {
+    return Promise.resolve({
+      success: false,
+      sessionName,
+      message: `Failed to run in zellij: ${err.message}`,
+    });
+  }
+}
+
+/**
+ * Run command in Docker container
+ * @param {string} command - Command to execute
+ * @param {object} options - Options (image, session/name, detached)
+ * @returns {Promise<{success: boolean, containerName: string, message: string}>}
+ */
+function runInDocker(command, options = {}) {
+  if (!isCommandAvailable('docker')) {
+    return Promise.resolve({
+      success: false,
+      containerName: null,
+      message:
+        'docker is not installed. Install Docker from https://docs.docker.com/get-docker/',
+    });
+  }
+
+  if (!options.image) {
+    return Promise.resolve({
+      success: false,
+      containerName: null,
+      message: 'Docker isolation requires --image option',
+    });
+  }
+
+  const containerName = options.session || generateSessionName('docker');
+
+  try {
+    if (options.detached) {
+      // Detached mode: docker run -d --name <name> <image> <shell> -c '<command>'
+      const dockerArgs = [
+        'run',
+        '-d',
+        '--name',
+        containerName,
+        options.image,
+        '/bin/sh',
+        '-c',
+        command,
+      ];
+
+      if (DEBUG) {
+        console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
+      }
+
+      const containerId = execSync(`docker ${dockerArgs.join(' ')}`, {
+        encoding: 'utf8',
+      }).trim();
+
+      return Promise.resolve({
+        success: true,
+        containerName,
+        containerId,
+        message: `Command started in detached docker container: ${containerName}\nContainer ID: ${containerId.substring(0, 12)}\nAttach with: docker attach ${containerName}\nView logs: docker logs ${containerName}`,
+      });
+    } 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,
+      ];
+
+      if (DEBUG) {
+        console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
+      }
+
+      return new Promise((resolve) => {
+        const child = spawn('docker', dockerArgs, {
+          stdio: 'inherit',
+        });
+
+        child.on('exit', (code) => {
+          resolve({
+            success: code === 0,
+            containerName,
+            message: `Docker container "${containerName}" exited with code ${code}`,
+            exitCode: code,
+          });
+        });
+
+        child.on('error', (err) => {
+          resolve({
+            success: false,
+            containerName,
+            message: `Failed to start docker: ${err.message}`,
+          });
+        });
+      });
+    }
+  } catch (err) {
+    return Promise.resolve({
+      success: false,
+      containerName,
+      message: `Failed to run in docker: ${err.message}`,
+    });
+  }
+}
+
+/**
+ * Run command in the specified isolation backend
+ * @param {string} backend - Isolation backend (screen, tmux, docker, zellij)
+ * @param {string} command - Command to execute
+ * @param {object} options - Options
+ * @returns {Promise<{success: boolean, message: string}>}
+ */
+function runIsolated(backend, command, options = {}) {
+  switch (backend) {
+    case 'screen':
+      return runInScreen(command, options);
+    case 'tmux':
+      return runInTmux(command, options);
+    case 'zellij':
+      return runInZellij(command, options);
+    case 'docker':
+      return runInDocker(command, options);
+    default:
+      return Promise.resolve({
+        success: false,
+        message: `Unknown isolation backend: ${backend}`,
+      });
+  }
+}
+
+module.exports = {
+  isCommandAvailable,
+  runInScreen,
+  runInTmux,
+  runInZellij,
+  runInDocker,
+  runIsolated,
+};