start-command 0.7.5 → 0.9.0

package/src/lib/args-parser.js

@@ -6,11 +6,13 @@
  * 2. $ [wrapper-options] command [command-options]
  *
  * Wrapper Options:
- * --isolated, -i <backend>  Run in isolated environment (screen, tmux, docker)
- * --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)
+ * --isolated, -i <backend>         Run in isolated environment (screen, tmux, docker)
+ * --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)
+ * --keep-alive, -k                 Keep isolation environment alive after command exits
+ * --auto-remove-docker-container   Automatically remove docker container after exit (disabled by default)
  */
 
 // Debug mode from environment
@@ -34,6 +36,8 @@ function parseArgs(args) {
     detached: false, // Run in detached mode
     session: null, // Session name
     image: null, // Docker image
+    keepAlive: false, // Keep environment alive after command exits
+    autoRemoveDockerContainer: false, // Auto-remove docker container after exit
   };
 
   let commandArgs = [];
@@ -171,6 +175,18 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --keep-alive or -k
+  if (arg === '--keep-alive' || arg === '-k') {
+    options.keepAlive = true;
+    return 1;
+  }
+
+  // --auto-remove-docker-container
+  if (arg === '--auto-remove-docker-container') {
+    options.autoRemoveDockerContainer = true;
+    return 1;
+  }
+
   // Not a recognized wrapper option
   return 0;
 }
@@ -213,6 +229,18 @@ function validateOptions(options) {
   if (options.image && options.isolated !== 'docker') {
     throw new Error('--image option is only valid with --isolated docker');
   }
+
+  // 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'
+    );
+  }
 }
 
 /**

package/src/lib/isolation.js

@@ -299,7 +299,7 @@ function runScreenWithLogCapture(command, sessionName, shellInfo) {
 /**
  * Run command in GNU Screen
  * @param {string} command - Command to execute
- * @param {object} options - Options (session, detached)
+ * @param {object} options - Options (session, detached, keepAlive)
  * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
  */
 function runInScreen(command, options = {}) {
@@ -319,10 +319,28 @@ function runInScreen(command, options = {}) {
   try {
     if (options.detached) {
       // Detached mode: screen -dmS <session> <shell> -c '<command>'
-      const screenArgs = ['-dmS', sessionName, shell, shellArg, 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}`;
+      }
+      // Without keep-alive: command runs and session exits naturally when done
+
+      const screenArgs = [
+        '-dmS',
+        sessionName,
+        shell,
+        shellArg,
+        effectiveCommand,
+      ];
 
       if (DEBUG) {
         console.log(`[DEBUG] Running: screen ${screenArgs.join(' ')}`);
+        console.log(`[DEBUG] keepAlive: ${options.keepAlive || false}`);
       }
 
       // Use spawnSync with array arguments to avoid shell quoting issues
@@ -336,10 +354,18 @@ function runInScreen(command, options = {}) {
         throw result.error;
       }
 
+      let message = `Command started in detached screen session: ${sessionName}`;
+      if (options.keepAlive) {
+        message += `\nSession will stay alive after command completes.`;
+      } else {
+        message += `\nSession will exit automatically after command completes.`;
+      }
+      message += `\nReattach with: screen -r ${sessionName}`;
+
       return Promise.resolve({
         success: true,
         sessionName,
-        message: `Command started in detached screen session: ${sessionName}\nReattach with: screen -r ${sessionName}`,
+        message,
       });
     } else {
       // Attached mode: always use detached mode with log capture
@@ -371,7 +397,7 @@ function runInScreen(command, options = {}) {
 /**
  * Run command in tmux
  * @param {string} command - Command to execute
- * @param {object} options - Options (session, detached)
+ * @param {object} options - Options (session, detached, keepAlive)
  * @returns {Promise<{success: boolean, sessionName: string, message: string}>}
  */
 function runInTmux(command, options = {}) {
@@ -385,24 +411,48 @@ function runInTmux(command, options = {}) {
   }
 
   const sessionName = options.session || generateSessionName('tmux');
+  const shellInfo = getShell();
+  const { shell } = shellInfo;
 
   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}`;
+      }
+      // Without keep-alive: command runs and session exits naturally when done
+
       if (DEBUG) {
         console.log(
-          `[DEBUG] Running: tmux new-session -d -s "${sessionName}" "${command}"`
+          `[DEBUG] Running: tmux new-session -d -s "${sessionName}" "${effectiveCommand}"`
         );
+        console.log(`[DEBUG] keepAlive: ${options.keepAlive || false}`);
       }
 
-      execSync(`tmux new-session -d -s "${sessionName}" "${command}"`, {
-        stdio: 'inherit',
-      });
+      execSync(
+        `tmux new-session -d -s "${sessionName}" "${effectiveCommand}"`,
+        {
+          stdio: 'inherit',
+        }
+      );
+
+      let message = `Command started in detached tmux session: ${sessionName}`;
+      if (options.keepAlive) {
+        message += `\nSession will stay alive after command completes.`;
+      } else {
+        message += `\nSession will exit automatically after command completes.`;
+      }
+      message += `\nReattach with: tmux attach -t ${sessionName}`;
 
       return Promise.resolve({
         success: true,
         sessionName,
-        message: `Command started in detached tmux session: ${sessionName}\nReattach with: tmux attach -t ${sessionName}`,
+        message,
       });
     } else {
       // Attached mode: tmux new-session -s <session> '<command>'
@@ -451,7 +501,7 @@ function runInTmux(command, options = {}) {
 /**
  * Run command in Docker container
  * @param {string} command - Command to execute
- * @param {object} options - Options (image, session/name, detached)
+ * @param {object} options - Options (image, session/name, detached, keepAlive, autoRemoveDockerContainer)
  * @returns {Promise<{success: boolean, containerName: string, message: string}>}
  */
 function runInDocker(command, options = {}) {
@@ -477,6 +527,16 @@ function runInDocker(command, options = {}) {
   try {
     if (options.detached) {
       // Detached mode: docker run -d --name <name> <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;
+
+      if (options.keepAlive) {
+        // With keep-alive: run command, then keep shell alive
+        effectiveCommand = `${command}; exec /bin/sh`;
+      }
+      // Without keep-alive: container exits naturally when command completes
+
       const dockerArgs = [
         'run',
         '-d',
@@ -485,22 +545,47 @@ function runInDocker(command, options = {}) {
         options.image,
         '/bin/sh',
         '-c',
-        command,
+        effectiveCommand,
       ];
 
+      // Add --rm flag if autoRemoveDockerContainer is true
+      // Note: --rm must come before the image name
+      if (options.autoRemoveDockerContainer) {
+        dockerArgs.splice(2, 0, '--rm');
+      }
+
       if (DEBUG) {
         console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
+        console.log(`[DEBUG] keepAlive: ${options.keepAlive || false}`);
+        console.log(
+          `[DEBUG] autoRemoveDockerContainer: ${options.autoRemoveDockerContainer || false}`
+        );
       }
 
       const containerId = execSync(`docker ${dockerArgs.join(' ')}`, {
         encoding: 'utf8',
       }).trim();
 
+      let message = `Command started in detached docker container: ${containerName}`;
+      message += `\nContainer ID: ${containerId.substring(0, 12)}`;
+      if (options.keepAlive) {
+        message += `\nContainer will stay alive after command completes.`;
+      } else {
+        message += `\nContainer will exit automatically after command completes.`;
+      }
+      if (options.autoRemoveDockerContainer) {
+        message += `\nContainer will be automatically removed after exit.`;
+      } else {
+        message += `\nContainer filesystem will be preserved after exit.`;
+      }
+      message += `\nAttach with: docker attach ${containerName}`;
+      message += `\nView logs: docker logs ${containerName}`;
+
       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}`,
+        message,
       });
     } else {
       // Attached mode: docker run -it --name <name> <image> <shell> -c '<command>'

package/test/args-parser.test.js

@@ -219,6 +219,136 @@ describe('parseArgs', () => {
     });
   });
 
+  describe('keep-alive option', () => {
+    it('should parse --keep-alive flag', () => {
+      const result = parseArgs([
+        '--isolated',
+        'tmux',
+        '--keep-alive',
+        '--',
+        'npm',
+        'test',
+      ]);
+      assert.strictEqual(result.wrapperOptions.keepAlive, true);
+    });
+
+    it('should parse -k shorthand', () => {
+      const result = parseArgs(['-i', 'screen', '-k', '--', 'npm', 'start']);
+      assert.strictEqual(result.wrapperOptions.keepAlive, true);
+    });
+
+    it('should default keepAlive to false', () => {
+      const result = parseArgs(['-i', 'tmux', '--', 'npm', 'test']);
+      assert.strictEqual(result.wrapperOptions.keepAlive, false);
+    });
+
+    it('should throw error for keep-alive without isolation', () => {
+      assert.throws(() => {
+        parseArgs(['--keep-alive', '--', 'npm', 'test']);
+      }, /--keep-alive option is only valid with --isolated/);
+    });
+
+    it('should work with detached mode', () => {
+      const result = parseArgs([
+        '-i',
+        'screen',
+        '-d',
+        '-k',
+        '--',
+        'npm',
+        'start',
+      ]);
+      assert.strictEqual(result.wrapperOptions.isolated, 'screen');
+      assert.strictEqual(result.wrapperOptions.detached, true);
+      assert.strictEqual(result.wrapperOptions.keepAlive, true);
+    });
+
+    it('should work with docker', () => {
+      const result = parseArgs([
+        '-i',
+        'docker',
+        '--image',
+        'node:20',
+        '-k',
+        '--',
+        'npm',
+        'test',
+      ]);
+      assert.strictEqual(result.wrapperOptions.isolated, 'docker');
+      assert.strictEqual(result.wrapperOptions.image, 'node:20');
+      assert.strictEqual(result.wrapperOptions.keepAlive, true);
+    });
+  });
+
+  describe('auto-remove-docker-container option', () => {
+    it('should parse --auto-remove-docker-container flag', () => {
+      const result = parseArgs([
+        '--isolated',
+        'docker',
+        '--image',
+        'alpine',
+        '--auto-remove-docker-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+      assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
+    });
+
+    it('should default autoRemoveDockerContainer to false', () => {
+      const result = parseArgs([
+        '-i',
+        'docker',
+        '--image',
+        'alpine',
+        '--',
+        'npm',
+        'test',
+      ]);
+      assert.strictEqual(
+        result.wrapperOptions.autoRemoveDockerContainer,
+        false
+      );
+    });
+
+    it('should throw error for auto-remove-docker-container without docker isolation', () => {
+      assert.throws(() => {
+        parseArgs([
+          '-i',
+          'tmux',
+          '--auto-remove-docker-container',
+          '--',
+          'npm',
+          'test',
+        ]);
+      }, /--auto-remove-docker-container option is only valid with --isolated docker/);
+    });
+
+    it('should throw error for auto-remove-docker-container without isolation', () => {
+      assert.throws(() => {
+        parseArgs(['--auto-remove-docker-container', '--', 'npm', 'test']);
+      }, /--auto-remove-docker-container option is only valid with --isolated docker/);
+    });
+
+    it('should work with keep-alive and auto-remove-docker-container', () => {
+      const result = parseArgs([
+        '-i',
+        'docker',
+        '--image',
+        'node:20',
+        '-k',
+        '--auto-remove-docker-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+      assert.strictEqual(result.wrapperOptions.isolated, 'docker');
+      assert.strictEqual(result.wrapperOptions.image, 'node:20');
+      assert.strictEqual(result.wrapperOptions.keepAlive, true);
+      assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
+    });
+  });
+
   describe('command without separator', () => {
     it('should parse command after options without separator', () => {
       const result = parseArgs(['-i', 'tmux', '-d', 'npm', 'start']);

package/test/docker-autoremove.test.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env bun
+/**
+ * Tests for Docker auto-remove container feature
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { isCommandAvailable } = require('../src/lib/isolation');
+const { runInDocker } = require('../src/lib/isolation');
+const { execSync } = require('child_process');
+
+// Helper to wait for a condition with timeout
+async function waitFor(conditionFn, timeout = 5000, interval = 100) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    if (conditionFn()) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+  return false;
+}
+
+// Helper function to check if docker daemon is running
+function isDockerRunning() {
+  if (!isCommandAvailable('docker')) {
+    return false;
+  }
+  try {
+    execSync('docker info', { stdio: 'ignore', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('Docker Auto-Remove Container Feature', () => {
+  // These tests verify the --auto-remove-docker-container option
+  // which automatically removes the container after exit (disabled by default)
+
+  describe('auto-remove enabled', () => {
+    it('should automatically remove container when autoRemoveDockerContainer is true', async () => {
+      if (!isDockerRunning()) {
+        console.log('  Skipping: docker not available or daemon not running');
+        return;
+      }
+
+      const containerName = `test-autoremove-${Date.now()}`;
+
+      // Run command with autoRemoveDockerContainer enabled
+      const result = await runInDocker('echo "test" && sleep 0.5', {
+        image: 'alpine:latest',
+        session: containerName,
+        detached: true,
+        keepAlive: false,
+        autoRemoveDockerContainer: true,
+      });
+
+      assert.strictEqual(result.success, true);
+      assert.ok(
+        result.message.includes('automatically removed'),
+        'Message should indicate auto-removal'
+      );
+
+      // Wait for container to finish and be removed
+      const containerRemoved = await waitFor(() => {
+        try {
+          execSync(`docker inspect -f '{{.State.Status}}' ${containerName}`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          return false; // Container still exists
+        } catch {
+          return true; // Container does not exist (removed)
+        }
+      }, 10000);
+
+      assert.ok(
+        containerRemoved,
+        'Container should be automatically removed after exit with --auto-remove-docker-container'
+      );
+
+      // Double-check with docker ps -a that container is completely removed
+      try {
+        const allContainers = execSync('docker ps -a', {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        assert.ok(
+          !allContainers.includes(containerName),
+          'Container should NOT appear in docker ps -a (completely removed)'
+        );
+        console.log(
+          '  ✓ Docker container auto-removed after exit (filesystem not preserved)'
+        );
+      } catch (err) {
+        assert.fail(`Failed to verify container removal: ${err.message}`);
+      }
+
+      // No cleanup needed - container should already be removed
+    });
+  });
+
+  describe('auto-remove disabled (default)', () => {
+    it('should preserve container filesystem by default (without autoRemoveDockerContainer)', async () => {
+      if (!isDockerRunning()) {
+        console.log('  Skipping: docker not available or daemon not running');
+        return;
+      }
+
+      const containerName = `test-preserve-${Date.now()}`;
+
+      // Run command without autoRemoveDockerContainer
+      const result = await runInDocker('echo "test" && sleep 0.1', {
+        image: 'alpine:latest',
+        session: containerName,
+        detached: true,
+        keepAlive: false,
+        autoRemoveDockerContainer: false,
+      });
+
+      assert.strictEqual(result.success, true);
+      assert.ok(
+        result.message.includes('filesystem will be preserved'),
+        'Message should indicate filesystem preservation'
+      );
+
+      // Wait for container to exit
+      await waitFor(() => {
+        try {
+          const status = execSync(
+            `docker inspect -f '{{.State.Status}}' ${containerName}`,
+            {
+              encoding: 'utf8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+            }
+          ).trim();
+          return status === 'exited';
+        } catch {
+          return false;
+        }
+      }, 10000);
+
+      // Container should still exist (in exited state)
+      try {
+        const allContainers = execSync('docker ps -a', {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        assert.ok(
+          allContainers.includes(containerName),
+          'Container should appear in docker ps -a (filesystem preserved)'
+        );
+        console.log(
+          '  ✓ Docker container filesystem preserved by default (can be re-entered)'
+        );
+      } catch (err) {
+        assert.fail(`Failed to verify container preservation: ${err.message}`);
+      }
+
+      // Clean up
+      try {
+        execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
+      } catch {
+        // Ignore cleanup errors
+      }
+    });
+  });
+});