start-command 0.17.4 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # start-command
 
+## 0.19.0
+
+### Minor Changes
+
+- 112a78e: Replace fixed-width box output with status spine format
+  - Width-independent output that doesn't truncate or create jagged boxes
+  - All metadata visible and copy-pasteable (log paths, session IDs)
+  - Works uniformly in TTY, tmux, SSH, CI, and log files
+  - Clear visual distinction: │ for metadata, $ for command, no prefix for output
+  - Result markers ✓ and ✗ for success/failure
+  - Isolation metadata repeated in footer for context
+
+## 0.18.0
+
+### Minor Changes
+
+- c918e82: feat: Use OS-matched default Docker image when --image is not specified
+
+  When using `$ --isolated docker -- command`, instead of requiring the `--image` option,
+  the system now automatically selects an appropriate default Docker image based on the
+  host operating system:
+  - macOS/Windows: `alpine:latest` (lightweight, portable)
+  - Ubuntu: `ubuntu:latest`
+  - Debian: `debian:latest`
+  - Arch Linux: `archlinux:latest`
+  - Fedora: `fedora:latest`
+  - CentOS/RHEL: `centos:latest`
+  - Other Linux/Fallback: `alpine:latest`
+
+  This allows users to use Docker isolation with a simple command like:
+  `$ --isolated docker -- echo 'hi'`
+
+  Fixes #62
+
 ## 0.17.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.17.4",
+  "version": "0.19.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/bin/cli.js

@@ -623,7 +623,7 @@ async function runWithIsolation(
     console.log('');
   }
 
-  // Print finish block with result message inside
+  // Print finish block with isolation metadata repeated
   // Add empty line before finish block for visual separation
   console.log('');
   const durationMs = Date.now() - startTimeMs;
@@ -634,7 +634,7 @@ async function runWithIsolation(
       exitCode,
       logPath: logFilePath,
       durationMs,
-      resultMessage: result.message,
+      extraLines, // Pass extraLines for isolation metadata repetition in footer
     })
   );
 

package/src/lib/args-parser.js

@@ -10,7 +10,7 @@
  * --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)
+ * --image <image>                  Docker image (optional, defaults to OS-matched image)
  * --endpoint <endpoint>            SSH endpoint (required for ssh isolation, e.g., user@host)
  * --isolated-user, -u [username]   Create isolated user with same permissions (auto-generated name if not specified)
  * --keep-user                      Keep isolated user after command completes (don't delete)
@@ -23,6 +23,8 @@
  * --cleanup-dry-run                Show stale records that would be cleaned up (without actually cleaning)
  */
 
+const { getDefaultDockerImage } = require('./docker-utils');
+
 // Debug mode from environment
 const DEBUG =
   process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
@@ -381,11 +383,9 @@ function validateOptions(options) {
       );
     }
 
-    // Docker requires --image
+    // Docker uses --image or defaults to OS-matched image
     if (options.isolated === 'docker' && !options.image) {
-      throw new Error(
-        'Docker isolation requires --image option to specify the container image'
-      );
+      options.image = getDefaultDockerImage();
     }
 
     // SSH requires --endpoint

package/src/lib/output-blocks.js

@@ -1,189 +1,205 @@
 /**
  * Output formatting utilities for nicely rendered command blocks
  *
- * Provides various styles for start/finish blocks to distinguish
- * command output from the $ wrapper output.
+ * Provides "status spine" format: a width-independent, lossless output format
+ * that works in TTY, tmux, SSH, CI, and logs.
  *
- * Available styles:
- * 1. 'rounded' (default): Rounded unicode box borders (╭─╮ ╰─╯)
- * 2. 'heavy': Heavy unicode box borders (┏━┓ ┗━┛)
- * 3. 'double': Double line box borders (╔═╗ ╚═╝)
- * 4. 'simple': Simple dash lines (────────)
- * 5. 'ascii': Pure ASCII compatible (-------- +------+)
+ * Core concepts:
+ * - `│` prefix → tool metadata
+ * - `$` → executed command
+ * - No prefix → program output (stdout/stderr)
+ * - Result marker (`✓` / `✗`) appears after output
  */
 
-// Box drawing characters for different styles
-const BOX_STYLES = {
-  rounded: {
-    topLeft: '╭',
-    topRight: '╮',
-    bottomLeft: '╰',
-    bottomRight: '╯',
-    horizontal: '─',
-    vertical: '│',
-  },
-  heavy: {
-    topLeft: '┏',
-    topRight: '┓',
-    bottomLeft: '┗',
-    bottomRight: '┛',
-    horizontal: '━',
-    vertical: '┃',
-  },
-  double: {
-    topLeft: '╔',
-    topRight: '╗',
-    bottomLeft: '╚',
-    bottomRight: '╝',
-    horizontal: '═',
-    vertical: '║',
-  },
-  simple: {
-    topLeft: '',
-    topRight: '',
-    bottomLeft: '',
-    bottomRight: '',
-    horizontal: '─',
-    vertical: '',
-  },
-  ascii: {
-    topLeft: '+',
-    topRight: '+',
-    bottomLeft: '+',
-    bottomRight: '+',
-    horizontal: '-',
-    vertical: '|',
-  },
-};
-
-// Default style (can be overridden via environment variable)
-const DEFAULT_STYLE = process.env.START_OUTPUT_STYLE || 'rounded';
+// Metadata spine character
+const SPINE = '│';
 
-// Default block width
-const DEFAULT_WIDTH = 60;
+// Result markers
+const SUCCESS_MARKER = '✓';
+const FAILURE_MARKER = '✗';
 
 /**
- * Get the box style configuration
- * @param {string} [styleName] - Style name (rounded, heavy, double, simple, ascii)
- * @returns {object} Box style configuration
+ * Create a metadata line with spine prefix
+ * @param {string} label - Label (e.g., 'session', 'start', 'exit')
+ * @param {string} value - Value for the label
+ * @returns {string} Formatted line with spine prefix
  */
-function getBoxStyle(styleName = DEFAULT_STYLE) {
-  return BOX_STYLES[styleName] || BOX_STYLES.rounded;
+function createSpineLine(label, value) {
+  // Pad label to 10 characters for alignment
+  const paddedLabel = label.padEnd(10);
+  return `${SPINE} ${paddedLabel}${value}`;
 }
 
 /**
- * Create a horizontal line
- * @param {number} width - Line width
- * @param {object} style - Box style
- * @returns {string} Horizontal line
+ * Create an empty spine line (just the spine character)
+ * @returns {string} Empty spine line
  */
-function createHorizontalLine(width, style) {
-  return style.horizontal.repeat(width);
+function createEmptySpineLine() {
+  return SPINE;
 }
 
 /**
- * Pad or truncate text to fit a specific width
- * @param {string} text - Text to pad
- * @param {number} width - Target width
- * @param {boolean} [allowOverflow=false] - If true, don't truncate long text
- * @returns {string} Padded text
+ * Create a command line with $ prefix
+ * @param {string} command - The command being executed
+ * @returns {string} Formatted command line
  */
-function padText(text, width, allowOverflow = false) {
-  if (text.length >= width) {
-    // If overflow is allowed, return text as-is (for copyable content like paths)
-    if (allowOverflow) {
-      return text;
-    }
-    return text.substring(0, width);
-  }
-  return text + ' '.repeat(width - text.length);
+function createCommandLine(command) {
+  return `$ ${command}`;
 }
 
 /**
- * Create a bordered line with text
- * @param {string} text - Text content
- * @param {number} width - Total width (including borders)
- * @param {object} style - Box style
- * @param {boolean} [allowOverflow=false] - If true, allow text to overflow (for copyable content)
- * @returns {string} Bordered line
+ * Get the result marker based on exit code
+ * @param {number} exitCode - Exit code (0 = success)
+ * @returns {string} Result marker (✓ or ✗)
  */
-function createBorderedLine(text, width, style, allowOverflow = false) {
-  if (style.vertical) {
-    const innerWidth = width - 4; // 2 for borders, 2 for padding
-    const paddedText = padText(text, innerWidth, allowOverflow);
-    // If text overflows, extend the right border position
-    if (allowOverflow && text.length > innerWidth) {
-      return `${style.vertical} ${paddedText} ${style.vertical}`;
-    }
-    return `${style.vertical} ${paddedText} ${style.vertical}`;
-  }
-  return text;
+function getResultMarker(exitCode) {
+  return exitCode === 0 ? SUCCESS_MARKER : FAILURE_MARKER;
 }
 
 /**
- * Create the top border of a box
- * @param {number} width - Box width
- * @param {object} style - Box style
- * @returns {string} Top border
+ * Parse isolation metadata from extraLines
+ * Extracts key-value pairs from lines like "[Isolation] Environment: docker, Mode: attached"
+ * @param {string[]} extraLines - Extra lines containing isolation info
+ * @returns {object} Parsed isolation metadata
  */
-function createTopBorder(width, style) {
-  if (style.topLeft) {
-    const lineWidth = width - 2; // Subtract corners
-    return `${style.topLeft}${createHorizontalLine(lineWidth, style)}${style.topRight}`;
+function parseIsolationMetadata(extraLines) {
+  const metadata = {
+    isolation: null,
+    mode: null,
+    image: null,
+    container: null,
+    screen: null,
+    session: null,
+    endpoint: null,
+    user: null,
+  };
+
+  for (const line of extraLines) {
+    // Parse [Isolation] Environment: docker, Mode: attached
+    const envModeMatch = line.match(
+      /\[Isolation\] Environment: (\w+), Mode: (\w+)/
+    );
+    if (envModeMatch) {
+      metadata.isolation = envModeMatch[1];
+      metadata.mode = envModeMatch[2];
+      continue;
+    }
+
+    // Parse [Isolation] Session: name
+    const sessionMatch = line.match(/\[Isolation\] Session: (.+)/);
+    if (sessionMatch) {
+      metadata.session = sessionMatch[1];
+      continue;
+    }
+
+    // Parse [Isolation] Image: name
+    const imageMatch = line.match(/\[Isolation\] Image: (.+)/);
+    if (imageMatch) {
+      metadata.image = imageMatch[1];
+      continue;
+    }
+
+    // Parse [Isolation] Endpoint: user@host
+    const endpointMatch = line.match(/\[Isolation\] Endpoint: (.+)/);
+    if (endpointMatch) {
+      metadata.endpoint = endpointMatch[1];
+      continue;
+    }
+
+    // Parse [Isolation] User: name (isolated)
+    const userMatch = line.match(/\[Isolation\] User: (\w+)/);
+    if (userMatch) {
+      metadata.user = userMatch[1];
+      continue;
+    }
   }
-  return createHorizontalLine(width, style);
+
+  return metadata;
 }
 
 /**
- * Create the bottom border of a box
- * @param {number} width - Box width
- * @param {object} style - Box style
- * @returns {string} Bottom border
+ * Generate isolation metadata lines for spine format
+ * @param {object} metadata - Parsed isolation metadata
+ * @param {string} [containerOrScreenName] - Container or screen session name
+ * @returns {string[]} Array of spine-formatted isolation lines
  */
-function createBottomBorder(width, style) {
-  if (style.bottomLeft) {
-    const lineWidth = width - 2; // Subtract corners
-    return `${style.bottomLeft}${createHorizontalLine(lineWidth, style)}${style.bottomRight}`;
+function generateIsolationLines(metadata, containerOrScreenName = null) {
+  const lines = [];
+
+  if (metadata.isolation) {
+    lines.push(createSpineLine('isolation', metadata.isolation));
+  }
+
+  if (metadata.mode) {
+    lines.push(createSpineLine('mode', metadata.mode));
+  }
+
+  if (metadata.image) {
+    lines.push(createSpineLine('image', metadata.image));
   }
-  return createHorizontalLine(width, style);
+
+  // Use provided container/screen name or fall back to metadata.session
+  if (metadata.isolation === 'docker') {
+    const containerName = containerOrScreenName || metadata.session;
+    if (containerName) {
+      lines.push(createSpineLine('container', containerName));
+    }
+  } else if (metadata.isolation === 'screen') {
+    const screenName = containerOrScreenName || metadata.session;
+    if (screenName) {
+      lines.push(createSpineLine('screen', screenName));
+    }
+  } else if (metadata.isolation === 'tmux') {
+    const tmuxName = containerOrScreenName || metadata.session;
+    if (tmuxName) {
+      lines.push(createSpineLine('tmux', tmuxName));
+    }
+  } else if (metadata.isolation === 'ssh') {
+    if (metadata.endpoint) {
+      lines.push(createSpineLine('endpoint', metadata.endpoint));
+    }
+  }
+
+  if (metadata.user) {
+    lines.push(createSpineLine('user', metadata.user));
+  }
+
+  return lines;
 }
 
 /**
- * Create a start block for command execution
+ * Create a start block for command execution using status spine format
  * @param {object} options - Options for the block
  * @param {string} options.sessionId - Session UUID
  * @param {string} options.timestamp - Timestamp string
  * @param {string} options.command - Command being executed
- * @param {string[]} [options.extraLines] - Additional lines to show after the command line
- * @param {string} [options.style] - Box style name
- * @param {number} [options.width] - Box width
- * @returns {string} Formatted start block
+ * @param {string[]} [options.extraLines] - Additional lines with isolation info
+ * @param {string} [options.style] - Ignored (kept for backward compatibility)
+ * @param {number} [options.width] - Ignored (kept for backward compatibility)
+ * @returns {string} Formatted start block in spine format
  */
 function createStartBlock(options) {
-  const {
-    sessionId,
-    timestamp,
-    command,
-    extraLines = [],
-    style: styleName = DEFAULT_STYLE,
-    width = DEFAULT_WIDTH,
-  } = options;
+  const { sessionId, timestamp, command, extraLines = [] } = options;
 
-  const style = getBoxStyle(styleName);
   const lines = [];
 
-  lines.push(createTopBorder(width, style));
-  lines.push(createBorderedLine(`Session ID: ${sessionId}`, width, style));
-  lines.push(
-    createBorderedLine(`Starting at ${timestamp}: ${command}`, width, style)
-  );
+  // Header: session and start time
+  lines.push(createSpineLine('session', sessionId));
+  lines.push(createSpineLine('start', timestamp));
 
-  // Add extra lines (e.g., isolation info, docker image, etc.)
-  for (const line of extraLines) {
-    lines.push(createBorderedLine(line, width, style));
+  // Parse and add isolation metadata if present
+  const metadata = parseIsolationMetadata(extraLines);
+
+  if (metadata.isolation) {
+    lines.push(createEmptySpineLine());
+    lines.push(...generateIsolationLines(metadata));
   }
 
-  lines.push(createBottomBorder(width, style));
+  // Empty spine line before command
+  lines.push(createEmptySpineLine());
+
+  // Command line
+  lines.push(createCommandLine(command));
 
   return lines.join('\n');
 }
@@ -191,34 +207,46 @@ function createStartBlock(options) {
 /**
  * Format duration in seconds with appropriate precision
  * @param {number} durationMs - Duration in milliseconds
- * @returns {string} Formatted duration string
+ * @returns {string} Formatted duration string (e.g., "0.273s")
  */
 function formatDuration(durationMs) {
   const seconds = durationMs / 1000;
   if (seconds < 0.001) {
-    return '0.001';
+    return '0.001s';
   } else if (seconds < 10) {
     // For durations under 10 seconds, show 3 decimal places
-    return seconds.toFixed(3);
+    return `${seconds.toFixed(3)}s`;
   } else if (seconds < 100) {
-    return seconds.toFixed(2);
+    return `${seconds.toFixed(2)}s`;
   } else {
-    return seconds.toFixed(1);
+    return `${seconds.toFixed(1)}s`;
   }
 }
 
 /**
- * Create a finish block for command execution
+ * Create a finish block for command execution using status spine format
+ *
+ * Bottom block ordering rules:
+ * 1. Result marker (✓ or ✗)
+ * 2. finish timestamp
+ * 3. duration
+ * 4. exit code
+ * 5. (repeated isolation metadata, if any)
+ * 6. empty spine line
+ * 7. log path (always second-to-last)
+ * 8. session ID (always last)
+ *
  * @param {object} options - Options for the block
  * @param {string} options.sessionId - Session UUID
  * @param {string} options.timestamp - Timestamp string
  * @param {number} options.exitCode - Exit code
  * @param {string} options.logPath - Path to log file
  * @param {number} [options.durationMs] - Duration in milliseconds
- * @param {string} [options.resultMessage] - Result message (e.g., "Screen session exited...")
- * @param {string} [options.style] - Box style name
- * @param {number} [options.width] - Box width
- * @returns {string} Formatted finish block
+ * @param {string} [options.resultMessage] - Result message (ignored in new format)
+ * @param {string[]} [options.extraLines] - Isolation info for repetition in footer
+ * @param {string} [options.style] - Ignored (kept for backward compatibility)
+ * @param {number} [options.width] - Ignored (kept for backward compatibility)
+ * @returns {string} Formatted finish block in spine format
  */
 function createFinishBlock(options) {
   const {
@@ -227,36 +255,36 @@ function createFinishBlock(options) {
     exitCode,
     logPath,
     durationMs,
-    resultMessage,
-    style: styleName = DEFAULT_STYLE,
-    width = DEFAULT_WIDTH,
+    extraLines = [],
   } = options;
 
-  const style = getBoxStyle(styleName);
   const lines = [];
 
-  // Format the finished message with optional duration
-  let finishedMsg = `Finished at ${timestamp}`;
+  // Result marker appears first in footer (after program output)
+  lines.push(getResultMarker(exitCode));
+
+  // Finish metadata
+  lines.push(createSpineLine('finish', timestamp));
+
   if (durationMs !== undefined && durationMs !== null) {
-    finishedMsg += ` in ${formatDuration(durationMs)} seconds`;
+    lines.push(createSpineLine('duration', formatDuration(durationMs)));
   }
 
-  lines.push(createTopBorder(width, style));
+  lines.push(createSpineLine('exit', String(exitCode)));
 
-  // Add result message first if provided (e.g., "Docker container exited...")
-  // Allow overflow so the full message is visible and copyable
-  if (resultMessage) {
-    lines.push(createBorderedLine(resultMessage, width, style, true));
+  // Repeat isolation metadata if present
+  const metadata = parseIsolationMetadata(extraLines);
+  if (metadata.isolation) {
+    lines.push(createEmptySpineLine());
+    lines.push(...generateIsolationLines(metadata));
   }
 
-  lines.push(createBorderedLine(finishedMsg, width, style));
-  lines.push(createBorderedLine(`Exit code: ${exitCode}`, width, style));
-  // Allow overflow for log path and session ID so they can be copied completely
-  lines.push(createBorderedLine(`Log: ${logPath}`, width, style, true));
-  lines.push(
-    createBorderedLine(`Session ID: ${sessionId}`, width, style, true)
-  );
-  lines.push(createBottomBorder(width, style));
+  // Empty spine line before final two entries
+  lines.push(createEmptySpineLine());
+
+  // Log and session are ALWAYS last (in that order)
+  lines.push(createSpineLine('log', logPath));
+  lines.push(createSpineLine('session', sessionId));
 
   return lines.join('\n');
 }
@@ -371,17 +399,23 @@ function formatAsNestedLinksNotation(obj, indent = 2, depth = 0) {
 }
 
 module.exports = {
-  BOX_STYLES,
-  DEFAULT_STYLE,
-  DEFAULT_WIDTH,
-  getBoxStyle,
-  createHorizontalLine,
-  createBorderedLine,
-  createTopBorder,
-  createBottomBorder,
+  // Status spine format API
+  SPINE,
+  SUCCESS_MARKER,
+  FAILURE_MARKER,
+  createSpineLine,
+  createEmptySpineLine,
+  createCommandLine,
+  getResultMarker,
+  parseIsolationMetadata,
+  generateIsolationLines,
+
+  // Main block creation functions
   createStartBlock,
   createFinishBlock,
   formatDuration,
+
+  // Links notation utilities
   escapeForLinksNotation,
   formatAsNestedLinksNotation,
 };

package/test/args-parser.test.js

@@ -199,10 +199,26 @@ describe('parseArgs', () => {
       assert.strictEqual(result.wrapperOptions.image, 'alpine:latest');
     });
 
-    it('should throw error for docker without image', () => {
-      assert.throws(() => {
-        parseArgs(['--isolated', 'docker', '--', 'npm', 'test']);
-      }, /Docker isolation requires --image option/);
+    it('should use default OS-matched image for docker without --image', () => {
+      const result = parseArgs(['--isolated', 'docker', '--', 'npm', 'test']);
+      // Should have a default image set (OS-matched)
+      assert.ok(
+        result.wrapperOptions.image,
+        'Expected default image to be set'
+      );
+      // Should be one of the known default images
+      const knownDefaults = [
+        'alpine:latest',
+        'ubuntu:latest',
+        'debian:latest',
+        'archlinux:latest',
+        'fedora:latest',
+        'centos:latest',
+      ];
+      assert.ok(
+        knownDefaults.includes(result.wrapperOptions.image),
+        `Expected image to be one of ${knownDefaults.join(', ')}, got ${result.wrapperOptions.image}`
+      );
     });
 
     it('should throw error for image with non-docker backend', () => {