start-command 0.32.1 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # start-command
 
+## 0.34.0
+
+### Minor Changes
+
+- 22c1158: Persist the terminal state of a detached Docker execution and record the container post-mortem. The completion watcher now writes `status`, `exitCode`, `oomKilled` and a real `endTime` back into the store instead of leaving the record `executing` forever, so `--status` stops calling the clock at query time and reporting a different "finish" on every call. `endTime` carries its provenance in `endTimeSource` (`docker-finished-at`, `log-footer`, `observed-at`); a stale record keeps `endTime` empty and records `staleDetectedAt` instead of a fabricated finish time. The single `docker inspect` now also collects `StartedAt`, `FinishedAt` and `State.Error`, and both the detached and the attached path write a post-mortem block for a kept container and a one-line note for a removed one. Signal decoding (`128+n`) is shared by the log and `--status`, so `137` reads as `137 (SIGKILL - 128+9)` everywhere.
+
+## 0.33.0
+
+### Minor Changes
+
+- Add `--attach`, `--resume`, `--resume-all` and `--list --running` so a detached isolated session can be re-entered, continued, or repaired after a supervisor restart, and surface an `exitReason` hint when a log shows memory exhaustion.
+
+  Keep argument boundaries when rebuilding the command from `argv`: `start node -e "console.log('hi')"` and `start echo "a  b"` now reach the shell with their quoting intact instead of being re-split by the inner `bash -c`. A single argument still runs verbatim as a shell script, so `start 'ls | wc -l'` keeps working; in the multi-argument form a quoted operator such as `start echo a '&&' echo b` is now a literal word.
+
+  Surface `memoryExhausted` and `memoryExhaustedReason` in `--status` when the log shows the runtime aborted on its own memory limit: a Node/V8 heap-limit abort dies below the container limit, so `oomKilled` stays `false` and the only evidence is the `FATAL ERROR` line the runtime printed. The log tail is now scanned with a 64 KiB window (V8 prints a long native stack trace after the marker), the observation covers attached sessions too, and the kept-container footer no longer asserts a bare `oomKilled=false` next to a fatal marker for exit codes 134/139.
+
+  Fix the release automation breaking on Node 24 with `$ is not a function`. `use-m` returns the raw CommonJS namespace `{ default, 'module.exports' }` instead of the callable default, so `const { $ } = await use('command-stream')` destructured `undefined` and every release job died at its first shell command. All eight affected scripts now go through the shared `scripts/load-command-stream.mjs` loader, which resolves either namespace shape and, when it cannot, throws an error naming the keys it actually saw.
+
+  Also hardens every external command the package spawns. `failure-handler` and
+  `ExecutionStore.execClink` interpolated data - the failing command's own name,
+  the log path, recorded command text - into shell strings; they now pass an
+  argument vector, so a backtick, `$(...)` or `'` in a command is no longer
+  executed by a shell. As part of that, `gh issue create` receives the report
+  body verbatim: its newlines previously reached GitHub as the two characters
+  `\n`. Session ids and isolation usernames are now drawn from `crypto` rather
+  than `Math.random()`.
+
 ## 0.32.1
 
 ### Patch Changes

package/README.md

@@ -24,6 +24,9 @@ $ ls -la
 $ bun test
 $ git status
 $ --list
+$ --attach <id>
+$ --resume <id> -- <command>
+$ --resume-all
 ```
 
 See the project-wide [README](../README.md), [docs/USAGE.md](../docs/USAGE.md),

package/eslint.config.mjs

@@ -76,6 +76,14 @@ export default [
         __filename: 'readonly',
         fetch: 'readonly',
         Bun: 'readonly',
+        // Web-standard globals Node exposes; used by the repository-level
+        // scripts/ directory, which the root config lints (issue #168).
+        AbortController: 'readonly',
+        URL: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
       },
     },
     rules: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {
@@ -17,7 +17,9 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "check:file-size": "bun ../scripts/check-file-size.mjs",
-    "check": "bun run lint && bun run format:check && bun run check:file-size",
+    "lint:scripts": "cd .. && eslint .",
+    "format:check:scripts": "cd .. && prettier --check \"scripts/**/*.{js,mjs,cjs}\"",
+    "check": "bun run lint && bun run lint:scripts && bun run format:check && bun run format:check:scripts && bun run check:file-size",
     "prepare": "cd .. && husky .husky || true",
     "changeset": "changeset",
     "changeset:version": "bun ../scripts/changeset-version.mjs",
@@ -70,6 +72,8 @@
     "lino-objects-codec": "^0.4.0"
   },
   "overrides": {
-    "flatted": "^3.4.2"
+    "brace-expansion": "^5.0.9",
+    "flatted": "^3.4.2",
+    "js-yaml": "^4.3.2"
   }
 }

package/src/bin/cli.js

@@ -33,13 +33,13 @@ const {
 } = require('../lib/user-manager');
 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 { uploadExecutionLog } = require('../lib/log-uploader');
+const { reconcileFinalizedRecord } = require('../lib/detached-finalize');
+const { dispatchQueryCommand, hasQueryMode } = require('../lib/query-commands');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
 const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
 const { printUsage } = require('../lib/usage');
+const { buildDisplayCommand, getCommandName } = require('../lib/shell-utils');
 
 // Configuration from environment variables
 const config = {
@@ -192,47 +192,12 @@ try {
 
 const { wrapperOptions, command: parsedCommand } = parsedArgs;
 
-// Handle --status flag
-if (wrapperOptions.status) {
-  handleStatusQuery(wrapperOptions.status, wrapperOptions.outputFormat);
-  process.exit(0);
-}
-
-// Handle --list flag
-if (wrapperOptions.list) {
-  handleListQuery(wrapperOptions.outputFormat);
-  process.exit(0);
-}
-
-// Handle --upload-log flag
-if (wrapperOptions.uploadLog) {
-  const exitCode = handleUploadLogQuery(wrapperOptions.uploadLog);
-  process.exit(exitCode);
-}
-
-// 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);
-  process.exit(0);
-}
+// Query/control modes (--status, --list, --attach, --resume, ...) address an
+// execution that already exists, so they never need a command of their own.
+const isQueryMode = hasQueryMode(wrapperOptions);
 
 // Check if no command was provided
-if (!parsedCommand || parsedCommand.trim() === '') {
+if (!isQueryMode && (!parsedCommand || parsedCommand.trim() === '')) {
   console.error('Error: No command provided');
   printUsage();
   process.exit(1);
@@ -242,7 +207,7 @@ if (!parsedCommand || parsedCommand.trim() === '') {
 let command = parsedCommand;
 let substitutionResult = null;
 
-if (!config.disableSubstitutions) {
+if (!config.disableSubstitutions && parsedCommand && parsedCommand.trim()) {
   substitutionResult = processCommand(parsedCommand, {
     customLinoPath: config.substitutionsPath,
     verbose: config.verbose,
@@ -267,6 +232,14 @@ const sessionId = wrapperOptions.sessionId || generateUUID();
 
 // Main execution
 (async () => {
+  if (isQueryMode) {
+    const queryExitCode = await dispatchQueryCommand(wrapperOptions, {
+      store: getExecutionStore(),
+      command: command && command.trim() ? command : null,
+    });
+    process.exit(queryExitCode === null ? 0 : queryExitCode);
+  }
+
   // Check if running in isolation mode or with user isolation
   if (hasIsolation(wrapperOptions) || wrapperOptions.user) {
     await runWithIsolation(
@@ -289,93 +262,6 @@ const sessionId = wrapperOptions.sessionId || generateUUID();
   }
 })();
 
-function handleStatusQuery(uuid, outputFormat) {
-  const result = queryStatus(getExecutionStore(), uuid, outputFormat);
-  if (result.success) {
-    console.log(result.output);
-  } else {
-    console.error(`Error: ${result.error}`);
-    process.exit(1);
-  }
-}
-
-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 handleUploadLogQuery(identifier) {
-  const result = uploadExecutionLog(getExecutionStore(), identifier);
-  if (result.success) {
-    return result.exitCode || 0;
-  }
-
-  console.error(`Error: ${result.error}`);
-  return result.exitCode || 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)
- * @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.');
-  }
-}
-
 /**
  * Run command in isolation mode
  * @param {object} options - Wrapper options
@@ -519,7 +405,7 @@ async function runWithIsolation(
     createStartBlock({
       sessionId,
       timestamp: startTime,
-      command: cmd,
+      command: buildDisplayCommand(cmd),
       extraLines,
       deferCommand,
     })
@@ -584,6 +470,9 @@ async function runWithIsolation(
       ...buildDockerRuntimeMetadata(options),
       shell: options.shell,
       logPath: logFilePath,
+      // Lets the detached completion watcher write the terminal state back
+      // into this record once the container is gone (issue #170.1).
+      executionId: executionRecord ? executionRecord.uuid : null,
     });
   } else if (createdUser) {
     // Run directly as the created user (no isolation environment)
@@ -619,7 +508,11 @@ async function runWithIsolation(
       executionRecord.complete(exitCode);
     }
     try {
-      store.save(executionRecord);
+      store.save(
+        mode === 'detached'
+          ? reconcileFinalizedRecord(store, executionRecord)
+          : executionRecord
+      );
     } catch (err) {
       if (config.verbose) {
         console.error(
@@ -680,7 +573,7 @@ async function runWithIsolation(
  */
 async function runDirect(cmd, sessionId) {
   // Get the command name (first word of the actual command to execute)
-  const commandName = cmd.split(' ')[0];
+  const commandName = getCommandName(cmd);
 
   // Determine the shell based on the platform
   const isWindows = process.platform === 'win32';
@@ -740,8 +633,8 @@ async function runDirect(cmd, sessionId) {
   // Print start block with session ID
   const displayCommand =
     substitutionResult && substitutionResult.matched
-      ? `${parsedCommand} -> ${cmd}`
-      : cmd;
+      ? `${buildDisplayCommand(parsedCommand)} -> ${buildDisplayCommand(cmd)}`
+      : buildDisplayCommand(cmd);
   console.log(
     createStartBlock({
       sessionId,
@@ -830,7 +723,7 @@ async function runDirectWithCommandStream(
   const { $, raw } = await getCommandStream();
 
   // Get the command name (first word of the actual command to execute)
-  const commandName = cmd.split(' ')[0];
+  const commandName = getCommandName(cmd);
 
   // Determine the shell based on the platform
   const isWindows = process.platform === 'win32';
@@ -890,7 +783,9 @@ async function runDirectWithCommandStream(
 
   // Print start block with session ID
   const displayCmd =
-    subResult && subResult.matched ? `${parsedCmd} -> ${cmd}` : cmd;
+    subResult && subResult.matched
+      ? `${buildDisplayCommand(parsedCmd)} -> ${buildDisplayCommand(cmd)}`
+      : buildDisplayCommand(cmd);
   console.log(
     createStartBlock({
       sessionId,

package/src/lib/args-parser-queries.js

@@ -0,0 +1,228 @@
+/**
+ * Query and control option parsing for the start-command wrapper.
+ *
+ * These options never launch a new command from scratch: they address an
+ * already tracked execution by UUID or session name. They are kept in their own
+ * module so `args-parser.js` stays focused on the launch options.
+ *
+ * Query modes:   --status, --list [--running]
+ * Control modes: --upload-log, --stop, --terminate, --attach [--read-only],
+ *                --resume [-- <command>], --resume-all, --cleanup
+ */
+
+/**
+ * Valid output formats for --status/--list and the machine-readable
+ * --resume/--resume-all summaries.
+ */
+const VALID_OUTPUT_FORMATS = ['links-notation', 'json', 'text'];
+
+/**
+ * Default values for every query/control option.
+ * @returns {object} Fresh defaults (never share the same object between parses)
+ */
+function createQueryOptionDefaults() {
+  return {
+    status: null, // UUID/session name to show status for
+    list: false, // List all tracked execution records
+    running: false, // Restrict --list to executions that are still running
+    uploadLog: null, // UUID/session name whose stored log should be uploaded
+    outputFormat: null, // Output format (links-notation, json, text)
+    stop: null, // UUID/session name to stop gracefully
+    terminate: null, // UUID/session name to terminate immediately
+    attach: null, // UUID/session name whose terminal should be attached
+    readOnly: false, // Follow --attach output without forwarding stdin
+    resume: null, // UUID/session name to resume (optionally with a new command)
+    resumeAll: false, // Re-attach/resume every execution still marked running
+    cleanup: false, // Clean up stale "executing" records
+    cleanupDryRun: false, // Show what would be cleaned without cleaning
+  };
+}
+
+/**
+ * Options that take a `<uuid-or-session-name>` argument, mapped to the wrapper
+ * option they populate.
+ */
+const IDENTIFIER_OPTIONS = {
+  '--status': 'status',
+  '--upload-log': 'uploadLog',
+  '--stop': 'stop',
+  '--terminate': 'terminate',
+  '--attach': 'attach',
+  '--resume': 'resume',
+};
+
+/**
+ * Boolean flags with no argument.
+ */
+const FLAG_OPTIONS = {
+  '--list': (options) => {
+    options.list = true;
+  },
+  '--running': (options) => {
+    options.running = true;
+  },
+  '--read-only': (options) => {
+    options.readOnly = true;
+  },
+  '--resume-all': (options) => {
+    options.resumeAll = true;
+  },
+  '--cleanup': (options) => {
+    options.cleanup = true;
+  },
+  '--cleanup-dry-run': (options) => {
+    options.cleanup = true;
+    options.cleanupDryRun = true;
+  },
+};
+
+function hasValue(value) {
+  return value !== null && value !== undefined;
+}
+
+/**
+ * Parse a single query/control option.
+ * @param {string[]} args - Arguments array
+ * @param {number} index - Current index
+ * @param {object} options - Options object to populate
+ * @returns {number} Number of arguments consumed (0 if not recognized)
+ */
+function parseQueryOption(args, index, options) {
+  const arg = args[index];
+
+  const flag = FLAG_OPTIONS[arg];
+  if (flag) {
+    flag(options);
+    return 1;
+  }
+
+  const identifierKey = IDENTIFIER_OPTIONS[arg];
+  if (identifierKey) {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options[identifierKey] = args[index + 1];
+      return 2;
+    }
+    throw new Error(`Option ${arg} requires a UUID or session name argument`);
+  }
+
+  for (const [name, key] of Object.entries(IDENTIFIER_OPTIONS)) {
+    const prefix = `${name}=`;
+    if (arg.startsWith(prefix)) {
+      const value = arg.slice(prefix.length);
+      if (!value) {
+        throw new Error(
+          `Option ${name} requires a UUID or session name argument`
+        );
+      }
+      options[key] = value;
+      return 1;
+    }
+  }
+
+  // --output-format <format>
+  if (arg === '--output-format') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.outputFormat = args[index + 1].toLowerCase();
+      return 2;
+    }
+    throw new Error(`Option ${arg} requires a format argument`);
+  }
+
+  // --output-format=<value>
+  if (arg.startsWith('--output-format=')) {
+    options.outputFormat = arg.split('=')[1].toLowerCase();
+    return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Modes that address one stored execution and therefore cannot be combined.
+ * @param {object} options - Parsed wrapper options
+ * @returns {string[]} Names of the modes that are active
+ */
+function activeQueryModes(options) {
+  const modes = [];
+  if (hasValue(options.status)) {
+    modes.push('--status');
+  }
+  if (options.list) {
+    modes.push('--list');
+  }
+  if (hasValue(options.uploadLog)) {
+    modes.push('--upload-log');
+  }
+  if (hasValue(options.stop)) {
+    modes.push('--stop');
+  }
+  if (hasValue(options.terminate)) {
+    modes.push('--terminate');
+  }
+  if (hasValue(options.attach)) {
+    modes.push('--attach');
+  }
+  if (hasValue(options.resume)) {
+    modes.push('--resume');
+  }
+  if (options.resumeAll) {
+    modes.push('--resume-all');
+  }
+  if (options.cleanup) {
+    modes.push('--cleanup');
+  }
+  return modes;
+}
+
+/**
+ * Formats are only meaningful for modes that print a machine-readable report.
+ */
+const OUTPUT_FORMAT_MODES = ['--status', '--list', '--resume', '--resume-all'];
+
+/**
+ * Validate query/control options.
+ * @param {object} options - Parsed wrapper options
+ * @throws {Error} When the combination is not supported
+ */
+function validateQueryOptions(options) {
+  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(', ')}`
+      );
+    }
+  }
+
+  const modes = activeQueryModes(options);
+
+  if (modes.length > 1) {
+    throw new Error(
+      'Cannot combine --status, --list, --upload-log, --stop, --terminate, --attach, --resume, --resume-all, or --cleanup in the same invocation'
+    );
+  }
+
+  if (
+    hasValue(options.outputFormat) &&
+    !modes.some((mode) => OUTPUT_FORMAT_MODES.includes(mode))
+  ) {
+    throw new Error(
+      '--output-format option is only valid with --status, --list, --resume, or --resume-all'
+    );
+  }
+
+  if (options.running && !options.list) {
+    throw new Error('--running option is only valid with --list');
+  }
+
+  if (options.readOnly && !hasValue(options.attach)) {
+    throw new Error('--read-only option is only valid with --attach');
+  }
+}
+
+module.exports = {
+  VALID_OUTPUT_FORMATS,
+  activeQueryModes,
+  createQueryOptionDefaults,
+  parseQueryOption,
+  validateQueryOptions,
+};