command-stream 0.8.3 → 0.9.1

package/js/src/$.process-runner-stream-kill.mjs

@@ -0,0 +1,312 @@
+// ProcessRunner stream and kill methods - streaming and process termination
+// Part of the modular ProcessRunner architecture
+
+import { trace } from './$.trace.mjs';
+import { createResult } from './$.result.mjs';
+
+const isBun = typeof globalThis.Bun !== 'undefined';
+
+/**
+ * Send a signal to a process and its group
+ * @param {number} pid - Process ID
+ * @param {string} sig - Signal name (e.g., 'SIGTERM', 'SIGKILL')
+ * @param {string} runtime - Runtime identifier for logging
+ * @returns {string[]} List of successful operations
+ */
+function sendSignalToProcess(pid, sig, runtime) {
+  const operations = [];
+  const prefix = runtime === 'Bun' ? 'Bun ' : '';
+
+  try {
+    process.kill(pid, sig);
+    trace('ProcessRunner', () => `Sent ${sig} to ${prefix}process ${pid}`);
+    operations.push(`${sig} to process`);
+  } catch (err) {
+    trace(
+      'ProcessRunner',
+      () => `Error sending ${sig} to ${prefix}process: ${err.message}`
+    );
+  }
+
+  try {
+    process.kill(-pid, sig);
+    trace(
+      'ProcessRunner',
+      () => `Sent ${sig} to ${prefix}process group -${pid}`
+    );
+    operations.push(`${sig} to group`);
+  } catch (err) {
+    trace(
+      'ProcessRunner',
+      () => `${prefix}process group ${sig} failed: ${err.message}`
+    );
+  }
+
+  return operations;
+}
+
+/**
+ * Kill a child process with escalating signals
+ * @param {object} child - Child process object
+ */
+function killChildProcess(child) {
+  if (!child || !child.pid) {
+    return;
+  }
+
+  const runtime = isBun ? 'Bun' : 'Node';
+  trace(
+    'ProcessRunner',
+    () =>
+      `Killing ${runtime} process | ${JSON.stringify({ pid: child.pid }, null, 2)}`
+  );
+
+  const killOperations = [];
+  killOperations.push(...sendSignalToProcess(child.pid, 'SIGTERM', runtime));
+  killOperations.push(...sendSignalToProcess(child.pid, 'SIGKILL', runtime));
+
+  trace(
+    'ProcessRunner',
+    () => `${runtime} kill operations attempted: ${killOperations.join(', ')}`
+  );
+
+  if (isBun) {
+    try {
+      child.kill();
+      trace(
+        'ProcessRunner',
+        () => `Called child.kill() for Bun process ${child.pid}`
+      );
+    } catch (err) {
+      trace(
+        'ProcessRunner',
+        () => `Error calling child.kill(): ${err.message}`
+      );
+    }
+  }
+
+  child.removeAllListeners?.();
+}
+
+/**
+ * Kill pipeline components (source and destination)
+ * @param {object} spec - Process runner spec
+ * @param {string} signal - Kill signal
+ */
+function killPipelineComponents(spec, signal) {
+  if (spec?.mode !== 'pipeline') {
+    return;
+  }
+  trace('ProcessRunner', () => 'Killing pipeline components');
+  if (spec.source && typeof spec.source.kill === 'function') {
+    spec.source.kill(signal);
+  }
+  if (spec.destination && typeof spec.destination.kill === 'function') {
+    spec.destination.kill(signal);
+  }
+}
+
+/**
+ * Handle abort controller during kill
+ * @param {AbortController} controller - The abort controller
+ */
+function abortController(controller) {
+  if (!controller) {
+    trace('ProcessRunner', () => 'No abort controller to abort');
+    return;
+  }
+  trace(
+    'ProcessRunner',
+    () =>
+      `Aborting internal controller | ${JSON.stringify({ wasAborted: controller?.signal?.aborted }, null, 2)}`
+  );
+  controller.abort();
+  trace(
+    'ProcessRunner',
+    () =>
+      `Internal controller aborted | ${JSON.stringify({ nowAborted: controller?.signal?.aborted }, null, 2)}`
+  );
+}
+
+/**
+ * Handle virtual generator cleanup during kill
+ * @param {object} generator - The virtual generator
+ * @param {string} signal - Kill signal
+ */
+function cleanupVirtualGenerator(generator, signal) {
+  if (!generator) {
+    trace(
+      'ProcessRunner',
+      () =>
+        `No virtual generator to cleanup | ${JSON.stringify({ hasVirtualGenerator: false }, null, 2)}`
+    );
+    return;
+  }
+
+  trace(
+    'ProcessRunner',
+    () =>
+      `Virtual generator found for cleanup | ${JSON.stringify(
+        {
+          hasReturn: typeof generator.return === 'function',
+          hasThrow: typeof generator.throw === 'function',
+          signal,
+        },
+        null,
+        2
+      )}`
+  );
+
+  if (generator.return) {
+    trace('ProcessRunner', () => 'Closing virtual generator with return()');
+    try {
+      generator.return();
+      trace('ProcessRunner', () => 'Virtual generator closed successfully');
+    } catch (err) {
+      trace(
+        'ProcessRunner',
+        () =>
+          `Error closing generator | ${JSON.stringify({ error: err.message, stack: err.stack?.slice(0, 200) }, null, 2)}`
+      );
+    }
+  } else {
+    trace('ProcessRunner', () => 'Virtual generator has no return() method');
+  }
+}
+
+/**
+ * Get exit code for signal
+ * @param {string} signal - Signal name
+ * @returns {number} Exit code
+ */
+function getSignalExitCode(signal) {
+  if (signal === 'SIGKILL') {
+    return 137;
+  }
+  if (signal === 'SIGTERM') {
+    return 143;
+  }
+  return 130;
+}
+
+/**
+ * Kill the runner and create result
+ * @param {object} runner - ProcessRunner instance
+ * @param {string} signal - Kill signal
+ */
+function killRunner(runner, signal) {
+  runner._cancelled = true;
+  runner._cancellationSignal = signal;
+  killPipelineComponents(runner.spec, signal);
+
+  if (runner._cancelResolve) {
+    trace('ProcessRunner', () => 'Resolving cancel promise');
+    runner._cancelResolve();
+  }
+
+  abortController(runner._abortController);
+  cleanupVirtualGenerator(runner._virtualGenerator, signal);
+
+  if (runner.child && !runner.finished) {
+    trace('ProcessRunner', () => `Killing child process ${runner.child.pid}`);
+    try {
+      killChildProcess(runner.child);
+      runner.child = null;
+    } catch (err) {
+      trace('ProcessRunner', () => `Error killing process: ${err.message}`);
+      console.error('Error killing process:', err.message);
+    }
+  }
+
+  const result = createResult({
+    code: getSignalExitCode(signal),
+    stdout: '',
+    stderr: `Process killed with ${signal}`,
+    stdin: '',
+  });
+  runner.finish(result);
+}
+
+/**
+ * Attach stream and kill methods to ProcessRunner prototype
+ * @param {Function} ProcessRunner - The ProcessRunner class
+ * @param {Object} deps - Dependencies (not used but kept for consistency)
+ */
+export function attachStreamKillMethods(ProcessRunner) {
+  ProcessRunner.prototype[Symbol.asyncIterator] = async function* () {
+    yield* this.stream();
+  };
+
+  ProcessRunner.prototype.stream = async function* () {
+    trace('ProcessRunner', () => `stream ENTER | started=${this.started}`);
+    this._isStreaming = true;
+    if (!this.started) {
+      this._startAsync();
+    }
+
+    let buffer = [];
+    let resolve, _reject;
+    let ended = false;
+    let killed = false;
+
+    const onData = (chunk) => {
+      if (!killed) {
+        buffer.push(chunk);
+        if (resolve) {
+          resolve();
+          resolve = _reject = null;
+        }
+      }
+    };
+
+    const onEnd = () => {
+      ended = true;
+      if (resolve) {
+        resolve();
+        resolve = _reject = null;
+      }
+    };
+
+    this.on('data', onData);
+    this.on('end', onEnd);
+
+    try {
+      while (!ended || buffer.length > 0) {
+        if (killed) {
+          break;
+        }
+        if (buffer.length > 0) {
+          const chunk = buffer.shift();
+          this._streamYielding = true;
+          yield chunk;
+          this._streamYielding = false;
+        } else if (!ended) {
+          await new Promise((res, rej) => {
+            resolve = res;
+            _reject = rej;
+          });
+        }
+      }
+    } finally {
+      this.off('data', onData);
+      this.off('end', onEnd);
+      if (!this.finished) {
+        killed = true;
+        buffer = [];
+        this._streamBreaking = true;
+        this.kill();
+      }
+    }
+  };
+
+  ProcessRunner.prototype.kill = function (signal = 'SIGTERM') {
+    trace(
+      'ProcessRunner',
+      () => `kill | signal=${signal} finished=${this.finished}`
+    );
+    if (this.finished) {
+      return;
+    }
+    killRunner(this, signal);
+  };
+}

package/js/src/$.process-runner-virtual.mjs

@@ -0,0 +1,297 @@
+// ProcessRunner virtual command methods - virtual command execution
+// Part of the modular ProcessRunner architecture
+
+import { trace } from './$.trace.mjs';
+import { safeWrite } from './$.stream-utils.mjs';
+
+/**
+ * Get stdin data from options
+ * @param {object} options - Runner options
+ * @returns {string} Stdin data
+ */
+function getStdinData(options) {
+  if (options.stdin && typeof options.stdin === 'string') {
+    return options.stdin;
+  }
+  if (options.stdin && Buffer.isBuffer(options.stdin)) {
+    return options.stdin.toString('utf8');
+  }
+  return '';
+}
+
+/**
+ * Get exit code for cancellation signal
+ * @param {string} signal - Cancellation signal
+ * @returns {number} Exit code
+ */
+function getCancellationExitCode(signal) {
+  if (signal === 'SIGINT') {
+    return 130;
+  }
+  if (signal === 'SIGTERM') {
+    return 143;
+  }
+  return 1;
+}
+
+/**
+ * Create abort promise for non-generator handlers
+ * @param {AbortController} abortController - Abort controller
+ * @returns {Promise} Promise that rejects on abort
+ */
+function createAbortPromise(abortController) {
+  return new Promise((_, reject) => {
+    if (abortController && abortController.signal.aborted) {
+      reject(new Error('Command cancelled'));
+    }
+    if (abortController) {
+      abortController.signal.addEventListener('abort', () => {
+        reject(new Error('Command cancelled'));
+      });
+    }
+  });
+}
+
+/**
+ * Emit output and mirror if needed
+ * @param {object} runner - ProcessRunner instance
+ * @param {string} type - Output type (stdout/stderr)
+ * @param {string} data - Output data
+ */
+function emitOutput(runner, type, data) {
+  if (!data) {
+    return;
+  }
+  const buf = Buffer.from(data);
+  const stream = type === 'stdout' ? process.stdout : process.stderr;
+  if (runner.options.mirror) {
+    safeWrite(stream, buf);
+  }
+  runner._emitProcessedData(type, buf);
+}
+
+/**
+ * Handle error in virtual command
+ * @param {object} runner - ProcessRunner instance
+ * @param {Error} error - Error that occurred
+ * @param {object} shellSettings - Global shell settings
+ * @returns {object} Result object
+ */
+function handleVirtualError(runner, error, shellSettings) {
+  let exitCode = error.code ?? 1;
+  if (runner._cancelled && runner._cancellationSignal) {
+    exitCode = getCancellationExitCode(runner._cancellationSignal);
+  }
+
+  const result = {
+    code: exitCode,
+    stdout: error.stdout ?? '',
+    stderr: error.stderr ?? error.message,
+    stdin: '',
+  };
+
+  emitOutput(runner, 'stderr', result.stderr);
+  runner.finish(result);
+
+  if (shellSettings.errexit) {
+    error.result = result;
+    throw error;
+  }
+
+  return result;
+}
+
+/**
+ * Run async generator handler
+ * @param {object} runner - ProcessRunner instance
+ * @param {Function} handler - Generator handler
+ * @param {Array} argValues - Argument values
+ * @param {string} stdinData - Stdin data
+ * @returns {Promise<object>} Result object
+ */
+async function runGeneratorHandler(runner, handler, argValues, stdinData) {
+  const chunks = [];
+  const commandOptions = {
+    cwd: runner.options.cwd,
+    env: runner.options.env,
+    options: runner.options,
+    isCancelled: () => runner._cancelled,
+  };
+
+  const generator = handler({
+    args: argValues,
+    stdin: stdinData,
+    abortSignal: runner._abortController?.signal,
+    ...commandOptions,
+  });
+  runner._virtualGenerator = generator;
+
+  const cancelPromise = new Promise((resolve) => {
+    runner._cancelResolve = resolve;
+  });
+
+  try {
+    const iterator = generator[Symbol.asyncIterator]();
+    let done = false;
+
+    while (!done && !runner._cancelled) {
+      const result = await Promise.race([
+        iterator.next(),
+        cancelPromise.then(() => ({ done: true, cancelled: true })),
+      ]);
+
+      if (result.cancelled || runner._cancelled) {
+        if (iterator.return) {
+          await iterator.return();
+        }
+        break;
+      }
+
+      done = result.done;
+
+      if (!done && !runner._cancelled && !runner._streamBreaking) {
+        const buf = Buffer.from(result.value);
+        chunks.push(buf);
+
+        if (runner.options.mirror) {
+          safeWrite(process.stdout, buf);
+        }
+        runner._emitProcessedData('stdout', buf);
+      }
+    }
+  } finally {
+    runner._virtualGenerator = null;
+    runner._cancelResolve = null;
+  }
+
+  return {
+    code: 0,
+    stdout: runner.options.capture
+      ? Buffer.concat(chunks).toString('utf8')
+      : undefined,
+    stderr: runner.options.capture ? '' : undefined,
+    stdin: runner.options.capture ? stdinData : undefined,
+  };
+}
+
+/**
+ * Run regular (non-generator) handler
+ * @param {object} runner - ProcessRunner instance
+ * @param {Function} handler - Handler function
+ * @param {Array} argValues - Argument values
+ * @param {string} stdinData - Stdin data
+ * @returns {Promise<object>} Result object
+ */
+async function runRegularHandler(runner, handler, argValues, stdinData) {
+  const commandOptions = {
+    cwd: runner.options.cwd,
+    env: runner.options.env,
+    options: runner.options,
+    isCancelled: () => runner._cancelled,
+  };
+
+  const handlerPromise = handler({
+    args: argValues,
+    stdin: stdinData,
+    abortSignal: runner._abortController?.signal,
+    ...commandOptions,
+  });
+
+  const abortPromise = createAbortPromise(runner._abortController);
+  let result;
+
+  try {
+    result = await Promise.race([handlerPromise, abortPromise]);
+  } catch (err) {
+    if (err.message === 'Command cancelled') {
+      const exitCode = getCancellationExitCode(runner._cancellationSignal);
+      result = { code: exitCode, stdout: '', stderr: '' };
+    } else {
+      throw err;
+    }
+  }
+
+  result = {
+    ...result,
+    code: result.code ?? 0,
+    stdout: runner.options.capture ? (result.stdout ?? '') : undefined,
+    stderr: runner.options.capture ? (result.stderr ?? '') : undefined,
+    stdin: runner.options.capture ? stdinData : undefined,
+  };
+
+  emitOutput(runner, 'stdout', result.stdout);
+  emitOutput(runner, 'stderr', result.stderr);
+
+  return result;
+}
+
+/**
+ * Attach virtual command methods to ProcessRunner prototype
+ * @param {Function} ProcessRunner - The ProcessRunner class
+ * @param {Object} deps - Dependencies
+ */
+export function attachVirtualCommandMethods(ProcessRunner, deps) {
+  const { virtualCommands, globalShellSettings } = deps;
+
+  ProcessRunner.prototype._runVirtual = async function (
+    cmd,
+    args,
+    originalCommand = null
+  ) {
+    trace('ProcessRunner', () => `_runVirtual | cmd=${cmd}`);
+
+    const handler = virtualCommands.get(cmd);
+    if (!handler) {
+      throw new Error(`Virtual command not found: ${cmd}`);
+    }
+
+    try {
+      // Special handling for streaming mode (stdin: "pipe")
+      if (this.options.stdin === 'pipe') {
+        const modifiedOptions = {
+          ...this.options,
+          stdin: 'pipe',
+          _bypassVirtual: true,
+        };
+        const ProcessRunnerRef = this.constructor;
+        const realRunner = new ProcessRunnerRef(
+          { mode: 'shell', command: originalCommand || cmd },
+          modifiedOptions
+        );
+        return await realRunner._doStartAsync();
+      }
+
+      const stdinData = getStdinData(this.options);
+      const argValues = args.map((arg) =>
+        arg.value !== undefined ? arg.value : arg
+      );
+
+      if (globalShellSettings.xtrace) {
+        console.log(`+ ${originalCommand || `${cmd} ${argValues.join(' ')}`}`);
+      }
+      if (globalShellSettings.verbose) {
+        console.log(`${originalCommand || `${cmd} ${argValues.join(' ')}`}`);
+      }
+
+      const isGenerator = handler.constructor.name === 'AsyncGeneratorFunction';
+      const result = isGenerator
+        ? await runGeneratorHandler(this, handler, argValues, stdinData)
+        : await runRegularHandler(this, handler, argValues, stdinData);
+
+      this.finish(result);
+
+      if (globalShellSettings.errexit && result.code !== 0) {
+        const error = new Error(`Command failed with exit code ${result.code}`);
+        error.code = result.code;
+        error.stdout = result.stdout;
+        error.stderr = result.stderr;
+        error.result = result;
+        throw error;
+      }
+
+      return result;
+    } catch (error) {
+      return handleVirtualError(this, error, globalShellSettings);
+    }
+  };
+}