start-command 0.20.3 → 0.21.0

package/src/lib/sequence-parser.js

@@ -0,0 +1,231 @@
+/**
+ * Sequence Parser for Isolation Stacking
+ *
+ * Parses space-separated sequences with underscore placeholders for
+ * distributing options across isolation levels.
+ *
+ * Based on Links Notation conventions (https://github.com/link-foundation/links-notation)
+ */
+
+/**
+ * Parse a space-separated sequence with underscore placeholders
+ * @param {string} value - Space-separated values (e.g., "screen ssh docker")
+ * @returns {(string|null)[]} Array of values, with null for underscore placeholders
+ */
+function parseSequence(value) {
+  if (!value || typeof value !== 'string') {
+    return [];
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  // Split by whitespace
+  const parts = trimmed.split(/\s+/);
+
+  // Convert underscores to null (placeholder)
+  return parts.map((v) => (v === '_' ? null : v));
+}
+
+/**
+ * Format a sequence array back to a string
+ * @param {(string|null)[]} sequence - Array of values with nulls for placeholders
+ * @returns {string} Space-separated string with underscores for nulls
+ */
+function formatSequence(sequence) {
+  if (!Array.isArray(sequence) || sequence.length === 0) {
+    return '';
+  }
+
+  return sequence.map((v) => (v === null ? '_' : v)).join(' ');
+}
+
+/**
+ * Shift sequence by removing first element
+ * @param {(string|null)[]} sequence - Parsed sequence
+ * @returns {(string|null)[]} New sequence without first element
+ */
+function shiftSequence(sequence) {
+  if (!Array.isArray(sequence) || sequence.length === 0) {
+    return [];
+  }
+  return sequence.slice(1);
+}
+
+/**
+ * Check if a string represents a multi-value sequence (contains spaces)
+ * @param {string} value - Value to check
+ * @returns {boolean} True if contains spaces (multi-value)
+ */
+function isSequence(value) {
+  return typeof value === 'string' && value.includes(' ');
+}
+
+/**
+ * Distribute a single option value across all isolation levels
+ * If the value is a sequence, validate length matches stack depth
+ * If the value is a single value, replicate it for all levels
+ *
+ * @param {string} optionValue - Space-separated or single value
+ * @param {number} stackDepth - Number of isolation levels
+ * @param {string} optionName - Name of option for error messages
+ * @returns {(string|null)[]} Array of values for each level
+ * @throws {Error} If sequence length doesn't match stack depth
+ */
+function distributeOption(optionValue, stackDepth, optionName) {
+  if (!optionValue) {
+    return Array(stackDepth).fill(null);
+  }
+
+  const parsed = parseSequence(optionValue);
+
+  // Single value: replicate for all levels
+  if (parsed.length === 1 && stackDepth > 1) {
+    return Array(stackDepth).fill(parsed[0]);
+  }
+
+  // Sequence: validate length matches
+  if (parsed.length !== stackDepth) {
+    throw new Error(
+      `${optionName} has ${parsed.length} value(s) but isolation stack has ${stackDepth} level(s). ` +
+        `Use underscores (_) as placeholders for levels that don't need this option.`
+    );
+  }
+
+  return parsed;
+}
+
+/**
+ * Get the value at a specific level from a distributed option
+ * @param {(string|null)[]} distributedOption - Distributed option array
+ * @param {number} level - Zero-based level index
+ * @returns {string|null} Value at that level or null
+ */
+function getValueAtLevel(distributedOption, level) {
+  if (
+    !Array.isArray(distributedOption) ||
+    level < 0 ||
+    level >= distributedOption.length
+  ) {
+    return null;
+  }
+  return distributedOption[level];
+}
+
+/**
+ * Validate that required options are provided for specific isolation types
+ * @param {(string|null)[]} isolationStack - Stack of isolation backends
+ * @param {object} options - Object containing distributed options
+ * @param {(string|null)[]} options.endpoints - Distributed endpoints for SSH
+ * @param {(string|null)[]} options.images - Distributed images for Docker
+ * @throws {Error} If required options are missing
+ */
+function validateStackOptions(isolationStack, options) {
+  const errors = [];
+
+  isolationStack.forEach((backend, i) => {
+    if (backend === 'ssh') {
+      if (!options.endpoints || !options.endpoints[i]) {
+        errors.push(
+          `Level ${i + 1} is SSH but no endpoint specified. ` +
+            `Use --endpoint with a value at position ${i + 1}.`
+        );
+      }
+    }
+    // Docker doesn't require image - has default
+    // Screen and tmux don't require special options
+  });
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('\n'));
+  }
+}
+
+/**
+ * Build remaining options for next isolation level
+ * @param {object} options - Current level options
+ * @returns {object} Options for next level
+ */
+function buildNextLevelOptions(options) {
+  const next = { ...options };
+
+  // Shift isolation stack
+  if (next.isolatedStack && next.isolatedStack.length > 1) {
+    next.isolatedStack = shiftSequence(next.isolatedStack);
+    next.isolated = next.isolatedStack[0];
+  } else {
+    next.isolatedStack = [];
+    next.isolated = null;
+  }
+
+  // Shift distributed options
+  if (next.imageStack && next.imageStack.length > 1) {
+    next.imageStack = shiftSequence(next.imageStack);
+    next.image = next.imageStack[0];
+  } else if (next.imageStack) {
+    next.imageStack = [];
+  }
+
+  if (next.endpointStack && next.endpointStack.length > 1) {
+    next.endpointStack = shiftSequence(next.endpointStack);
+    next.endpoint = next.endpointStack[0];
+  } else if (next.endpointStack) {
+    next.endpointStack = [];
+  }
+
+  if (next.sessionStack && next.sessionStack.length > 1) {
+    next.sessionStack = shiftSequence(next.sessionStack);
+    next.session = next.sessionStack[0];
+  } else if (next.sessionStack) {
+    next.sessionStack = [];
+  }
+
+  return next;
+}
+
+/**
+ * Format isolation chain for display
+ * @param {(string|null)[]} stack - Isolation stack
+ * @param {object} options - Options with distributed values
+ * @returns {string} Formatted chain (e.g., "screen → ssh@host → docker:ubuntu")
+ */
+function formatIsolationChain(stack, options = {}) {
+  if (!Array.isArray(stack) || stack.length === 0) {
+    return '';
+  }
+
+  return stack
+    .map((backend, i) => {
+      if (!backend) {
+        return '_';
+      }
+
+      if (backend === 'ssh' && options.endpointStack?.[i]) {
+        return `ssh@${options.endpointStack[i]}`;
+      }
+
+      if (backend === 'docker' && options.imageStack?.[i]) {
+        // Extract short image name
+        const image = options.imageStack[i];
+        const shortName = image.split(':')[0].split('/').pop();
+        return `docker:${shortName}`;
+      }
+
+      return backend;
+    })
+    .join(' → ');
+}
+
+module.exports = {
+  parseSequence,
+  formatSequence,
+  shiftSequence,
+  isSequence,
+  distributeOption,
+  getValueAtLevel,
+  validateStackOptions,
+  buildNextLevelOptions,
+  formatIsolationChain,
+};

package/test/args-parser.test.js

@@ -232,7 +232,7 @@ describe('parseArgs', () => {
           'npm',
           'test',
         ]);
-      }, /--image option is only valid with --isolated docker/);
+      }, /--image option is only valid when isolation stack includes docker/);
     });
   });
 
@@ -264,7 +264,7 @@ describe('parseArgs', () => {
     it('should throw error for ssh without endpoint', () => {
       assert.throws(() => {
         parseArgs(['--isolated', 'ssh', '--', 'npm', 'test']);
-      }, /SSH isolation requires --endpoint option/);
+      }, /SSH isolation at level 1 requires --endpoint option/);
     });
 
     it('should throw error for endpoint with non-ssh backend', () => {
@@ -278,7 +278,7 @@ describe('parseArgs', () => {
           'npm',
           'test',
         ]);
-      }, /--endpoint option is only valid with --isolated ssh/);
+      }, /--endpoint option is only valid when isolation stack includes ssh/);
     });
   });
 
@@ -384,13 +384,13 @@ describe('parseArgs', () => {
           'npm',
           'test',
         ]);
-      }, /--auto-remove-docker-container option is only valid with --isolated docker/);
+      }, /--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 with --isolated docker/);
+      }, /--auto-remove-docker-container option is only valid when isolation stack includes docker/);
     });
 
     it('should work with keep-alive and auto-remove-docker-container', () => {
@@ -706,7 +706,7 @@ describe('user isolation option', () => {
         'npm',
         'install',
       ]);
-    }, /--isolated-user is not supported with Docker isolation/);
+    }, /--isolated-user is not supported with Docker as the first isolation level/);
   });
 
   it('should work with tmux isolation', () => {

package/test/isolation-stacking.test.js

@@ -0,0 +1,366 @@
+/**
+ * Tests for isolation stacking feature (issue #77)
+ */
+
+const { describe, it, expect } = require('bun:test');
+const {
+  parseArgs,
+  validateOptions,
+  hasStackedIsolation,
+  MAX_ISOLATION_DEPTH,
+} = require('../src/lib/args-parser');
+
+describe('Isolation Stacking - Args Parser', () => {
+  describe('parseArgs with stacked --isolated', () => {
+    it('should parse single isolation (backward compatible)', () => {
+      const result = parseArgs(['--isolated', 'docker', '--', 'npm', 'test']);
+      expect(result.wrapperOptions.isolated).toBe('docker');
+      expect(result.wrapperOptions.isolatedStack).toEqual(['docker']);
+      expect(result.command).toBe('npm test');
+    });
+
+    it('should parse multi-level isolation', () => {
+      const result = parseArgs([
+        '--isolated',
+        'screen ssh docker',
+        '--endpoint',
+        '_ user@host _',
+        '--',
+        'npm',
+        'test',
+      ]);
+      expect(result.wrapperOptions.isolated).toBe('screen');
+      expect(result.wrapperOptions.isolatedStack).toEqual([
+        'screen',
+        'ssh',
+        'docker',
+      ]);
+    });
+
+    it('should parse 5-level isolation', () => {
+      const result = parseArgs([
+        '--isolated',
+        'screen ssh tmux ssh docker',
+        '--endpoint',
+        '_ user@server1 _ user@server2 _',
+        '--',
+        'npm',
+        'test',
+      ]);
+      expect(result.wrapperOptions.isolatedStack).toEqual([
+        'screen',
+        'ssh',
+        'tmux',
+        'ssh',
+        'docker',
+      ]);
+      expect(result.wrapperOptions.endpointStack).toEqual([
+        null,
+        'user@server1',
+        null,
+        'user@server2',
+        null,
+      ]);
+    });
+
+    it('should parse --isolated=value syntax', () => {
+      const result = parseArgs(['--isolated=screen tmux', '--', 'ls']);
+      expect(result.wrapperOptions.isolatedStack).toEqual(['screen', 'tmux']);
+    });
+  });
+
+  describe('parseArgs with stacked --image', () => {
+    it('should parse single image (backward compatible)', () => {
+      const result = parseArgs([
+        '--isolated',
+        'docker',
+        '--image',
+        'ubuntu:22.04',
+        '--',
+        'bash',
+      ]);
+      expect(result.wrapperOptions.image).toBe('ubuntu:22.04');
+    });
+
+    it('should parse image sequence with placeholders', () => {
+      const result = parseArgs([
+        '--isolated',
+        'screen docker',
+        '--image',
+        '_ ubuntu:22.04',
+        '--',
+        'bash',
+      ]);
+      expect(result.wrapperOptions.imageStack).toEqual([null, 'ubuntu:22.04']);
+    });
+
+    it('should parse --image=value syntax', () => {
+      const result = parseArgs([
+        '--isolated',
+        'docker',
+        '--image=alpine:latest',
+        '--',
+        'sh',
+      ]);
+      expect(result.wrapperOptions.image).toBe('alpine:latest');
+    });
+  });
+
+  describe('parseArgs with stacked --endpoint', () => {
+    it('should parse single endpoint (backward compatible)', () => {
+      const result = parseArgs([
+        '--isolated',
+        'ssh',
+        '--endpoint',
+        'user@host',
+        '--',
+        'ls',
+      ]);
+      expect(result.wrapperOptions.endpoint).toBe('user@host');
+    });
+
+    it('should parse endpoint sequence with placeholders', () => {
+      const result = parseArgs([
+        '--isolated',
+        'screen ssh ssh docker',
+        '--endpoint',
+        '_ user@host1 user@host2 _',
+        '--',
+        'bash',
+      ]);
+      expect(result.wrapperOptions.endpointStack).toEqual([
+        null,
+        'user@host1',
+        'user@host2',
+        null,
+      ]);
+    });
+  });
+
+  describe('hasStackedIsolation', () => {
+    it('should return true for multi-level', () => {
+      const { wrapperOptions } = parseArgs([
+        '--isolated',
+        'screen docker',
+        '--',
+        'test',
+      ]);
+      expect(hasStackedIsolation(wrapperOptions)).toBe(true);
+    });
+
+    it('should return false for single level', () => {
+      const { wrapperOptions } = parseArgs([
+        '--isolated',
+        'docker',
+        '--',
+        'test',
+      ]);
+      expect(hasStackedIsolation(wrapperOptions)).toBe(false);
+    });
+
+    it('should return false for no isolation', () => {
+      const { wrapperOptions } = parseArgs(['echo', 'hello']);
+      // When no isolation, isolatedStack is null, so hasStackedIsolation returns falsy
+      expect(hasStackedIsolation(wrapperOptions)).toBeFalsy();
+    });
+  });
+});
+
+describe('Isolation Stacking - Validation', () => {
+  describe('validateOptions', () => {
+    it('should validate single backend (backward compatible)', () => {
+      const options = {
+        isolated: 'docker',
+        isolatedStack: ['docker'],
+      };
+      expect(() => validateOptions(options)).not.toThrow();
+      // Should apply default image
+      expect(options.imageStack[0]).toBeDefined();
+    });
+
+    it('should validate multi-level stack', () => {
+      const options = {
+        isolated: 'screen',
+        isolatedStack: ['screen', 'ssh', 'docker'],
+        endpointStack: [null, 'user@host', null],
+      };
+      expect(() => validateOptions(options)).not.toThrow();
+    });
+
+    it('should throw on invalid backend in stack', () => {
+      const options = {
+        isolated: 'screen',
+        isolatedStack: ['screen', 'invalid', 'docker'],
+      };
+      expect(() => validateOptions(options)).toThrow(/Invalid isolation/);
+    });
+
+    it('should throw on missing SSH endpoint', () => {
+      const options = {
+        isolated: 'ssh',
+        isolatedStack: ['ssh'],
+        endpointStack: [null],
+      };
+      expect(() => validateOptions(options)).toThrow(/requires --endpoint/);
+    });
+
+    it('should throw on image/stack length mismatch', () => {
+      const options = {
+        isolated: 'screen',
+        isolatedStack: ['screen', 'ssh', 'docker'],
+        imageStack: [null, 'ubuntu:22.04'], // Only 2, should be 3
+        endpointStack: [null, 'user@host', null],
+      };
+      expect(() => validateOptions(options)).toThrow(/value\(s\)/);
+    });
+
+    it('should throw on depth exceeding limit', () => {
+      const tooDeep = Array(MAX_ISOLATION_DEPTH + 1).fill('screen');
+      const options = {
+        isolated: 'screen',
+        isolatedStack: tooDeep,
+      };
+      expect(() => validateOptions(options)).toThrow(/too deep/);
+    });
+
+    it('should distribute single image to all levels', () => {
+      const options = {
+        isolated: 'screen',
+        isolatedStack: ['screen', 'docker', 'docker'],
+        image: 'ubuntu:22.04',
+      };
+      validateOptions(options);
+      expect(options.imageStack).toEqual([
+        'ubuntu:22.04',
+        'ubuntu:22.04',
+        'ubuntu:22.04',
+      ]);
+    });
+
+    it('should apply default docker image for each docker level', () => {
+      const options = {
+        isolated: 'docker',
+        isolatedStack: ['docker'],
+      };
+      validateOptions(options);
+      expect(options.imageStack[0]).toBeDefined();
+      expect(options.imageStack[0]).toContain(':'); // Should have image:tag format
+    });
+
+    it('should throw if image provided but no docker in stack', () => {
+      const options = {
+        isolated: 'screen',
+        isolatedStack: ['screen', 'tmux'],
+        image: 'ubuntu:22.04',
+      };
+      expect(() => validateOptions(options)).toThrow(/docker/);
+    });
+
+    it('should throw if endpoint provided but no ssh in stack', () => {
+      const options = {
+        isolated: 'screen',
+        isolatedStack: ['screen', 'docker'],
+        endpoint: 'user@host',
+        imageStack: [null, 'ubuntu:22.04'],
+      };
+      expect(() => validateOptions(options)).toThrow(/ssh/);
+    });
+  });
+});
+
+describe('Isolation Stacking - Backward Compatibility', () => {
+  it('should work with existing docker command', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--image',
+      'node:18',
+      '--',
+      'npm',
+      'test',
+    ]);
+    expect(result.wrapperOptions.isolated).toBe('docker');
+    expect(result.wrapperOptions.image).toBe('node:18');
+    expect(result.wrapperOptions.isolatedStack).toEqual(['docker']);
+    expect(result.command).toBe('npm test');
+  });
+
+  it('should work with existing ssh command', () => {
+    const result = parseArgs([
+      '--isolated',
+      'ssh',
+      '--endpoint',
+      'user@server',
+      '--',
+      'ls',
+      '-la',
+    ]);
+    expect(result.wrapperOptions.isolated).toBe('ssh');
+    expect(result.wrapperOptions.endpoint).toBe('user@server');
+    expect(result.wrapperOptions.isolatedStack).toEqual(['ssh']);
+  });
+
+  it('should work with existing screen command', () => {
+    const result = parseArgs([
+      '--isolated',
+      'screen',
+      '--detached',
+      '--keep-alive',
+      '--',
+      'long-running-task',
+    ]);
+    expect(result.wrapperOptions.isolated).toBe('screen');
+    expect(result.wrapperOptions.detached).toBe(true);
+    expect(result.wrapperOptions.keepAlive).toBe(true);
+    expect(result.wrapperOptions.isolatedStack).toEqual(['screen']);
+  });
+
+  it('should work with -i shorthand', () => {
+    const result = parseArgs(['-i', 'tmux', '--', 'vim']);
+    expect(result.wrapperOptions.isolated).toBe('tmux');
+    expect(result.wrapperOptions.isolatedStack).toEqual(['tmux']);
+  });
+
+  it('should work with attached mode', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--attached',
+      '--image',
+      'alpine',
+      '--',
+      'sh',
+    ]);
+    expect(result.wrapperOptions.attached).toBe(true);
+    expect(result.wrapperOptions.isolated).toBe('docker');
+  });
+
+  it('should work with session name', () => {
+    const result = parseArgs([
+      '--isolated',
+      'screen',
+      '--session',
+      'my-session',
+      '--',
+      'bash',
+    ]);
+    expect(result.wrapperOptions.session).toBe('my-session');
+  });
+
+  it('should work with session-id', () => {
+    const result = parseArgs([
+      '--isolated',
+      'docker',
+      '--image',
+      'alpine',
+      '--session-id',
+      '12345678-1234-4123-8123-123456789012',
+      '--',
+      'echo',
+      'hi',
+    ]);
+    expect(result.wrapperOptions.sessionId).toBe(
+      '12345678-1234-4123-8123-123456789012'
+    );
+  });
+});

package/test/output-blocks.test.js

@@ -533,13 +533,41 @@ describe('output-blocks module', () => {
       // $ docker pull alpine:latest
       // <empty line>
       // <docker output>
+      // <empty line>
       // ✓
       // │
       // $ echo hi
       // <empty line>
       // hi
+      // <empty line>
       // ✓
     });
+
+    it('output formatting follows visual continuity pattern', () => {
+      // Issue #73: All commands should have consistent formatting:
+      // 1. Command line ($ ...)
+      // 2. Empty line (visual separation)
+      // 3. Command output
+      // 4. Empty line (visual separation)
+      // 5. Result marker (✓ or ✗)
+      //
+      // This test documents the expected output structure that
+      // dockerPullImage and runInDocker should produce.
+
+      // Verify createCommandLine produces the correct format
+      const commandLine = createCommandLine('docker pull alpine:latest');
+      expect(commandLine).toBe('$ docker pull alpine:latest');
+
+      // Verify createVirtualCommandBlock matches
+      const virtualCommandLine = createVirtualCommandBlock(
+        'docker pull alpine:latest'
+      );
+      expect(virtualCommandLine).toBe(commandLine);
+
+      // Verify result markers
+      expect(createVirtualCommandResult(true)).toBe('✓');
+      expect(createVirtualCommandResult(false)).toBe('✗');
+    });
   });
 });