start-command 0.32.0 → 0.33.0

package/src/lib/query-commands.js

@@ -0,0 +1,202 @@
+/**
+ * Query and control command handlers.
+ *
+ * Every option in this module addresses an execution that already exists in
+ * the tracking store instead of launching a new one: --status, --list,
+ * --upload-log, --stop, --terminate, --attach, --resume, --resume-all and
+ * --cleanup. `dispatchQueryCommand` is the single entry point the CLI calls
+ * before it starts interpreting the command line as a command to run.
+ */
+
+const { queryStatus, listExecutions } = require('./status-formatter');
+const { ControlAction, controlExecution } = require('./execution-control');
+const { attachExecution } = require('./execution-attach');
+const { resumeAllExecutions, resumeExecution } = require('./execution-resume');
+const { uploadExecutionLog } = require('./log-uploader');
+
+/**
+ * Print a handler result, returning the process exit code.
+ * @param {{success: boolean, output?: string, error?: string, exitCode?: number}} result
+ * @returns {number} Exit code
+ */
+function reportResult(result) {
+  if (result.success) {
+    if (result.output) {
+      console.log(result.output);
+    }
+    return result.exitCode || 0;
+  }
+  console.error(`Error: ${result.error}`);
+  return result.exitCode || 1;
+}
+
+function handleStatusQuery(store, identifier, outputFormat) {
+  return reportResult(queryStatus(store, identifier, outputFormat));
+}
+
+function handleListQuery(store, outputFormat, options = {}) {
+  return reportResult(listExecutions(store, outputFormat, options));
+}
+
+function handleUploadLogQuery(store, identifier) {
+  const result = uploadExecutionLog(store, identifier);
+  if (result.success) {
+    return result.exitCode || 0;
+  }
+  console.error(`Error: ${result.error}`);
+  return result.exitCode || 1;
+}
+
+function handleControlQuery(store, identifier, action) {
+  return reportResult(controlExecution(store, identifier, action));
+}
+
+function handleAttachQuery(store, identifier, readOnly) {
+  return reportResult(attachExecution(store, identifier, { readOnly }));
+}
+
+async function handleResumeQuery(store, identifier, command, outputFormat) {
+  return reportResult(
+    await resumeExecution(store, identifier, { command, outputFormat })
+  );
+}
+
+function handleResumeAllQuery(store, outputFormat) {
+  return reportResult(resumeAllExecutions(store, { outputFormat }));
+}
+
+/**
+ * Handle --cleanup / --cleanup-dry-run.
+ * Cleans up stale "executing" records (processes that crashed or were killed).
+ * @param {?object} store - Execution store
+ * @param {boolean} dryRun - If true, just report what would be cleaned
+ * @returns {number} Exit code
+ */
+function handleCleanup(store, dryRun) {
+  if (!store) {
+    console.error('Error: Execution tracking is disabled.');
+    return 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 0;
+  }
+
+  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.');
+  }
+  return 0;
+}
+
+function hasValue(value) {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Report whether any query/control mode is active.
+ * @param {object} options - Parsed wrapper options
+ * @returns {boolean} True when the invocation addresses a stored execution
+ */
+function hasQueryMode(options) {
+  return (
+    hasValue(options.status) ||
+    options.list === true ||
+    hasValue(options.uploadLog) ||
+    hasValue(options.stop) ||
+    hasValue(options.terminate) ||
+    hasValue(options.attach) ||
+    hasValue(options.resume) ||
+    options.resumeAll === true ||
+    options.cleanup === true
+  );
+}
+
+/**
+ * Run the query/control mode selected by the wrapper options, if any.
+ * @param {object} options - Parsed wrapper options
+ * @param {object} context - {store, command}
+ * @returns {Promise<?number>} Exit code, or null when no query mode is active
+ */
+async function dispatchQueryCommand(options, context = {}) {
+  const store = context.store || null;
+  const outputFormat = options.outputFormat;
+
+  if (hasValue(options.status)) {
+    return handleStatusQuery(store, options.status, outputFormat);
+  }
+  if (options.list) {
+    return handleListQuery(store, outputFormat, { running: options.running });
+  }
+  if (hasValue(options.uploadLog)) {
+    return handleUploadLogQuery(store, options.uploadLog);
+  }
+  if (hasValue(options.stop)) {
+    return handleControlQuery(store, options.stop, ControlAction.STOP);
+  }
+  if (hasValue(options.terminate)) {
+    return handleControlQuery(
+      store,
+      options.terminate,
+      ControlAction.TERMINATE
+    );
+  }
+  if (hasValue(options.attach)) {
+    return handleAttachQuery(store, options.attach, options.readOnly === true);
+  }
+  if (hasValue(options.resume)) {
+    return await handleResumeQuery(
+      store,
+      options.resume,
+      context.command || null,
+      outputFormat
+    );
+  }
+  if (options.resumeAll) {
+    return handleResumeAllQuery(store, outputFormat);
+  }
+  if (options.cleanup) {
+    return handleCleanup(store, options.cleanupDryRun);
+  }
+
+  return null;
+}
+
+module.exports = {
+  dispatchQueryCommand,
+  hasQueryMode,
+  handleAttachQuery,
+  handleCleanup,
+  handleControlQuery,
+  handleListQuery,
+  handleResumeAllQuery,
+  handleResumeQuery,
+  handleStatusQuery,
+  handleUploadLogQuery,
+  reportResult,
+};

package/src/lib/screen-isolation.js

@@ -8,6 +8,7 @@ const {
   getTempDir,
   wrapCommandWithLogFooter,
 } = require('./isolation-log-utils');
+const { toShellWords } = require('./shell-utils');
 
 const setTimeout = globalThis.setTimeout;
 
@@ -213,7 +214,7 @@ function runScreenWithLogCapture(
             '-L',
             '-c',
             screenrcFile,
-            ...command.trim().split(/\s+/),
+            ...toShellWords(command),
           ]
         : [
             '-dmS',

package/src/lib/session-probe.js

@@ -0,0 +1,121 @@
+/**
+ * Session liveness probing for tracked executions.
+ *
+ * `--attach`, `--resume` and `--resume-all` all need the same question
+ * answered first: is the isolation session behind this execution record still
+ * alive, stopped but recoverable, or gone entirely? The probe never mutates
+ * anything, so it is safe to run against every tracked record.
+ */
+
+const { runCommand } = require('./execution-control');
+const { getDockerCommand } = require('./docker-cleanup');
+
+/**
+ * States a tracked isolation session can be observed in.
+ * - RUNNING: the session/container is alive and can be attached to
+ * - STOPPED: the container still exists but is not running (resumable)
+ * - MISSING: no trace of the session/container remains
+ * - UNKNOWN: the backend cannot be probed locally (e.g. ssh)
+ */
+const SessionState = {
+  RUNNING: 'running',
+  STOPPED: 'stopped',
+  MISSING: 'missing',
+  UNKNOWN: 'unknown',
+};
+
+/**
+ * Map a `docker inspect -f {{.State.Status}}` value to a session state.
+ * @param {?string} status - Docker container status
+ * @returns {string} SessionState value
+ */
+function mapDockerStatusToState(status) {
+  const normalized = String(status || '')
+    .trim()
+    .toLowerCase();
+  if (!normalized) {
+    return SessionState.UNKNOWN;
+  }
+  if (normalized === 'running' || normalized === 'restarting') {
+    return SessionState.RUNNING;
+  }
+  return SessionState.STOPPED;
+}
+
+/**
+ * Find a session in `screen -ls` output.
+ * Session names are matched exactly against the `<pid>.<name>` column so a
+ * prefix like "session" never matches "my-session".
+ * @param {string} output - Combined stdout/stderr of `screen -ls`
+ * @param {string} sessionName - Session name to look for
+ * @returns {string} SessionState.RUNNING or SessionState.MISSING
+ */
+function parseScreenSessionState(output, sessionName) {
+  for (const line of String(output || '').split('\n')) {
+    const firstColumn = line.trim().split(/\s+/)[0] || '';
+    const match = firstColumn.match(/^(\d+)\.(.+)$/);
+    if (match && match[2] === sessionName) {
+      return SessionState.RUNNING;
+    }
+  }
+  return SessionState.MISSING;
+}
+
+/**
+ * Probe the isolation session behind an execution record.
+ * @param {object} record - Execution record
+ * @param {function} runner - Command runner (injectable for tests)
+ * @returns {{backend: ?string, sessionName: ?string, state: string, alive: boolean, containerStatus: ?string}}
+ */
+function probeSession(record, runner = runCommand) {
+  const opts = (record && record.options) || {};
+  const backend = opts.isolated || null;
+  const sessionName = opts.sessionName || null;
+  const probe = {
+    backend,
+    sessionName,
+    state: SessionState.UNKNOWN,
+    alive: false,
+    containerStatus: null,
+  };
+
+  if (!sessionName || !backend) {
+    return probe;
+  }
+
+  if (backend === 'docker') {
+    const result = runner(getDockerCommand(), [
+      'inspect',
+      '-f',
+      '{{.State.Status}}',
+      sessionName,
+    ]);
+    if (!result.success) {
+      probe.state = SessionState.MISSING;
+      return probe;
+    }
+    probe.containerStatus = String(result.stdout || '').trim() || null;
+    probe.state = mapDockerStatusToState(probe.containerStatus);
+  } else if (backend === 'screen') {
+    const result = runner('screen', ['-ls']);
+    // `screen -ls` exits non-zero even when it lists sessions, so the output is
+    // authoritative, not the exit status.
+    probe.state = parseScreenSessionState(
+      `${result.stdout || ''}${result.stderr || ''}`,
+      sessionName
+    );
+  } else if (backend === 'tmux') {
+    const result = runner('tmux', ['has-session', '-t', sessionName]);
+    probe.state = result.success ? SessionState.RUNNING : SessionState.MISSING;
+  }
+
+  probe.alive = probe.state === SessionState.RUNNING;
+  return probe;
+}
+
+module.exports = {
+  SessionState,
+  mapDockerStatusToState,
+  parseScreenSessionState,
+  probeSession,
+};

package/src/lib/shell-utils.js

@@ -4,21 +4,146 @@ const path = require('path');
 
 const SHELL_NAMES = ['bash', 'zsh', 'sh', 'fish', 'ksh', 'csh', 'tcsh', 'dash'];
 
+/** Argument characters that a POSIX shell reads literally, so they need no quoting. */
+const SAFE_ARG_PATTERN = /^[A-Za-z0-9_@%+=:,./^-]+$/;
+
+/**
+ * Argument characters PowerShell reads literally. Narrower than the POSIX set:
+ * `,` builds an array, `@` splats and `%` is an alias for ForEach-Object.
+ */
+const POWERSHELL_SAFE_ARG_PATTERN = /^[A-Za-z0-9_=:.\\/-]+$/;
+
+/** The quoting dialect of the shell that will run the rebuilt command line. */
+function defaultShellQuotingStyle() {
+  return process.platform === 'win32' ? 'powershell' : 'posix';
+}
+
+/**
+ * Quote one argv element so the target shell parses it back as exactly that
+ * element (issue #164). PowerShell escapes a single quote by doubling it;
+ * a POSIX shell closes the quote, escapes, and reopens.
+ * @param {string} arg - Argument to quote
+ * @param {'posix'|'powershell'} [style] - Quoting dialect; defaults to the host shell
+ * @returns {string} Quoted argument
+ */
+function quoteShellArg(arg, style = defaultShellQuotingStyle()) {
+  const value = String(arg);
+  if (style === 'powershell') {
+    return POWERSHELL_SAFE_ARG_PATTERN.test(value)
+      ? value
+      : `'${value.replace(/'/g, "''")}'`;
+  }
+  return SAFE_ARG_PATTERN.test(value)
+    ? value
+    : `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Rebuild a shell command line from the argv the user typed (issue #164).
+ * A single element is a shell script the user quoted as a whole (`$ "ls | wc -l"`)
+ * and is kept verbatim; multiple elements were split by the outer shell, so each
+ * one is quoted to survive the inner shell unchanged.
+ * @param {string[]} argv - Command arguments
+ * @param {'posix'|'powershell'} [style] - Quoting dialect; defaults to the host shell
+ * @returns {string} Command line for `sh -c` (or `powershell -Command` on Windows)
+ */
+function buildCommandString(argv, style = defaultShellQuotingStyle()) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    return '';
+  }
+  return argv.length === 1
+    ? argv[0]
+    : argv.map((arg) => quoteShellArg(arg, style)).join(' ');
+}
+
+/**
+ * Split a command line into shell words, reversing quoteShellArg for the same
+ * dialect: a POSIX shell escapes with a backslash, PowerShell has no backslash
+ * escape (it is a path separator) and writes a literal quote as a doubled one.
+ * @param {string} command - Command line
+ * @param {'posix'|'powershell'} [style] - Quoting dialect; defaults to the host shell
+ * @returns {string[]|null} Words, or null when quoting is unbalanced
+ */
+function splitShellWords(command, style = defaultShellQuotingStyle()) {
+  const isPowerShell = style === 'powershell';
+  const words = [];
+  let current = '';
+  let started = false;
+  let quote = null;
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+    if (quote === null && /\s/.test(char)) {
+      if (started) {
+        words.push(current);
+        current = '';
+        started = false;
+      }
+      continue;
+    }
+    started = true;
+    if (!isPowerShell && char === '\\' && quote !== "'") {
+      if (i + 1 >= command.length) {
+        return null;
+      }
+      current += command[++i];
+      continue;
+    }
+    if (quote === null && (char === "'" || char === '"')) {
+      quote = char;
+      continue;
+    }
+    if (char === quote) {
+      if (isPowerShell && command[i + 1] === quote) {
+        current += quote;
+        i++;
+        continue;
+      }
+      quote = null;
+      continue;
+    }
+    current += char;
+  }
+
+  if (quote !== null) {
+    return null;
+  }
+  if (started) {
+    words.push(current);
+  }
+  return words;
+}
+
+/** Split a command into words, falling back to whitespace splitting when quoting is unbalanced. */
+function toShellWords(command) {
+  return (
+    splitShellWords(command) ?? command.trim().split(/\s+/).filter(Boolean)
+  );
+}
+
 /** True if command is a bare shell invocation (no -c); avoids bash-inside-bash (issue #84). */
 function isInteractiveShellCommand(command) {
-  const parts = command.trim().split(/\s+/);
-  return SHELL_NAMES.includes(path.basename(parts[0])) && !parts.includes('-c');
+  const parts = toShellWords(command);
+  return (
+    parts.length > 0 &&
+    SHELL_NAMES.includes(path.basename(parts[0])) &&
+    !parts.includes('-c')
+  );
 }
 
 /** True if command is a shell invocation with -c (e.g. `bash -i -c "cmd"`); avoids double-wrapping (issue #91). */
 function isShellInvocationWithArgs(command) {
-  const parts = command.trim().split(/\s+/);
-  return SHELL_NAMES.includes(path.basename(parts[0])) && parts.includes('-c');
+  const parts = toShellWords(command);
+  return (
+    parts.length > 0 &&
+    SHELL_NAMES.includes(path.basename(parts[0])) &&
+    parts.includes('-c')
+  );
 }
 
-/** Build argv for shell-with-c command; everything after -c is one argument (reverses commandArgs.join(' ')). */
+/** Build argv for shell-with-c command; everything after -c is one script argument. */
 function buildShellWithArgsCmdArgs(command) {
-  const parts = command.trim().split(/\s+/);
+  const parts = toShellWords(command);
   const cIdx = parts.indexOf('-c');
   if (cIdx === -1) {
     return parts;
@@ -29,19 +154,48 @@ function buildShellWithArgsCmdArgs(command) {
     : parts.slice(0, cIdx + 1);
 }
 
-/** Build a display string for a command, quoting arguments that contain spaces (issue #91). */
+/** Quote an argument for display only, keeping the user-facing double-quoted form (issue #91). */
+function quoteForDisplay(arg) {
+  if (SAFE_ARG_PATTERN.test(arg)) {
+    return arg;
+  }
+  return arg.includes('"') ? `'${arg}'` : `"${arg}"`;
+}
+
+/**
+ * Build a display string that shows the argument boundaries the user typed
+ * (issues #91, #164). A command the user quoted as one shell script is shown
+ * verbatim, because its metacharacters are meant for the shell, not for display.
+ * @param {string} command - Command line
+ * @returns {string} Display string
+ */
 function buildDisplayCommand(command) {
-  if (!isShellInvocationWithArgs(command)) {
+  if (isShellInvocationWithArgs(command)) {
+    return buildShellWithArgsCmdArgs(command).map(quoteForDisplay).join(' ');
+  }
+  const words = splitShellWords(command);
+  if (!words || buildCommandString(words) !== command) {
     return command;
   }
-  const argv = buildShellWithArgsCmdArgs(command);
-  return argv.map((arg) => (arg.includes(' ') ? `"${arg}"` : arg)).join(' ');
+  return words.map(quoteForDisplay).join(' ');
+}
+
+/** First word of a command line, used for failure reports and log headers. */
+function getCommandName(command) {
+  const parts = toShellWords(command);
+  return parts.length > 0 ? parts[0] : '';
 }
 
 module.exports = {
   SHELL_NAMES,
+  defaultShellQuotingStyle,
+  quoteShellArg,
+  buildCommandString,
+  splitShellWords,
+  toShellWords,
   isInteractiveShellCommand,
   isShellInvocationWithArgs,
   buildShellWithArgsCmdArgs,
   buildDisplayCommand,
+  getCommandName,
 };