start-command 0.32.1 → 0.34.0

package/src/lib/args-parser.js

@@ -28,11 +28,15 @@
  * --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
- * --list                           List all tracked command executions
+ * --list [--running]               List all (or only running) tracked command executions
  * --upload-log <uuid-or-session>    Upload the stored log for a tracked execution
  * --output-format <format>         Output format for status/list (links-notation, json, text)
  * --stop <uuid-or-session-name>     Ask a detached execution to stop gracefully
  * --terminate <uuid-or-session-name> Terminate a detached execution immediately
+ * --attach <uuid-or-session-name>   Attach to a running detached session terminal
+ * --read-only                      Follow --attach output without forwarding stdin
+ * --resume <uuid-or-session> [-- cmd] Resume a stored execution (optionally with a new command)
+ * --resume-all                     Re-attach or reconcile every execution still marked running
  * --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)
  */
@@ -40,6 +44,13 @@
 const { getDefaultDockerImage } = require('./docker-utils');
 const dockerNetworkOptions = require('./docker-network-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
+const { buildCommandString } = require('./shell-utils');
+const {
+  VALID_OUTPUT_FORMATS,
+  createQueryOptionDefaults,
+  parseQueryOption,
+  validateQueryOptions,
+} = require('./args-parser-queries');
 
 // Debug mode from environment
 const DEBUG =
@@ -60,15 +71,6 @@ const VALID_SHELLS = ['auto', 'bash', 'zsh', 'sh'];
  */
 const MAX_ISOLATION_DEPTH = 7;
 
-/**
- * Valid output formats for --status
- */
-const VALID_OUTPUT_FORMATS = ['links-notation', 'json', 'text'];
-
-function hasValue(value) {
-  return value !== null && value !== undefined;
-}
-
 /**
  * UUID v4 regex pattern for validation
  */
@@ -89,18 +91,25 @@ function isValidUUID(str) {
  * @returns {string} A new UUID v4 string
  */
 function generateUUID() {
-  // Try to use Node.js/Bun crypto module
-  try {
-    const crypto = require('crypto');
+  const crypto = require('crypto');
+  if (typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID();
-  } catch {
-    // Fallback for environments without crypto.randomUUID
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-      const r = (Math.random() * 16) | 0;
-      const v = c === 'x' ? r : (r & 0x3) | 0x8;
-      return v.toString(16);
-    });
   }
+
+  // Fallback for runtimes without crypto.randomUUID (Node < 14.17). Still a
+  // CSPRNG: session ids name isolation sessions and users, so a predictable
+  // generator is a security bug, not a cosmetic one (CodeQL js/insecure-randomness).
+  const bytes = crypto.randomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 1
+  const hex = bytes.toString('hex');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join('-');
 }
 
 /**
@@ -164,6 +173,8 @@ function parseEndpointValue(value, options) {
  * Parse command line arguments into wrapper options and command
  * @param {string[]} args - Array of command line arguments
  * @returns {{wrapperOptions: object, command: string, rawCommand: string[]}}
+ *   `command` re-quotes each argv element so the inner shell sees the argument
+ *   boundaries the user typed (issue #164); `rawCommand` keeps the raw argv.
  */
 function parseArgs(args) {
   const wrapperOptions = {
@@ -195,14 +206,7 @@ function parseArgs(args) {
     keepContainerOnFail: false, // Keep docker container filesystem when command fails or OOM-kills
     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
-    list: false, // List all tracked execution records
-    uploadLog: null, // UUID/session name whose stored log should be uploaded
-    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
+    ...createQueryOptionDefaults(),
   };
 
   let commandArgs = [];
@@ -241,7 +245,7 @@ function parseArgs(args) {
 
   return {
     wrapperOptions,
-    command: commandArgs.join(' '),
+    command: buildCommandString(commandArgs),
     rawCommand: commandArgs,
   };
 }
@@ -529,125 +533,10 @@ function parseOption(args, index, options) {
     return 1;
   }
 
-  // --status <uuid-or-session-name>
-  if (arg === '--status') {
-    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.status = args[index + 1];
-      return 2;
-    } else {
-      throw new Error(`Option ${arg} requires a UUID or session name argument`);
-    }
-  }
-
-  // --status=<value>
-  if (arg.startsWith('--status=')) {
-    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;
-  }
-
-  // --upload-log <uuid-or-session-name>
-  if (arg === '--upload-log') {
-    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.uploadLog = args[index + 1];
-      return 2;
-    } else {
-      throw new Error(`Option ${arg} requires a UUID or session name argument`);
-    }
-  }
-
-  // --upload-log=<value>
-  if (arg.startsWith('--upload-log=')) {
-    const value = arg.slice('--upload-log='.length);
-    if (!value) {
-      throw new Error(
-        `Option --upload-log requires a UUID or session name argument`
-      );
-    }
-    options.uploadLog = 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;
-  }
-
-  // --output-format <format>
-  if (arg === '--output-format') {
-    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
-      options.outputFormat = args[index + 1].toLowerCase();
-      return 2;
-    } else {
-      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;
-  }
-
-  // --cleanup
-  if (arg === '--cleanup') {
-    options.cleanup = true;
-    return 1;
-  }
-
-  // --cleanup-dry-run
-  if (arg === '--cleanup-dry-run') {
-    options.cleanup = true;
-    options.cleanupDryRun = true;
-    return 1;
+  // Query/control options (--status, --list, --attach, --resume, ...)
+  const queryConsumed = parseQueryOption(args, index, options);
+  if (queryConsumed > 0) {
+    return queryConsumed;
   }
 
   // Not a recognized wrapper option
@@ -889,37 +778,7 @@ function validateOptions(options) {
     throw new Error('--keep-user option is only valid with --isolated-user');
   }
 
-  // Validate output format
-  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(', ')}`
-      );
-    }
-  }
-
-  // Query/control modes are mutually exclusive
-  const queryModes = [
-    hasValue(options.status),
-    options.list,
-    hasValue(options.uploadLog),
-    hasValue(options.stop),
-    hasValue(options.terminate),
-    options.cleanup,
-  ].filter(Boolean).length;
-
-  if (queryModes > 1) {
-    throw new Error(
-      'Cannot combine --status, --list, --upload-log, --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'
-    );
-  }
+  validateQueryOptions(options);
 
   // Validate shell option
   if (options.shell !== null && options.shell !== undefined) {

package/src/lib/detached-finalize.js

@@ -0,0 +1,281 @@
+/**
+ * Detached completion finalizer (issue #170)
+ *
+ * A detached Docker session outlives the CLI process that started it: the
+ * foreground `start` invocation returns as soon as the container is up, so
+ * nobody is left to write the terminal state back into the execution store.
+ * The record therefore stayed `executing` forever, with `exitCode: null` and
+ * `endTime: null`, and every `--status` query had to re-derive the outcome from
+ * scratch — fabricating `endTime` with `new Date()` in the process.
+ *
+ * The detached completion watcher (see `docker-cleanup.js`) now re-invokes this
+ * module once the container is gone, handing over the facts it already read out
+ * of a single `docker inspect`. This module is deliberately tiny and
+ * dependency-light: it is executed as a short-lived child process on a host
+ * whose CLI invocation is long gone, so it must never throw and never block.
+ */
+
+const path = require('path');
+
+const {
+  SHELL_VARS,
+  describeExitCode,
+  normalizeDockerTimestamp,
+} = require('./docker-post-mortem');
+const { shellQuote } = require('./isolation-log-utils');
+
+/** Provenance markers for `endTime` (issue #170.2). */
+const END_TIME_SOURCE = {
+  /** `docker inspect .State.FinishedAt` — the container's own clock. */
+  DOCKER_FINISHED_AT: 'docker-finished-at',
+  /** The anchored `Finished:` line `start` itself wrote into the log. */
+  LOG_FOOTER: 'log-footer',
+  /** No real finish time exists: this is when the end was *observed*. */
+  OBSERVED_AT: 'observed-at',
+};
+
+/**
+ * Persist the terminal state of a detached execution.
+ *
+ * Purely additive with respect to the observation-vs-verdict discipline of
+ * issues #148/#151/#162: `oomKilled` and `exitReason` are recorded as facts
+ * next to the exit code, never as a substitute for it.
+ *
+ * @param {Object} options - Finalization input
+ * @param {Object} options.store - An `ExecutionStore`
+ * @param {string} options.executionId - UUID (or session name) of the record
+ * @param {number|string|null} [options.exitCode] - `.State.ExitCode`
+ * @param {boolean|string|null} [options.oomKilled] - `.State.OOMKilled`
+ * @param {string|null} [options.startedAt] - `.State.StartedAt`
+ * @param {string|null} [options.finishedAt] - `.State.FinishedAt`
+ * @param {string|null} [options.containerError] - `.State.Error`
+ * @returns {{updated: boolean, reason?: string, record?: Object}} Outcome
+ */
+function finalizeDetachedExecution(options = {}) {
+  const { store, executionId } = options;
+  if (!store || !executionId) {
+    return { updated: false, reason: 'missing-arguments' };
+  }
+
+  let record;
+  try {
+    record = store.get(executionId);
+  } catch {
+    return { updated: false, reason: 'store-unreadable' };
+  }
+  if (!record) {
+    return { updated: false, reason: 'record-not-found' };
+  }
+  if (record.status === 'executed' && record.endTime) {
+    // Already finalized (e.g. a `--status` query got there first, or the
+    // watcher ran twice after a resume). Nothing to correct.
+    return { updated: false, reason: 'already-final', record };
+  }
+
+  const described = describeExitCode(options.exitCode);
+  record.status = 'executed';
+  if (described.code !== null) {
+    record.exitCode = described.code;
+  } else if (record.exitCode === null || record.exitCode === undefined) {
+    record.exitCode = -1;
+  }
+
+  const finishedAt = normalizeDockerTimestamp(options.finishedAt);
+  if (finishedAt) {
+    record.endTime = new Date(finishedAt).toISOString();
+    record.endTimeSource = END_TIME_SOURCE.DOCKER_FINISHED_AT;
+  } else {
+    // Docker has no finish time for this container (it never started, or it
+    // was removed before we could look). Record *when we noticed*, and say so,
+    // rather than passing observation time off as a finish time (issue #170.2).
+    record.endTime = new Date().toISOString();
+    record.endTimeSource = END_TIME_SOURCE.OBSERVED_AT;
+    record.observedAt = record.endTime;
+  }
+
+  const startedAt = normalizeDockerTimestamp(options.startedAt);
+  if (startedAt) {
+    record.containerStartedAt = startedAt;
+  }
+
+  const oomKilled = normalizeBoolean(options.oomKilled);
+  if (oomKilled !== null) {
+    record.oomKilled = oomKilled;
+  }
+
+  const exitReason = resolveReason(record);
+  if (exitReason) {
+    record.exitReason = exitReason;
+  }
+
+  const containerError = normalizeContainerError(options.containerError);
+  if (containerError) {
+    record.options = { ...(record.options || {}), containerError };
+  }
+
+  try {
+    store.save(record);
+  } catch (err) {
+    return { updated: false, reason: `save-failed: ${err.message}`, record };
+  }
+  return { updated: true, record };
+}
+
+/**
+ * Derive the `exitReason` hint from the same evidence `--status` would use.
+ * Kept in a helper so a failure to read the log never aborts finalization.
+ * @param {Object} record - Execution record being finalized
+ * @returns {string|null} Reason hint, or null
+ */
+function resolveReason(record) {
+  try {
+    const { resolveExitReason } = require('./exit-reason');
+    const {
+      FATAL_MARKER_TAIL_BYTES,
+      readLogTail,
+    } = require('./isolation-log-utils');
+    const logTail = record.logPath
+      ? readLogTail(record.logPath, FATAL_MARKER_TAIL_BYTES)
+      : null;
+    return resolveExitReason({
+      exitCode: record.exitCode,
+      logTail,
+      oomKilled: record.oomKilled,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {boolean|string|null|undefined} value - Raw shell-provided flag
+ * @returns {boolean|null} Parsed flag, or null when it carries no information
+ */
+function normalizeBoolean(value) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (value === 'true') {
+    return true;
+  }
+  if (value === 'false') {
+    return false;
+  }
+  return null;
+}
+
+/**
+ * @param {string|null|undefined} value - Raw `.State.Error`
+ * @returns {string|null} Error text, or null when docker reported none
+ */
+function normalizeContainerError(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (trimmed === '' || trimmed === '<no value>' || trimmed === '(none)') {
+    return null;
+  }
+  return trimmed;
+}
+
+/**
+ * Reconcile an in-memory record with one the detached watcher already
+ * finalized.
+ *
+ * A container that exits almost immediately can be finalized by the watcher
+ * before the foreground `start` invocation writes its own last update. Saving
+ * the stale in-memory copy would resurrect `status: executing` and throw the
+ * terminal facts away, so the stored record wins and only the fields the
+ * foreground process learned (its `options`, e.g. `containerId`) are merged in.
+ *
+ * @param {Object} store - An `ExecutionStore`
+ * @param {Object} record - The in-memory record about to be saved
+ * @returns {Object} The record to save
+ */
+function reconcileFinalizedRecord(store, record) {
+  try {
+    const stored = store.get(record.uuid);
+    if (!stored || stored.status !== 'executed' || !stored.endTime) {
+      return record;
+    }
+    stored.options = { ...(stored.options || {}), ...(record.options || {}) };
+    return stored;
+  } catch {
+    return record;
+  }
+}
+
+/**
+ * Shell fragment that hands the inspected docker facts to this module.
+ *
+ * Runs with the same runtime that started the session, inherits
+ * `START_APP_FOLDER`/`START_DISABLE_TRACKING` from the detached watcher, and is
+ * suffixed with `|| true` so a finalization failure can never abort the
+ * watcher's remaining cleanup work.
+ *
+ * @param {string} executionId - UUID of the record to finalize
+ * @returns {string} POSIX shell fragment
+ */
+function buildDetachedFinalizeSnippet(executionId) {
+  const v = SHELL_VARS;
+  return (
+    `${shellQuote(process.execPath)} ${shellQuote(__filename)} ` +
+    `${shellQuote(executionId)} "$${v.exit}" "$${v.oom}" ` +
+    `"$${v.started}" "$${v.finished}" "$${v.error}" ` +
+    `>/dev/null 2>&1 || true`
+  );
+}
+
+/**
+ * Entry point used by the detached watcher:
+ *   <runtime> detached-finalize.js <uuid> <exit> <oom> <started> <finished> <error>
+ * Always exits 0 — a bookkeeping failure must never turn into a visible error
+ * in a log the user is reading for the command's own output.
+ * @param {string[]} argv - Positional arguments
+ * @returns {void}
+ */
+function main(argv) {
+  const [
+    executionId,
+    exitCode,
+    oomKilled,
+    startedAt,
+    finishedAt,
+    containerError,
+  ] = argv;
+  if (!executionId || process.env.START_DISABLE_TRACKING === 'true') {
+    return;
+  }
+  try {
+    const { ExecutionStore } = require('./execution-store');
+    const store = new ExecutionStore(
+      process.env.START_APP_FOLDER
+        ? { appFolder: path.resolve(process.env.START_APP_FOLDER) }
+        : {}
+    );
+    finalizeDetachedExecution({
+      store,
+      executionId,
+      exitCode,
+      oomKilled,
+      startedAt,
+      finishedAt,
+      containerError,
+    });
+  } catch {
+    // Deliberately silent: see the exit-0 contract above.
+  }
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = {
+  END_TIME_SOURCE,
+  buildDetachedFinalizeSnippet,
+  finalizeDetachedExecution,
+  main,
+  reconcileFinalizedRecord,
+};