refactor: delete camelToKebab + dead types file; fix doc drift

Org-scan R4 #1: camelToKebab was a subset of toKebabCase (snake_case
support + more comprehensive acronym handling). Zero internal + zero
sibling-repo callers confirmed via grep. Deleted the function and its
tests (~130 LOC across src + test); updated toKebabCase JSDoc to drop
the now-defunct cross-reference.

Org-scan R4 #4: src/types/external-modules.d.ts was an ambient module
declaration for cacache/pacote/make-fetch-happen that shadowed the actual
typings already provided via tsconfig paths mapping to src/external/*.d.ts.
Deleted the file + empty src/types/ dir. One caller (provenance.ts) was
using the old ambient's shape for make-fetch-happen — switched its _fetcher
type annotation to ReturnType<typeof makeFetchHappen.defaults>.

Docs scan R4:
- README.md: setupIPC() doesn't exist; replaced with real exports
  (processLock.lock/unlock, writeIpcStub/getIpcStubPath)
- docs/process-utilities.md: rewrote ProcessLock class-style docs to
  match the actual processLock singleton API (acquire/release/withLock);
  replaced fictional setupIPC() section with docs for the two real IPC
  surfaces (ipc stub, ipc-cli env vars)
- docs/http-utilities.md: User-Agent default is SOCKET_LIB_USER_AGENT
  (socketsecurity-lib/<version>), not socket-registry/1.0;
  httpDownload options type is HttpDownloadOptions not HttpDownloadResult
- docs/visual-effects.md: Spinner({ spinner: 'dots' }) was wrong
  (SpinnerStyle is an object) — replaced with a getSpinner('dots') hint

Author: jdalton

README.md

@@ -97,8 +97,8 @@ Spawn child processes safely with cross-platform support.
 - `spawnSync()` - Synchronous version for blocking operations
 - Array-based arguments prevent command injection
 - Automatic Windows `.cmd`/`.bat` handling
-- `ProcessLock` - Ensure only one instance runs at a time
-- `setupIPC()` - Inter-process communication
+- `processLock.lock()` / `processLock.unlock()` - Ensure only one instance runs at a time
+- `writeIpcStub()` / `getIpcStubPath()` - Filesystem-based inter-process data handoff
 
 ### Environment Detection
 

docs/http-utilities.md

@@ -219,7 +219,7 @@ console.log(response.headers['location']) // Redirect target
 
 - `url` (string): The URL to download from
 - `destPath` (string): Path where file should be saved (absolute path recommended)
-- `options` (HttpDownloadResult): Download configuration
+- `options` (HttpDownloadOptions): Download configuration
 
 **Returns:** `Promise<HttpDownloadResult>` with `headers`, `ok`, `path`, `size`, `status`, and `statusText`
 
@@ -309,7 +309,7 @@ await httpJson('https://api.example.com/data', {
 })
 ```
 
-**Default:** Includes `User-Agent: socket-registry/1.0`
+**Default:** Includes `User-Agent: socketsecurity-lib/<version> (<url>)` (see `SOCKET_LIB_USER_AGENT` in `constants/socket`).
 
 ### body
 

docs/process-utilities.md

@@ -14,21 +14,16 @@ Spawn child processes, manage inter-process communication (IPC), handle process
 
 ```typescript
 import { spawn } from '@socketsecurity/lib/spawn'
-import { ProcessLock } from '@socketsecurity/lib/process-lock'
+import { processLock } from '@socketsecurity/lib/process-lock'
 
 // Run a command
 const result = await spawn('git', ['status'])
 console.log(result.stdout)
 
 // Ensure only one instance runs
-const lock = new ProcessLock('my-operation')
-if (await lock.acquire()) {
-  try {
-    await doWork()
-  } finally {
-    await lock.release()
-  }
-}
+await processLock.withLock('/tmp/my-operation.lock', async () => {
+  await doWork()
+})
 ```
 
 ## Spawning Processes
@@ -334,114 +329,109 @@ try {
 
 ## Process Locks
 
-### ProcessLock
+### processLock
 
-**What it does:** Ensures only one instance of an operation runs at a time.
+**What it does:** Filesystem-based advisory lock for ensuring only one process runs a critical section at a time.
 
 **When to use:** Preventing duplicate builds, ensuring atomic operations, coordinating between processes.
 
+The module exports a singleton `processLock` (type `ProcessLockManager`). There is NO `ProcessLock` constructor — use the singleton.
+
 **Example:**
 
 ```typescript
-import { ProcessLock } from '@socketsecurity/lib/process-lock'
+import { processLock } from '@socketsecurity/lib/process-lock'
 
-const lock = new ProcessLock('my-critical-operation')
+const lockPath = '/tmp/my-critical-operation.lock'
 
-if (await lock.acquire()) {
+const acquired = await processLock.acquire(lockPath)
+if (acquired) {
   try {
     // Do critical work that shouldn't run concurrently
     await buildProject()
   } finally {
-    // Always release in finally block
-    await lock.release()
+    processLock.release(lockPath)
   }
-} else {
-  console.log('Another process is running this operation')
 }
 ```
 
-### ProcessLock Methods
+### withLock (scoped helper)
 
-#### constructor(name, options?)
-
-Creates a new process lock.
+Prefer `withLock` for automatic release:
 
 ```typescript
-const lock = new ProcessLock('build-process', {
-  lockDir: '/tmp/locks', // Custom lock directory
-  timeout: 30000, // Timeout in ms
+import { processLock } from '@socketsecurity/lib/process-lock'
+
+await processLock.withLock('/tmp/build.lock', async () => {
+  await buildProject()
 })
 ```
 
-#### acquire()
+### processLock Methods
 
-Attempts to acquire the lock.
+#### acquire(lockPath, options?)
+
+Attempts to acquire the lock at `lockPath`. Returns `true` if acquired, `false` if another process holds it.
 
 ```typescript
-const acquired = await lock.acquire()
-if (acquired) {
-  // Lock acquired, do work
-}
+const acquired = await processLock.acquire('/tmp/my.lock', {
+  retries: 10, // retry up to 10 times
+  baseDelayMs: 100, // start retrying with 100ms backoff
+  staleMs: 60_000, // consider lock stale after 60s
+})
 ```
 
-Returns `true` if lock was acquired, `false` if another process holds it.
-
-#### release()
+#### release(lockPath)
 
-Releases the lock.
+Releases a lock previously acquired by this process. Always pair with `acquire` in a `finally` block, or use `withLock`.
 
 ```typescript
-await lock.release()
+processLock.release('/tmp/my.lock')
 ```
 
-Always call this in a `finally` block to ensure cleanup.
+#### withLock(lockPath, fn, options?)
 
-#### isLocked()
-
-Checks if the lock is currently held.
+Scoped helper — acquires the lock, runs `fn`, releases the lock even on error. Returns the value of `fn`.
 
 ```typescript
-if (await lock.isLocked()) {
-  console.log('Lock is held by another process')
-}
+const result = await processLock.withLock('/tmp/my.lock', async () => {
+  return await doWork()
+})
 ```
 
 ## Inter-Process Communication (IPC)
 
-### setupIPC()
-
-**What it does:** Sets up IPC channel for communication between parent and child processes.
+Two complementary IPC modules are provided:
 
-**When to use:** Sending messages between processes, coordinating work, passing data.
+### Filesystem stub IPC (`@socketsecurity/lib/ipc`)
 
-**Example:**
+For passing data between parent and child processes when the payload may exceed environment-variable size limits or needs restricted-perm (0o600) storage.
 
 ```typescript
-import { setupIPC } from '@socketsecurity/lib/ipc'
+import { writeIpcStub, getIpcStubPath } from '@socketsecurity/lib/ipc'
 
-// In parent process
-const child = spawn('node', ['worker.js'], {
-  stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-})
-
-setupIPC(child.process, {
-  onMessage: message => {
-    console.log('Received from child:', message)
+// Parent: write payload to stub file and pass path to child
+const stubPath = await writeIpcStub('socket-cli', {
+  apiToken: 'secret',
+  config: {
+    /* ... */
   },
 })
+spawn('node', ['child.js', stubPath])
 
-// Send to child
-child.process.send({ type: 'work', data: 'foo' })
+// Child: read the stub path from argv and load the JSON
+import { readFile } from 'node:fs/promises'
+const data = JSON.parse(await readFile(process.argv[2], 'utf8'))
+```
 
-// In child (worker.js)
-setupIPC(process, {
-  onMessage: message => {
-    if (message.type === 'work') {
-      const result = doWork(message.data)
-      process.send({ type: 'result', value: result })
-    }
-  },
-})
+### CLI env-var IPC (`@socketsecurity/lib/ipc-cli`)
+
+For reading `SOCKET_CLI_*` environment variables forwarded by a parent Socket CLI.
+
+```typescript
+import { getIpc } from '@socketsecurity/lib/ipc-cli'
+
+const { SOCKET_CLI_FIX, SOCKET_CLI_OPTIMIZE } = await getIpc()
 ```
 
 ## Real-World Examples

docs/visual-effects.md

@@ -35,8 +35,9 @@ import { Spinner } from '@socketsecurity/lib/spinner'
 const spinner = Spinner({
   text: 'Loading data...',
   color: [140, 82, 255], // Socket purple RGB
-  spinner: 'dots', // Animation style
 })
+// Use a preset animation by name via getSpinner('dots'):
+// const spinner = Spinner({ spinner: getSpinner('dots') })
 ```
 
 **What it does:** Creates an animated CLI spinner with custom text, colors, and animation style.

src/packages/provenance.ts

@@ -21,7 +21,7 @@ const ArrayIsArray = Array.isArray
 const SLSA_PROVENANCE_V0_2 = 'https://slsa.dev/provenance/v0.2'
 const SLSA_PROVENANCE_V1_0 = 'https://slsa.dev/provenance/v1'
 
-let _fetcher: typeof import('make-fetch-happen') | undefined
+let _fetcher: ReturnType<typeof makeFetchHappen.defaults> | undefined
 
 /**
  * Find the first attestation with valid provenance data.
@@ -98,7 +98,7 @@ function getFetcher() {
       cache: 'force-cache',
     })
   }
-  return _fetcher as typeof import('make-fetch-happen')
+  return _fetcher
 }
 
 /**

src/strings.ts

@@ -82,84 +82,6 @@ export function applyLinePrefix(
     : str
 }
 
-/**
- * Convert a camelCase string to kebab-case.
- *
- * Transforms camelCase strings by converting uppercase letters to lowercase
- * and inserting hyphens before uppercase sequences. Handles consecutive
- * uppercase letters (like "XMLHttpRequest") by treating them as a single word.
- * Returns empty string for empty input.
- *
- * Note: This function only handles camelCase. For mixed formats including
- * snake_case, use `toKebabCase()` instead.
- *
- * @param str - The camelCase string to convert
- * @returns The kebab-case string
- *
- * @example
- * ```ts
- * camelToKebab('helloWorld')
- * // Returns: 'hello-world'
- *
- * camelToKebab('XMLHttpRequest')
- * // Returns: 'xmlhttp-request'
- *
- * camelToKebab('iOS')
- * // Returns: 'i-os'
- *
- * camelToKebab('')
- * // Returns: ''
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export function camelToKebab(str: string): string {
-  const { length } = str
-  if (!length) {
-    return ''
-  }
-  let result = ''
-  let i = 0
-  while (i < length) {
-    const char = str[i]
-    if (!char) {
-      break
-    }
-    const charCode = char.charCodeAt(0)
-    // Check if current character is uppercase letter.
-    // A = 65, Z = 90
-    const isUpperCase = charCode >= 65 /*'A'*/ && charCode <= 90 /*'Z'*/
-    if (isUpperCase) {
-      // Add dash before uppercase sequence (except at start).
-      if (result.length > 0) {
-        result += '-'
-      }
-      // Collect all consecutive uppercase letters.
-      while (i < length) {
-        const currChar = str[i]
-        if (!currChar) {
-          break
-        }
-        const currCharCode = currChar.charCodeAt(0)
-        const isCurrUpper =
-          currCharCode >= 65 /*'A'*/ && currCharCode <= 90 /*'Z'*/
-        if (isCurrUpper) {
-          // Convert uppercase to lowercase: subtract 32 (A=65 -> a=97, diff=32)
-          result += fromCharCode(currCharCode + 32 /*'a'-'A'*/)
-          i += 1
-        } else {
-          // Stop when we hit non-uppercase.
-          break
-        }
-      }
-    } else {
-      // Handle lowercase letters, digits, and other characters.
-      result += char
-      i += 1
-    }
-  }
-  return result
-}
-
 /**
  * Center text within a given width.
  *
@@ -800,8 +722,8 @@ export function stripBom(str: string): string {
  * - Inserting hyphens before uppercase letters (for camelCase)
  * - Replacing underscores with hyphens (for snake_case)
  *
- * This is more comprehensive than `camelToKebab()` as it handles mixed
- * formats including snake_case. Returns empty string for empty input.
+ * Handles mixed formats (camelCase, snake_case, acronyms) in one pass.
+ * Returns empty string for empty input.
  *
  * @param str - The string to convert
  * @returns The kebab-case string