Demystifying 'Error: spawn ENOENT' in Node.js

// Enhanced error logging for 2025
const { spawn } = require("child_process");

function spawnWithLogging(command, args = [], options = {}) {
  console.log(`Attempting to spawn: ${command}`);
  console.log(`Arguments: ${JSON.stringify(args)}`);
  console.log(`Current PATH: ${process.env.PATH}`);
  console.log(`Working Directory: ${process.cwd()}`);

  const child = spawn(command, args, options);

  child.on("error", (error) => {
    if (error.code === "ENOENT") {
      console.error(`ENOENT Error Details:`);
      console.error(`Command: ${command}`);
      console.error(`Error: ${error.message}`);
      console.error(`PATH: ${process.env.PATH}`);

      // 2025 Enhancement: Check common locations
      checkCommonLocations(command);
    }
  });

  return child;
}

// Check common installation locations (2025 update)
function checkCommonLocations(command) {
  const fs = require("fs");
  const path = require("path");

  const commonPaths = [
    "/usr/local/bin",
    "/usr/bin",
    "/opt/homebrew/bin", // Apple Silicon Macs
    "C:\\Program Files\\nodejs",
    "C:\\Users\\%USERNAME%\\AppData\\Roaming\\npm",
    process.env.HOME + "/.local/bin", // Modern Python tools
    process.env.HOME + "/.cargo/bin" // Rust tools
  ];

  for (const dir of commonPaths) {
    const fullPath = path.join(dir, command);
    if (fs.existsSync(fullPath)) {
      console.log(`Found ${command} at: ${fullPath}`);
    }
  }
}

// Comprehensive environment check for 2025
function analyzeEnvironment() {
  console.log("=== Environment Analysis ===");
  console.log(`Node.js Version: ${process.version}`);
  console.log(`Platform: ${process.platform}`);
  console.log(`Architecture: ${process.arch}`);
  console.log(`Shell: ${process.env.SHELL || process.env.ComSpec}`);

  // Check package manager versions
  const packageManagers = ["npm", "npx", "yarn", "pnpm", "bun", "uv", "uvx"];

  packageManagers.forEach((pm) => {
    try {
      const { execSync } = require("child_process");
      const version = execSync(`${pm} --version`, { encoding: "utf8" }).trim();
      console.log(`${pm}: ${version}`);
    } catch (error) {
      console.log(`${pm}: Not found (${error.code})`);
    }
  });
}

// Advanced PATH analysis for 2025
function analyzePath() {
  const path = require("path");
  const fs = require("fs");

  const pathDirs = process.env.PATH.split(path.delimiter);

  console.log("=== PATH Analysis ===");
  pathDirs.forEach((dir, index) => {
    console.log(`${index + 1}. ${dir}`);

    try {
      if (fs.existsSync(dir)) {
        const files = fs.readdirSync(dir);
        const executables = files.filter((file) => {
          const fullPath = path.join(dir, file);
          try {
            return fs.statSync(fullPath).isFile();
          } catch (e) {
            return false;
          }
        });
        console.log(
          `   Contains: ${executables.slice(0, 5).join(", ")}${
            executables.length > 5 ? "..." : ""
          }`
        );
      } else {
        console.log(`   ❌ Directory does not exist`);
      }
    } catch (error) {
      console.log(`   ❌ Cannot access: ${error.message}`);
    }
  });
}

// Windows spawn helper (2025)
function windowsSpawn(command, args, options = {}) {
  if (process.platform === "win32") {
    // Handle .cmd, .bat extensions
    const possibleExtensions = ["", ".cmd", ".bat", ".exe"];

    for (const ext of possibleExtensions) {
      try {
        return spawn(command + ext, args, {
          ...options,
          shell: true
        });
      } catch (error) {
        if (error.code !== "ENOENT") {
          throw error;
        }
      }
    }
  }

  return spawn(command, args, options);
}

// Advanced debugging utility (2025)
class SpawnDebugger {
  static async diagnose(command, args = [], options = {}) {
    const fs = require("fs").promises;
    const path = require("path");
    const { execSync } = require("child_process");

    console.log(`🔍 Diagnosing spawn command: ${command}`);

    // Check if command exists in PATH
    try {
      const result =
        process.platform === "win32"
          ? execSync(`where ${command}`, { encoding: "utf8" })
          : execSync(`which ${command}`, { encoding: "utf8" });
      console.log(`✅ Found at: ${result.trim()}`);
    } catch (error) {
      console.log(`❌ Command not found in PATH`);

      // Check common locations
      await this.checkCommonLocations(command);
    }

    // Check permissions
    await this.checkPermissions(command);

    // Environment analysis
    this.analyzeEnvironment();
  }

  static async checkCommonLocations(command) {
    const locations = [
      "/usr/local/bin",
      "/usr/bin",
      "/opt/homebrew/bin",
      process.env.HOME + "/.local/bin",
      process.env.HOME + "/.npm-global/bin",
      "C:\\Program Files\\nodejs",
      "C:\\Users\\" + process.env.USERNAME + "\\AppData\\Roaming\\npm"
    ];

    for (const location of locations) {
      try {
        const fullPath = path.join(location, command);
        await fs.access(fullPath);
        console.log(`📍 Found alternative location: ${fullPath}`);
      } catch (error) {
        // File doesn't exist at this location
      }
    }
  }

  static async checkPermissions(command) {
    try {
      const { execSync } = require("child_process");
      const result = execSync(`ls -la $(which ${command})`, {
        encoding: "utf8"
      });
      console.log(`🔐 Permissions: ${result.trim()}`);
    } catch (error) {
      console.log(`❌ Cannot check permissions: ${error.message}`);
    }
  }

  static analyzeEnvironment() {
    console.log(`🖥️  Platform: ${process.platform}`);
    console.log(`🏗️  Node.js: ${process.version}`);
    console.log(`📁 Current directory: ${process.cwd()}`);
    console.log(
      `🛤️  PATH entries: ${process.env.PATH.split(path.delimiter).length}`
    );
  }
}

// Usage
SpawnDebugger.diagnose("npm");

// Secure spawn implementation
function secureSpawn(command, args, options = {}) {
  const allowedCommands = ["npm", "npx", "node", "yarn", "pnpm"];

  if (!allowedCommands.includes(command)) {
    throw new Error(`Command '${command}' not in allowed list`);
  }

  // Use absolute paths when possible
  const { execSync } = require("child_process");
  try {
    const fullPath = execSync(`which ${command}`, { encoding: "utf8" }).trim();
    return spawn(fullPath, args, options);
  } catch (error) {
    throw new Error(`Command '${command}' not found in PATH`);
  }
}

// Validate command arguments
function validateArgs(args) {
  const dangerousPatterns = [";", "&&", "||", "|", ">", "<", "`", "$"];

  for (const arg of args) {
    for (const pattern of dangerousPatterns) {
      if (arg.includes(pattern)) {
        throw new Error(
          `Dangerous pattern '${pattern}' found in argument: ${arg}`
        );
      }
    }
  }
}

// Error tracking for production (2025)
class SpawnErrorTracker {
  constructor() {
    this.errors = new Map();
    this.successCount = 0;
  }

  trackSpawn(command, success, error = null) {
    if (success) {
      this.successCount++;
    } else {
      const key = `${command}:${error?.code || "unknown"}`;
      this.errors.set(key, (this.errors.get(key) || 0) + 1);
    }
  }

  getStats() {
    return {
      totalSuccess: this.successCount,
      totalErrors: Array.from(this.errors.values()).reduce((a, b) => a + b, 0),
      errorBreakdown: Object.fromEntries(this.errors)
    };
  }
}

const tracker = new SpawnErrorTracker();

// Monitored spawn wrapper
function monitoredSpawn(command, args, options) {
  return new Promise((resolve, reject) => {
    const child = spawn(command, args, options);

    child.on("close", (code) => {
      if (code === 0) {
        tracker.trackSpawn(command, true);
        resolve(child);
      } else {
        tracker.trackSpawn(command, false, { code });
        reject(new Error(`Command failed with code ${code}`));
      }
    });

    child.on("error", (error) => {
      tracker.trackSpawn(command, false, error);
      reject(error);
    });
  });
}