start-command 0.17.3 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # start-command
 
+## 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
+
+- 89d04d6: fix: Ensure execution status is updated when process is interrupted
+
+  This fix addresses Issue #60 where `$ --status` shows "executing" for finished commands.
+
+  Changes:
+  - Added signal handlers (SIGINT, SIGTERM, SIGHUP) to update execution status when process is interrupted
+  - Added `--cleanup` and `--cleanup-dry-run` flags to clean up stale records from crashed/killed processes
+  - Added `cleanupStale()` method to ExecutionStore to detect and clean stale records
+
+  The cleanup logic detects stale records by:
+  1. Checking if the PID is still running (if on same platform)
+  2. Checking if the record has exceeded max age (default: 24 hours)
+
+  Stale records are marked as "executed" with exit code -1 to indicate abnormal termination.
+
 ## 0.17.3
 
 ### Patch Changes

package/package.json

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

@@ -73,6 +73,10 @@ const config = {
 // Global execution store instance (initialized lazily)
 let executionStore = null;
 
+// Global reference to current execution record for cleanup on signals
+// This allows us to mark the execution as completed if the process is interrupted
+let currentExecutionRecord = null;
+
 /**
  * Get the execution store instance
  * @returns {ExecutionStore}
@@ -87,6 +91,57 @@ function getExecutionStore() {
   return executionStore;
 }
 
+/**
+ * Cleanup handler for signals and process exit
+ * Marks the current execution as completed with an appropriate exit code
+ * @param {string} signal - The signal that triggered the cleanup (e.g., 'SIGINT', 'SIGTERM')
+ * @param {number} exitCode - The exit code to use
+ */
+function cleanupExecution(signal, exitCode) {
+  if (currentExecutionRecord && executionStore) {
+    // Signal-based exit codes:
+    // SIGINT (Ctrl+C): 130 (128 + 2)
+    // SIGTERM: 143 (128 + 15)
+    // SIGHUP: 129 (128 + 1)
+    currentExecutionRecord.complete(exitCode);
+    try {
+      executionStore.save(currentExecutionRecord);
+      if (config.verbose) {
+        console.error(
+          `\n[Tracking] Execution ${currentExecutionRecord.uuid} marked as completed (${signal}, exit code: ${exitCode})`
+        );
+      }
+    } catch (err) {
+      if (config.verbose) {
+        console.error(
+          `[Tracking] Warning: Could not save execution record on ${signal}: ${err.message}`
+        );
+      }
+    }
+    // Clear the reference to prevent double cleanup
+    currentExecutionRecord = null;
+  }
+}
+
+// Set up signal handlers to ensure execution status is updated on interruption
+// SIGINT (Ctrl+C) - exit code 130 (128 + signal number 2)
+process.on('SIGINT', () => {
+  cleanupExecution('SIGINT', 130);
+  process.exit(130);
+});
+
+// SIGTERM (kill command) - exit code 143 (128 + signal number 15)
+process.on('SIGTERM', () => {
+  cleanupExecution('SIGTERM', 143);
+  process.exit(143);
+});
+
+// SIGHUP (terminal closed) - exit code 129 (128 + signal number 1)
+process.on('SIGHUP', () => {
+  cleanupExecution('SIGHUP', 129);
+  process.exit(129);
+});
+
 // Get all arguments passed after the command
 const args = process.argv.slice(2);
 
@@ -138,6 +193,12 @@ if (wrapperOptions.status) {
   process.exit(0);
 }
 
+// Handle --cleanup flag
+if (wrapperOptions.cleanup) {
+  handleCleanup(wrapperOptions.cleanupDryRun);
+  process.exit(0);
+}
+
 // Check if no command was provided
 if (!parsedCommand || parsedCommand.trim() === '') {
   console.error('Error: No command provided');
@@ -206,6 +267,53 @@ function handleStatusQuery(uuid, outputFormat) {
   }
 }
 
+/**
+ * Handle --cleanup flag
+ * Cleans up stale "executing" records (processes that crashed or were killed)
+ * @param {boolean} dryRun - If true, just report what would be cleaned
+ */
+function handleCleanup(dryRun) {
+  const store = getExecutionStore();
+  if (!store) {
+    console.error('Error: Execution tracking is disabled.');
+    process.exit(1);
+  }
+
+  const result = store.cleanupStale({ dryRun });
+
+  if (result.errors.length > 0) {
+    for (const error of result.errors) {
+      console.error(`Error: ${error}`);
+    }
+  }
+
+  if (result.records.length === 0) {
+    console.log('No stale records found.');
+    return;
+  }
+
+  if (dryRun) {
+    console.log(
+      `Found ${result.records.length} stale record(s) that would be cleaned up:\n`
+    );
+  } else {
+    console.log(`Cleaned up ${result.cleaned} stale record(s):\n`);
+  }
+
+  for (const record of result.records) {
+    const startTime = new Date(record.startTime).toLocaleString();
+    console.log(`  UUID: ${record.uuid}`);
+    console.log(`  Command: ${record.command}`);
+    console.log(`  Started: ${startTime}`);
+    console.log(`  PID: ${record.pid || 'N/A'}`);
+    console.log('');
+  }
+
+  if (dryRun) {
+    console.log('Run with --cleanup to actually clean up these records.');
+  }
+}
+
 /** Print usage information */
 function printUsage() {
   console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>]
@@ -225,6 +333,8 @@ Options:
   --auto-remove-docker-container  Auto-remove docker container after exit
   --use-command-stream  Use command-stream library for execution (experimental)
   --status <uuid>       Show status of execution by UUID (--output-format: links-notation|json|text)
+  --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
 
 Examples:
@@ -411,8 +521,9 @@ async function runWithIsolation(
   );
   console.log('');
 
-  // Save initial execution record
+  // Save initial execution record and set global reference for signal cleanup
   if (executionRecord && store) {
+    currentExecutionRecord = executionRecord;
     try {
       store.save(executionRecord);
     } catch (err) {
@@ -478,7 +589,7 @@ async function runWithIsolation(
   // Write log file
   writeLogFile(logFilePath, logContent);
 
-  // Update execution record as completed
+  // Update execution record as completed and clear global reference
   if (executionRecord && store) {
     executionRecord.complete(exitCode);
     try {
@@ -490,6 +601,8 @@ async function runWithIsolation(
         );
       }
     }
+    // Clear global reference since we've completed normally
+    currentExecutionRecord = null;
   }
 
   // Cleanup: delete the created user if we created one (unless --keep-user)
@@ -580,6 +693,8 @@ async function runDirect(cmd, sessionId) {
         runtimeVersion,
       },
     });
+    // Set global reference for signal cleanup
+    currentExecutionRecord = executionRecord;
   }
 
   // Log header
@@ -615,6 +730,8 @@ async function runDirect(cmd, sessionId) {
 
   // Completion callback
   const onComplete = (exitCode, endTime, _logContent, durationMs) => {
+    // Clear global reference since execution completed normally
+    currentExecutionRecord = null;
     console.log('');
     console.log(
       createFinishBlock({
@@ -633,6 +750,8 @@ async function runDirect(cmd, sessionId) {
 
   // Error callback
   const onError = (errorMessage, endTime, durationMs) => {
+    // Clear global reference since execution completed (with error)
+    currentExecutionRecord = null;
     console.error(`\n${errorMessage}`);
     console.log('');
     console.log(
@@ -726,6 +845,8 @@ async function runDirectWithCommandStream(
         executionMode: 'command-stream',
       },
     });
+    // Set global reference for signal cleanup
+    currentExecutionRecord = executionRecord;
   }
 
   // Log header
@@ -817,7 +938,7 @@ async function runDirectWithCommandStream(
     console.error(`\nWarning: Could not save log file: ${err.message}`);
   }
 
-  // Update execution record as completed
+  // Update execution record as completed and clear global reference
   if (executionRecord && store) {
     executionRecord.complete(exitCode);
     try {
@@ -829,6 +950,8 @@ async function runDirectWithCommandStream(
         );
       }
     }
+    // Clear global reference since we've completed normally
+    currentExecutionRecord = null;
   }
 
   // Print finish block

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)
@@ -19,8 +19,12 @@
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --status <uuid>                  Show status of a previous command execution by UUID
  * --output-format <format>         Output format for status (links-notation, json, text)
+ * --cleanup                        Clean up stale "executing" records (processes that crashed or were killed)
+ * --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';
@@ -91,6 +95,8 @@ function parseArgs(args) {
     useCommandStream: false, // Use command-stream library for command execution
     status: null, // UUID to show status for
     outputFormat: null, // Output format for status (links-notation, json, text)
+    cleanup: false, // Clean up stale "executing" records
+    cleanupDryRun: false, // Show what would be cleaned without actually cleaning
   };
 
   let commandArgs = [];
@@ -339,6 +345,19 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --cleanup
+  if (arg === '--cleanup') {
+    options.cleanup = true;
+    return 1;
+  }
+
+  // --cleanup-dry-run
+  if (arg === '--cleanup-dry-run') {
+    options.cleanup = true;
+    options.cleanupDryRun = true;
+    return 1;
+  }
+
   // Not a recognized wrapper option
   return 0;
 }
@@ -364,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/execution-store.js

@@ -517,6 +517,112 @@ class ExecutionStore {
     return records.slice(0, limit);
   }
 
+  /**
+   * Clean up stale "executing" records
+   *
+   * Stale records are those that:
+   * 1. Have status "executing"
+   * 2. Either:
+   *    - Their process (by PID) is no longer running (on same hostname)
+   *    - They have been "executing" for longer than maxAgeMs (default: 24 hours)
+   *
+   * @param {object} options - Cleanup options
+   * @param {number} options.maxAgeMs - Max age for executing records (default: 24 hours)
+   * @param {boolean} options.dryRun - If true, just report what would be cleaned (default: false)
+   * @returns {{cleaned: number, records: ExecutionRecord[], errors: string[]}}
+   */
+  cleanupStale(options = {}) {
+    const maxAgeMs = options.maxAgeMs || 24 * 60 * 60 * 1000; // 24 hours
+    const dryRun = options.dryRun || false;
+
+    const result = {
+      cleaned: 0,
+      records: [],
+      errors: [],
+    };
+
+    const records = this.readLinoRecords();
+    const executingRecords = records.filter(
+      (r) => r.status === ExecutionStatus.EXECUTING
+    );
+
+    const staleRecords = [];
+
+    for (const record of executingRecords) {
+      let isStale = false;
+      let reason = '';
+
+      // Check if the process is still running (only if on same platform)
+      if (record.pid && record.platform === process.platform) {
+        try {
+          // Signal 0 just checks if process exists
+          process.kill(record.pid, 0);
+          // Process exists, check age
+        } catch {
+          // Process doesn't exist - record is stale
+          isStale = true;
+          reason = `process ${record.pid} no longer running`;
+        }
+      }
+
+      // Check age if not already determined to be stale
+      if (!isStale) {
+        const startTime = new Date(record.startTime).getTime();
+        const age = Date.now() - startTime;
+        if (age > maxAgeMs) {
+          isStale = true;
+          reason = `running for ${Math.round(age / 1000 / 60)} minutes (max: ${Math.round(maxAgeMs / 1000 / 60)} minutes)`;
+        }
+      }
+
+      if (isStale) {
+        this.log(`Stale record found: ${record.uuid} (${reason})`);
+        staleRecords.push(record);
+      }
+    }
+
+    result.records = staleRecords;
+
+    if (!dryRun && staleRecords.length > 0) {
+      const lock = new LockManager(this.lockFilePath);
+
+      if (!lock.acquire()) {
+        result.errors.push('Failed to acquire lock for cleanup');
+        return result;
+      }
+
+      try {
+        // Re-read records to ensure consistency
+        const currentRecords = this.readLinoRecords();
+
+        // Update stale records to "executed" status with exit code -1 (abnormal termination)
+        for (const staleRecord of staleRecords) {
+          const index = currentRecords.findIndex(
+            (r) => r.uuid === staleRecord.uuid
+          );
+          if (index >= 0) {
+            // Mark as executed with exit code -1 to indicate abnormal termination
+            currentRecords[index].status = ExecutionStatus.EXECUTED;
+            currentRecords[index].exitCode = -1;
+            currentRecords[index].endTime = new Date().toISOString();
+            result.cleaned++;
+          }
+        }
+
+        this.writeLinoRecords(currentRecords);
+        this.log(`Cleaned up ${result.cleaned} stale records`);
+      } catch (err) {
+        result.errors.push(`Cleanup error: ${err.message}`);
+      } finally {
+        lock.release();
+      }
+    } else if (dryRun) {
+      result.cleaned = staleRecords.length;
+    }
+
+    return result;
+  }
+
   /**
    * Delete an execution record
    * @param {string} uuid

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', () => {
@@ -889,3 +905,25 @@ describe('VALID_OUTPUT_FORMATS', () => {
     assert.ok(VALID_OUTPUT_FORMATS.includes('text'));
   });
 });
+
+describe('cleanup options', () => {
+  it('should parse --cleanup flag', () => {
+    const result = parseArgs(['--cleanup']);
+    assert.strictEqual(result.wrapperOptions.cleanup, true);
+    assert.strictEqual(result.wrapperOptions.cleanupDryRun, false);
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --cleanup-dry-run flag', () => {
+    const result = parseArgs(['--cleanup-dry-run']);
+    assert.strictEqual(result.wrapperOptions.cleanup, true);
+    assert.strictEqual(result.wrapperOptions.cleanupDryRun, true);
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should default cleanup to false', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.cleanup, false);
+    assert.strictEqual(result.wrapperOptions.cleanupDryRun, false);
+  });
+});

package/test/execution-store.test.js

@@ -480,4 +480,125 @@ describe('ExecutionStore verifyConsistency', () => {
   });
 });
 
+describe('ExecutionStore cleanupStale', () => {
+  let store;
+
+  beforeEach(() => {
+    cleanupTestDir();
+    store = new ExecutionStore({
+      appFolder: TEST_APP_FOLDER,
+      useLinks: false,
+    });
+  });
+
+  afterEach(() => {
+    cleanupTestDir();
+  });
+
+  it('should return empty result when no stale records exist', () => {
+    // Create a completed record
+    const record = new ExecutionRecord({
+      command: 'echo 1',
+      pid: process.pid, // Current process
+    });
+    record.complete(0);
+    store.save(record);
+
+    const result = store.cleanupStale();
+    expect(result.cleaned).toBe(0);
+    expect(result.records.length).toBe(0);
+    expect(result.errors.length).toBe(0);
+  });
+
+  it('should detect stale records with non-existent PIDs', () => {
+    // Create an "executing" record with a non-existent PID
+    const record = new ExecutionRecord({
+      command: 'echo stale',
+      pid: 999999999, // Non-existent PID
+      platform: process.platform,
+    });
+    store.save(record);
+
+    const result = store.cleanupStale({ dryRun: true });
+    expect(result.records.length).toBe(1);
+    expect(result.records[0].uuid).toBe(record.uuid);
+    expect(result.cleaned).toBe(1);
+  });
+
+  it('should detect stale records that exceed max age', () => {
+    // Create an "executing" record with an old start time
+    const oldTime = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString(); // 25 hours ago
+    const record = new ExecutionRecord({
+      command: 'echo old',
+      pid: process.pid, // Current process (still running)
+      startTime: oldTime,
+      platform: process.platform,
+    });
+    store.save(record);
+
+    // Use default max age (24 hours)
+    const result = store.cleanupStale({ dryRun: true });
+    expect(result.records.length).toBe(1);
+    expect(result.records[0].uuid).toBe(record.uuid);
+  });
+
+  it('should not detect records within max age as stale', () => {
+    // Create an "executing" record with a recent start time
+    const record = new ExecutionRecord({
+      command: 'echo recent',
+      pid: process.pid, // Current process (still running)
+      platform: process.platform,
+    });
+    store.save(record);
+
+    const result = store.cleanupStale({ dryRun: true });
+    // Should not find this as stale because process is running and not too old
+    expect(result.records.length).toBe(0);
+  });
+
+  it('should clean up stale records when dryRun is false', () => {
+    // Create an "executing" record with a non-existent PID
+    const record = new ExecutionRecord({
+      command: 'echo cleanup-me',
+      pid: 999999999, // Non-existent PID
+      platform: process.platform,
+    });
+    store.save(record);
+
+    // Verify it's still "executing"
+    let retrieved = store.get(record.uuid);
+    expect(retrieved.status).toBe(ExecutionStatus.EXECUTING);
+
+    // Clean it up
+    const result = store.cleanupStale({ dryRun: false });
+    expect(result.cleaned).toBe(1);
+
+    // Verify it's now "executed" with exit code -1
+    retrieved = store.get(record.uuid);
+    expect(retrieved.status).toBe(ExecutionStatus.EXECUTED);
+    expect(retrieved.exitCode).toBe(-1);
+    expect(retrieved.endTime).toBeTruthy();
+  });
+
+  it('should handle custom max age', () => {
+    // Create an "executing" record with start time 5 minutes ago
+    const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+    const record = new ExecutionRecord({
+      command: 'echo custom-age',
+      pid: process.pid, // Current process (still running)
+      startTime: fiveMinutesAgo,
+      platform: process.platform,
+    });
+    store.save(record);
+
+    // Should not find as stale with default 24h max age
+    let result = store.cleanupStale({ dryRun: true });
+    expect(result.records.length).toBe(0);
+
+    // Should find as stale with 1 minute max age
+    result = store.cleanupStale({ dryRun: true, maxAgeMs: 60 * 1000 });
+    expect(result.records.length).toBe(1);
+  });
+});
+
 console.log('=== Execution Store Unit Tests ===');

package/test/isolation.test.js

@@ -714,13 +714,19 @@ describe('Isolation Runner with Available Backends', () => {
     });
 
     it('should pass options to backend', async () => {
-      // Test docker without image - should fail with specific error
-      const result = await runIsolated('docker', 'echo test', {});
-      assert.strictEqual(result.success, false);
-      // Either docker not installed or image required
-      assert.ok(
-        result.message.includes('docker') || result.message.includes('image')
-      );
+      // Test docker with explicit image - should work if docker is installed
+      // or fail with docker-not-installed error (not image-required error)
+      const result = await runIsolated('docker', 'echo test', {
+        image: 'alpine:latest',
+      });
+      // If docker is not installed, we get a docker-related error
+      // If docker is installed, it might succeed or fail for other reasons
+      if (!result.success) {
+        assert.ok(
+          result.message.toLowerCase().includes('docker'),
+          `Expected docker-related error, got: ${result.message}`
+        );
+      }
     });
   });
 });