refactor(build): improve build infrastructure and E2E testing

Enhance build-infra APIs with better signatures and return types.
Unify E2E test scripts with single configuration approach.

Build Infrastructure:
- Improve exec() to support both exec(cmd, opts) and exec(cmd, args, opts)
- Return structured data from checkDiskSpace() and checkCompiler()
- Use whichBinSync() for reliable binary detection

E2E Testing:
- Add unified scripts/e2e.mjs for all binary types (js/sea/smol/all)
- Simplify to single .env.e2e with dynamic TEST_*_BINARY flags
- Remove redundant .env.e2e.{sea,smol,all} files
- Improve build feedback with timing and manual build instructions

Builder Scripts:
- Update node-smol-builder to use improved build-infra APIs
- Update node-sea-builder to use improved build-infra APIs
- Make Socket bootstrap optional with clear skip message

Author: jdalton

packages/build-infra/lib/build-exec.mjs

@@ -8,26 +8,31 @@
 import { spawn } from '@socketsecurity/lib/spawn'
 
 /**
- * Execute command and inherit stdio.
+ * Execute command with arguments.
  *
  * @param {string} command - Command to execute
- * @param {object} options - Spawn options
- * @returns {Promise<void>}
+ * @param {string[]|object} argsOrOptions - Arguments array or options object
+ * @param {object} [options] - Spawn options (if args provided)
+ * @returns {Promise<object>}
  */
-export async function exec(command, options = {}) {
-  const result = await spawn(command, [], {
-    shell: true,
-    stdio: options.stdio || 'pipe',
+export async function exec(command, argsOrOptions = [], options = {}) {
+  // Handle both signatures: exec(cmd, opts) and exec(cmd, args, opts).
+  const args = Array.isArray(argsOrOptions) ? argsOrOptions : []
+  const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions
+
+  const result = await spawn(command, args, {
+    stdio: opts.stdio || 'inherit',
     stdioString: true,
     stripAnsi: false,
-    ...options,
+    ...opts,
   })
 
   // Treat undefined or null status as success (0).
   const exitCode = result.status ?? 0
 
   if (exitCode !== 0) {
-    const error = new Error(`Command failed with exit code ${exitCode}: ${command}`)
+    const cmdString = args.length ? `${command} ${args.join(' ')}` : command
+    const error = new Error(`Command failed with exit code ${exitCode}: ${cmdString}`)
     error.stdout = result.stdout
     error.stderr = result.stderr
     error.code = exitCode
@@ -38,9 +43,10 @@ export async function exec(command, options = {}) {
 }
 
 /**
- * Execute command and capture output.
+ * Execute shell command and capture output.
+ * Always uses shell for proper command execution with redirections and pipes.
  *
- * @param {string} command - Command to execute
+ * @param {string} command - Shell command to execute
  * @param {object} options - Spawn options
  * @returns {Promise<{stdout: string, stderr: string, code: number}>}
  */

packages/build-infra/lib/build-helpers.mjs

@@ -8,72 +8,78 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 
+import { whichBinSync } from '@socketsecurity/lib/bin'
+
 import { exec, execCapture } from './build-exec.mjs'
 import { printError, printStep, printWarning } from './build-output.mjs'
 
 /**
  * Check available disk space.
  *
  * @param {string} dir - Directory to check
- * @param {number} requiredBytes - Required bytes
- * @returns {Promise<boolean>}
+ * @param {number} [requiredGB=5] - Required GB (defaults to 5GB)
+ * @returns {Promise<{availableGB: number|null, sufficient: boolean}>}
  */
-export async function checkDiskSpace(dir, requiredBytes) {
+export async function checkDiskSpace(dir, requiredGB = 5) {
   printStep('Checking disk space')
 
   try {
     const { stdout } = await execCapture(`df -k "${dir}"`)
     const lines = stdout.trim().split('\n')
     if (lines.length < 2) {
       printWarning('Could not determine disk space')
-      return true
+      return { availableGB: null, sufficient: true }
     }
 
     const stats = lines[1].split(/\s+/)
     const availableKB = Number.parseInt(stats[3], 10)
     const availableBytes = availableKB * 1024
+    const availableGBValue = Number((availableBytes / (1024 * 1024 * 1024)).toFixed(2))
+    const sufficient = availableGBValue >= requiredGB
 
-    if (availableBytes < requiredBytes) {
-      const requiredGB = (requiredBytes / (1024 * 1024 * 1024)).toFixed(2)
-      const availableGB = (availableBytes / (1024 * 1024 * 1024)).toFixed(2)
-      printError(
-        `Insufficient disk space. Required: ${requiredGB} GB, Available: ${availableGB} GB`
-      )
-      return false
+    return {
+      availableGB: availableGBValue,
+      sufficient,
     }
-
-    return true
   } catch {
     printWarning('Could not check disk space')
-    return true
+    return { availableGB: null, sufficient: true }
   }
 }
 
 /**
  * Check if compiler is available.
+ * Tries multiple compilers if none specified.
  *
- * @param {string} compiler - Compiler command (e.g., 'clang++', 'gcc')
- * @returns {Promise<boolean>}
+ * @param {string|string[]} [compilers] - Compiler command(s) to check (e.g., 'clang++', ['clang++', 'g++', 'c++'])
+ * @returns {Promise<{available: boolean, compiler: string|undefined}>}
  */
-export async function checkCompiler(compiler) {
-  printStep(`Checking for ${compiler}`)
-
-  try {
-    await execCapture(`which ${compiler}`)
-    return true
-  } catch {
-    printError(`${compiler} not found. Please install ${compiler}.`)
-    return false
+export async function checkCompiler(compilers) {
+  const compilerList = Array.isArray(compilers)
+    ? compilers
+    : compilers
+      ? [compilers]
+      : ['clang++', 'g++', 'c++']
+
+  for (const compiler of compilerList) {
+    printStep(`Checking for ${compiler}`)
+
+    const binPath = whichBinSync(compiler, { nothrow: true })
+    if (binPath) {
+      return { available: true, compiler }
+    }
   }
+
+  return { available: false, compiler: undefined }
 }
 
 /**
  * Check Python version.
  *
- * @param {string} minVersion - Minimum required version (e.g., '3.8')
- * @returns {Promise<boolean>}
+ * @param {string} [minVersion='3.6'] - Minimum required version (e.g., '3.8')
+ * @returns {Promise<{available: boolean, sufficient: boolean, version: string|null}>}
  */
-export async function checkPythonVersion(minVersion) {
+export async function checkPythonVersion(minVersion = '3.6') {
   printStep('Checking Python version')
 
   try {
@@ -84,17 +90,19 @@ export async function checkPythonVersion(minVersion) {
     const [major, minor] = version.split('.').map(Number)
     const [minMajor, minMinor] = minVersion.split('.').map(Number)
 
-    if (major < minMajor || (major === minMajor && minor < minMinor)) {
-      printError(
-        `Python ${minVersion}+ required, but found ${version}`
-      )
-      return false
-    }
+    const sufficient = major > minMajor || (major === minMajor && minor >= minMinor)
 
-    return true
+    return {
+      available: true,
+      sufficient,
+      version,
+    }
   } catch {
-    printError('Python 3 not found. Please install Python 3.')
-    return false
+    return {
+      available: false,
+      sufficient: false,
+      version: null,
+    }
   }
 }
 
@@ -295,18 +303,11 @@ export async function cleanCheckpoint(buildDir) {
 export async function checkNetworkConnectivity() {
   try {
     // Try to reach GitHub (where we clone from).
-    const result = await execCapture('curl', [
-      '-s',
-      '-o',
-      '/dev/null',
-      '-w',
-      '%{http_code}',
-      '--connect-timeout',
-      '5',
-      'https://github.com',
-    ])
-
-    const statusCode = result.stdout
+    const result = await execCapture(
+      'curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 https://github.com'
+    )
+
+    const statusCode = result.stdout.trim()
     return {
       connected:
         statusCode === '200' || statusCode === '301' || statusCode === '302',
@@ -325,12 +326,9 @@ export async function checkNetworkConnectivity() {
  */
 export async function verifyGitTag(version) {
   try {
-    const result = await execCapture('git', [
-      'ls-remote',
-      '--tags',
-      'https://github.com/nodejs/node.git',
-      version,
-    ])
+    const result = await execCapture(
+      `git ls-remote --tags https://github.com/nodejs/node.git ${version}`
+    )
 
     return {
       exists: result.stdout.includes(version),

packages/cli/.env.e2e

@@ -1,5 +1,6 @@
 # E2E Test Environment Configuration
-# Extends .env.test with E2E-specific settings
+# Used by all e2e tests (js, sea, smol, all)
+# The e2e.mjs script sets TEST_*_BINARY flags dynamically
 
 NODE_COMPILE_CACHE="./.cache"
 NODE_OPTIONS="--max-old-space-size=2048 --unhandled-rejections=warn"
@@ -10,3 +11,5 @@ SOCKET_CLI_JS_PATH="./dist/cli.js"
 
 # Enable E2E tests (requires Socket API token)
 RUN_E2E_TESTS=1
+
+# Note: TEST_SEA_BINARY and TEST_SMOL_BINARY are set by scripts/e2e.mjs

packages/cli/.env.e2e.all

@@ -56,10 +56,10 @@
     "bs": "dotenvx -q run -f .env.local -- pnpm run build; pnpm exec socket --",
     "s": "dotenvx -q run -f .env.local -- pnpm exec socket --",
     "e2e-tests": "dotenvx -q run -f .env.test -- vitest run --config vitest.e2e.config.mts",
-    "e2e:js": "dotenvx -q run -f .env.e2e -- vitest run test/e2e/binary-test-suite.e2e.test.mts --config vitest.e2e.config.mts",
-    "e2e:smol": "dotenvx -q run -f .env.e2e.smol -- vitest run test/e2e/binary-test-suite.e2e.test.mts --config vitest.e2e.config.mts",
-    "e2e:sea": "dotenvx -q run -f .env.e2e.sea -- vitest run test/e2e/binary-test-suite.e2e.test.mts --config vitest.e2e.config.mts",
-    "e2e:all": "dotenvx -q run -f .env.e2e.all -- vitest run test/e2e/binary-test-suite.e2e.test.mts --config vitest.e2e.config.mts",
+    "e2e:js": "node scripts/e2e.mjs --js",
+    "e2e:smol": "node scripts/e2e.mjs --smol",
+    "e2e:sea": "node scripts/e2e.mjs --sea",
+    "e2e:all": "node scripts/e2e.mjs --all",
     "test": "run-s check test:*",
     "test:prepare": "dotenvx -q run -f .env.test -- pnpm build && del-cli 'test/**/node_modules'",
     "test:unit": "dotenvx -q run -f .env.test -- vitest run",