start-command 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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
@@ -15,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

@@ -32,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.26.0",
+  "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

@@ -32,6 +32,7 @@ const {
 const { handleFailure } = require('../lib/failure-handler');
 const { ExecutionStore, ExecutionRecord } = require('../lib/execution-store');
 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');
@@ -200,6 +201,21 @@ if (wrapperOptions.list) {
   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);
@@ -284,6 +300,16 @@ function handleListQuery(outputFormat) {
   }
 }
 
+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)
@@ -445,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: {
@@ -556,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

@@ -22,6 +22,8 @@
  * --status <uuid>                  Show status of a previous command execution by UUID
  * --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)
  */
@@ -53,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
  */
@@ -172,6 +178,8 @@ function parseArgs(args) {
     status: null, // UUID to show status for
     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
   };
@@ -432,7 +440,55 @@ 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;
   }
 
@@ -656,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(', ')}`
@@ -664,12 +720,22 @@ function validateOptions(options) {
     }
   }
 
-  // Single-record and list query modes are mutually exclusive
-  if (options.status && options.list) {
-    throw new Error('Cannot use both --status and --list at the same time');
+  // 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 query modes
+  // 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'

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,
+};

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
@@ -288,7 +330,7 @@ function indentBlock(block, spaces) {
 }
 
 function prepareRecordForList(record) {
-  return attachCurrentTime(enrichDetachedStatus(record));
+  return attachCurrentTime(attachProcessIds(enrichDetachedStatus(record)));
 }
 
 /**
@@ -374,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'),
@@ -421,4 +464,5 @@ module.exports = {
   isDetachedSessionAlive,
   enrichDetachedStatus,
   attachCurrentTime,
+  attachProcessIds,
 };