feat(spawn): enhance error messages with detailed context

Improve spawn error debugging by replacing generic "command failed" messages with detailed error information including command, arguments, exit code/signal, and stderr output.

Key improvements:
- Add enhanceSpawnError() function to enrich spawn errors with context
- Include full command and arguments in error message (with truncation for long values)
- Show exit code or termination signal
- Include first line of stderr for immediate context
- Use lazy stack trace computation with WeakMap cache for performance
- Handle both synthetic errors (modify in-place) and non-synthetic errors (wrap with cause)
- Export enhanceSpawnError for external use
- Add pony-cause dependency for cause chain handling

Technical details:
- Lazy getter for stack traces avoids computation until accessed
- WeakMap cache prevents memory leaks (auto-cleanup on GC)
- Avoid infinite recursion by computing stack from original error
- Preserve all spawn error properties (cmd, args, code, signal, stdout, stderr)

Author: jdalton

package.json

@@ -359,6 +359,10 @@
       "types": "./dist/env/xdg.d.ts",
       "default": "./dist/env/xdg.js"
     },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
     "./fs": {
       "types": "./dist/fs.d.ts",
       "default": "./dist/fs.js"
@@ -760,6 +764,7 @@
     "npm-package-arg": "13.0.0",
     "pacote": "21.0.1",
     "picomatch": "2.3.1",
+    "pony-cause": "2.1.11",
     "semver": "7.7.2",
     "signal-exit": "4.1.0",
     "spdx-correct": "3.2.0",

pnpm-lock.yaml

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Error utilities with cause chain support.
+ * Provides helpers for working with error causes and stack traces.
+ */
+
+import { messageWithCauses, stackWithCauses } from './external/pony-cause'
+
+export { messageWithCauses, stackWithCauses }

src/errors.ts

@@ -27,6 +27,7 @@
  */
 
 import { getAbortSignal } from './constants/process'
+import { stackWithCauses } from './errors'
 
 import npmCliPromiseSpawn from './external/@npmcli/promise-spawn'
 
@@ -55,6 +56,9 @@ import type { EventEmitter } from 'node:events'
 const abortSignal = getAbortSignal()
 const spinner = getDefaultSpinner()
 
+// Cache for lazy stack trace computation.
+const stackCache = new WeakMap<Error, string>()
+
 // Define BufferEncoding type for TypeScript compatibility.
 type BufferEncoding = globalThis.BufferEncoding
 
@@ -246,6 +250,103 @@ export interface SpawnSyncReturns<T> {
   error?: Error | undefined
 }
 
+/**
+ * Enhances spawn error with better context.
+ * Converts generic "command failed" to detailed error with command, exit code, and stderr.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export function enhanceSpawnError(error: unknown): unknown {
+  if (error === null || typeof error !== 'object') {
+    return error
+  }
+
+  if (!isSpawnError(error)) {
+    return error
+  }
+
+  const err = error as SpawnError
+  const { args, cmd, code, signal, stderr } = err
+  const stderrText =
+    typeof stderr === 'string' ? stderr : (stderr?.toString() ?? '')
+
+  // Build enhanced message.
+  let enhancedMessage = `Command failed: ${cmd}`
+
+  if (args && args.length > 0) {
+    const argsStr = args.join(' ')
+    if (argsStr.length < 100) {
+      enhancedMessage += ` ${argsStr}`
+    } else {
+      enhancedMessage += ` ${argsStr.slice(0, 97)}...`
+    }
+  }
+
+  if (signal) {
+    enhancedMessage += ` (terminated by ${signal})`
+  } else if (code !== undefined) {
+    enhancedMessage += ` (exit code ${code})`
+  }
+
+  // Add first line of stderr for context.
+  const trimmedStderr = stderrText.trim()
+  if (trimmedStderr) {
+    const firstLine = trimmedStderr.split('\n')[0]
+    if (firstLine.length < 200) {
+      enhancedMessage += `\n${firstLine}`
+    } else {
+      enhancedMessage += `\n${firstLine.slice(0, 197)}...`
+    }
+  }
+
+  // Check if this is a synthetic error (generic "command failed" message).
+  const isSynthetic = err.message === 'command failed'
+
+  if (isSynthetic) {
+    // Modify the error directly.
+    Object.defineProperty(err, 'message', {
+      __proto__: null,
+      value: enhancedMessage,
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    } as PropertyDescriptor)
+
+    return err
+  }
+
+  // Create enhanced error with original error as cause.
+  const enhancedError = new Error(enhancedMessage, {
+    cause: err,
+  }) as SpawnError
+
+  // Copy all spawn error properties except message and stack.
+  const descriptors = Object.getOwnPropertyDescriptors(err)
+  delete descriptors.message
+  delete descriptors.stack
+  Object.defineProperties(enhancedError, descriptors)
+
+  // Build stack lazily on first access using WeakMap cache.
+  Object.defineProperty(enhancedError, 'stack', {
+    __proto__: null,
+    configurable: true,
+    enumerable: false,
+    get() {
+      let stack = stackCache.get(enhancedError)
+      if (stack === undefined) {
+        try {
+          stack = stackWithCauses(err)
+        } catch {
+          stack = err.stack ?? new Error().stack ?? ''
+        }
+        stackCache.set(enhancedError, stack)
+      }
+      return stack
+    },
+  } as PropertyDescriptor)
+
+  return enhancedError
+}
+
 /**
  * Check if a value is a spawn error with expected error properties.
  * Tests for common error properties from child process failures.
@@ -652,18 +753,25 @@ export function spawn(
         return strippedResult
       })
       .catch(error => {
-        throw stripAnsiFromSpawnResult(error)
+        const strippedError = stripAnsiFromSpawnResult(error)
+        const enhancedError = enhanceSpawnError(strippedError)
+        throw enhancedError
       }) as PromiseSpawnResult
   } else {
-    newSpawnPromise = spawnPromise.then(result => {
-      // Add exitCode as an alias for code.
-      if ('code' in result) {
-        const res = result as typeof result & { exitCode: number }
-        res.exitCode = result.code
-        return res
-      }
-      return result
-    }) as PromiseSpawnResult
+    newSpawnPromise = spawnPromise
+      .then(result => {
+        // Add exitCode as an alias for code.
+        if ('code' in result) {
+          const res = result as typeof result & { exitCode: number }
+          res.exitCode = result.code
+          return res
+        }
+        return result
+      })
+      .catch(error => {
+        const enhancedError = enhanceSpawnError(error)
+        throw enhancedError
+      }) as PromiseSpawnResult
   }
   if (shouldRestartSpinner) {
     newSpawnPromise = newSpawnPromise.finally(() => {

src/spawn.ts

@@ -35,7 +35,9 @@ describe('spawn integration', () => {
         await spawn('node', ['--invalid-flag'])
         expect.fail('Should have thrown')
       } catch (error: any) {
-        expect(error.message).toContain('command failed')
+        expect(error.message).toContain('Command failed')
+        expect(error.message).toContain('exit code')
+        expect(error.code).toBe(9)
       }
     })