start-command 0.29.1 → 0.30.0

package/test/args-parser-docker-cleanup.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env bun
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs } = require('../src/lib/args-parser');
+
+function parseDocker(args = []) {
+  return parseArgs([
+    '--isolated',
+    'docker',
+    '--image',
+    'alpine',
+    ...args,
+    '--',
+    'npm',
+    'test',
+  ]);
+}
+
+describe('docker container cleanup options', () => {
+  it('should parse --auto-remove-docker-container flag', () => {
+    const result = parseDocker(['--auto-remove-docker-container']);
+    assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, true);
+  });
+
+  it('should parse --always-cleanup-container flag', () => {
+    const result = parseDocker(['--always-cleanup-container']);
+    assert.strictEqual(result.wrapperOptions.alwaysCleanupContainer, true);
+  });
+
+  it('should parse --keep-container flag', () => {
+    const result = parseDocker(['--keep-container']);
+    assert.strictEqual(result.wrapperOptions.keepContainer, true);
+  });
+
+  it('should parse --keep-container-on-fail flag', () => {
+    const result = parseDocker(['--keep-container-on-fail']);
+    assert.strictEqual(result.wrapperOptions.keepContainerOnFail, true);
+  });
+
+  it('should default cleanup flags to false', () => {
+    const result = parseDocker();
+    assert.strictEqual(result.wrapperOptions.autoRemoveDockerContainer, false);
+    assert.strictEqual(result.wrapperOptions.alwaysCleanupContainer, false);
+    assert.strictEqual(result.wrapperOptions.keepContainer, false);
+    assert.strictEqual(result.wrapperOptions.keepContainerOnFail, false);
+  });
+
+  it('should throw error for docker cleanup options without docker isolation', () => {
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'tmux',
+        '--auto-remove-docker-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'tmux',
+        '--always-cleanup-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /--always-cleanup-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['-i', 'tmux', '--keep-container', '--', 'npm', 'test']);
+    }, /--keep-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'tmux',
+        '--keep-container-on-fail',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /--keep-container-on-fail option is only valid when isolation stack includes docker/);
+  });
+
+  it('should throw error for docker cleanup options without isolation', () => {
+    assert.throws(() => {
+      parseArgs(['--auto-remove-docker-container', '--', 'npm', 'test']);
+    }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--always-cleanup-container', '--', 'npm', 'test']);
+    }, /--always-cleanup-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--keep-container', '--', 'npm', 'test']);
+    }, /--keep-container option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--keep-container-on-fail', '--', 'npm', 'test']);
+    }, /--keep-container-on-fail option is only valid when isolation stack includes 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);
+  });
+
+  it('should reject conflicting docker cleanup options', () => {
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'docker',
+        '--keep-container',
+        '--always-cleanup-container',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /Cannot combine docker container cleanup policies/);
+
+    assert.throws(() => {
+      parseArgs([
+        '-i',
+        'docker',
+        '--keep-container',
+        '--keep-container-on-fail',
+        '--',
+        'npm',
+        'test',
+      ]);
+    }, /Cannot combine docker container cleanup policies/);
+  });
+});

package/test/args-parser.js

@@ -343,75 +343,6 @@ describe('parseArgs', () => {
     });
   });
 
-  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 when isolation stack includes 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 when isolation stack includes 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/command-builder-docker-cleanup.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { buildNextLevelCommand } = require('../src/lib/command-builder');
+
+describe('command-builder docker cleanup forwarding', () => {
+  it('forwards cleanup policy flags when a remaining level uses docker', () => {
+    const command = buildNextLevelCommand(
+      {
+        isolatedStack: ['tmux', 'docker'],
+        imageStack: [null, 'alpine'],
+        keepContainerOnFail: true,
+      },
+      'npm test'
+    );
+
+    assert.match(command, /--isolated "docker"/);
+    assert.match(command, /--keep-container-on-fail/);
+  });
+
+  it('does not forward docker cleanup flags after the docker level is consumed', () => {
+    const command = buildNextLevelCommand(
+      {
+        isolatedStack: ['docker', 'tmux'],
+        imageStack: ['alpine', null],
+        keepContainer: true,
+      },
+      'npm test'
+    );
+
+    assert.match(command, /--isolated "tmux"/);
+    assert.doesNotMatch(command, /--keep-container/);
+  });
+});

package/test/docker-autoremove.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env bun
 /**
- * Tests for Docker auto-remove container feature
+ * Tests for Docker container cleanup behavior
  */
 
 const { describe, it } = require('node:test');
 const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { isCommandAvailable } = require('../src/lib/isolation');
 const { runInDocker } = require('../src/lib/isolation');
 const { execSync } = require('child_process');
@@ -26,9 +29,9 @@ async function waitFor(conditionFn, timeout = 5000, interval = 100) {
 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('Docker Container Cleanup Policy', () => {
+  // These tests verify that docker isolation removes finished containers by
+  // default while still providing explicit flags to keep them for investigation.
 
   describe('auto-remove enabled', () => {
     it(
@@ -55,8 +58,8 @@ describe('Docker Auto-Remove Container Feature', () => {
 
         assert.strictEqual(result.success, true);
         assert.ok(
-          result.message.includes('automatically removed'),
-          'Message should indicate auto-removal'
+          result.message.includes('will be removed'),
+          'Message should indicate cleanup'
         );
 
         // Wait for container to finish and be removed
@@ -99,9 +102,9 @@ describe('Docker Auto-Remove Container Feature', () => {
     );
   });
 
-  describe('auto-remove disabled (default)', () => {
+  describe('default cleanup', () => {
     it(
-      'should preserve container filesystem by default (without autoRemoveDockerContainer)',
+      'should remove container filesystem by default',
       { timeout: DOCKER_TEST_TIMEOUT },
       async () => {
         if (!canRunLinuxDockerImages()) {
@@ -111,9 +114,10 @@ describe('Docker Auto-Remove Container Feature', () => {
           return;
         }
 
-        const containerName = `test-preserve-${Date.now()}`;
+        const containerName = `test-default-cleanup-${Date.now()}`;
 
-        // Run command without autoRemoveDockerContainer
+        // Run command without any cleanup flag. The default should still remove
+        // the container after the command finishes.
         const result = await runInDocker('echo "test" && sleep 0.1', {
           image: 'alpine:latest',
           session: containerName,
@@ -124,12 +128,76 @@ describe('Docker Auto-Remove Container Feature', () => {
 
         assert.strictEqual(result.success, true);
         assert.ok(
-          result.message.includes('filesystem will be preserved'),
-          'Message should indicate filesystem preservation'
+          result.message.includes('will be removed'),
+          'Message should indicate default cleanup'
         );
 
-        // Wait for container to exit
-        await waitFor(() => {
+        const containerRemoved = await waitFor(() => {
+          try {
+            execSync(`docker inspect -f '{{.State.Status}}' ${containerName}`, {
+              encoding: 'utf8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return false;
+          } catch {
+            return true;
+          }
+        }, 10000);
+
+        assert.ok(
+          containerRemoved,
+          'Container should be removed after exit by default'
+        );
+
+        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 after default cleanup'
+          );
+        } catch (err) {
+          assert.fail(`Failed to verify container cleanup: ${err.message}`);
+        }
+      }
+    );
+  });
+
+  describe('keep-container opt-out', () => {
+    it(
+      'should preserve container filesystem when keepContainer 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-keep-container-${Date.now()}`;
+
+        const result = await runInDocker('echo "test" && sleep 0.1', {
+          image: 'alpine:latest',
+          session: containerName,
+          detached: true,
+          keepAlive: false,
+          keepContainer: true,
+        });
+
+        assert.strictEqual(result.success, true);
+        assert.ok(
+          result.message.includes('Container kept for investigation'),
+          'Message should explain that the container is kept'
+        );
+        assert.ok(
+          result.message.includes(`docker rm -f ${containerName}`),
+          'Message should include cleanup command'
+        );
+
+        const containerExited = await waitFor(() => {
           try {
             const status = execSync(
               `docker inspect -f '{{.State.Status}}' ${containerName}`,
@@ -144,26 +212,66 @@ describe('Docker Auto-Remove Container Feature', () => {
           }
         }, 10000);
 
-        // Container should still exist (in exited state)
+        assert.ok(containerExited, 'Container should remain 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)'
-          );
+          execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+    );
+
+    it(
+      'should preserve failed containers when keepContainerOnFail is true',
+      { timeout: DOCKER_TEST_TIMEOUT },
+      async () => {
+        if (!canRunLinuxDockerImages()) {
           console.log(
-            '  ✓ Docker container filesystem preserved by default (can be re-entered)'
-          );
-        } catch (err) {
-          assert.fail(
-            `Failed to verify container preservation: ${err.message}`
+            '  Skipping: docker not available, daemon not running, or Linux containers not supported'
           );
+          return;
         }
 
-        // Clean up
+        const containerName = `test-keep-on-fail-${Date.now()}`;
+
+        const result = await runInDocker('echo "test" && exit 7', {
+          image: 'alpine:latest',
+          session: containerName,
+          detached: true,
+          keepAlive: false,
+          keepContainerOnFail: true,
+        });
+
+        assert.strictEqual(result.success, true);
+        assert.ok(
+          result.message.includes(
+            'Container will be kept if the command fails'
+          ),
+          'Message should describe failure retention'
+        );
+        assert.ok(
+          result.message.includes(`docker rm -f ${containerName}`),
+          'Message should include cleanup command'
+        );
+
+        const containerExited = await waitFor(() => {
+          try {
+            const status = execSync(
+              `docker inspect -f '{{.State.Status}} {{.State.ExitCode}}' ${containerName}`,
+              {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+              }
+            ).trim();
+            return status === 'exited 7';
+          } catch {
+            return false;
+          }
+        }, 10000);
+
+        assert.ok(containerExited, 'Failed container should be preserved');
+
         try {
           execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
         } catch {
@@ -172,4 +280,71 @@ describe('Docker Auto-Remove Container Feature', () => {
       }
     );
   });
+
+  describe('attached mode logging', () => {
+    it(
+      'should write attached docker output to the provided host log path',
+      { 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-attached-log-${Date.now()}`;
+        const logPath = path.join(
+          os.tmpdir(),
+          `start-attached-docker-${process.pid}-${Date.now()}.log`
+        );
+        fs.writeFileSync(logPath, '=== test log header ===\n');
+
+        try {
+          const result = await runInDocker("printf 'attached-log-line\\n'", {
+            image: 'alpine:latest',
+            session: containerName,
+            detached: false,
+            keepAlive: false,
+            logPath,
+          });
+
+          assert.strictEqual(result.success, true);
+          assert.ok(
+            result.message.includes('Container removed after completion'),
+            'Attached container should be removed after completion by default'
+          );
+
+          const contents = fs.readFileSync(logPath, 'utf8');
+          assert.ok(
+            contents.includes('attached-log-line'),
+            `Attached docker output should be written to host log, got:\n${contents}`
+          );
+
+          const containerRemoved = await waitFor(() => {
+            try {
+              execSync(
+                `docker inspect -f '{{.State.Status}}' ${containerName}`,
+                {
+                  encoding: 'utf8',
+                  stdio: ['pipe', 'pipe', 'pipe'],
+                }
+              );
+              return false;
+            } catch {
+              return true;
+            }
+          }, 10000);
+          assert.ok(containerRemoved, 'Attached container should be removed');
+        } finally {
+          try {
+            execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' });
+          } catch {
+            // Ignore cleanup errors
+          }
+          fs.rmSync(logPath, { force: true });
+        }
+      }
+    );
+  });
 });