start-command 0.25.5 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # start-command
 
+## 0.27.0
+
+### Minor Changes
+
+- Add `--stop` and `--terminate` controls for detached isolated executions and include best-effort process IDs in status output.
+
+  Fix CI release note generation so language-prefixed GitHub Releases read the package changelog and include exact-version badges.
+
+  Fix release pipeline so multi-changeset merges and JS GitHub Releases work end-to-end. The `merge-changesets.mjs` helper now reads the package name from `package.json` and accepts a `--working-dir` flag, fixing the `ENOENT: no such file or directory, scandir '.changeset'` failure on the JS release workflow when more than one changeset is pending. JS GitHub Releases now also include the exact-version npm badge alongside the existing Rust crates badge.
+
+## 0.26.0
+
+### Minor Changes
+
+- 01fbd90: Add `--list` to show all tracked command executions in Links Notation, JSON, or text format.
+
 ## 0.25.5
 
 ### Patch Changes
@@ -9,7 +25,7 @@
   releases are now tagged `js-v<version>` with title `[JavaScript] <version>`,
   matching the `rust-v<version>` / `[Rust] <version>` convention needed for the
   mono-repo. Extracted the tag/title construction into `scripts/release-name.mjs`
-  with unit tests in `test/release-name.test.mjs`. See `docs/case-studies/issue-108/`
+  with unit tests in `test/release-name.mjs`. See `docs/case-studies/issue-108/`
   for the full analysis.
 
 ## 0.25.4

package/README.md

@@ -21,6 +21,7 @@ npm install -g start-command
 $ ls -la
 $ npm test
 $ git status
+$ --list
 ```
 
 See the project-wide [README](../README.md), [docs/USAGE.md](../docs/USAGE.md),
@@ -31,7 +32,7 @@ and [docs/PIPES.md](../docs/PIPES.md) for the full user-facing guide.
 ```bash
 cd js
 bun install
-bun test
+bun run test
 bun run lint
 ```
 

package/bunfig.toml

@@ -1,3 +1,3 @@
 # Bun configuration
-# Note: Bun doesn't support excluding test files directly in config
-# Use CLI flags or file naming patterns instead
+# Tests use repository naming without conventional suffixes, so package scripts pass
+# the test files explicitly instead of relying on Bun's default discovery.

package/eslint.config.mjs

@@ -101,8 +101,8 @@ export default [
     // Test files and experiments have different requirements
     files: [
       'test/**/*.js',
+      'test/**/*.mjs',
       'tests/**/*.js',
-      '**/*.test.js',
       'experiments/**/*.js',
     ],
     languageOptions: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.25.5",
+  "version": "0.27.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {
@@ -11,7 +11,7 @@
     "$": "./src/bin/cli.js"
   },
   "scripts": {
-    "test": "bun test test/",
+    "test": "bun ../scripts/run-js-tests.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",

package/src/bin/cli.js

@@ -31,10 +31,12 @@ const {
 } = require('../lib/user-manager');
 const { handleFailure } = require('../lib/failure-handler');
 const { ExecutionStore, ExecutionRecord } = require('../lib/execution-store');
-const { queryStatus } = require('../lib/status-formatter');
+const { queryStatus, listExecutions } = require('../lib/status-formatter');
+const { ControlAction, controlExecution } = require('../lib/execution-control');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
 const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
+const { printUsage } = require('../lib/usage');
 
 // Configuration from environment variables
 const config = {
@@ -193,6 +195,27 @@ if (wrapperOptions.status) {
   process.exit(0);
 }
 
+// Handle --list flag
+if (wrapperOptions.list) {
+  handleListQuery(wrapperOptions.outputFormat);
+  process.exit(0);
+}
+
+// Handle --stop flag
+if (wrapperOptions.stop !== null && wrapperOptions.stop !== undefined) {
+  handleControlQuery(wrapperOptions.stop, ControlAction.STOP);
+  process.exit(0);
+}
+
+// Handle --terminate flag
+if (
+  wrapperOptions.terminate !== null &&
+  wrapperOptions.terminate !== undefined
+) {
+  handleControlQuery(wrapperOptions.terminate, ControlAction.TERMINATE);
+  process.exit(0);
+}
+
 // Handle --cleanup flag
 if (wrapperOptions.cleanup) {
   handleCleanup(wrapperOptions.cleanupDryRun);
@@ -267,6 +290,26 @@ function handleStatusQuery(uuid, outputFormat) {
   }
 }
 
+function handleListQuery(outputFormat) {
+  const result = listExecutions(getExecutionStore(), outputFormat);
+  if (result.success) {
+    console.log(result.output);
+  } else {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+}
+
+function handleControlQuery(identifier, action) {
+  const result = controlExecution(getExecutionStore(), identifier, action);
+  if (result.success) {
+    console.log(result.output);
+  } else {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+}
+
 /**
  * Handle --cleanup flag
  * Cleans up stale "executing" records (processes that crashed or were killed)
@@ -314,72 +357,6 @@ function handleCleanup(dryRun) {
   }
 }
 
-/** Print usage information */
-function printUsage() {
-  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>]
-
-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)
-  --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
-  $ --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'
-  );
-}
-
 /**
  * Run command in isolation mode
  * @param {object} options - Wrapper options
@@ -494,6 +471,7 @@ async function runWithIsolation(
       uuid: sessionId, // Use the provided session ID
       command: cmd,
       logPath: logFilePath,
+      pid: process.pid,
       shell,
       workingDirectory: process.cwd(),
       options: {
@@ -605,6 +583,9 @@ async function runWithIsolation(
 
   // Update execution record: detached keeps "executing" (resolved at query time)
   if (executionRecord && store) {
+    if (result.containerId) {
+      executionRecord.options.containerId = result.containerId;
+    }
     if (mode !== 'detached') {
       executionRecord.complete(exitCode);
     }

package/src/lib/args-parser.js

@@ -20,7 +20,10 @@
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --verbose                        Enable verbose/debug output (sets START_VERBOSE=1)
  * --status <uuid>                  Show status of a previous command execution by UUID
- * --output-format <format>         Output format for status (links-notation, json, text)
+ * --list                           List all tracked command executions
+ * --output-format <format>         Output format for status/list (links-notation, json, text)
+ * --stop <uuid-or-session-name>     Send CTRL+C/SIGINT to a detached execution
+ * --terminate <uuid-or-session-name> Terminate a detached execution immediately
  * --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)
  */
@@ -52,6 +55,10 @@ const MAX_ISOLATION_DEPTH = 7;
  */
 const VALID_OUTPUT_FORMATS = ['links-notation', 'json', 'text'];
 
+function hasValue(value) {
+  return value !== null && value !== undefined;
+}
+
 /**
  * UUID v4 regex pattern for validation
  */
@@ -169,7 +176,10 @@ function parseArgs(args) {
     shell: 'auto', // Shell to use in isolation environments: auto, bash, zsh, sh
     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)
+    list: false, // List all tracked execution records
+    outputFormat: null, // Output format for status/list (links-notation, json, text)
+    stop: null, // UUID/session name to stop gracefully
+    terminate: null, // UUID/session name to terminate immediately
     cleanup: false, // Clean up stale "executing" records
     cleanupDryRun: false, // Show what would be cleaned without actually cleaning
   };
@@ -430,7 +440,61 @@ function parseOption(args, index, options) {
 
   // --status=<value>
   if (arg.startsWith('--status=')) {
-    options.status = arg.split('=')[1];
+    const value = arg.slice('--status='.length);
+    if (!value) {
+      throw new Error(
+        `Option --status requires a UUID or session name argument`
+      );
+    }
+    options.status = value;
+    return 1;
+  }
+
+  // --stop <uuid-or-session-name>
+  if (arg === '--stop') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.stop = args[index + 1];
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires a UUID or session name argument`);
+    }
+  }
+
+  // --stop=<value>
+  if (arg.startsWith('--stop=')) {
+    const value = arg.slice('--stop='.length);
+    if (!value) {
+      throw new Error(`Option --stop requires a UUID or session name argument`);
+    }
+    options.stop = value;
+    return 1;
+  }
+
+  // --terminate <uuid-or-session-name>
+  if (arg === '--terminate') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.terminate = args[index + 1];
+      return 2;
+    } else {
+      throw new Error(`Option ${arg} requires a UUID or session name argument`);
+    }
+  }
+
+  // --terminate=<value>
+  if (arg.startsWith('--terminate=')) {
+    const value = arg.slice('--terminate='.length);
+    if (!value) {
+      throw new Error(
+        `Option --terminate requires a UUID or session name argument`
+      );
+    }
+    options.terminate = value;
+    return 1;
+  }
+
+  // --list
+  if (arg === '--list') {
+    options.list = true;
     return 1;
   }
 
@@ -648,7 +712,7 @@ function validateOptions(options) {
   }
 
   // Validate output format
-  if (options.outputFormat !== null && options.outputFormat !== undefined) {
+  if (hasValue(options.outputFormat)) {
     if (!VALID_OUTPUT_FORMATS.includes(options.outputFormat)) {
       throw new Error(
         `Invalid output format: "${options.outputFormat}". Valid options are: ${VALID_OUTPUT_FORMATS.join(', ')}`
@@ -656,9 +720,26 @@ function validateOptions(options) {
     }
   }
 
-  // Output format is only valid with --status
-  if (options.outputFormat && !options.status) {
-    throw new Error('--output-format option is only valid with --status');
+  // Query/control modes are mutually exclusive
+  const queryModes = [
+    hasValue(options.status),
+    options.list,
+    hasValue(options.stop),
+    hasValue(options.terminate),
+    options.cleanup,
+  ].filter(Boolean).length;
+
+  if (queryModes > 1) {
+    throw new Error(
+      'Cannot combine --status, --list, --stop, --terminate, or --cleanup in the same invocation'
+    );
+  }
+
+  // Output format is only valid with read-only query modes
+  if (options.outputFormat && !options.status && !options.list) {
+    throw new Error(
+      '--output-format option is only valid with --status or --list'
+    );
   }
 
   // Validate shell option

package/src/lib/execution-control.js

@@ -0,0 +1,317 @@
+/**
+ * Detached execution control helpers.
+ *
+ * Maps start-command execution records back to their native isolation backend
+ * controls so `--stop` and `--terminate` can target the stored session name.
+ */
+
+const { spawnSync } = require('child_process');
+const {
+  escapeForLinksNotation,
+  formatAsNestedLinksNotation,
+} = require('./output-blocks');
+
+const ControlAction = {
+  STOP: 'stop',
+  TERMINATE: 'terminate',
+};
+
+function runCommand(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  return {
+    success: !result.error && result.status === 0,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    status: result.status,
+    error: result.error ? result.error.message : null,
+  };
+}
+
+function parsePid(value) {
+  const pid = Number.parseInt(String(value).trim(), 10);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+function parsePids(output) {
+  return output
+    .split(/\s+/)
+    .map(parsePid)
+    .filter((pid) => pid !== null);
+}
+
+function parseScreenPid(screenListOutput, sessionName) {
+  for (const line of screenListOutput.split('\n')) {
+    const firstColumn = line.trim().split(/\s+/)[0] || '';
+    const match = firstColumn.match(/^(\d+)\.(.+)$/);
+    if (match && match[2] === sessionName) {
+      return parsePid(match[1]);
+    }
+  }
+  return null;
+}
+
+function collectDescendantPids(rootPid, runner = runCommand) {
+  const descendants = [];
+  const seen = new Set([rootPid]);
+  const queue = [rootPid];
+
+  while (queue.length > 0) {
+    const parentPid = queue.shift();
+    const result = runner('pgrep', ['-P', String(parentPid)]);
+    if (!result.success && !result.stdout) {
+      continue;
+    }
+
+    for (const childPid of parsePids(result.stdout)) {
+      if (seen.has(childPid)) {
+        continue;
+      }
+      seen.add(childPid);
+      descendants.push(childPid);
+      queue.push(childPid);
+    }
+  }
+
+  return descendants;
+}
+
+function addIfPresent(target, key, value) {
+  if (value !== null && value !== undefined) {
+    if (!Array.isArray(value) || value.length > 0) {
+      target[key] = value;
+    }
+  }
+}
+
+function collectProcessIds(record, runner = runCommand) {
+  if (!record) {
+    return null;
+  }
+
+  const processIds = {};
+  const opts = record.options || {};
+  const sessionName = opts.sessionName;
+  const isolated = opts.isolated;
+
+  addIfPresent(processIds, 'wrapperPid', record.pid);
+
+  if (!sessionName || !isolated) {
+    return Object.keys(processIds).length > 0 ? processIds : null;
+  }
+
+  if (isolated === 'screen') {
+    const result = runner('screen', ['-ls']);
+    const output = `${result.stdout || ''}${result.stderr || ''}`;
+    const screenPid = parseScreenPid(output, sessionName);
+    addIfPresent(processIds, 'screenPid', screenPid);
+    if (screenPid) {
+      addIfPresent(
+        processIds,
+        'commandPids',
+        collectDescendantPids(screenPid, runner)
+      );
+    }
+  } else if (isolated === 'tmux') {
+    const tmuxPidResult = runner('tmux', [
+      'display-message',
+      '-p',
+      '-t',
+      sessionName,
+      '#{pid}',
+    ]);
+    addIfPresent(processIds, 'tmuxPid', parsePid(tmuxPidResult.stdout));
+
+    const panePidResult = runner('tmux', [
+      'list-panes',
+      '-t',
+      sessionName,
+      '-F',
+      '#{pane_pid}',
+    ]);
+    const panePids = parsePids(panePidResult.stdout);
+    addIfPresent(processIds, 'panePids', panePids);
+
+    const commandPids = [
+      ...new Set(
+        panePids.flatMap((panePid) => collectDescendantPids(panePid, runner))
+      ),
+    ];
+    addIfPresent(processIds, 'commandPids', commandPids);
+  } else if (isolated === 'docker') {
+    addIfPresent(processIds, 'containerId', opts.containerId);
+    const result = runner('docker', [
+      'inspect',
+      '-f',
+      '{{.Id}} {{.State.Pid}}',
+      sessionName,
+    ]);
+    if (result.success && result.stdout.trim()) {
+      const [containerId, pidValue] = result.stdout.trim().split(/\s+/);
+      addIfPresent(processIds, 'containerId', containerId);
+      addIfPresent(processIds, 'containerPid', parsePid(pidValue));
+    }
+  } else if (isolated === 'ssh') {
+    addIfPresent(processIds, 'remotePid', opts.remotePid);
+  }
+
+  return Object.keys(processIds).length > 0 ? processIds : null;
+}
+
+function getControlCommand(record, action) {
+  const opts = record.options || {};
+  const backend = opts.isolated;
+  const sessionName = opts.sessionName;
+
+  if (!sessionName) {
+    return {
+      error: 'Execution record does not contain an isolation session name.',
+    };
+  }
+
+  if (opts.isolationMode !== 'detached') {
+    return {
+      error: 'Only detached isolated executions can be stopped or terminated.',
+    };
+  }
+
+  if (action === ControlAction.STOP) {
+    switch (backend) {
+      case 'screen':
+        return {
+          command: 'screen',
+          args: ['-S', sessionName, '-X', 'stuff', '\x03'],
+          method: 'CTRL_C',
+          message: `Sent CTRL+C to detached screen session: ${sessionName}`,
+        };
+      case 'tmux':
+        return {
+          command: 'tmux',
+          args: ['send-keys', '-t', sessionName, 'C-c'],
+          method: 'CTRL_C',
+          message: `Sent CTRL+C to detached tmux session: ${sessionName}`,
+        };
+      case 'docker':
+        return {
+          command: 'docker',
+          args: ['kill', '--signal=SIGINT', sessionName],
+          method: 'SIGINT',
+          message: `Sent SIGINT to detached docker container: ${sessionName}`,
+        };
+      default:
+        return {
+          error: `Stopping detached ${backend || 'unknown'} executions is not supported.`,
+        };
+    }
+  }
+
+  if (action === ControlAction.TERMINATE) {
+    switch (backend) {
+      case 'screen':
+        return {
+          command: 'screen',
+          args: ['-S', sessionName, '-X', 'quit'],
+          method: 'SCREEN_QUIT',
+          message: `Terminated detached screen session: ${sessionName}`,
+        };
+      case 'tmux':
+        return {
+          command: 'tmux',
+          args: ['kill-session', '-t', sessionName],
+          method: 'KILL_SESSION',
+          message: `Terminated detached tmux session: ${sessionName}`,
+        };
+      case 'docker':
+        return {
+          command: 'docker',
+          args: ['kill', sessionName],
+          method: 'SIGKILL',
+          message: `Terminated detached docker container: ${sessionName}`,
+        };
+      default:
+        return {
+          error: `Terminating detached ${backend || 'unknown'} executions is not supported.`,
+        };
+    }
+  }
+
+  return { error: `Unknown control action: ${action}` };
+}
+
+function formatControlResultAsLinksNotation(result) {
+  const lines = [
+    'executionControl',
+    `  action ${escapeForLinksNotation(result.action)}`,
+    `  identifier ${escapeForLinksNotation(result.identifier)}`,
+    `  uuid ${escapeForLinksNotation(result.uuid)}`,
+    `  status ${escapeForLinksNotation(result.status)}`,
+    `  backend ${escapeForLinksNotation(result.backend)}`,
+    `  sessionName ${escapeForLinksNotation(result.sessionName)}`,
+    `  method ${escapeForLinksNotation(result.method)}`,
+  ];
+
+  if (result.processIds) {
+    lines.push('  processIds');
+    lines.push(formatAsNestedLinksNotation(result.processIds, 2, 2));
+  }
+
+  lines.push(`  message ${escapeForLinksNotation(result.message)}`);
+  return lines.join('\n');
+}
+
+function controlExecution(store, identifier, action, runner = runCommand) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+
+  const record = store.get(identifier);
+  if (!record) {
+    return {
+      success: false,
+      error: `No execution found with UUID or session name: ${identifier}`,
+    };
+  }
+
+  const control = getControlCommand(record, action);
+  if (control.error) {
+    return { success: false, error: control.error };
+  }
+
+  const result = runner(control.command, control.args);
+  if (!result.success) {
+    const detail =
+      result.stderr || result.error || `exit code ${result.status}`;
+    return {
+      success: false,
+      error: `Failed to ${action} ${record.options.isolated} session "${record.options.sessionName}": ${detail}`,
+    };
+  }
+
+  const output = formatControlResultAsLinksNotation({
+    action,
+    identifier,
+    uuid: record.uuid,
+    status: action === ControlAction.STOP ? 'signal-sent' : 'terminated',
+    backend: record.options.isolated,
+    sessionName: record.options.sessionName,
+    method: control.method,
+    processIds: collectProcessIds(record, runner),
+    message: control.message,
+  });
+
+  return { success: true, output };
+}
+
+module.exports = {
+  ControlAction,
+  collectDescendantPids,
+  collectProcessIds,
+  controlExecution,
+  formatControlResultAsLinksNotation,
+  getControlCommand,
+  parseScreenPid,
+  runCommand,
+};