command-stream 0.9.0 → 0.9.2

package/js/src/$.quote.mjs

@@ -0,0 +1,161 @@
+// Shell quoting and command building utilities
+// Handles safe interpolation of values into shell commands
+
+import { trace } from './$.trace.mjs';
+
+/**
+ * Quote a value for safe shell interpolation
+ * @param {*} value - Value to quote
+ * @returns {string} Safely quoted string
+ */
+export function quote(value) {
+  if (value === null || value === undefined) {
+    return "''";
+  }
+  if (Array.isArray(value)) {
+    return value.map(quote).join(' ');
+  }
+  if (typeof value !== 'string') {
+    value = String(value);
+  }
+  if (value === '') {
+    return "''";
+  }
+
+  // If the value is already properly quoted and doesn't need further escaping,
+  // check if we can use it as-is or with simpler quoting
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    // If it's already single-quoted and doesn't contain unescaped single quotes in the middle,
+    // we can potentially use it as-is
+    const inner = value.slice(1, -1);
+    if (!inner.includes("'")) {
+      // The inner content has no single quotes, so the original quoting is fine
+      return value;
+    }
+  }
+
+  if (value.startsWith('"') && value.endsWith('"') && value.length > 2) {
+    // If it's already double-quoted, wrap it in single quotes to preserve it
+    return `'${value}'`;
+  }
+
+  // Check if the string needs quoting at all
+  // Safe characters: alphanumeric, dash, underscore, dot, slash, colon, equals, comma, plus
+  // This regex matches strings that DON'T need quoting
+  const safePattern = /^[a-zA-Z0-9_\-./=,+@:]+$/;
+
+  if (safePattern.test(value)) {
+    // The string is safe and doesn't need quoting
+    return value;
+  }
+
+  // Default behavior: wrap in single quotes and escape any internal single quotes
+  // This handles spaces, special shell characters, etc.
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Build a shell command from template strings and values
+ * @param {string[]} strings - Template literal strings
+ * @param {*[]} values - Interpolated values
+ * @returns {string} Complete shell command
+ */
+export function buildShellCommand(strings, values) {
+  trace(
+    'Utils',
+    () =>
+      `buildShellCommand ENTER | ${JSON.stringify(
+        {
+          stringsLength: strings.length,
+          valuesLength: values.length,
+        },
+        null,
+        2
+      )}`
+  );
+
+  // Special case: if we have a single value with empty surrounding strings,
+  // and the value looks like a complete shell command, treat it as raw
+  if (
+    values.length === 1 &&
+    strings.length === 2 &&
+    strings[0] === '' &&
+    strings[1] === '' &&
+    typeof values[0] === 'string'
+  ) {
+    const commandStr = values[0];
+    // Check if this looks like a complete shell command (contains spaces and shell-safe characters)
+    const commandPattern = /^[a-zA-Z0-9_\-./=,+@:\s"'`$(){}<>|&;*?[\]~\\]+$/;
+    if (commandPattern.test(commandStr) && commandStr.trim().length > 0) {
+      trace(
+        'Utils',
+        () =>
+          `BRANCH: buildShellCommand => COMPLETE_COMMAND | ${JSON.stringify({ command: commandStr }, null, 2)}`
+      );
+      return commandStr;
+    }
+  }
+
+  let out = '';
+  for (let i = 0; i < strings.length; i++) {
+    out += strings[i];
+    if (i < values.length) {
+      const v = values[i];
+      if (
+        v &&
+        typeof v === 'object' &&
+        Object.prototype.hasOwnProperty.call(v, 'raw')
+      ) {
+        trace(
+          'Utils',
+          () =>
+            `BRANCH: buildShellCommand => RAW_VALUE | ${JSON.stringify({ value: String(v.raw) }, null, 2)}`
+        );
+        out += String(v.raw);
+      } else {
+        const quoted = quote(v);
+        trace(
+          'Utils',
+          () =>
+            `BRANCH: buildShellCommand => QUOTED_VALUE | ${JSON.stringify({ original: v, quoted }, null, 2)}`
+        );
+        out += quoted;
+      }
+    }
+  }
+
+  trace(
+    'Utils',
+    () =>
+      `buildShellCommand EXIT | ${JSON.stringify({ command: out }, null, 2)}`
+  );
+  return out;
+}
+
+/**
+ * Mark a value as raw (not to be quoted)
+ * @param {*} value - Value to mark as raw
+ * @returns {{ raw: string }} Raw value wrapper
+ */
+export function raw(value) {
+  trace('API', () => `raw() called with value: ${String(value).slice(0, 50)}`);
+  return { raw: String(value) };
+}
+
+/**
+ * Pump a readable stream, calling onChunk for each chunk
+ * @param {Readable} readable - Readable stream
+ * @param {function} onChunk - Callback for each chunk
+ */
+export async function pumpReadable(readable, onChunk) {
+  if (!readable) {
+    trace('Utils', () => 'pumpReadable: No readable stream provided');
+    return;
+  }
+  trace('Utils', () => 'pumpReadable: Starting to pump readable stream');
+  for await (const chunk of readable) {
+    const { asBuffer } = await import('./$.stream-utils.mjs');
+    await onChunk(asBuffer(chunk));
+  }
+  trace('Utils', () => 'pumpReadable: Finished pumping readable stream');
+}

package/js/src/$.result.mjs

@@ -0,0 +1,23 @@
+// Result creation utilities for command-stream
+// Creates standardized result objects
+
+/**
+ * Create a standardized result object
+ * @param {object} params - Result parameters
+ * @param {number} params.code - Exit code
+ * @param {string} params.stdout - Standard output
+ * @param {string} params.stderr - Standard error
+ * @param {string} params.stdin - Standard input that was sent
+ * @returns {object} Result object with text() method
+ */
+export function createResult({ code, stdout = '', stderr = '', stdin = '' }) {
+  return {
+    code,
+    stdout,
+    stderr,
+    stdin,
+    text() {
+      return Promise.resolve(stdout);
+    },
+  };
+}

package/js/src/$.shell-settings.mjs

@@ -0,0 +1,84 @@
+// Shell settings management (set, unset, shell object)
+// Provides bash-like shell option management
+
+import { trace } from './$.trace.mjs';
+import { getShellSettings, setShellSettings } from './$.state.mjs';
+
+/**
+ * Set a shell option
+ * @param {string} option - Option to set
+ * @returns {object} Current shell settings
+ */
+export function set(option) {
+  trace('API', () => `set() called with option: ${option}`);
+  const mapping = {
+    e: 'errexit', // set -e: exit on error
+    errexit: 'errexit',
+    v: 'verbose', // set -v: verbose
+    verbose: 'verbose',
+    x: 'xtrace', // set -x: trace execution
+    xtrace: 'xtrace',
+    u: 'nounset', // set -u: error on unset vars
+    nounset: 'nounset',
+    'o pipefail': 'pipefail', // set -o pipefail
+    pipefail: 'pipefail',
+  };
+
+  const globalShellSettings = getShellSettings();
+
+  if (mapping[option]) {
+    setShellSettings({ [mapping[option]]: true });
+    if (globalShellSettings.verbose) {
+      console.log(`+ set -${option}`);
+    }
+  }
+  return getShellSettings();
+}
+
+/**
+ * Unset a shell option
+ * @param {string} option - Option to unset
+ * @returns {object} Current shell settings
+ */
+export function unset(option) {
+  trace('API', () => `unset() called with option: ${option}`);
+  const mapping = {
+    e: 'errexit',
+    errexit: 'errexit',
+    v: 'verbose',
+    verbose: 'verbose',
+    x: 'xtrace',
+    xtrace: 'xtrace',
+    u: 'nounset',
+    nounset: 'nounset',
+    'o pipefail': 'pipefail',
+    pipefail: 'pipefail',
+  };
+
+  const globalShellSettings = getShellSettings();
+
+  if (mapping[option]) {
+    setShellSettings({ [mapping[option]]: false });
+    if (globalShellSettings.verbose) {
+      console.log(`+ set +${option}`);
+    }
+  }
+  return getShellSettings();
+}
+
+/**
+ * Convenience object for common shell patterns
+ */
+export const shell = {
+  set,
+  unset,
+  settings: () => ({ ...getShellSettings() }),
+
+  // Bash-like shortcuts
+  errexit: (enable = true) => (enable ? set('e') : unset('e')),
+  verbose: (enable = true) => (enable ? set('v') : unset('v')),
+  xtrace: (enable = true) => (enable ? set('x') : unset('x')),
+  pipefail: (enable = true) =>
+    enable ? set('o pipefail') : unset('o pipefail'),
+  nounset: (enable = true) => (enable ? set('u') : unset('u')),
+};

package/js/src/$.shell.mjs

@@ -0,0 +1,157 @@
+// Shell detection utilities for command-stream
+// Handles cross-platform shell detection and caching
+
+import cp from 'child_process';
+import fs from 'fs';
+import { trace } from './$.trace.mjs';
+
+// Shell detection cache
+let cachedShell = null;
+
+/**
+ * Find an available shell by checking multiple options in order
+ * Returns the shell command and arguments to use
+ * @returns {{ cmd: string, args: string[] }} Shell command and arguments
+ */
+export function findAvailableShell() {
+  if (cachedShell) {
+    trace('ShellDetection', () => `Using cached shell: ${cachedShell.cmd}`);
+    return cachedShell;
+  }
+
+  const isWindows = process.platform === 'win32';
+
+  // Windows-specific shells
+  const windowsShells = [
+    // Git Bash is the most Unix-compatible option on Windows
+    // Check common installation paths
+    {
+      cmd: 'C:\\Program Files\\Git\\bin\\bash.exe',
+      args: ['-c'],
+      checkPath: true,
+    },
+    {
+      cmd: 'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
+      args: ['-c'],
+      checkPath: true,
+    },
+    {
+      cmd: 'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+      args: ['-c'],
+      checkPath: true,
+    },
+    // Git Bash via PATH (if added to PATH by user)
+    { cmd: 'bash.exe', args: ['-c'], checkPath: false },
+    // WSL bash as fallback
+    { cmd: 'wsl.exe', args: ['bash', '-c'], checkPath: false },
+    // PowerShell as last resort (different syntax for commands)
+    { cmd: 'powershell.exe', args: ['-Command'], checkPath: false },
+    { cmd: 'pwsh.exe', args: ['-Command'], checkPath: false },
+    // cmd.exe as final fallback
+    { cmd: 'cmd.exe', args: ['/c'], checkPath: false },
+  ];
+
+  // Unix-specific shells
+  const unixShells = [
+    // Try absolute paths first (most reliable)
+    { cmd: '/bin/sh', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/bin/sh', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    // macOS specific paths
+    { cmd: '/usr/local/bin/bash', args: ['-l', '-c'], checkPath: true },
+    { cmd: '/usr/local/bin/zsh', args: ['-l', '-c'], checkPath: true },
+    // Linux brew paths
+    {
+      cmd: '/home/linuxbrew/.linuxbrew/bin/bash',
+      args: ['-l', '-c'],
+      checkPath: true,
+    },
+    {
+      cmd: '/home/linuxbrew/.linuxbrew/bin/zsh',
+      args: ['-l', '-c'],
+      checkPath: true,
+    },
+    // Try shells in PATH as fallback (which might not work in all environments)
+    // Using separate -l and -c flags for better compatibility
+    { cmd: 'sh', args: ['-l', '-c'], checkPath: false },
+    { cmd: 'bash', args: ['-l', '-c'], checkPath: false },
+    { cmd: 'zsh', args: ['-l', '-c'], checkPath: false },
+  ];
+
+  // Select shells based on platform
+  const shellsToTry = isWindows ? windowsShells : unixShells;
+
+  for (const shell of shellsToTry) {
+    try {
+      if (shell.checkPath) {
+        // Check if the absolute path exists
+        if (fs.existsSync(shell.cmd)) {
+          trace(
+            'ShellDetection',
+            () => `Found shell at absolute path: ${shell.cmd}`
+          );
+          cachedShell = { cmd: shell.cmd, args: shell.args };
+          return cachedShell;
+        }
+      } else {
+        // On Windows, use 'where' instead of 'which'
+        const whichCmd = isWindows ? 'where' : 'which';
+        const result = cp.spawnSync(whichCmd, [shell.cmd], {
+          encoding: 'utf-8',
+          // On Windows, we need shell: true for 'where' to work
+          shell: isWindows,
+        });
+        if (result.status === 0 && result.stdout) {
+          const shellPath = result.stdout.trim().split('\n')[0]; // Take first result
+          trace(
+            'ShellDetection',
+            () => `Found shell in PATH: ${shell.cmd} => ${shellPath}`
+          );
+          cachedShell = { cmd: shell.cmd, args: shell.args };
+          return cachedShell;
+        }
+      }
+    } catch (e) {
+      // Continue to next shell option
+      trace(
+        'ShellDetection',
+        () => `Failed to check shell ${shell.cmd}: ${e.message}`
+      );
+    }
+  }
+
+  // Final fallback based on platform
+  if (isWindows) {
+    trace(
+      'ShellDetection',
+      () => 'WARNING: No shell found, using cmd.exe as fallback on Windows'
+    );
+    cachedShell = { cmd: 'cmd.exe', args: ['/c'] };
+  } else {
+    trace(
+      'ShellDetection',
+      () => 'WARNING: No shell found, using /bin/sh as fallback'
+    );
+    cachedShell = { cmd: '/bin/sh', args: ['-l', '-c'] };
+  }
+  return cachedShell;
+}
+
+/**
+ * Clear the shell cache (useful for testing)
+ */
+export function clearShellCache() {
+  cachedShell = null;
+  trace('ShellDetection', () => 'Shell cache cleared');
+}
+
+/**
+ * Get the currently cached shell (if any)
+ * @returns {{ cmd: string, args: string[] } | null}
+ */
+export function getCachedShell() {
+  return cachedShell;
+}