start-command 0.20.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # start-command
 
+## 0.20.1
+
+### Patch Changes
+
+- 7e11703: feat: Sync JS implementation with Rust for timeline naming and virtual commands
+  - Renamed "spine" terminology to "timeline" throughout the codebase
+    - `SPINE` constant → `TIMELINE_MARKER` (old name deprecated)
+    - `createSpineLine()` → `createTimelineLine()` (old name deprecated)
+    - `createEmptySpineLine()` → `createEmptyTimelineLine()` (old name deprecated)
+  - Added virtual command visualization for Docker image pulls
+    - When Docker isolation requires pulling an image, it's shown as `$ docker pull <image>`
+    - Pull output is streamed in real-time with result markers (✓/✗)
+    - Only displayed when image actually needs to be pulled (conditional display)
+  - New API additions:
+    - `createVirtualCommandBlock()` - for formatting virtual commands
+    - `createVirtualCommandResult()` - for result markers
+    - `createTimelineSeparator()` - for separator between virtual and user commands
+    - `dockerImageExists()` - check if image is available locally
+    - `dockerPullImage()` - pull with streaming output
+    - `createStartBlock({ deferCommand })` - defer command display for multi-step execution
+  - Renamed "isolation backend" to "isolation environment" in docs and error messages
+  - All deprecated items have backward-compatible aliases for smooth migration
+
+  Fixes #70
+
 ## 0.20.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "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

@@ -512,12 +512,15 @@ async function runWithIsolation(
   }
 
   // Print start block with session ID and isolation info
+  // For docker isolation, defer command printing to allow virtual commands (like docker pull) to be shown first
+  const deferCommand = environment === 'docker';
   console.log(
     createStartBlock({
       sessionId,
       timestamp: startTime,
       command: cmd,
       extraLines,
+      deferCommand,
     })
   );
   console.log('');
@@ -558,8 +561,8 @@ async function runWithIsolation(
   let result;
 
   if (environment) {
-    // Run in isolation backend (screen, tmux, docker, ssh)
-    // Note: Isolation backends currently use native spawn/execSync
+    // Run in isolation environment (screen, tmux, docker, ssh)
+    // Note: Isolation environments currently use native spawn/execSync
     // Future: Add command-stream support with raw() function for multiplexers
     result = await runIsolated(environment, cmd, {
       session: options.session,
@@ -571,7 +574,7 @@ async function runWithIsolation(
       autoRemoveDockerContainer: options.autoRemoveDockerContainer,
     });
   } else if (createdUser) {
-    // Run directly as the created user (no isolation backend)
+    // Run directly as the created user (no isolation environment)
     result = await runAsIsolatedUser(cmd, createdUser);
   } else {
     // This shouldn't happen in isolation mode, but handle gracefully

package/src/lib/args-parser.js

@@ -30,7 +30,7 @@ const DEBUG =
   process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
 
 /**
- * Valid isolation backends
+ * Valid isolation environments
  */
 const VALID_BACKENDS = ['screen', 'tmux', 'docker', 'ssh'];
 
@@ -80,7 +80,7 @@ function generateUUID() {
  */
 function parseArgs(args) {
   const wrapperOptions = {
-    isolated: null, // Isolation backend: screen, tmux, docker, ssh
+    isolated: null, // Isolation environment: screen, tmux, docker, ssh
     attached: false, // Run in attached mode
     detached: false, // Run in detached mode
     session: null, // Session name
@@ -375,11 +375,11 @@ function validateOptions(options) {
     );
   }
 
-  // Validate isolation backend
+  // Validate isolation environment
   if (options.isolated !== null) {
     if (!VALID_BACKENDS.includes(options.isolated)) {
       throw new Error(
-        `Invalid isolation backend: "${options.isolated}". Valid options are: ${VALID_BACKENDS.join(', ')}`
+        `Invalid isolation environment: "${options.isolated}". Valid options are: ${VALID_BACKENDS.join(', ')}`
       );
     }
 

package/src/lib/docker-utils.js

@@ -2,10 +2,12 @@
  * Docker utilities for the start-command CLI
  *
  * Provides Docker-related helper functions like detecting the default
- * Docker image based on the host operating system.
+ * Docker image based on the host operating system, checking if images
+ * exist locally, and pulling images with virtual command visualization.
  */
 
 const fs = require('fs');
+const { execSync, spawnSync } = require('child_process');
 
 /**
  * Get the default Docker image based on the host operating system
@@ -84,6 +86,122 @@ function getDefaultDockerImage() {
   return 'alpine:latest';
 }
 
+/**
+ * Check if a Docker image exists locally
+ * @param {string} image - Docker image name
+ * @returns {boolean} True if image exists locally
+ */
+function dockerImageExists(image) {
+  try {
+    execSync(`docker image inspect ${image}`, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pull a Docker image with output streaming
+ * Displays the pull operation as a virtual command in the timeline
+ * @param {string} image - Docker image to pull
+ * @returns {{success: boolean, output: string}} Pull result
+ */
+function dockerPullImage(image) {
+  const {
+    createVirtualCommandBlock,
+    createVirtualCommandResult,
+    createTimelineSeparator,
+  } = require('./output-blocks');
+
+  // Print the virtual command line
+  console.log(createVirtualCommandBlock(`docker pull ${image}`));
+  console.log();
+
+  let output = '';
+  let success = false;
+
+  try {
+    // Run docker pull with inherited stdio for real-time output
+    const result = spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+
+    success = result.status === 0;
+
+    if (result.stdout) {
+      output = result.stdout.toString();
+    }
+    if (result.stderr) {
+      output += result.stderr.toString();
+    }
+  } catch (err) {
+    console.error(`Failed to run docker pull: ${err.message}`);
+    output = err.message;
+    success = false;
+  }
+
+  // Print result marker and separator
+  console.log();
+  console.log(createVirtualCommandResult(success));
+  console.log(createTimelineSeparator());
+
+  return { success, output };
+}
+
+/**
+ * Check if Docker is available (command exists and daemon is running)
+ * @returns {boolean} True if Docker is available
+ */
+function isDockerAvailable() {
+  try {
+    execSync('docker info', { stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the Docker daemon can run Linux container images
+ * On Windows with Docker Desktop in Windows containers mode,
+ * Linux images like alpine:latest cannot be pulled or run.
+ * @returns {boolean} True if Linux Docker images can be run
+ */
+function canRunLinuxDockerImages() {
+  if (!isDockerAvailable()) {
+    return false;
+  }
+
+  try {
+    // On Windows, check if Docker is configured for Linux containers
+    if (process.platform === 'win32') {
+      try {
+        const osType = execSync('docker info --format "{{.OSType}}"', {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 5000,
+        }).trim();
+
+        // Docker must be using Linux containers to run Linux images
+        return osType === 'linux';
+      } catch {
+        // If we can't determine the OS type, assume Linux images won't work on Windows
+        return false;
+      }
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 module.exports = {
   getDefaultDockerImage,
+  dockerImageExists,
+  dockerPullImage,
+  isDockerAvailable,
+  canRunLinuxDockerImages,
 };

package/src/lib/isolation.js

@@ -618,6 +618,9 @@ function runInSsh(command, options = {}) {
   }
 }
 
+// Import docker image utilities from docker-utils
+const { dockerImageExists, dockerPullImage } = require('./docker-utils');
+
 /**
  * Run command in Docker container
  * @param {string} command - Command to execute
@@ -644,6 +647,24 @@ function runInDocker(command, options = {}) {
 
   const containerName = options.session || generateSessionName('docker');
 
+  // Check if image exists locally; if not, pull it as a virtual command
+  if (!dockerImageExists(options.image)) {
+    const pullResult = dockerPullImage(options.image);
+    if (!pullResult.success) {
+      return Promise.resolve({
+        success: false,
+        containerName: null,
+        message: `Failed to pull Docker image: ${options.image}`,
+        exitCode: 1,
+      });
+    }
+  }
+
+  // Print the user command (this appears after any virtual commands like docker pull)
+  const { createCommandLine } = require('./output-blocks');
+  console.log(createCommandLine(command));
+  console.log();
+
   try {
     if (options.detached) {
       // Detached mode: docker run -d --name <name> [--user <user>] <image> <shell> -c '<command>'
@@ -753,8 +774,8 @@ function runInDocker(command, options = {}) {
 }
 
 /**
- * Run command in the specified isolation backend
- * @param {string} backend - Isolation backend (screen, tmux, docker, ssh)
+ * Run command in the specified isolation environment
+ * @param {string} backend - Isolation environment (screen, tmux, docker, ssh)
  * @param {string} command - Command to execute
  * @param {object} options - Options
  * @returns {Promise<{success: boolean, message: string}>}
@@ -772,7 +793,7 @@ function runIsolated(backend, command, options = {}) {
     default:
       return Promise.resolve({
         success: false,
-        message: `Unknown isolation backend: ${backend}`,
+        message: `Unknown isolation environment: ${backend}`,
       });
   }
 }
@@ -885,7 +906,7 @@ function resetScreenVersionCache() {
 }
 
 /**
- * Run command as an isolated user (without isolation backend)
+ * Run command as an isolated user (without isolation environment)
  * Uses sudo -u to switch users
  * @param {string} cmd - Command to execute
  * @param {string} username - User to run as
@@ -915,58 +936,11 @@ function runAsIsolatedUser(cmd, username) {
   });
 }
 
-/**
- * Check if the Docker daemon can run Linux container images
- * On Windows with Docker Desktop in Windows containers mode,
- * Linux images like alpine:latest cannot be pulled or run.
- * @returns {boolean} True if Linux Docker images can be run
- */
-function canRunLinuxDockerImages() {
-  if (!isCommandAvailable('docker')) {
-    return false;
-  }
-
-  try {
-    // First check if Docker daemon is running
-    execSync('docker info', { stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 });
-
-    // On Windows, check if Docker is configured for Linux containers
-    if (process.platform === 'win32') {
-      try {
-        const osType = execSync('docker info --format "{{.OSType}}"', {
-          encoding: 'utf8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-          timeout: 5000,
-        }).trim();
-
-        // Docker must be using Linux containers to run Linux images
-        if (osType !== 'linux') {
-          if (DEBUG) {
-            console.log(
-              `[DEBUG] Docker is running in ${osType} containers mode, cannot run Linux images`
-            );
-          }
-          return false;
-        }
-      } catch {
-        // If we can't determine the OS type, assume Linux images won't work on Windows
-        if (DEBUG) {
-          console.log(
-            '[DEBUG] Could not determine Docker OS type, assuming Linux images unavailable'
-          );
-        }
-        return false;
-      }
-    }
-
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Re-export getDefaultDockerImage from docker-utils for backwards compatibility
-const { getDefaultDockerImage } = require('./docker-utils');
+// Re-export docker utilities from docker-utils for backwards compatibility
+const {
+  getDefaultDockerImage,
+  canRunLinuxDockerImages,
+} = require('./docker-utils');
 
 module.exports = {
   isCommandAvailable,
@@ -989,5 +963,8 @@ module.exports = {
   supportsLogfileOption,
   resetScreenVersionCache,
   canRunLinuxDockerImages,
+  // Re-exported from docker-utils for backwards compatibility
   getDefaultDockerImage,
+  dockerImageExists,
+  dockerPullImage,
 };

package/src/lib/output-blocks.js

@@ -1,41 +1,60 @@
 /**
  * Output formatting utilities for nicely rendered command blocks
  *
- * Provides "status spine" format: a width-independent, lossless output format
+ * Provides "timeline" format: a width-independent, lossless output format
  * that works in TTY, tmux, SSH, CI, and logs.
  *
  * Core concepts:
- * - `│` prefix → tool metadata
- * - `$` → executed command
+ * - `│` prefix → tool metadata (timeline marker)
+ * - `$` → executed command (virtual or user command)
  * - No prefix → program output (stdout/stderr)
  * - Result marker (`✓` / `✗`) appears after output
  */
 
-// Metadata spine character
-const SPINE = '│';
+// Timeline marker character (formerly called "spine")
+const TIMELINE_MARKER = '│';
+
+// Alias for backward compatibility
+const SPINE = TIMELINE_MARKER;
 
 // Result markers
 const SUCCESS_MARKER = '✓';
 const FAILURE_MARKER = '✗';
 
 /**
- * Create a metadata line with spine prefix
+ * Create a metadata line with timeline marker prefix
  * @param {string} label - Label (e.g., 'session', 'start', 'exit')
  * @param {string} value - Value for the label
- * @returns {string} Formatted line with spine prefix
+ * @returns {string} Formatted line with timeline marker prefix
  */
-function createSpineLine(label, value) {
+function createTimelineLine(label, value) {
   // Pad label to 10 characters for alignment
   const paddedLabel = label.padEnd(10);
-  return `${SPINE} ${paddedLabel}${value}`;
+  return `${TIMELINE_MARKER} ${paddedLabel}${value}`;
+}
+
+/**
+ * Alias for backward compatibility
+ * @deprecated Use createTimelineLine instead
+ */
+function createSpineLine(label, value) {
+  return createTimelineLine(label, value);
+}
+
+/**
+ * Create an empty timeline line (just the timeline marker character)
+ * @returns {string} Empty timeline line
+ */
+function createEmptyTimelineLine() {
+  return TIMELINE_MARKER;
 }
 
 /**
- * Create an empty spine line (just the spine character)
- * @returns {string} Empty spine line
+ * Alias for backward compatibility
+ * @deprecated Use createEmptyTimelineLine instead
  */
 function createEmptySpineLine() {
-  return SPINE;
+  return createEmptyTimelineLine();
 }
 
 /**
@@ -56,6 +75,34 @@ function getResultMarker(exitCode) {
   return exitCode === 0 ? SUCCESS_MARKER : FAILURE_MARKER;
 }
 
+/**
+ * Create a virtual command block for setup steps (like docker pull)
+ * Virtual commands are displayed separately in the timeline to show
+ * intermediate steps that the tool performs automatically
+ * @param {string} command - The virtual command being executed
+ * @returns {string} Formatted command line
+ */
+function createVirtualCommandBlock(command) {
+  return createCommandLine(command);
+}
+
+/**
+ * Create a result marker line for a virtual command
+ * @param {boolean} success - Whether the virtual command succeeded
+ * @returns {string} Result marker (✓ or ✗)
+ */
+function createVirtualCommandResult(success) {
+  return success ? SUCCESS_MARKER : FAILURE_MARKER;
+}
+
+/**
+ * Create a separator line between virtual commands and user commands
+ * @returns {string} Empty timeline line
+ */
+function createTimelineSeparator() {
+  return createEmptyTimelineLine();
+}
+
 /**
  * Parse isolation metadata from extraLines
  * Extracts key-value pairs from lines like "[Isolation] Environment: docker, Mode: attached"
@@ -118,88 +165,97 @@ function parseIsolationMetadata(extraLines) {
 }
 
 /**
- * Generate isolation metadata lines for spine format
+ * Generate isolation metadata lines for timeline format
  * @param {object} metadata - Parsed isolation metadata
  * @param {string} [containerOrScreenName] - Container or screen session name
- * @returns {string[]} Array of spine-formatted isolation lines
+ * @returns {string[]} Array of timeline-formatted isolation lines
  */
 function generateIsolationLines(metadata, containerOrScreenName = null) {
   const lines = [];
 
   if (metadata.isolation) {
-    lines.push(createSpineLine('isolation', metadata.isolation));
+    lines.push(createTimelineLine('isolation', metadata.isolation));
   }
 
   if (metadata.mode) {
-    lines.push(createSpineLine('mode', metadata.mode));
+    lines.push(createTimelineLine('mode', metadata.mode));
   }
 
   if (metadata.image) {
-    lines.push(createSpineLine('image', metadata.image));
+    lines.push(createTimelineLine('image', metadata.image));
   }
 
   // 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));
+      lines.push(createTimelineLine('container', containerName));
     }
   } else if (metadata.isolation === 'screen') {
     const screenName = containerOrScreenName || metadata.session;
     if (screenName) {
-      lines.push(createSpineLine('screen', screenName));
+      lines.push(createTimelineLine('screen', screenName));
     }
   } else if (metadata.isolation === 'tmux') {
     const tmuxName = containerOrScreenName || metadata.session;
     if (tmuxName) {
-      lines.push(createSpineLine('tmux', tmuxName));
+      lines.push(createTimelineLine('tmux', tmuxName));
     }
   } else if (metadata.isolation === 'ssh') {
     if (metadata.endpoint) {
-      lines.push(createSpineLine('endpoint', metadata.endpoint));
+      lines.push(createTimelineLine('endpoint', metadata.endpoint));
     }
   }
 
   if (metadata.user) {
-    lines.push(createSpineLine('user', metadata.user));
+    lines.push(createTimelineLine('user', metadata.user));
   }
 
   return lines;
 }
 
 /**
- * Create a start block for command execution using status spine format
+ * Create a start block for command execution using timeline 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 with isolation info
+ * @param {boolean} [options.deferCommand] - If true, omit command line (for virtual command handling)
  * @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
+ * @returns {string} Formatted start block in timeline format
  */
 function createStartBlock(options) {
-  const { sessionId, timestamp, command, extraLines = [] } = options;
+  const {
+    sessionId,
+    timestamp,
+    command,
+    extraLines = [],
+    deferCommand = false,
+  } = options;
 
   const lines = [];
 
   // Header: session and start time
-  lines.push(createSpineLine('session', sessionId));
-  lines.push(createSpineLine('start', timestamp));
+  lines.push(createTimelineLine('session', sessionId));
+  lines.push(createTimelineLine('start', timestamp));
 
   // Parse and add isolation metadata if present
   const metadata = parseIsolationMetadata(extraLines);
 
   if (metadata.isolation) {
-    lines.push(createEmptySpineLine());
+    lines.push(createEmptyTimelineLine());
     lines.push(...generateIsolationLines(metadata));
   }
 
-  // Empty spine line before command
-  lines.push(createEmptySpineLine());
+  // Empty timeline line before command (always needed for separation)
+  lines.push(createEmptyTimelineLine());
 
-  // Command line
-  lines.push(createCommandLine(command));
+  // Command line (unless deferred for virtual command handling)
+  if (!deferCommand) {
+    lines.push(createCommandLine(command));
+  }
 
   return lines.join('\n');
 }
@@ -224,7 +280,7 @@ function formatDuration(durationMs) {
 }
 
 /**
- * Create a finish block for command execution using status spine format
+ * Create a finish block for command execution using timeline format
  *
  * Bottom block ordering rules:
  * 1. Result marker (✓ or ✗)
@@ -232,7 +288,7 @@ function formatDuration(durationMs) {
  * 3. duration
  * 4. exit code
  * 5. (repeated isolation metadata, if any)
- * 6. empty spine line
+ * 6. empty timeline line
  * 7. log path (always second-to-last)
  * 8. session ID (always last)
  *
@@ -246,7 +302,7 @@ function formatDuration(durationMs) {
  * @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
+ * @returns {string} Formatted finish block in timeline format
  */
 function createFinishBlock(options) {
   const {
@@ -264,27 +320,27 @@ function createFinishBlock(options) {
   lines.push(getResultMarker(exitCode));
 
   // Finish metadata
-  lines.push(createSpineLine('finish', timestamp));
+  lines.push(createTimelineLine('finish', timestamp));
 
   if (durationMs !== undefined && durationMs !== null) {
-    lines.push(createSpineLine('duration', formatDuration(durationMs)));
+    lines.push(createTimelineLine('duration', formatDuration(durationMs)));
   }
 
-  lines.push(createSpineLine('exit', String(exitCode)));
+  lines.push(createTimelineLine('exit', String(exitCode)));
 
   // Repeat isolation metadata if present
   const metadata = parseIsolationMetadata(extraLines);
   if (metadata.isolation) {
-    lines.push(createEmptySpineLine());
+    lines.push(createEmptyTimelineLine());
     lines.push(...generateIsolationLines(metadata));
   }
 
-  // Empty spine line before final two entries
-  lines.push(createEmptySpineLine());
+  // Empty timeline line before final two entries
+  lines.push(createEmptyTimelineLine());
 
   // Log and session are ALWAYS last (in that order)
-  lines.push(createSpineLine('log', logPath));
-  lines.push(createSpineLine('session', sessionId));
+  lines.push(createTimelineLine('log', logPath));
+  lines.push(createTimelineLine('session', sessionId));
 
   return lines.join('\n');
 }
@@ -399,17 +455,25 @@ function formatAsNestedLinksNotation(obj, indent = 2, depth = 0) {
 }
 
 module.exports = {
-  // Status spine format API
-  SPINE,
+  // Timeline format API (formerly "status spine")
+  TIMELINE_MARKER,
+  SPINE, // deprecated, use TIMELINE_MARKER
   SUCCESS_MARKER,
   FAILURE_MARKER,
-  createSpineLine,
-  createEmptySpineLine,
+  createTimelineLine,
+  createSpineLine, // deprecated, use createTimelineLine
+  createEmptyTimelineLine,
+  createEmptySpineLine, // deprecated, use createEmptyTimelineLine
   createCommandLine,
   getResultMarker,
   parseIsolationMetadata,
   generateIsolationLines,
 
+  // Virtual command API (for multi-step execution)
+  createVirtualCommandBlock,
+  createVirtualCommandResult,
+  createTimelineSeparator,
+
   // Main block creation functions
   createStartBlock,
   createFinishBlock,

package/test/args-parser.test.js

@@ -463,7 +463,7 @@ describe('parseArgs', () => {
     it('should throw error for invalid backend', () => {
       assert.throws(() => {
         parseArgs(['--isolated', 'invalid-backend', '--', 'npm', 'test']);
-      }, /Invalid isolation backend/);
+      }, /Invalid isolation environment/);
     });
 
     it('should list valid backends in error message', () => {

package/test/isolation.test.js

@@ -89,8 +89,8 @@ describe('Isolation Module', () => {
     });
   });
 
-  describe('isolation backend checks', () => {
-    // These tests check if specific backends are available
+  describe('isolation environment checks', () => {
+    // These tests check if specific isolation environments are available
     // They don't fail if not installed, just report status
 
     it('should check if screen is available', () => {
@@ -710,7 +710,7 @@ describe('Isolation Runner with Available Backends', () => {
       // Test with a backend that returns predictable error for missing tools
       const result = await runIsolated('nonexistent-backend', 'echo test', {});
       assert.strictEqual(result.success, false);
-      assert.ok(result.message.includes('Unknown isolation backend'));
+      assert.ok(result.message.includes('Unknown isolation environment'));
     });
 
     it('should pass options to backend', async () => {

package/test/output-blocks.test.js

@@ -1,23 +1,36 @@
 /**
  * Tests for output-blocks module
  *
- * Tests the "status spine" format: width-independent, lossless output
+ * Tests the "timeline" format: width-independent, lossless output
+ * (formerly called "status spine" format)
  */
 
 const { describe, it, expect } = require('bun:test');
 
 const {
-  // Spine format exports
+  // Timeline format exports (new names)
+  TIMELINE_MARKER,
+  createTimelineLine,
+  createEmptyTimelineLine,
+
+  // Deprecated aliases (for backward compatibility)
   SPINE,
-  SUCCESS_MARKER,
-  FAILURE_MARKER,
   createSpineLine,
   createEmptySpineLine,
+
+  // Common exports
+  SUCCESS_MARKER,
+  FAILURE_MARKER,
   createCommandLine,
   getResultMarker,
   parseIsolationMetadata,
   generateIsolationLines,
 
+  // Virtual command API
+  createVirtualCommandBlock,
+  createVirtualCommandResult,
+  createTimelineSeparator,
+
   // Main block functions
   createStartBlock,
   createFinishBlock,
@@ -29,9 +42,13 @@ const {
 } = require('../src/lib/output-blocks');
 
 describe('output-blocks module', () => {
-  describe('spine format constants', () => {
-    it('should export spine character', () => {
-      expect(SPINE).toBe('│');
+  describe('timeline format constants', () => {
+    it('should export timeline marker character', () => {
+      expect(TIMELINE_MARKER).toBe('│');
+    });
+
+    it('should export spine as alias for backward compatibility', () => {
+      expect(SPINE).toBe(TIMELINE_MARKER);
     });
 
     it('should export result markers', () => {
@@ -40,24 +57,37 @@ describe('output-blocks module', () => {
     });
   });
 
-  describe('createSpineLine', () => {
-    it('should create a line with spine prefix and padded label', () => {
-      const line = createSpineLine('session', 'abc-123');
+  describe('createTimelineLine', () => {
+    it('should create a line with timeline marker prefix and padded label', () => {
+      const line = createTimelineLine('session', 'abc-123');
       expect(line).toBe('│ session   abc-123');
     });
 
     it('should pad labels to 10 characters', () => {
-      const shortLabel = createSpineLine('exit', '0');
+      const shortLabel = createTimelineLine('exit', '0');
       expect(shortLabel).toBe('│ exit      0');
 
-      const longLabel = createSpineLine('isolation', 'docker');
+      const longLabel = createTimelineLine('isolation', 'docker');
       expect(longLabel).toBe('│ isolation docker');
     });
   });
 
-  describe('createEmptySpineLine', () => {
-    it('should create just the spine character', () => {
-      expect(createEmptySpineLine()).toBe('│');
+  describe('createSpineLine (deprecated alias)', () => {
+    it('should work as alias for createTimelineLine', () => {
+      const line = createSpineLine('session', 'abc-123');
+      expect(line).toBe(createTimelineLine('session', 'abc-123'));
+    });
+  });
+
+  describe('createEmptyTimelineLine', () => {
+    it('should create just the timeline marker character', () => {
+      expect(createEmptyTimelineLine()).toBe('│');
+    });
+  });
+
+  describe('createEmptySpineLine (deprecated alias)', () => {
+    it('should work as alias for createEmptyTimelineLine', () => {
+      expect(createEmptySpineLine()).toBe(createEmptyTimelineLine());
     });
   });
 
@@ -373,6 +403,62 @@ describe('output-blocks module', () => {
       expect(formatAsNestedLinksNotation(null)).toBe('null');
     });
   });
+
+  describe('Virtual Command API', () => {
+    describe('createVirtualCommandBlock', () => {
+      it('should create a command line for virtual commands', () => {
+        const block = createVirtualCommandBlock('docker pull ubuntu:latest');
+        expect(block).toBe('$ docker pull ubuntu:latest');
+      });
+
+      it('should behave like createCommandLine', () => {
+        const virtualBlock = createVirtualCommandBlock('npm install');
+        const commandLine = createCommandLine('npm install');
+        expect(virtualBlock).toBe(commandLine);
+      });
+    });
+
+    describe('createVirtualCommandResult', () => {
+      it('should return success marker for true', () => {
+        expect(createVirtualCommandResult(true)).toBe('✓');
+      });
+
+      it('should return failure marker for false', () => {
+        expect(createVirtualCommandResult(false)).toBe('✗');
+      });
+    });
+
+    describe('createTimelineSeparator', () => {
+      it('should create an empty timeline line', () => {
+        expect(createTimelineSeparator()).toBe('│');
+      });
+
+      it('should behave like createEmptyTimelineLine', () => {
+        expect(createTimelineSeparator()).toBe(createEmptyTimelineLine());
+      });
+    });
+  });
+
+  describe('createStartBlock with deferCommand', () => {
+    it('should include command line by default', () => {
+      const block = createStartBlock({
+        sessionId: 'test-uuid',
+        timestamp: '2025-01-01 00:00:00',
+        command: 'echo hello',
+      });
+      expect(block).toContain('$ echo hello');
+    });
+
+    it('should omit command line when deferCommand is true', () => {
+      const block = createStartBlock({
+        sessionId: 'test-uuid',
+        timestamp: '2025-01-01 00:00:00',
+        command: 'echo hello',
+        deferCommand: true,
+      });
+      expect(block).not.toContain('$ echo hello');
+    });
+  });
 });
 
 console.log('=== Output Blocks Unit Tests ===');