start-command 0.26.0 → 0.27.0

package/src/lib/usage.js

@@ -1,6 +1,6 @@
 /** Print usage information */
 function printUsage() {
-  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>]
+  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>] | $ --stop <id> | $ --terminate <id>
 
 Options:
   --isolated, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
@@ -19,6 +19,8 @@ Options:
   --use-command-stream  Use command-stream library for execution (experimental)
   --status <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)
   --list                List all tracked executions (--output-format: links-notation|json|text)
+  --stop <id>           Send CTRL+C/SIGINT to a detached isolated execution
+  --terminate <id>      Terminate a detached isolated execution immediately
   --cleanup             Clean up stale "executing" records (crashed/killed processes)
   --cleanup-dry-run     Show stale records that would be cleaned up (without cleaning)
   --version, -v         Show version information
@@ -36,6 +38,8 @@ Examples:
   $ --isolated-user --keep-user -- npm start
   $ --list                                 # List stored execution records
   $ --list --output-format json            # List stored records as JSON
+  $ --stop my-screen-session               # Ask detached execution to stop gracefully
+  $ --terminate my-screen-session          # Terminate detached execution immediately
   $ --use-command-stream echo "Hello"      # Use command-stream library`);
   console.log('');
   console.log('Piping with $:');

package/test/args-parser-control.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs } = require('../src/lib/args-parser');
+
+describe('control options', () => {
+  it('should parse --stop with UUID or session name', () => {
+    const result = parseArgs(['--stop', 'my-session']);
+    assert.strictEqual(result.wrapperOptions.stop, 'my-session');
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --stop=value format', () => {
+    const result = parseArgs(['--stop=my-session']);
+    assert.strictEqual(result.wrapperOptions.stop, 'my-session');
+  });
+
+  it('should parse --terminate with UUID or session name', () => {
+    const result = parseArgs(['--terminate', 'my-session']);
+    assert.strictEqual(result.wrapperOptions.terminate, 'my-session');
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --terminate=value format', () => {
+    const result = parseArgs(['--terminate=my-session']);
+    assert.strictEqual(result.wrapperOptions.terminate, 'my-session');
+  });
+
+  it('should throw error for missing --stop argument', () => {
+    assert.throws(() => {
+      parseArgs(['--stop']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for empty --stop=value argument', () => {
+    assert.throws(() => {
+      parseArgs(['--stop=']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for missing --terminate argument', () => {
+    assert.throws(() => {
+      parseArgs(['--terminate']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for empty --terminate=value argument', () => {
+    assert.throws(() => {
+      parseArgs(['--terminate=']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should reject combining query and control modes', () => {
+    assert.throws(() => {
+      parseArgs(['--status', 'uuid-here', '--stop', 'my-session']);
+    }, /Cannot combine --status, --list, --stop, --terminate, or --cleanup/);
+  });
+
+  it('should reject output-format with control modes', () => {
+    assert.throws(() => {
+      parseArgs(['--stop', 'my-session', '--output-format', 'json']);
+    }, /--output-format option is only valid with --status or --list/);
+  });
+
+  it('should default control options to null', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.stop, null);
+    assert.strictEqual(result.wrapperOptions.terminate, null);
+  });
+});

package/test/{args-parser.test.js → args-parser.js}

@@ -952,4 +952,4 @@ describe('cleanup options', () => {
   });
 });
 
-// Shell option tests moved to args-parser-shell.test.js
+// Shell option tests moved to args-parser-shell.js

package/test/cli.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env bun
+/**
+ * Unit tests for the CLI
+ * Tests version flag and basic CLI behavior
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Path to the CLI script
+const CLI_PATH = path.join(__dirname, '../src/bin/cli.js');
+
+// Timeout for CLI operations - longer on Windows due to cold-start latency
+const CLI_TIMEOUT = process.platform === 'win32' ? 30000 : 10000;
+const CLI_TEST_TIMEOUT = CLI_TIMEOUT + 5000;
+
+// Helper to run CLI with timeout
+function runCLI(args = [], options = {}) {
+  return spawnSync('bun', [CLI_PATH, ...args], {
+    encoding: 'utf8',
+    timeout: options.timeout ?? CLI_TIMEOUT,
+    env: {
+      ...process.env,
+      START_DISABLE_AUTO_ISSUE: '1',
+      START_DISABLE_LOG_UPLOAD: '1',
+    },
+  });
+}
+
+describe('CLI version flag', () => {
+  it(
+    'should display version with --version',
+    { timeout: CLI_TEST_TIMEOUT },
+    () => {
+      const result = runCLI(['--version']);
+
+      // Check if process was killed (e.g., due to timeout)
+      assert.notStrictEqual(
+        result.status,
+        null,
+        `Process should complete (was killed with signal: ${result.signal})`
+      );
+      assert.strictEqual(result.status, 0, 'Exit code should be 0');
+
+      // Check for key elements in version output
+      assert.ok(
+        result.stdout.includes('start-command version:'),
+        'Should display start-command version'
+      );
+      assert.ok(result.stdout.includes('OS:'), 'Should display OS');
+      assert.ok(
+        result.stdout.includes('OS Version:'),
+        'Should display OS Version'
+      );
+      // Check for either Bun or Node.js version depending on runtime
+      const hasBunVersion = result.stdout.includes('Bun Version:');
+      const hasNodeVersion = result.stdout.includes('Node.js Version:');
+      assert.ok(
+        hasBunVersion || hasNodeVersion,
+        'Should display Bun Version or Node.js Version'
+      );
+      assert.ok(
+        result.stdout.includes('Architecture:'),
+        'Should display Architecture'
+      );
+      assert.ok(
+        result.stdout.includes('Isolation tools:'),
+        'Should display Isolation tools section'
+      );
+      assert.ok(
+        result.stdout.includes('screen:'),
+        'Should check for screen installation'
+      );
+      assert.ok(
+        result.stdout.includes('tmux:'),
+        'Should check for tmux installation'
+      );
+      assert.ok(
+        result.stdout.includes('docker:'),
+        'Should check for docker installation'
+      );
+    }
+  );
+
+  it('should display version with -v', { timeout: CLI_TEST_TIMEOUT }, () => {
+    const result = runCLI(['-v']);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+    assert.ok(
+      result.stdout.includes('start-command version:'),
+      'Should display start-command version'
+    );
+  });
+
+  it(
+    'should show correct package version',
+    { timeout: CLI_TEST_TIMEOUT },
+    () => {
+      const result = runCLI(['--version']);
+      const packageJson = JSON.parse(
+        fs.readFileSync(path.join(__dirname, '../package.json'), 'utf8')
+      );
+
+      assert.ok(
+        result.stdout.includes(`start-command version: ${packageJson.version}`),
+        `Should display version ${packageJson.version}`
+      );
+    }
+  );
+});
+
+describe('CLI basic behavior', () => {
+  it('should show usage when no arguments provided', () => {
+    const result = runCLI([]);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+    assert.ok(result.stdout.includes('Usage:'), 'Should display usage');
+    assert.ok(
+      result.stdout.includes('--version'),
+      'Usage should mention --version flag'
+    );
+  });
+
+  it('should show usage when no command provided after --', () => {
+    const result = runCLI(['--']);
+
+    assert.strictEqual(result.status, 0, 'Exit code should be 0');
+    assert.ok(result.stdout.includes('Usage:'), 'Should display usage');
+  });
+});
+
+describe('CLI isolation output (issue #67)', () => {
+  const { isCommandAvailable } = require('../src/lib/isolation');
+
+  it('should display screen session name when using screen isolation', async () => {
+    if (!isCommandAvailable('screen')) {
+      console.log('  Skipping: screen not installed');
+      return;
+    }
+
+    const result = runCLI(['-i', 'screen', '--', 'echo', 'hello']);
+
+    // The output should contain the screen session name (in format screen-timestamp-random)
+    // Check that the session UUID is displayed
+    assert.ok(
+      result.stdout.includes('│ session'),
+      'Should display session UUID'
+    );
+    // Check that screen isolation info is displayed
+    assert.ok(
+      result.stdout.includes('│ isolation screen'),
+      'Should display screen isolation'
+    );
+    // Check that the actual screen session name is displayed (issue #67 fix)
+    assert.ok(
+      result.stdout.includes('│ screen    screen-'),
+      'Should display actual screen session name for reconnection (issue #67)'
+    );
+  });
+
+  it('should display tmux session name when using tmux isolation', async () => {
+    if (!isCommandAvailable('tmux')) {
+      console.log('  Skipping: tmux not installed');
+      return;
+    }
+
+    const result = runCLI(['-i', 'tmux', '--', 'echo', 'hello']);
+
+    // The output should contain the tmux session name
+    assert.ok(
+      result.stdout.includes('│ session'),
+      'Should display session UUID'
+    );
+    assert.ok(
+      result.stdout.includes('│ isolation tmux'),
+      'Should display tmux isolation'
+    );
+    // Check that the actual tmux session name is displayed (issue #67 fix)
+    assert.ok(
+      result.stdout.includes('│ tmux      tmux-'),
+      'Should display actual tmux session name for reconnection (issue #67)'
+    );
+  });
+
+  it(
+    'should display docker container name when using docker isolation',
+    { timeout: 70000 },
+    () => {
+      const { canRunLinuxDockerImages } = require('../src/lib/isolation');
+
+      if (!canRunLinuxDockerImages()) {
+        console.log(
+          '  Skipping: docker not available or cannot run Linux images'
+        );
+        return;
+      }
+
+      const containerName = `docker-cli-${Date.now()}`;
+      let result;
+      try {
+        result = runCLI(
+          [
+            '-i',
+            'docker',
+            '-d',
+            '--session',
+            containerName,
+            '--image',
+            'alpine:latest',
+            '--',
+            'echo',
+            'hello',
+          ],
+          { timeout: 60000 }
+        );
+      } finally {
+        try {
+          execSync(`docker rm -f ${containerName}`, {
+            stdio: 'ignore',
+          });
+        } catch {
+          // Container may have already exited.
+        }
+      }
+
+      assert.notStrictEqual(
+        result.status,
+        null,
+        `CLI should complete before timeout. signal=${result.signal}, stderr=${result.stderr}`
+      );
+      assert.strictEqual(
+        result.status,
+        0,
+        `CLI should exit 0. stdout=${result.stdout}, stderr=${result.stderr}`
+      );
+
+      // The output should contain the docker container name
+      assert.ok(
+        result.stdout.includes('│ session'),
+        'Should display session UUID'
+      );
+      assert.ok(
+        result.stdout.includes('│ isolation docker'),
+        'Should display docker isolation'
+      );
+      assert.ok(
+        result.stdout.includes('│ image     alpine:latest'),
+        'Should display docker image'
+      );
+      // Check that the actual container name is displayed (issue #67 fix)
+      assert.ok(
+        result.stdout.includes('│ container docker-'),
+        'Should display actual container name for reconnection (issue #67)'
+      );
+    }
+  );
+});

package/test/docker-autoremove.js

@@ -0,0 +1,175 @@
+#!/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;
+}
+
+// Use the canRunLinuxDockerImages function from isolation module
+// to properly detect if Linux containers can run (handles Windows containers mode)
+const { canRunLinuxDockerImages } = require('../src/lib/isolation');
+const DOCKER_TEST_TIMEOUT = 20000;
+
+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',
+      { timeout: DOCKER_TEST_TIMEOUT },
+      async () => {
+        if (!canRunLinuxDockerImages()) {
+          console.log(
+            '  Skipping: docker not available, daemon not running, or Linux containers not supported'
+          );
+          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)',
+      { timeout: DOCKER_TEST_TIMEOUT },
+      async () => {
+        if (!canRunLinuxDockerImages()) {
+          console.log(
+            '  Skipping: docker not available, daemon not running, or Linux containers not supported'
+          );
+          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
+        }
+      }
+    );
+  });
+});