feat(build-infra): add preflight-checks runner for DRY build validation

Create unified preflight checks module that combines disk space, compiler,
and Python version checks with configurable options and error handling.

New utilities:
- runPreflightChecks: Configurable checks with result aggregation
- runPreflightChecksOrExit: Convenience wrapper that exits on failure

Configuration options:
- disk: Check disk space (default: true, 5GB)
- compiler: Check for C++ compiler with fallback list
- python: Check Python version (default: 3.6+)
- quiet: Suppress output
- failFast: Exit on first failure (default: true)

Benefits:
- Eliminates ~165 lines of repeated preflight code across 12 builders
- Consistent check patterns and error messages
- Configurable checks per build script needs
- Better error aggregation and reporting
- Reusable across all builder packages

Next: Update builder scripts to use shared preflight runner

Author: jdalton

packages/build-infra/lib/preflight-checks.mjs

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Preflight checks runner for build scripts.
+ * Provides a DRY way to run common pre-build validation checks.
+ */
+
+import { logger } from '@socketsecurity/lib/logger'
+
+import { printError, printSuccess } from './build-output.mjs'
+import {
+  checkCompiler,
+  checkDiskSpace,
+  checkPythonVersion,
+} from './build-helpers.mjs'
+
+/**
+ * Run preflight checks for build scripts.
+ *
+ * @param {object} options - Check options
+ * @param {boolean} [options.disk=true] - Check disk space
+ * @param {number} [options.diskGB=5] - Required disk space in GB
+ * @param {boolean} [options.compiler=false] - Check for C++ compiler
+ * @param {string|string[]} [options.compilers] - Specific compiler(s) to check
+ * @param {boolean} [options.python=false] - Check Python version
+ * @param {string} [options.pythonVersion='3.6'] - Minimum Python version
+ * @param {boolean} [options.quiet=false] - Suppress output
+ * @param {boolean} [options.failFast=true] - Exit on first failure
+ * @returns {Promise<{passed: boolean, failures: string[]}>}
+ */
+export async function runPreflightChecks(options = {}) {
+  const {
+    compiler = false,
+    compilers,
+    disk = true,
+    diskGB = 5,
+    failFast = true,
+    python = false,
+    pythonVersion = '3.6',
+    quiet = false,
+  } = options
+
+  const failures = []
+
+  if (!quiet) {
+    logger.step('Running preflight checks')
+    logger.log('')
+  }
+
+  // Check disk space.
+  if (disk) {
+    const diskCheck = await checkDiskSpace('.', diskGB)
+    if (!diskCheck.sufficient) {
+      const msg = `Insufficient disk space: ${diskCheck.availableGB}GB available, ${diskGB}GB required`
+      failures.push(msg)
+      if (!quiet) {
+        printError(msg)
+      }
+      if (failFast) {
+        return { failures, passed: false }
+      }
+    }
+  }
+
+  // Check compiler.
+  if (compiler) {
+    const compilerCheck = await checkCompiler(compilers)
+    if (!compilerCheck.available) {
+      const msg = compilers
+        ? `No C++ compiler found (tried: ${Array.isArray(compilers) ? compilers.join(', ') : compilers})`
+        : 'No C++ compiler found'
+      failures.push(msg)
+      if (!quiet) {
+        printError(msg)
+      }
+      if (failFast) {
+        return { failures, passed: false }
+      }
+    }
+  }
+
+  // Check Python.
+  if (python) {
+    const pythonCheck = await checkPythonVersion(pythonVersion)
+    if (!pythonCheck.available) {
+      const msg = `Python ${pythonVersion}+ not found`
+      failures.push(msg)
+      if (!quiet) {
+        printError(msg)
+      }
+      if (failFast) {
+        return { failures, passed: false }
+      }
+    }
+  }
+
+  if (!quiet) {
+    if (!failures.length) {
+      printSuccess('All preflight checks passed')
+      logger.log('')
+    } else {
+      printError(`${failures.length} preflight check(s) failed`)
+      logger.log('')
+    }
+  }
+
+  return {
+    failures,
+    passed: !failures.length,
+  }
+}
+
+/**
+ * Run preflight checks and exit on failure.
+ *
+ * @param {object} options - Check options
+ * @returns {Promise<void>}
+ */
+export async function runPreflightChecksOrExit(options = {}) {
+  const result = await runPreflightChecks(options)
+
+  if (!result.passed) {
+    if (!options.quiet) {
+      logger.error('Preflight checks failed')
+      for (const failure of result.failures) {
+        logger.error(`  - ${failure}`)
+      }
+    }
+    process.exit(1)
+  }
+}

packages/build-infra/package.json

@@ -13,6 +13,7 @@
     "./lib/emscripten-builder": "./lib/emscripten-builder.mjs",
     "./lib/extraction-cache": "./lib/extraction-cache.mjs",
     "./lib/patch-validator": "./lib/patch-validator.mjs",
+    "./lib/preflight-checks": "./lib/preflight-checks.mjs",
     "./lib/rust-builder": "./lib/rust-builder.mjs",
     "./lib/script-runner": "./lib/script-runner.mjs",
     "./lib/tool-installer": "./lib/tool-installer.mjs"