start-command 0.25.5 → 0.27.0

package/src/lib/isolation.js

@@ -545,9 +545,13 @@ function runInDocker(command, options = {}) {
 
   try {
     if (options.detached) {
-      const dockerArgs = ['run', '-d', '--name', containerName];
+      const dockerArgs = ['run', '-d'];
+      if (options.keepAlive) {
+        dockerArgs.push('-i', '-t');
+      }
+      dockerArgs.push('--name', containerName);
       if (options.autoRemoveDockerContainer) {
-        dockerArgs.splice(2, 0, '--rm');
+        dockerArgs.push('--rm');
       }
 
       if (options.user) {
@@ -576,9 +580,23 @@ function runInDocker(command, options = {}) {
         );
       }
 
-      const containerId = execSync(`docker ${dockerArgs.join(' ')}`, {
+      const dockerResult = spawnSync('docker', dockerArgs, {
         encoding: 'utf8',
-      }).trim();
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      if (dockerResult.error) {
+        throw dockerResult.error;
+      }
+      if (dockerResult.status !== 0) {
+        const dockerError =
+          dockerResult.stderr.trim() ||
+          dockerResult.stdout.trim() ||
+          `docker exited with code ${dockerResult.status}`;
+        throw new Error(dockerError);
+      }
+
+      const containerId = dockerResult.stdout.trim();
 
       if (options.logPath) {
         const loggerScript = [

package/src/lib/status-formatter.js

@@ -13,6 +13,7 @@ const {
   escapeForLinksNotation,
   formatAsNestedLinksNotation,
 } = require('./output-blocks');
+const { collectProcessIds } = require('./execution-control');
 
 /**
  * Check if a detached isolation session is still running
@@ -165,6 +166,47 @@ function attachCurrentTime(record) {
   return wrapped;
 }
 
+/**
+ * Wrap a record so its serialized form includes best-effort process IDs.
+ * The original record is not mutated.
+ * @param {Object} record - Execution record
+ * @returns {Object} Record-like object with processIds in toObject()
+ */
+function attachProcessIds(record) {
+  const processIds = collectProcessIds(record);
+  if (!processIds) {
+    return record;
+  }
+
+  const wrapped = Object.create(Object.getPrototypeOf(record));
+  Object.assign(wrapped, record);
+  wrapped.processIds = processIds;
+
+  const sourceToObject =
+    typeof record.toObject === 'function'
+      ? () => record.toObject()
+      : () => ({ ...record });
+
+  wrapped.toObject = function () {
+    const base = sourceToObject();
+    const ordered = {};
+    let inserted = false;
+    for (const [key, value] of Object.entries(base)) {
+      ordered[key] = value;
+      if (key === 'pid') {
+        ordered.processIds = processIds;
+        inserted = true;
+      }
+    }
+    if (!inserted) {
+      ordered.processIds = processIds;
+    }
+    return ordered;
+  };
+
+  return wrapped;
+}
+
 /**
  * Format execution record as Links Notation (indented style)
  * Uses nested Links notation for object values (like options) instead of JSON
@@ -273,6 +315,86 @@ function formatRecord(record, format) {
   }
 }
 
+function sortRecordsByStartTimeDesc(records) {
+  return [...records].sort(
+    (a, b) => new Date(b.startTime).getTime() - new Date(a.startTime).getTime()
+  );
+}
+
+function indentBlock(block, spaces) {
+  const prefix = ' '.repeat(spaces);
+  return block
+    .split('\n')
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function prepareRecordForList(record) {
+  return attachCurrentTime(attachProcessIds(enrichDetachedStatus(record)));
+}
+
+/**
+ * Format execution records as a Links Notation list.
+ * @param {Object[]} records - Execution records
+ * @returns {string} Links Notation formatted list
+ */
+function formatRecordListAsLinksNotation(records) {
+  const lines = ['executions', `  count ${records.length}`];
+
+  if (records.length === 0) {
+    lines.push('  records ()');
+    return lines.join('\n');
+  }
+
+  lines.push('  records');
+  for (const record of records) {
+    lines.push(indentBlock(formatRecordAsLinksNotation(record), 4));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format execution records as human-readable text.
+ * @param {Object[]} records - Execution records
+ * @returns {string} Human-readable list
+ */
+function formatRecordListAsText(records) {
+  const lines = ['Executions', `${'='.repeat(50)}`, `Count: ${records.length}`];
+
+  for (const record of records) {
+    lines.push('', formatRecordAsText(record));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format execution records based on format type.
+ * @param {Object[]} records - Execution records
+ * @param {string} format - Output format (links-notation, json, text)
+ * @returns {string} Formatted output string
+ */
+function formatRecordList(records, format) {
+  switch (format) {
+    case 'links-notation':
+      return formatRecordListAsLinksNotation(records);
+    case 'json':
+      return JSON.stringify(
+        {
+          count: records.length,
+          executions: records.map((record) => record.toObject()),
+        },
+        null,
+        2
+      );
+    case 'text':
+      return formatRecordListAsText(records);
+    default:
+      throw new Error(`Unknown output format: ${format}`);
+  }
+}
+
 /**
  * Handle status query and output the result
  * @param {Object} store - ExecutionStore instance
@@ -294,8 +416,9 @@ function queryStatus(store, identifier, outputFormat) {
   try {
     // Enrich detached execution status with live session check
     const enrichedRecord = enrichDetachedStatus(record);
+    const withProcessIds = attachProcessIds(enrichedRecord);
     // Attach currentTime so callers can see how long an executing command has been running
-    const withCurrentTime = attachCurrentTime(enrichedRecord);
+    const withCurrentTime = attachCurrentTime(withProcessIds);
     return {
       success: true,
       output: formatRecord(withCurrentTime, outputFormat || 'links-notation'),
@@ -305,12 +428,41 @@ function queryStatus(store, identifier, outputFormat) {
   }
 }
 
+/**
+ * Handle execution list query and output the result
+ * @param {Object} store - ExecutionStore instance
+ * @param {string|null} outputFormat - Output format (links-notation, json, text)
+ * @returns {{success: boolean, output?: string, error?: string}}
+ */
+function listExecutions(store, outputFormat) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+
+  try {
+    const records = sortRecordsByStartTimeDesc(
+      store.getAll().map(prepareRecordForList)
+    );
+    return {
+      success: true,
+      output: formatRecordList(records, outputFormat || 'links-notation'),
+    };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
 module.exports = {
   formatRecordAsLinksNotation,
   formatRecordAsText,
   formatRecord,
+  formatRecordListAsLinksNotation,
+  formatRecordListAsText,
+  formatRecordList,
   queryStatus,
+  listExecutions,
   isDetachedSessionAlive,
   enrichDetachedStatus,
   attachCurrentTime,
+  attachProcessIds,
 };

package/src/lib/usage.js

@@ -0,0 +1,74 @@
+/** Print usage information */
+function printUsage() {
+  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>] | $ --stop <id> | $ --terminate <id>
+
+Options:
+  --isolated, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
+  --attached, -a        Run in attached mode (foreground)
+  --detached, -d        Run in detached mode (background)
+  --session, -s <name>  Session name for isolation
+  --session-id <uuid>   Session UUID for tracking (auto-generated if not provided)
+  --session-name <uuid> Alias for --session-id
+  --image <image>       Docker image (required for docker isolation)
+  --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
+  --isolated-user, -u [name]  Create isolated user with same permissions
+  --keep-user           Keep isolated user after command completes
+  --keep-alive, -k      Keep isolation environment alive after command exits
+  --auto-remove-docker-container  Auto-remove docker container after exit
+  --shell <shell>       Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
+  --use-command-stream  Use command-stream library for execution (experimental)
+  --status <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)
+  --list                List all tracked executions (--output-format: links-notation|json|text)
+  --stop <id>           Send CTRL+C/SIGINT to a detached isolated execution
+  --terminate <id>      Terminate a detached isolated execution immediately
+  --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:
+  $ echo "Hello World"
+  $ bun test
+  $ --isolated tmux -- bun start
+  $ -i screen -d bun start
+  $ --isolated docker --image oven/bun:latest -- bun install
+  $ --isolated ssh --endpoint user@remote.server -- ls -la
+  $ --isolated-user -- npm test            # Create isolated user
+  $ -u myuser -- npm start                 # Custom username
+  $ -i screen --isolated-user -- npm test  # Combine with process isolation
+  $ --isolated-user --keep-user -- npm start
+  $ --list                                 # List stored execution records
+  $ --list --output-format json            # List stored records as JSON
+  $ --stop my-screen-session               # Ask detached execution to stop gracefully
+  $ --terminate my-screen-session          # Terminate detached execution immediately
+  $ --use-command-stream echo "Hello"      # Use command-stream library`);
+  console.log('');
+  console.log('Piping with $:');
+  console.log('  echo "hi" | $ agent       # Preferred - pipe TO $ command');
+  console.log(
+    '  $ \'echo "hi" | agent\'   # Alternative - quote entire pipeline'
+  );
+  console.log('');
+  console.log('Quoting for special characters:');
+  console.log("  $ 'npm test && npm build' # Wrap for logical operators");
+  console.log("  $ 'cat file > output.txt' # Wrap for redirections");
+  console.log('');
+  console.log('Features:');
+  console.log('  - Logs all output to temporary directory');
+  console.log('  - Displays timestamps and exit codes');
+  console.log(
+    '  - Auto-reports failures for NPM packages (when gh is available)'
+  );
+  console.log('  - Natural language command aliases (via substitutions.lino)');
+  console.log('  - Process isolation via screen, tmux, or docker');
+  console.log('');
+  console.log('Alias examples:');
+  console.log('  $ install lodash npm package           -> npm install lodash');
+  console.log(
+    '  $ install 4.17.21 version of lodash npm package -> npm install lodash@4.17.21'
+  );
+  console.log(
+    '  $ clone https://github.com/user/repo repository -> git clone https://github.com/user/repo'
+  );
+}
+
+module.exports = { printUsage };

package/test/args-parser-control.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { parseArgs } = require('../src/lib/args-parser');
+
+describe('control options', () => {
+  it('should parse --stop with UUID or session name', () => {
+    const result = parseArgs(['--stop', 'my-session']);
+    assert.strictEqual(result.wrapperOptions.stop, 'my-session');
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --stop=value format', () => {
+    const result = parseArgs(['--stop=my-session']);
+    assert.strictEqual(result.wrapperOptions.stop, 'my-session');
+  });
+
+  it('should parse --terminate with UUID or session name', () => {
+    const result = parseArgs(['--terminate', 'my-session']);
+    assert.strictEqual(result.wrapperOptions.terminate, 'my-session');
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --terminate=value format', () => {
+    const result = parseArgs(['--terminate=my-session']);
+    assert.strictEqual(result.wrapperOptions.terminate, 'my-session');
+  });
+
+  it('should throw error for missing --stop argument', () => {
+    assert.throws(() => {
+      parseArgs(['--stop']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for empty --stop=value argument', () => {
+    assert.throws(() => {
+      parseArgs(['--stop=']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for missing --terminate argument', () => {
+    assert.throws(() => {
+      parseArgs(['--terminate']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should throw error for empty --terminate=value argument', () => {
+    assert.throws(() => {
+      parseArgs(['--terminate=']);
+    }, /requires a UUID or session name argument/);
+  });
+
+  it('should reject combining query and control modes', () => {
+    assert.throws(() => {
+      parseArgs(['--status', 'uuid-here', '--stop', 'my-session']);
+    }, /Cannot combine --status, --list, --stop, --terminate, or --cleanup/);
+  });
+
+  it('should reject output-format with control modes', () => {
+    assert.throws(() => {
+      parseArgs(['--stop', 'my-session', '--output-format', 'json']);
+    }, /--output-format option is only valid with --status or --list/);
+  });
+
+  it('should default control options to null', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.stop, null);
+    assert.strictEqual(result.wrapperOptions.terminate, null);
+  });
+});

package/test/{args-parser.test.js → args-parser.js}

@@ -817,13 +817,13 @@ describe('status option', () => {
   it('should throw error for missing UUID argument', () => {
     assert.throws(() => {
       parseArgs(['--status']);
-    }, /requires a UUID argument/);
+    }, /requires a UUID or session name argument/);
   });
 
   it('should throw error for --status with -flag as next argument', () => {
     assert.throws(() => {
       parseArgs(['--status', '--output-format']);
-    }, /requires a UUID argument/);
+    }, /requires a UUID or session name argument/);
   });
 
   it('should default status to null', () => {
@@ -832,6 +832,30 @@ describe('status option', () => {
   });
 });
 
+describe('list option', () => {
+  it('should parse --list flag', () => {
+    const result = parseArgs(['--list']);
+    assert.strictEqual(result.wrapperOptions.list, true);
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --list with JSON output format', () => {
+    const result = parseArgs(['--list', '--output-format', 'json']);
+    assert.strictEqual(result.wrapperOptions.list, true);
+    assert.strictEqual(result.wrapperOptions.outputFormat, 'json');
+  });
+
+  it('should normalize output format with --list', () => {
+    const result = parseArgs(['--list', '--output-format', 'TEXT']);
+    assert.strictEqual(result.wrapperOptions.outputFormat, 'text');
+  });
+
+  it('should default list to false', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.list, false);
+  });
+});
+
 describe('output-format option', () => {
   it('should parse --output-format with --status', () => {
     const uuid = '12345678-1234-1234-1234-123456789abc';
@@ -874,7 +898,7 @@ describe('output-format option', () => {
   it('should throw error for output-format without status', () => {
     assert.throws(() => {
       parseArgs(['--output-format', 'json', '--', 'npm', 'test']);
-    }, /--output-format option is only valid with --status/);
+    }, /--output-format option is only valid with --status or --list/);
   });
 
   it('should accept all valid output formats', () => {
@@ -928,4 +952,4 @@ describe('cleanup options', () => {
   });
 });
 
-// Shell option tests moved to args-parser-shell.test.js
+// Shell option tests moved to args-parser-shell.js