command-stream 0.9.0 → 0.9.2

package/js/src/$.stream-utils.mjs

@@ -0,0 +1,390 @@
+// Stream utility functions for safe operations and error handling
+// Provides cross-runtime compatible stream operations
+
+import { trace } from './$.trace.mjs';
+
+const isBun = typeof globalThis.Bun !== 'undefined';
+
+// Stream utility functions for safe operations and error handling
+export const StreamUtils = {
+  /**
+   * Check if a stream is safe to write to
+   * @param {object} stream - The stream to check
+   * @returns {boolean} Whether the stream is writable
+   */
+  isStreamWritable(stream) {
+    return stream && stream.writable && !stream.destroyed && !stream.closed;
+  },
+
+  /**
+   * Add standardized error handler to stdin streams
+   * @param {object} stream - The stream to add handler to
+   * @param {string} contextName - Name for trace logging
+   * @param {function} onNonEpipeError - Optional callback for non-EPIPE errors
+   */
+  addStdinErrorHandler(stream, contextName = 'stdin', onNonEpipeError = null) {
+    if (stream && typeof stream.on === 'function') {
+      stream.on('error', (error) => {
+        const handled = this.handleStreamError(
+          error,
+          `${contextName} error event`,
+          false
+        );
+        if (!handled && onNonEpipeError) {
+          onNonEpipeError(error);
+        }
+      });
+    }
+  },
+
+  /**
+   * Safely write to a stream with comprehensive error handling
+   * @param {object} stream - The stream to write to
+   * @param {Buffer|string} data - The data to write
+   * @param {string} contextName - Name for trace logging
+   * @returns {boolean} Whether the write was successful
+   */
+  safeStreamWrite(stream, data, contextName = 'stream') {
+    if (!this.isStreamWritable(stream)) {
+      trace(
+        'ProcessRunner',
+        () =>
+          `${contextName} write skipped - not writable | ${JSON.stringify(
+            {
+              hasStream: !!stream,
+              writable: stream?.writable,
+              destroyed: stream?.destroyed,
+              closed: stream?.closed,
+            },
+            null,
+            2
+          )}`
+      );
+      return false;
+    }
+
+    try {
+      const result = stream.write(data);
+      trace(
+        'ProcessRunner',
+        () =>
+          `${contextName} write successful | ${JSON.stringify(
+            {
+              dataLength: data?.length || 0,
+            },
+            null,
+            2
+          )}`
+      );
+      return result;
+    } catch (error) {
+      if (error.code !== 'EPIPE') {
+        trace(
+          'ProcessRunner',
+          () =>
+            `${contextName} write error | ${JSON.stringify(
+              {
+                error: error.message,
+                code: error.code,
+                isEPIPE: false,
+              },
+              null,
+              2
+            )}`
+        );
+        throw error; // Re-throw non-EPIPE errors
+      } else {
+        trace(
+          'ProcessRunner',
+          () =>
+            `${contextName} EPIPE error (ignored) | ${JSON.stringify(
+              {
+                error: error.message,
+                code: error.code,
+                isEPIPE: true,
+              },
+              null,
+              2
+            )}`
+        );
+      }
+      return false;
+    }
+  },
+
+  /**
+   * Safely end a stream with error handling
+   * @param {object} stream - The stream to end
+   * @param {string} contextName - Name for trace logging
+   * @returns {boolean} Whether the end was successful
+   */
+  safeStreamEnd(stream, contextName = 'stream') {
+    if (!this.isStreamWritable(stream) || typeof stream.end !== 'function') {
+      trace(
+        'ProcessRunner',
+        () =>
+          `${contextName} end skipped - not available | ${JSON.stringify(
+            {
+              hasStream: !!stream,
+              hasEnd: stream && typeof stream.end === 'function',
+              writable: stream?.writable,
+            },
+            null,
+            2
+          )}`
+      );
+      return false;
+    }
+
+    try {
+      stream.end();
+      trace('ProcessRunner', () => `${contextName} ended successfully`);
+      return true;
+    } catch (error) {
+      if (error.code !== 'EPIPE') {
+        trace(
+          'ProcessRunner',
+          () =>
+            `${contextName} end error | ${JSON.stringify(
+              {
+                error: error.message,
+                code: error.code,
+              },
+              null,
+              2
+            )}`
+        );
+      } else {
+        trace(
+          'ProcessRunner',
+          () =>
+            `${contextName} EPIPE on end (ignored) | ${JSON.stringify(
+              {
+                error: error.message,
+                code: error.code,
+              },
+              null,
+              2
+            )}`
+        );
+      }
+      return false;
+    }
+  },
+
+  /**
+   * Setup comprehensive stdin handling (error handler + safe operations)
+   * @param {object} stream - The stream to setup
+   * @param {string} contextName - Name for trace logging
+   * @returns {{ write: function, end: function, isWritable: function }}
+   */
+  setupStdinHandling(stream, contextName = 'stdin') {
+    this.addStdinErrorHandler(stream, contextName);
+
+    return {
+      write: (data) => this.safeStreamWrite(stream, data, contextName),
+      end: () => this.safeStreamEnd(stream, contextName),
+      isWritable: () => this.isStreamWritable(stream),
+    };
+  },
+
+  /**
+   * Handle stream errors with consistent EPIPE behavior
+   * @param {Error} error - The error to handle
+   * @param {string} contextName - Name for trace logging
+   * @param {boolean} shouldThrow - Whether to throw non-EPIPE errors
+   * @returns {boolean} Whether the error was an EPIPE (handled gracefully)
+   */
+  handleStreamError(error, contextName, shouldThrow = true) {
+    if (error.code !== 'EPIPE') {
+      trace(
+        'ProcessRunner',
+        () =>
+          `${contextName} error | ${JSON.stringify(
+            {
+              error: error.message,
+              code: error.code,
+              isEPIPE: false,
+            },
+            null,
+            2
+          )}`
+      );
+      if (shouldThrow) {
+        throw error;
+      }
+      return false;
+    } else {
+      trace(
+        'ProcessRunner',
+        () =>
+          `${contextName} EPIPE error (ignored) | ${JSON.stringify(
+            {
+              error: error.message,
+              code: error.code,
+              isEPIPE: true,
+            },
+            null,
+            2
+          )}`
+      );
+      return true; // EPIPE handled gracefully
+    }
+  },
+
+  /**
+   * Detect if stream supports Bun-style writing
+   * @param {object} stream - The stream to check
+   * @returns {boolean}
+   */
+  isBunStream(stream) {
+    return isBun && stream && typeof stream.getWriter === 'function';
+  },
+
+  /**
+   * Detect if stream supports Node.js-style writing
+   * @param {object} stream - The stream to check
+   * @returns {boolean}
+   */
+  isNodeStream(stream) {
+    return stream && typeof stream.write === 'function';
+  },
+
+  /**
+   * Write to either Bun or Node.js style stream
+   * @param {object} stream - The stream to write to
+   * @param {Buffer|string} data - The data to write
+   * @param {string} contextName - Name for trace logging
+   * @returns {Promise<boolean>} Whether the write was successful
+   */
+  async writeToStream(stream, data, contextName = 'stream') {
+    if (this.isBunStream(stream)) {
+      try {
+        const writer = stream.getWriter();
+        await writer.write(data);
+        writer.releaseLock();
+        return true;
+      } catch (error) {
+        return this.handleStreamError(
+          error,
+          `${contextName} Bun writer`,
+          false
+        );
+      }
+    } else if (this.isNodeStream(stream)) {
+      try {
+        stream.write(data);
+        return true;
+      } catch (error) {
+        return this.handleStreamError(
+          error,
+          `${contextName} Node writer`,
+          false
+        );
+      }
+    }
+    return false;
+  },
+};
+
+/**
+ * Safe write to a stream with parent stream monitoring
+ * @param {object} stream - The stream to write to
+ * @param {Buffer|string} data - The data to write
+ * @param {object} processRunner - Optional ProcessRunner for parent stream handling
+ * @param {function} monitorParentStreams - Function to call for monitoring
+ * @returns {boolean} Whether the write was successful
+ */
+export function safeWrite(
+  stream,
+  data,
+  processRunner = null,
+  monitorParentStreams = null
+) {
+  if (monitorParentStreams) {
+    monitorParentStreams();
+  }
+
+  if (!StreamUtils.isStreamWritable(stream)) {
+    trace(
+      'ProcessRunner',
+      () =>
+        `safeWrite skipped - stream not writable | ${JSON.stringify(
+          {
+            hasStream: !!stream,
+            writable: stream?.writable,
+            destroyed: stream?.destroyed,
+            closed: stream?.closed,
+          },
+          null,
+          2
+        )}`
+    );
+
+    if (
+      processRunner &&
+      processRunner._handleParentStreamClosure &&
+      (stream === process.stdout || stream === process.stderr)
+    ) {
+      processRunner._handleParentStreamClosure();
+    }
+
+    return false;
+  }
+
+  try {
+    return stream.write(data);
+  } catch (error) {
+    trace(
+      'ProcessRunner',
+      () =>
+        `safeWrite error | ${JSON.stringify(
+          {
+            error: error.message,
+            code: error.code,
+            writable: stream.writable,
+            destroyed: stream.destroyed,
+          },
+          null,
+          2
+        )}`
+    );
+
+    if (
+      error.code === 'EPIPE' &&
+      processRunner &&
+      processRunner._handleParentStreamClosure &&
+      (stream === process.stdout || stream === process.stderr)
+    ) {
+      processRunner._handleParentStreamClosure();
+    }
+
+    return false;
+  }
+}
+
+/**
+ * Convert data to Buffer
+ * @param {Buffer|string|object} chunk - Data to convert
+ * @returns {Buffer} The data as a Buffer
+ */
+export function asBuffer(chunk) {
+  if (chunk === null || chunk === undefined) {
+    return Buffer.alloc(0);
+  }
+  if (Buffer.isBuffer(chunk)) {
+    return chunk;
+  }
+  if (typeof chunk === 'string') {
+    return Buffer.from(chunk, 'utf8');
+  }
+  // Handle ArrayBuffer and other views
+  if (chunk instanceof Uint8Array || chunk instanceof ArrayBuffer) {
+    return Buffer.from(chunk);
+  }
+  // Handle objects with toString
+  if (typeof chunk.toString === 'function') {
+    return Buffer.from(chunk.toString(), 'utf8');
+  }
+  return Buffer.from(String(chunk), 'utf8');
+}

package/js/src/$.trace.mjs

@@ -0,0 +1,36 @@
+// Trace function for verbose logging
+// Can be controlled via COMMAND_STREAM_VERBOSE or COMMAND_STREAM_TRACE env vars
+// Can be disabled per-command via trace: false option
+// CI environment no longer auto-enables tracing
+
+/**
+ * Log trace messages for debugging
+ * @param {string} category - The category of the trace message
+ * @param {string|function} messageOrFunc - The message or a function that returns the message
+ * @param {object} runner - Optional runner object to check for trace option
+ */
+export function trace(category, messageOrFunc, runner = null) {
+  // Check if runner explicitly disabled tracing
+  if (runner && runner.options && runner.options.trace === false) {
+    return;
+  }
+
+  // Check global trace setting (evaluated dynamically for runtime changes)
+  const TRACE_ENV = process.env.COMMAND_STREAM_TRACE;
+  const VERBOSE_ENV = process.env.COMMAND_STREAM_VERBOSE === 'true';
+
+  // COMMAND_STREAM_TRACE=false explicitly disables tracing even if COMMAND_STREAM_VERBOSE=true
+  // COMMAND_STREAM_TRACE=true explicitly enables tracing
+  // Otherwise, use COMMAND_STREAM_VERBOSE
+  const VERBOSE =
+    TRACE_ENV === 'false' ? false : TRACE_ENV === 'true' ? true : VERBOSE_ENV;
+
+  if (!VERBOSE) {
+    return;
+  }
+
+  const message =
+    typeof messageOrFunc === 'function' ? messageOrFunc() : messageOrFunc;
+  const timestamp = new Date().toISOString();
+  console.error(`[TRACE ${timestamp}] [${category}] ${message}`);
+}

package/js/src/$.utils.mjs

@@ -1,28 +1,7 @@
 import path from 'path';
 
-// Trace function for verbose logging - consistent with src/$.mjs
-// Can be controlled via COMMAND_STREAM_VERBOSE or COMMAND_STREAM_TRACE env vars
-// CI environment no longer auto-enables tracing
-export function trace(category, messageOrFunc) {
-  // Check global trace setting (evaluated dynamically for runtime changes)
-  const TRACE_ENV = process.env.COMMAND_STREAM_TRACE;
-  const VERBOSE_ENV = process.env.COMMAND_STREAM_VERBOSE === 'true';
-
-  // COMMAND_STREAM_TRACE=false explicitly disables tracing even if COMMAND_STREAM_VERBOSE=true
-  // COMMAND_STREAM_TRACE=true explicitly enables tracing
-  // Otherwise, use COMMAND_STREAM_VERBOSE
-  const VERBOSE =
-    TRACE_ENV === 'false' ? false : TRACE_ENV === 'true' ? true : VERBOSE_ENV;
-
-  if (!VERBOSE) {
-    return;
-  }
-
-  const message =
-    typeof messageOrFunc === 'function' ? messageOrFunc() : messageOrFunc;
-  const timestamp = new Date().toISOString();
-  console.error(`[TRACE ${timestamp}] [${category}] ${message}`);
-}
+// Re-export trace from the dedicated trace module for consistency
+export { trace } from './$.trace.mjs';
 
 export const VirtualUtils = {
   /**

package/js/src/$.virtual-commands.mjs

@@ -0,0 +1,113 @@
+// Virtual commands registration and management
+// Handles registration of built-in and custom virtual commands
+
+import { trace } from './$.trace.mjs';
+import { virtualCommands, getShellSettings } from './$.state.mjs';
+
+// Import virtual command implementations
+import cdCommand from './commands/$.cd.mjs';
+import pwdCommand from './commands/$.pwd.mjs';
+import echoCommand from './commands/$.echo.mjs';
+import sleepCommand from './commands/$.sleep.mjs';
+import trueCommand from './commands/$.true.mjs';
+import falseCommand from './commands/$.false.mjs';
+import createWhichCommand from './commands/$.which.mjs';
+import createExitCommand from './commands/$.exit.mjs';
+import envCommand from './commands/$.env.mjs';
+import catCommand from './commands/$.cat.mjs';
+import lsCommand from './commands/$.ls.mjs';
+import mkdirCommand from './commands/$.mkdir.mjs';
+import rmCommand from './commands/$.rm.mjs';
+import mvCommand from './commands/$.mv.mjs';
+import cpCommand from './commands/$.cp.mjs';
+import touchCommand from './commands/$.touch.mjs';
+import basenameCommand from './commands/$.basename.mjs';
+import dirnameCommand from './commands/$.dirname.mjs';
+import yesCommand from './commands/$.yes.mjs';
+import seqCommand from './commands/$.seq.mjs';
+import testCommand from './commands/$.test.mjs';
+
+/**
+ * Register a virtual command
+ * @param {string} name - Command name
+ * @param {function} handler - Command handler function
+ * @returns {Map} The virtual commands map
+ */
+export function register(name, handler) {
+  trace(
+    'VirtualCommands',
+    () => `register ENTER | ${JSON.stringify({ name }, null, 2)}`
+  );
+  virtualCommands.set(name, handler);
+  trace(
+    'VirtualCommands',
+    () => `register EXIT | ${JSON.stringify({ registered: true }, null, 2)}`
+  );
+  return virtualCommands;
+}
+
+/**
+ * Unregister a virtual command
+ * @param {string} name - Command name to remove
+ * @returns {boolean} Whether the command was removed
+ */
+export function unregister(name) {
+  trace(
+    'VirtualCommands',
+    () => `unregister ENTER | ${JSON.stringify({ name }, null, 2)}`
+  );
+  const deleted = virtualCommands.delete(name);
+  trace(
+    'VirtualCommands',
+    () => `unregister EXIT | ${JSON.stringify({ deleted }, null, 2)}`
+  );
+  return deleted;
+}
+
+/**
+ * List all registered virtual commands
+ * @returns {string[]} Array of command names
+ */
+export function listCommands() {
+  const commands = Array.from(virtualCommands.keys());
+  trace(
+    'VirtualCommands',
+    () => `listCommands() returning ${commands.length} commands`
+  );
+  return commands;
+}
+
+/**
+ * Register all built-in virtual commands
+ */
+export function registerBuiltins() {
+  trace(
+    'VirtualCommands',
+    () => 'registerBuiltins() called - registering all built-in commands'
+  );
+
+  const globalShellSettings = getShellSettings();
+
+  // Register all imported commands
+  register('cd', cdCommand);
+  register('pwd', pwdCommand);
+  register('echo', echoCommand);
+  register('sleep', sleepCommand);
+  register('true', trueCommand);
+  register('false', falseCommand);
+  register('which', createWhichCommand(virtualCommands));
+  register('exit', createExitCommand(globalShellSettings));
+  register('env', envCommand);
+  register('cat', catCommand);
+  register('ls', lsCommand);
+  register('mkdir', mkdirCommand);
+  register('rm', rmCommand);
+  register('mv', mvCommand);
+  register('cp', cpCommand);
+  register('touch', touchCommand);
+  register('basename', basenameCommand);
+  register('dirname', dirnameCommand);
+  register('yes', yesCommand);
+  register('seq', seqCommand);
+  register('test', testCommand);
+}

package/js/src/commands/$.which.mjs

@@ -28,7 +28,9 @@ export default function createWhichCommand(virtualCommands) {
           if (fs.statSync(fullPath).isFile()) {
             return VirtualUtils.success(`${fullPath}\n`);
           }
-        } catch {}
+        } catch {
+          // File doesn't exist or isn't accessible, continue searching
+        }
       }
     }
 

package/js/src/commands/index.mjs

@@ -0,0 +1,24 @@
+// Command module index
+// Re-exports all built-in virtual commands
+
+export { default as cd } from './$.cd.mjs';
+export { default as pwd } from './$.pwd.mjs';
+export { default as echo } from './$.echo.mjs';
+export { default as sleep } from './$.sleep.mjs';
+export { default as trueCmd } from './$.true.mjs';
+export { default as falseCmd } from './$.false.mjs';
+export { default as createWhich } from './$.which.mjs';
+export { default as createExit } from './$.exit.mjs';
+export { default as env } from './$.env.mjs';
+export { default as cat } from './$.cat.mjs';
+export { default as ls } from './$.ls.mjs';
+export { default as mkdir } from './$.mkdir.mjs';
+export { default as rm } from './$.rm.mjs';
+export { default as mv } from './$.mv.mjs';
+export { default as cp } from './$.cp.mjs';
+export { default as touch } from './$.touch.mjs';
+export { default as basename } from './$.basename.mjs';
+export { default as dirname } from './$.dirname.mjs';
+export { default as yes } from './$.yes.mjs';
+export { default as seq } from './$.seq.mjs';
+export { default as test } from './$.test.mjs';