feat(build): add dependency-aware caching and binary build scripts

Solve cache invalidation and slow test issues by:
1. Tracking critical dependencies in cache keys
2. Separating binary builds from test suite
3. Adding intelligent cache management

Cache Improvements:
- New cache key utility tracks dependency versions
- Auto-invalidates when dependencies update
- Tracks @socketsecurity/{lib,packageurl-js,sdk,registry}
- Prevents stale dependency versions in builds

Build Scripts:
- build:binaries - Build WASM/SEA/smol without tests
- build:sea/smol/wasm - Build specific binaries
- build:binaries:dev - Fast dev mode builds
- clean:cache - Remove stale caches intelligently

Test Performance:
- Changed pretest from "build" to "build:cli"
- Tests now skip slow binary builds (especially WASM)
- Reduces test startup time significantly

Files:
- packages/build-infra/lib/cache-key.mjs - Dependency tracking
- scripts/build-binaries.mjs - Binary orchestration
- scripts/clean-cache.mjs - Cache management
- package.json - New scripts and fixed pretest

Usage:
  pnpm run build:smol --dev     # Fast smol build
  pnpm run build:wasm           # Just WASM (slow)
  pnpm test                     # Now fast - no binary rebuild
  pnpm run clean:cache          # Remove old caches

Author: jdalton

package.json

@@ -171,6 +171,11 @@
     "build:force": "node scripts/build.mjs --force",
     "build:cli": "pnpm --filter @socketsecurity/cli run build",
     "build:watch": "pnpm --filter @socketsecurity/cli run build:watch",
+    "build:binaries": "node scripts/build-binaries.mjs",
+    "build:binaries:dev": "node scripts/build-binaries.mjs --dev",
+    "build:sea": "node scripts/build-binaries.mjs --sea",
+    "build:smol": "node scripts/build-binaries.mjs --smol",
+    "build:wasm": "node scripts/build-binaries.mjs --wasm",
     "dev": "pnpm run build:watch",
     "// Quality Checks": "",
     "check": "node scripts/check.mjs",
@@ -198,12 +203,14 @@
     "wasm:setup": "node scripts/wasm/setup-build-env.mjs",
     "// Maintenance": "",
     "clean": "pnpm --filter \"./packages/**\" run clean",
+    "clean:cache": "node scripts/clean-cache.mjs",
+    "clean:cache:all": "node scripts/clean-cache.mjs --all",
     "update": "node scripts/update.mjs",
     "// Publishing": "",
     "publish": "node scripts/publish.mjs",
     "// Setup": "",
     "prepare": "husky",
-    "pretest": "pnpm run build"
+    "pretest": "pnpm run build:cli"
   },
   "lint-staged": {
     "*.{cjs,cts,js,json,md,mjs,mts,ts}": [

packages/build-infra/lib/cache-key.mjs

@@ -0,0 +1,149 @@
+/**
+ * Generate cache keys with version and content hash for proper invalidation.
+ *
+ * Cache directory format: v{nodeVersion}-{arch}-{contentHash}-{pkgVersion}
+ * Example: v24.10.0-arm64-b71671ba-2.1.5
+ *
+ * Cache-busting dependencies:
+ * - Bootstrap: @socketsecurity/lib, @socketsecurity/packageurl-js
+ * - CLI: @socketsecurity/lib, @socketsecurity/packageurl-js, @socketsecurity/sdk, @socketsecurity/registry
+ * - CLI-with-sentry: @socketsecurity/lib, @socketsecurity/packageurl-js
+ */
+
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { platform, arch } from 'node:process'
+
+/**
+ * Critical dependencies that trigger cache invalidation.
+ * When these packages are updated, caches must be rebuilt.
+ */
+const CACHE_BUSTING_DEPS = {
+  bootstrap: [
+    '@socketsecurity/lib',
+    '@socketsecurity/packageurl-js',
+  ],
+  cli: [
+    '@socketsecurity/lib',
+    '@socketsecurity/packageurl-js',
+    '@socketsecurity/sdk',
+    '@socketsecurity/registry',
+  ],
+  'cli-with-sentry': [
+    '@socketsecurity/lib',
+    '@socketsecurity/packageurl-js',
+  ],
+}
+
+/**
+ * Get dependency versions from package.json.
+ *
+ * @param {string} packageJsonPath - Path to package.json
+ * @param {string[]} depNames - Dependency names to extract
+ * @returns {Record<string, string>} Dependency versions
+ */
+function getDependencyVersions(packageJsonPath, depNames) {
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    const versions = {}
+
+    for (const depName of depNames) {
+      const version = packageJson.dependencies?.[depName] || packageJson.devDependencies?.[depName]
+      if (version) {
+        versions[depName] = version
+      }
+    }
+
+    return versions
+  } catch (error) {
+    return {}
+  }
+}
+
+/**
+ * Generate a cache key for a package build.
+ *
+ * @param {object} options
+ * @param {string} options.nodeVersion - Node.js version (e.g., '24.10.0')
+ * @param {string} [options.platform] - Platform (defaults to current)
+ * @param {string} [options.arch] - Architecture (defaults to current)
+ * @param {string} options.packageVersion - Package version from package.json
+ * @param {string} [options.packageName] - Package name for dependency tracking (e.g., 'bootstrap', 'cli')
+ * @param {string} [options.packageJsonPath] - Path to package.json for dependency resolution
+ * @param {string[]} [options.contentFiles] - Files to hash for content-based invalidation
+ * @param {string[]} [options.cacheBustingDeps] - Override cache-busting dependencies
+ * @returns {string} Cache key
+ */
+export function generateCacheKey({
+  nodeVersion,
+  platform: targetPlatform = platform,
+  arch: targetArch = arch,
+  packageVersion,
+  packageName,
+  packageJsonPath,
+  contentFiles = [],
+  cacheBustingDeps,
+}) {
+  // Hash content files.
+  const hash = createHash('sha256')
+
+  for (const file of contentFiles) {
+    try {
+      const content = readFileSync(file, 'utf8')
+      hash.update(content)
+    } catch (error) {
+      // File doesn't exist - use filename in hash.
+      hash.update(file)
+    }
+  }
+
+  // Include cache-busting dependency versions.
+  const depsToCheck = cacheBustingDeps || (packageName ? CACHE_BUSTING_DEPS[packageName] : null)
+  if (depsToCheck && packageJsonPath) {
+    const depVersions = getDependencyVersions(packageJsonPath, depsToCheck)
+    // Sort for consistent hashing.
+    const sortedDeps = Object.keys(depVersions).sort()
+    for (const dep of sortedDeps) {
+      hash.update(`${dep}@${depVersions[dep]}`)
+    }
+  }
+
+  const contentHash = hash.digest('hex').slice(0, 8)
+
+  // Format: v{nodeVersion}-{arch}-{contentHash}-{pkgVersion}
+  return `v${nodeVersion}-${targetArch}-${contentHash}-${packageVersion.replace(/\./g, '')}`
+}
+
+/**
+ * Parse a cache key to extract components.
+ *
+ * @param {string} cacheKey
+ * @returns {object|null}
+ */
+export function parseCacheKey(cacheKey) {
+  const match = cacheKey.match(/^v([\d.]+)-(\w+)-([a-f0-9]+)-(\d+)$/)
+  if (!match) return null
+
+  return {
+    nodeVersion: match[1],
+    arch: match[2],
+    contentHash: match[3],
+    packageVersion: match[4].replace(/(\d)(\d)(\d)/, '$1.$2.$3'), // Restore dots.
+  }
+}
+
+/**
+ * Check if a cache key is still valid.
+ *
+ * @param {string} cacheKey
+ * @param {object} currentOptions - Current build options (same as generateCacheKey)
+ * @returns {boolean}
+ */
+export function isCacheValid(cacheKey, currentOptions) {
+  const parsed = parseCacheKey(cacheKey)
+  if (!parsed) return false
+
+  const currentKey = generateCacheKey(currentOptions)
+  return cacheKey === currentKey
+}

packages/build-infra/package.json

@@ -12,6 +12,7 @@
     "./lib/cmake-builder": "./lib/cmake-builder.mjs",
     "./lib/emscripten-builder": "./lib/emscripten-builder.mjs",
     "./lib/esbuild-plugin-unicode-transform": "./lib/esbuild-plugin-unicode-transform.mjs",
+    "./lib/cache-key": "./lib/cache-key.mjs",
     "./lib/extraction-cache": "./lib/extraction-cache.mjs",
     "./lib/fetch-with-retry": "./lib/fetch-with-retry.mjs",
     "./lib/patch-validator": "./lib/patch-validator.mjs",

scripts/build-binaries.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Build Socket binaries (WASM, SEA, smol) without running tests.
+ *
+ * Usage:
+ *   pnpm run build:binaries              # All binaries
+ *   pnpm run build:binaries --wasm       # Just WASM
+ *   pnpm run build:binaries --sea        # Just SEA
+ *   pnpm run build:binaries --smol       # Just smol
+ *   pnpm run build:binaries --smol --sea # Multiple
+ */
+
+import { spawn } from 'node:child_process'
+import { parseArgs } from 'node:util'
+
+const { values } = parseArgs({
+  options: {
+    wasm: { type: 'boolean' },
+    sea: { type: 'boolean' },
+    smol: { type: 'boolean' },
+    dev: { type: 'boolean' },
+    prod: { type: 'boolean' },
+    clean: { type: 'boolean' },
+  },
+  strict: false,
+})
+
+// If no specific binary selected, build all.
+const buildAll = !values.wasm && !values.sea && !values.smol
+const buildWasm = buildAll || values.wasm
+const buildSea = buildAll || values.sea
+const buildSmol = buildAll || values.smol
+
+const tasks = []
+
+// Build bootstrap first (required for all binaries).
+console.log('\n🔨 Building bootstrap...\n')
+tasks.push({ name: 'bootstrap', cmd: 'pnpm', args: ['--filter', '@socketsecurity/bootstrap', 'run', 'build'] })
+
+// Build CLI (required for binaries).
+console.log('🔨 Building CLI...\n')
+tasks.push({ name: 'cli', cmd: 'pnpm', args: ['--filter', '@socketsecurity/cli', 'run', 'build'] })
+
+// Build WASM (slowest, optional).
+if (buildWasm) {
+  const wasmArgs = ['run', values.dev ? 'wasm:build:dev' : 'wasm:build']
+  console.log(`🔨 Building WASM ${values.dev ? '(dev mode)' : ''}...\n`)
+  tasks.push({ name: 'wasm', cmd: 'pnpm', args: wasmArgs })
+}
+
+// Build SEA binary.
+if (buildSea) {
+  const seaArgs = ['--filter', '@socketsecurity/node-sea-builder', 'run', 'build']
+  if (values.dev) seaArgs.push('--dev')
+  if (values.prod) seaArgs.push('--prod')
+  if (values.clean) seaArgs.push('--clean')
+  console.log('🔨 Building SEA binary...\n')
+  tasks.push({ name: 'sea', cmd: 'pnpm', args: seaArgs })
+}
+
+// Build smol binary.
+if (buildSmol) {
+  const smolArgs = ['--filter', '@socketsecurity/node-smol-builder', 'run', 'build']
+  if (values.dev) smolArgs.push('--dev')
+  if (values.prod) smolArgs.push('--prod')
+  if (values.clean) smolArgs.push('--clean')
+  console.log('🔨 Building smol binary...\n')
+  tasks.push({ name: 'smol', cmd: 'pnpm', args: smolArgs })
+}
+
+// Run tasks sequentially.
+async function runTask(task) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(task.cmd, task.args, {
+      stdio: 'inherit',
+      shell: true,
+    })
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve()
+      } else {
+        reject(new Error(`${task.name} build failed with code ${code}`))
+      }
+    })
+  })
+}
+
+(async () => {
+  const startTime = Date.now()
+
+  for (const task of tasks) {
+    try {
+      await runTask(task)
+    } catch (error) {
+      console.error(`\n❌ Build failed: ${error.message}`)
+      process.exit(1)
+    }
+  }
+
+  const duration = ((Date.now() - startTime) / 1000 / 60).toFixed(1)
+  console.log(`\n✅ All binaries built successfully in ${duration}m`)
+})()