feat(build): add stub system for external dependencies

Add organized stub infrastructure to reduce external bundle sizes:
- Create scripts/build-externals/stubs/ directory
- Add utility stubs (empty.cjs, noop.cjs, throw.cjs)
- Add active stubs (encoding.cjs, debug.cjs)
- Integrate stubs into esbuild config via createStubPlugin()
- Document stub system with philosophy and usage

Conservative approach: Only stub provably unused dependencies.

Active stubs save ~18KB:
- encoding/iconv-lite: ~9KB (UTF-8 only)
- debug: ~9KB (already compiled out)

Author: jdalton

scripts/build-externals/esbuild-config.mjs

@@ -2,6 +2,59 @@
  * @fileoverview esbuild configuration for external package bundling.
  */
 
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const stubsDir = path.join(__dirname, 'stubs')
+
+/**
+ * Stub configuration - maps module patterns to stub files.
+ * Only includes conservative stubs that are safe to use.
+ */
+const STUB_MAP = {
+  // Character encoding - we only use UTF-8
+  '^(encoding|iconv-lite)$': 'encoding.cjs',
+
+  // Debug logging - already disabled via process.env.DEBUG = undefined
+  '^debug$': 'debug.cjs',
+}
+
+/**
+ * Create esbuild plugin to stub modules using files from stubs/ directory.
+ *
+ * @param {Record<string, string>} stubMap - Map of regex patterns to stub filenames
+ * @returns {import('esbuild').Plugin}
+ */
+function createStubPlugin(stubMap = STUB_MAP) {
+  // Pre-compile regex patterns and load stub contents
+  const stubs = Object.entries(stubMap).map(([pattern, filename]) => ({
+    filter: new RegExp(pattern),
+    contents: readFileSync(path.join(stubsDir, filename), 'utf8'),
+    stubFile: filename,
+  }))
+
+  return {
+    name: 'stub-modules',
+    setup(build) {
+      for (const { contents, filter, stubFile } of stubs) {
+        // Resolve: mark modules as stubbed
+        build.onResolve({ filter }, args => ({
+          path: args.path,
+          namespace: `stub:${stubFile}`,
+        }))
+
+        // Load: return stub file contents
+        build.onLoad({ filter: /.*/, namespace: `stub:${stubFile}` }, () => ({
+          contents,
+          loader: 'js',
+        }))
+      }
+    },
+  }
+}
+
 /**
  * Get package-specific esbuild options.
  *
@@ -81,23 +134,7 @@ export function getEsbuildConfig(entryPoint, outfile, packageOpts = {}) {
       '@socketsecurity/registry',
       ...(packageOpts.external || []),
     ],
-    plugins: [
-      {
-        name: 'stub-encoding',
-        setup(build) {
-          // Stub out encoding and iconv-lite packages.
-          build.onResolve({ filter: /^(encoding|iconv-lite)$/ }, args => ({
-            path: args.path,
-            namespace: 'stub-encoding',
-          }))
-
-          build.onLoad({ filter: /.*/, namespace: 'stub-encoding' }, () => ({
-            contents: 'module.exports = {};',
-            loader: 'js',
-          }))
-        },
-      },
-    ],
+    plugins: [createStubPlugin()],
     minify: true,
     sourcemap: false,
     metafile: true,

scripts/build-externals/stubs/README.md

@@ -0,0 +1,72 @@
+# External Dependency Stubs
+
+This directory contains stub modules used during the external package bundling process to replace unused dependencies and reduce bundle size.
+
+**Philosophy:** Be conservative. Only stub dependencies that are provably unused or already disabled.
+
+## How It Works
+
+The build-externals system bundles external npm dependencies (like pacote, cacache, make-fetch-happen) into standalone modules in `dist/external/`. During bundling, esbuild uses the stubs in this directory to replace dependencies we don't need.
+
+The stub configuration lives in `../esbuild-config.mjs`, which maps module patterns to stub files:
+
+```javascript
+const STUB_MAP = {
+  '^(encoding|iconv-lite)$': 'encoding.cjs',
+  '^debug$': 'debug.cjs',
+}
+```
+
+When esbuild encounters `require('encoding')` during bundling, it replaces it with the contents of `encoding.cjs` instead of bundling the entire encoding package.
+
+## Stub Types
+
+This directory provides both active stubs (currently in use) and utility stubs (available for future use):
+
+### Utility Stubs (Available for Use)
+
+**`empty.cjs`** - Empty object for unused modules
+- Exports: `{}`
+- Use case: Dependencies referenced but never executed
+
+**`noop.cjs`** - No-op function for optional features
+- Exports: Function that does nothing
+- Use case: Logging, debugging, optional callbacks
+
+**`throw.cjs`** - Error-throwing for unexpected usage
+- Exports: Function that throws descriptive error
+- Use case: Code paths that should never execute
+
+### Active Stubs (Currently in Use)
+
+**`encoding.cjs`** - Character encoding stub
+- Replaces: `encoding`, `iconv-lite`
+- Reason: We only use UTF-8, don't need legacy encoding support
+- Size impact: ~9KB saved (pacote, make-fetch-happen)
+
+**`debug.cjs`** - Debug logging stub
+- Replaces: `debug` module
+- Reason: Already compiled out via `process.env.DEBUG = undefined`
+- Size impact: ~9KB saved
+
+## Adding New Stubs
+
+**Before adding a stub:**
+1. Verify the dependency is truly unused via code analysis
+2. Check if it's already disabled via esbuild `define` constants
+3. Consider the risk - conservative only!
+
+**To add a stub:**
+1. Create stub file in this directory
+2. Document what it replaces and why it's safe
+3. Add entry to `STUB_MAP` in `../esbuild-config.mjs`
+4. Test: `pnpm build && pnpm test`
+5. Verify size savings: `du -sh dist/external`
+
+## Testing Stubs
+
+After adding stubs, verify:
+1. Build succeeds: `pnpm build`
+2. Tests pass: `pnpm test`
+3. No runtime errors in dependent packages
+4. Bundle size decreased as expected

scripts/build-externals/stubs/debug.cjs

@@ -0,0 +1,24 @@
+/**
+ * Debug stub - stubs out debug logging.
+ *
+ * Many npm packages include debug() calls for verbose logging.
+ * In production, these are disabled via process.env.DEBUG.
+ * This stub removes the debug module entirely.
+ *
+ * Used by: Various npm packages
+ * Savings: ~9KB + removes debug dependency checks
+ */
+'use strict'
+
+// Return a no-op function that accepts any arguments
+function debug() {
+  return function noop() {}
+}
+
+// Common debug properties
+debug.enabled = false
+debug.names = []
+debug.skips = []
+debug.formatters = {}
+
+module.exports = debug

scripts/build-externals/stubs/empty.cjs

@@ -0,0 +1,7 @@
+/**
+ * Empty stub - provides no functionality.
+ * Used for dependencies that are never actually called in our code paths.
+ */
+'use strict'
+
+module.exports = {}

scripts/build-externals/stubs/encoding.cjs

@@ -0,0 +1,11 @@
+/**
+ * Encoding/iconv-lite stub.
+ *
+ * These packages provide character encoding conversion (e.g., UTF-8 to Latin1).
+ * We only work with UTF-8, so we stub them out to save ~100KB.
+ *
+ * Used by: make-fetch-happen, pacote (for legacy content-encoding)
+ */
+'use strict'
+
+module.exports = {}

scripts/build-externals/stubs/noop.cjs

@@ -0,0 +1,10 @@
+/**
+ * No-op stub - provides functions that do nothing.
+ * Used for optional features we don't need (logging, debugging, etc).
+ */
+'use strict'
+
+const noop = () => {}
+
+module.exports = noop
+module.exports.default = noop

scripts/build-externals/stubs/throw.cjs

@@ -0,0 +1,15 @@
+/**
+ * Throw stub - errors if called.
+ * Used for dependencies that should never be reached in production.
+ * Helps catch bugs if accidentally called.
+ */
+'use strict'
+
+function throwStub(moduleName) {
+  throw new Error(
+    `Module '${moduleName}' is stubbed and should not be called. ` +
+      'This is likely a bundling error or unexpected code path.',
+  )
+}
+
+module.exports = throwStub