feat(process-lock): add general-purpose inter-process locking

Add process-lock module for cross-platform inter-process synchronization using
file-system based locks. Inspired by npm's withLock mechanism.

Features:
- Atomic lock acquisition using mkdir (POSIX standard)
- Stale lock detection and cleanup (10 second default, aligned with npm)
- Automatic process exit cleanup
- Exponential backoff retry strategy
- Cross-platform network filesystem compatibility

Includes comprehensive unit tests covering:
- Lock acquisition and release
- Stale lock handling
- Concurrent operations
- Error handling
- withLock convenience method

Author: jdalton

biome.json

@@ -78,7 +78,7 @@
         "useNumberNamespace": "error",
         "noInferrableTypes": "off",
         "noUselessElse": "error",
-        "useNumericSeparators": "error"
+        "useNumericSeparators": "off"
       },
       "suspicious": {
         "noExplicitAny": "off",

package.json

@@ -384,6 +384,10 @@
       "types": "./plugins/babel-plugin-inline-require-calls.d.ts",
       "default": "./plugins/babel-plugin-inline-require-calls.js"
     },
+    "./process-lock": {
+      "types": "./dist/process-lock.d.ts",
+      "default": "./dist/process-lock.js"
+    },
     "./promise-queue": {
       "types": "./dist/promise-queue.d.ts",
       "default": "./dist/promise-queue.js"

src/process-lock.ts

@@ -0,0 +1,271 @@
+/**
+ * Process locking utilities for cross-platform inter-process synchronization.
+ * Provides exclusive file-system based locks without external dependencies.
+ *
+ * This implementation is inspired by npm's withLock mechanism, using mkdir's
+ * atomic properties for lock acquisition. It includes stale lock detection,
+ * automatic cleanup on process exit, and exponential backoff retry strategy.
+ *
+ * Key Features:
+ * - Atomic lock acquisition using mkdir (POSIX standard)
+ * - Stale lock detection and cleanup (10 second default)
+ * - Automatic process exit cleanup
+ * - Exponential backoff retry strategy
+ * - Cross-platform network filesystem compatibility
+ *
+ * Usage:
+ * ```typescript
+ * import { processLock } from '@socketsecurity/lib/process-lock'
+ *
+ * // Acquire and release manually
+ * const release = await processLock.acquire('/path/to/lock')
+ * try {
+ *   // Critical section
+ * } finally {
+ *   release()
+ * }
+ *
+ * // Or use withLock for automatic management
+ * await processLock.withLock('/path/to/lock', async () => {
+ *   // Critical section
+ * })
+ * ```
+ *
+ * @module process-lock
+ */
+
+import { existsSync, mkdirSync, statSync } from 'node:fs'
+
+import { safeDeleteSync } from './fs'
+import { logger } from './logger'
+import { pRetry } from './promises'
+import { onExit } from './signal-exit'
+
+/**
+ * Lock acquisition options.
+ */
+export interface ProcessLockOptions {
+  /**
+   * Maximum number of retry attempts.
+   * @default 3
+   */
+  retries?: number | undefined
+  /**
+   * Base delay between retries in milliseconds.
+   * @default 100
+   */
+  baseDelayMs?: number | undefined
+  /**
+   * Maximum delay between retries in milliseconds.
+   * @default 1000
+   */
+  maxDelayMs?: number | undefined
+  /**
+   * Stale lock timeout in milliseconds.
+   * Locks older than this are considered abandoned and can be reclaimed.
+   * Aligned with npm's npx locking strategy (5-10 seconds).
+   * @default 10000 (10 seconds)
+   */
+  staleMs?: number | undefined
+}
+
+/**
+ * Process lock manager with stale detection and exit cleanup.
+ * Provides cross-platform inter-process synchronization using file-system
+ * based locks.
+ */
+class ProcessLockManager {
+  private activeLocks = new Set<string>()
+  private exitHandlerRegistered = false
+
+  /**
+   * Ensure process exit handler is registered for cleanup.
+   * Registers a handler that cleans up all active locks when the process exits.
+   */
+  private ensureExitHandler(): void {
+    if (this.exitHandlerRegistered) {
+      return
+    }
+
+    onExit(() => {
+      // Clean up all active locks on exit.
+      for (const lockPath of this.activeLocks) {
+        try {
+          if (existsSync(lockPath)) {
+            // Lock paths are typically in system temp or user directories.
+            // Force flag may be needed depending on lock location.
+            safeDeleteSync(lockPath, { recursive: true })
+          }
+        } catch {
+          // Best effort cleanup - don't throw on exit.
+        }
+      }
+    })
+
+    this.exitHandlerRegistered = true
+  }
+
+  /**
+   * Check if a lock is stale based on mtime.
+   * A lock is considered stale if it's older than the specified timeout,
+   * indicating the holding process likely died abnormally.
+   *
+   * @param lockPath - Path to the lock directory
+   * @param staleMs - Stale timeout in milliseconds
+   * @returns True if lock exists and is stale
+   */
+  private isStale(lockPath: string, staleMs: number): boolean {
+    try {
+      if (!existsSync(lockPath)) {
+        return false
+      }
+
+      const stats = statSync(lockPath)
+      const age = Date.now() - stats.mtime.getTime()
+      return age > staleMs
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Acquire a lock using mkdir for atomic operation.
+   * Handles stale locks and includes exit cleanup.
+   *
+   * This method attempts to create a lock directory atomically. If the lock
+   * already exists, it checks if it's stale and removes it before retrying.
+   * Uses exponential backoff with jitter for retry attempts.
+   *
+   * @param lockPath - Path to the lock directory
+   * @param options - Lock acquisition options
+   * @returns Release function to unlock
+   * @throws Error if lock cannot be acquired after all retries
+   *
+   * @example
+   * ```typescript
+   * const release = await processLock.acquire('/tmp/my-lock')
+   * try {
+   *   // Critical section
+   * } finally {
+   *   release()
+   * }
+   * ```
+   */
+  async acquire(
+    lockPath: string,
+    options: ProcessLockOptions = {},
+  ): Promise<() => void> {
+    const {
+      baseDelayMs = 100,
+      maxDelayMs = 1_000,
+      retries = 3,
+      staleMs = 10_000,
+    } = options
+
+    this.ensureExitHandler()
+
+    return (await pRetry(
+      async () => {
+        try {
+          // Check for stale locks and remove them.
+          if (existsSync(lockPath) && this.isStale(lockPath, staleMs)) {
+            logger.log(`Removing stale lock: ${lockPath}`)
+            try {
+              safeDeleteSync(lockPath, { recursive: true })
+            } catch {
+              // If we can't remove it, someone else might be using it.
+            }
+          }
+
+          // Use mkdir for atomic lock creation - will fail if already exists.
+          mkdirSync(lockPath, { recursive: false })
+
+          // Track for cleanup.
+          this.activeLocks.add(lockPath)
+
+          // Return release function.
+          return () => this.release(lockPath)
+        } catch (error) {
+          if (error instanceof Error && (error as any).code === 'EEXIST') {
+            // Lock already exists, check if stale.
+            if (this.isStale(lockPath, staleMs)) {
+              // Stale lock detected, will be handled on next retry.
+              throw new Error(`Stale lock detected: ${lockPath}`)
+            }
+            throw new Error(`Lock already exists: ${lockPath}`)
+          }
+          // Other errors are permanent.
+          throw error
+        }
+      },
+      {
+        retries,
+        baseDelayMs,
+        maxDelayMs,
+        jitter: true,
+      },
+    )) as () => void
+  }
+
+  /**
+   * Release a lock and remove from tracking.
+   * Removes the lock directory and stops tracking it for exit cleanup.
+   *
+   * @param lockPath - Path to the lock directory
+   *
+   * @example
+   * ```typescript
+   * processLock.release('/tmp/my-lock')
+   * ```
+   */
+  release(lockPath: string): void {
+    try {
+      if (existsSync(lockPath)) {
+        safeDeleteSync(lockPath, { recursive: true })
+      }
+      this.activeLocks.delete(lockPath)
+    } catch (error) {
+      logger.warn(
+        `Failed to release lock ${lockPath}: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
+  /**
+   * Execute a function with exclusive lock protection.
+   * Automatically handles lock acquisition, execution, and cleanup.
+   *
+   * This is the recommended way to use process locks, as it guarantees
+   * cleanup even if the callback throws an error.
+   *
+   * @param lockPath - Path to the lock directory
+   * @param fn - Function to execute while holding the lock
+   * @param options - Lock acquisition options
+   * @returns Result of the callback function
+   * @throws Error from callback or lock acquisition failure
+   *
+   * @example
+   * ```typescript
+   * const result = await processLock.withLock('/tmp/my-lock', async () => {
+   *   // Critical section
+   *   return someValue
+   * })
+   * ```
+   */
+  async withLock<T>(
+    lockPath: string,
+    fn: () => Promise<T>,
+    options?: ProcessLockOptions,
+  ): Promise<T> {
+    const release = await this.acquire(lockPath, options)
+
+    try {
+      return await fn()
+    } finally {
+      release()
+    }
+  }
+}
+
+// Export singleton instance.
+export const processLock = new ProcessLockManager()