refactor: convert Node.js module imports to lazy-loading pattern to avoid Webpack bundling issues

Replace direct imports of Node.js built-in modules (fs, path, os, crypto,
child_process, readline, async_hooks) with lazy-loading helper functions
that use non-'node:' prefixed require() calls. This prevents Webpack from
attempting to bundle Node.js built-ins when this library is used in browser
contexts.

Pattern used:
- Add private getter functions (getFs(), getPath(), etc.)
- Use non-'node:' prefixed require() to avoid Webpack errors
- Add /*@__NO_SIDE_EFFECTS__*/ and /*@__PURE__*/ annotations for tree-shaking
- Update all usage sites to call helpers instead of direct module references

Files converted:
- src/cover/code.ts (fs, path)
- src/dlx/cache.ts (crypto)
- src/dlx/manifest.ts (fs, path)
- src/env/rewire.ts (async_hooks)
- src/http-request.ts (fs - createWriteStream)
- src/ipc.ts (crypto, fs, path)
- src/packages/isolation.ts (fs, path)
- src/packages/licenses.ts (path)
- src/paths/socket.ts (os, path)
- src/process-lock.ts (fs)
- src/releases/github.ts (fs, path)
- src/releases/socket-btm.ts (fs)
- src/spawn.ts (path)
- src/stdio/mask.ts (child_process, readline)
- src/themes/context.ts (async_hooks)

Note: src/stdio/stdout.ts was not converted as it only imports the WriteStream
type, which doesn't require runtime code.

Author: jdalton

src/cover/code.ts

@@ -2,8 +2,6 @@
  * @fileoverview Code coverage utilities for parsing v8 coverage data.
  */
 
-import { promises as fs } from 'fs'
-
 import { readJson } from '../fs'
 import { isObjectObject } from '../objects'
 import { spawn } from '../spawn'
@@ -16,7 +14,21 @@ import type {
   V8FileCoverage,
 } from './types'
 
+let _fs: typeof import('node:fs') | undefined
 let _path: typeof import('node:path') | undefined
+/**
+ * Lazily load the fs module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getFs() {
+  if (_fs === undefined) {
+    // Use non-'node:' prefixed require to avoid Webpack errors.
+
+    _fs = /*@__PURE__*/ require('fs')
+  }
+  return _fs as typeof import('node:fs')
+}
 /**
  * Lazily load the path module to avoid Webpack errors.
  * @private
@@ -30,7 +42,6 @@ function getPath() {
   }
   return _path as typeof import('node:path')
 }
-
 /**
  * Get code coverage metrics from v8 coverage-final.json.
  *
@@ -55,7 +66,8 @@ export async function getCodeCoverage(
   }
 
   // Check if coverage file exists.
-  const coverageExists = await fs
+  const fs = getFs()
+  const coverageExists = await fs.promises
     .access(coveragePath)
     .then(() => true)
     .catch(() => false)
@@ -157,7 +169,6 @@ export async function getCodeCoverage(
     statements: calculateMetric(totals.statements),
   }
 }
-
 /**
  * Calculate coverage metric with percentage.
  */

src/dlx/cache.ts

@@ -1,6 +1,19 @@
 /** @fileoverview Cache key generation utilities for DLX package installations. */
 
-import { createHash } from 'node:crypto'
+let _crypto: typeof import('node:crypto') | undefined
+/**
+ * Lazily load the crypto module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getCrypto() {
+  if (_crypto === undefined) {
+    // Use non-'node:' prefixed require to avoid Webpack errors.
+
+    _crypto = /*@__PURE__*/ require('crypto')
+  }
+  return _crypto as typeof import('node:crypto')
+}
 
 /**
  * Generate a cache directory name using npm/npx approach.
@@ -27,5 +40,6 @@ import { createHash } from 'node:crypto'
  * npx hashes the package spec (name@version), not just name
  */
 export function generateCacheKey(spec: string): string {
-  return createHash('sha512').update(spec).digest('hex').substring(0, 16)
+  const crypto = getCrypto()
+  return crypto.createHash('sha512').update(spec).digest('hex').substring(0, 16)
 }

src/dlx/manifest.ts

@@ -25,9 +25,30 @@
  * - Rate limiting registry requests
  */
 
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'fs'
-import path from 'path'
-
+let _fs: typeof import('node:fs') | undefined
+let _path: typeof import('node:path') | undefined
+/**
+ * Lazily load the fs module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getFs() {
+  if (_fs === undefined) {
+    _fs = /*@__PURE__*/ require('fs')
+  }
+  return _fs as typeof import('node:fs')
+}
+/**
+ * Lazily load the path module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getPath() {
+  if (_path === undefined) {
+    _path = /*@__PURE__*/ require('path')
+  }
+  return _path as typeof import('node:path')
+}
 import { readFileUtf8Sync, safeMkdirSync } from '../fs'
 import { getDefaultLogger } from '../logger'
 import { getSocketDlxDir } from '../paths/socket'
@@ -52,7 +73,6 @@ export interface PackageDetails {
     latest_known: string
   }
 }
-
 /**
  * Details for binary download entries.
  */
@@ -67,7 +87,6 @@ export interface BinaryDetails {
     url: string
   }
 }
-
 export type ChecksumAlgorithm = 'sha256' | 'sha512'
 
 /**
@@ -80,7 +99,6 @@ export interface ManifestEntry {
   timestamp: number
   details: PackageDetails | BinaryDetails
 }
-
 /**
  * Type guard for package entries.
  */
@@ -89,7 +107,6 @@ export function isPackageEntry(
 ): entry is ManifestEntry & { details: PackageDetails } {
   return entry.type === 'package'
 }
-
 /**
  * Type guard for binary entries.
  */
@@ -98,7 +115,6 @@ export function isBinaryEntry(
 ): entry is ManifestEntry & { details: BinaryDetails } {
   return entry.type === 'binary'
 }
-
 /**
  * Legacy store record format (deprecated, for migration).
  */
@@ -107,14 +123,12 @@ export interface StoreRecord {
   timestampNotification: number
   version: string
 }
-
 export interface DlxManifestOptions {
   /**
    * Custom manifest file path (defaults to ~/.socket/_dlx/.dlx-manifest.json).
    */
   manifestPath?: string
 }
-
 /**
  * DLX manifest storage manager with atomic operations.
  * Supports both legacy format (package name keys) and new unified manifest format (spec keys).
@@ -125,7 +139,8 @@ export class DlxManifest {
 
   constructor(options: DlxManifestOptions = {}) {
     this.manifestPath =
-      options.manifestPath ?? path.join(getSocketDlxDir(), MANIFEST_FILE_NAME)
+      options.manifestPath ??
+      getPath().join(getSocketDlxDir(), MANIFEST_FILE_NAME)
     this.lockPath = `${this.manifestPath}.lock`
   }
 
@@ -134,7 +149,7 @@ export class DlxManifest {
    */
   private readManifest(): Record<string, ManifestEntry | StoreRecord> {
     try {
-      if (!existsSync(this.manifestPath)) {
+      if (!getFs().existsSync(this.manifestPath)) {
         return Object.create(null)
       }
 
@@ -240,7 +255,7 @@ export class DlxManifest {
     data: Record<string, ManifestEntry | StoreRecord>,
   ): Promise<void> {
     // Ensure directory exists.
-    const manifestDir = path.dirname(this.manifestPath)
+    const manifestDir = getPath().dirname(this.manifestPath)
     try {
       safeMkdirSync(manifestDir, { recursive: true })
     } catch (error) {
@@ -254,22 +269,22 @@ export class DlxManifest {
     const tempPath = `${this.manifestPath}.tmp`
 
     try {
-      writeFileSync(tempPath, content, 'utf8')
-      writeFileSync(this.manifestPath, content, 'utf8')
+      getFs().writeFileSync(tempPath, content, 'utf8')
+      getFs().writeFileSync(this.manifestPath, content, 'utf8')
 
       // Clean up temp file.
       try {
-        if (existsSync(tempPath)) {
-          unlinkSync(tempPath)
+        if (getFs().existsSync(tempPath)) {
+          getFs().unlinkSync(tempPath)
         }
       } catch {
         // Cleanup failed, not critical.
       }
     } catch (error) {
       // Clean up temp file on error.
       try {
-        if (existsSync(tempPath)) {
-          unlinkSync(tempPath)
+        if (getFs().existsSync(tempPath)) {
+          getFs().unlinkSync(tempPath)
         }
       } catch {
         // Best effort cleanup.
@@ -288,8 +303,8 @@ export class DlxManifest {
 
       // Read existing data.
       try {
-        if (existsSync(this.manifestPath)) {
-          const content = readFileSync(this.manifestPath, 'utf8')
+        if (getFs().existsSync(this.manifestPath)) {
+          const content = getFs().readFileSync(this.manifestPath, 'utf8')
           if (content.trim()) {
             data = JSON.parse(content) as Record<string, StoreRecord>
           }
@@ -304,7 +319,7 @@ export class DlxManifest {
       data[name] = record
 
       // Ensure directory exists.
-      const manifestDir = path.dirname(this.manifestPath)
+      const manifestDir = getPath().dirname(this.manifestPath)
       try {
         safeMkdirSync(manifestDir, { recursive: true })
       } catch (error) {
@@ -318,22 +333,22 @@ export class DlxManifest {
       const tempPath = `${this.manifestPath}.tmp`
 
       try {
-        writeFileSync(tempPath, content, 'utf8')
-        writeFileSync(this.manifestPath, content, 'utf8')
+        getFs().writeFileSync(tempPath, content, 'utf8')
+        getFs().writeFileSync(this.manifestPath, content, 'utf8')
 
         // Clean up temp file.
         try {
-          if (existsSync(tempPath)) {
-            unlinkSync(tempPath)
+          if (getFs().existsSync(tempPath)) {
+            getFs().unlinkSync(tempPath)
           }
         } catch {
           // Cleanup failed, not critical.
         }
       } catch (error) {
         // Clean up temp file on error.
         try {
-          if (existsSync(tempPath)) {
-            unlinkSync(tempPath)
+          if (getFs().existsSync(tempPath)) {
+            getFs().unlinkSync(tempPath)
           }
         } catch {
           // Best effort cleanup.
@@ -349,11 +364,11 @@ export class DlxManifest {
   async clear(name: string): Promise<void> {
     await processLock.withLock(this.lockPath, async () => {
       try {
-        if (!existsSync(this.manifestPath)) {
+        if (!getFs().existsSync(this.manifestPath)) {
           return
         }
 
-        const content = readFileSync(this.manifestPath, 'utf8')
+        const content = getFs().readFileSync(this.manifestPath, 'utf8')
         if (!content.trim()) {
           return
         }
@@ -362,7 +377,7 @@ export class DlxManifest {
         delete data[name]
 
         const updatedContent = JSON.stringify(data, null, 2)
-        writeFileSync(this.manifestPath, updatedContent, 'utf8')
+        getFs().writeFileSync(this.manifestPath, updatedContent, 'utf8')
       } catch (error) {
         logger.warn(
           `Failed to clear cache for ${name}: ${error instanceof Error ? error.message : String(error)}`,
@@ -377,8 +392,8 @@ export class DlxManifest {
   async clearAll(): Promise<void> {
     await processLock.withLock(this.lockPath, async () => {
       try {
-        if (existsSync(this.manifestPath)) {
-          unlinkSync(this.manifestPath)
+        if (getFs().existsSync(this.manifestPath)) {
+          getFs().unlinkSync(this.manifestPath)
         }
       } catch (error) {
         logger.warn(
@@ -405,7 +420,7 @@ export class DlxManifest {
    */
   getAllPackages(): string[] {
     try {
-      if (!existsSync(this.manifestPath)) {
+      if (!getFs().existsSync(this.manifestPath)) {
         return []
       }
 
@@ -429,6 +444,5 @@ export class DlxManifest {
     }
   }
 }
-
 // Export singleton instance using default manifest location.
 export const dlxManifest = new DlxManifest()

src/env/rewire.ts

@@ -9,14 +9,28 @@
  * - Thread-safe for concurrent test execution
  */
 
-import { AsyncLocalStorage } from 'async_hooks'
+let _async_hooks: typeof import('node:async_hooks') | undefined
+/**
+ * Lazily load the async_hooks module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getAsyncHooks() {
+  if (_async_hooks === undefined) {
+    // Use non-'node:' prefixed require to avoid Webpack errors.
+
+    _async_hooks = /*@__PURE__*/ require('async_hooks')
+  }
+  return _async_hooks as typeof import('node:async_hooks')
+}
 
 import { envAsBoolean } from './helpers'
 
 type EnvOverrides = Map<string, string | undefined>
 
 // Isolated execution context storage for nested overrides (withEnv/withEnvSync)
 // AsyncLocalStorage creates isolated contexts that don't leak between concurrent code
+const { AsyncLocalStorage } = getAsyncHooks()
 const isolatedOverridesStorage = new AsyncLocalStorage<EnvOverrides>()
 
 // Shared test hook overrides (setEnv/clearEnv/resetEnv in beforeEach/afterEach)

src/http-request.ts

@@ -14,7 +14,19 @@
  * - Zero dependencies on external HTTP libraries.
  */
 
-import { createWriteStream } from 'fs'
+let _fs: typeof import('node:fs') | undefined
+
+/**
+ * Lazily load the fs module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getFs() {
+  if (_fs === undefined) {
+    _fs = /*@__PURE__*/ require('fs')
+  }
+  return _fs as typeof import('node:fs')
+}
 
 import type { IncomingMessage } from 'http'
 
@@ -880,6 +892,8 @@ async function httpDownloadAttempt(
       timeout,
     }
 
+    const { createWriteStream } = getFs()
+
     let fileStream: ReturnType<typeof createWriteStream> | undefined
     let streamClosed = false