test(coverage): cover catch-branch error paths across 4 files (Push #2 P1)

Per "test them, don't dismiss them" feedback — the previous push punted
on defensive catch branches as "low ROI". This lands targeted unit
tests that mock the helper functions (`safeDelete[Sync]`, `safeMkdirSync`,
`readFileUtf8Sync`, `cacache.safeGet`/`remove`) so the SUT's catch
handlers actually fire under realistic failure modes.

New test files (+22 tests):
- test/unit/dlx/packages-errors.test.mts (8 tests). dlx/packages.ts: 71.4% → 96.4%.
- test/unit/dlx/manifest-errors.test.mts (6 tests). dlx/manifest.ts: 86.0% → 88.8%.
- test/unit/process-lock-errors.test.mts (3 tests). process-lock.ts: 86.7% → 87.8%.
- test/unit/cache-with-ttl-errors.test.mts (5 tests). cache-with-ttl.ts: 89.9% → 94.9%.

Also adds test/unit/utils/fs-error-helper.ts: a path-scoped fs spy
helper for future tests that need errno-typed errors injected at the
underlying fs op rather than at the helper layer.

Project: 90.09% → 90.29% lines, 80.22% → 80.35% branches, 95.40% →
95.48% functions across 6875 passing tests (+22).

Author: jdalton

test/unit/cache-with-ttl-errors.test.mts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Tests for catch branches in src/cache-with-ttl.ts that
+ * fire when persistent-cache reads or writes fail. Mocks the cacache
+ * helpers (`safeGet`, `remove`, `safePut`) so the SUT exercises the
+ * try/catch around JSON.parse and cacache.remove.
+ */
+
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { createTtlCache } from '../../src/cache-with-ttl'
+import { resetEnv, setEnv } from '../../src/env/rewire'
+import { invalidateCaches } from '../../src/paths/rewire'
+
+import * as cacacheModule from '../../src/cacache'
+
+vi.mock('../../src/cacache', async importOriginal => {
+  const original = await importOriginal<typeof import('../../src/cacache')>()
+  return {
+    ...original,
+    safeGet: vi.fn(original.safeGet),
+    remove: vi.fn(original.remove),
+  }
+})
+
+describe.sequential('cache-with-ttl — error branches', () => {
+  let testCacheDir: string
+
+  beforeEach(() => {
+    invalidateCaches()
+    testCacheDir = path.join(
+      tmpdir(),
+      `socket-cache-err-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    )
+    setEnv('SOCKET_CACACHE_DIR', testCacheDir)
+    vi.mocked(cacacheModule.safeGet).mockClear()
+    vi.mocked(cacacheModule.remove).mockClear()
+  })
+
+  afterEach(async () => {
+    vi.restoreAllMocks()
+    resetEnv()
+    invalidateCaches()
+  })
+
+  describe('get() — corrupted entry path', () => {
+    it('returns undefined when cached JSON is malformed', async () => {
+      const cache = createTtlCache({
+        ttl: 60_000,
+        prefix: 'corrupt',
+        memoize: false,
+      })
+      // Return a valid cacache entry shape with malformed JSON in data.
+      vi.mocked(cacacheModule.safeGet).mockResolvedValueOnce({
+        data: Buffer.from('this is not valid json{{{', 'utf8'),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any)
+      const result = await cache.get('any-key')
+      expect(result).toBeUndefined()
+      // The catch branch attempts to remove the corrupt entry.
+      expect(cacacheModule.remove).toHaveBeenCalled()
+    })
+
+    it('swallows remove errors during corrupted-entry cleanup', async () => {
+      const cache = createTtlCache({
+        ttl: 60_000,
+        prefix: 'corrupt-rm-fail',
+        memoize: false,
+      })
+      vi.mocked(cacacheModule.safeGet).mockResolvedValueOnce({
+        data: Buffer.from('garbage', 'utf8'),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any)
+      vi.mocked(cacacheModule.remove).mockRejectedValueOnce(
+        new Error('rm-failed'),
+      )
+      // Even with rm failing, get() must still return undefined cleanly.
+      await expect(cache.get('any-key')).resolves.toBeUndefined()
+    })
+  })
+
+  describe('get() — expired entry path', () => {
+    it('returns undefined and attempts removal when entry is expired', async () => {
+      const cache = createTtlCache({
+        ttl: 60_000,
+        prefix: 'expired',
+        memoize: false,
+      })
+      // Build a TtlCacheEntry shape with expiresAt in the past.
+      const expiredEntry = {
+        data: 'value',
+        expiresAt: Date.now() - 10_000,
+      }
+      vi.mocked(cacacheModule.safeGet).mockResolvedValueOnce({
+        data: Buffer.from(JSON.stringify(expiredEntry), 'utf8'),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any)
+      const result = await cache.get('expired-key')
+      expect(result).toBeUndefined()
+      expect(cacacheModule.remove).toHaveBeenCalled()
+    })
+
+    it('swallows remove errors during expired-entry cleanup', async () => {
+      const cache = createTtlCache({
+        ttl: 60_000,
+        prefix: 'expired-rm-fail',
+        memoize: false,
+      })
+      const expiredEntry = {
+        data: 'value',
+        expiresAt: Date.now() - 10_000,
+      }
+      vi.mocked(cacacheModule.safeGet).mockResolvedValueOnce({
+        data: Buffer.from(JSON.stringify(expiredEntry), 'utf8'),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any)
+      vi.mocked(cacacheModule.remove).mockRejectedValueOnce(
+        new Error('rm-failed-2'),
+      )
+      await expect(cache.get('expired-key')).resolves.toBeUndefined()
+    })
+  })
+
+  describe('isExpired() — clock-skew detection', () => {
+    it('treats far-future expiresAt as expired (clock-skew defense)', async () => {
+      const cache = createTtlCache({
+        ttl: 60_000,
+        prefix: 'skew',
+        memoize: false,
+      })
+      // expiresAt more than ttl + 10s past now → looks malformed.
+      const skewedEntry = {
+        data: 'should-be-rejected',
+        // 10 minutes in the future, well past ttl + skew window
+        expiresAt: Date.now() + 600_000,
+      }
+      vi.mocked(cacacheModule.safeGet).mockResolvedValueOnce({
+        data: Buffer.from(JSON.stringify(skewedEntry), 'utf8'),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any)
+      const result = await cache.get('skew-key')
+      expect(result).toBeUndefined()
+    })
+  })
+})

test/unit/dlx/manifest-errors.test.mts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Tests for catch branches in src/dlx/manifest.ts that
+ * fire when filesystem ops fail (safeMkdirSync / safeDeleteSync /
+ * readFileUtf8Sync / fs.writeFileSync / fs.renameSync).
+ *
+ * Mocks the resolved helper exports so the SUT's call surfaces the
+ * intended failure and exercises the corresponding catch / cleanup
+ * paths.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { DlxManifest } from '../../../src/dlx/manifest'
+
+import {
+  readFileUtf8Sync,
+  safeDeleteSync,
+  safeMkdirSync,
+} from '../../../src/fs'
+
+vi.mock('../../../src/fs', async importOriginal => {
+  const original = await importOriginal<typeof import('../../../src/fs')>()
+  return {
+    ...original,
+    readFileUtf8Sync: vi.fn(original.readFileUtf8Sync),
+    safeDeleteSync: vi.fn(original.safeDeleteSync),
+    safeMkdirSync: vi.fn(original.safeMkdirSync),
+  }
+})
+
+function makeFsError(code: string): Error {
+  const e = new Error(`simulated ${code}`) as Error & { code: string }
+  e.code = code
+  return e
+}
+
+describe.sequential('dlx/manifest — error branches', () => {
+  let testDir: string
+  let manifestPath: string
+  let manifest: DlxManifest
+
+  beforeEach(() => {
+    testDir = path.join(tmpdir(), `socket-manifest-err-${randomUUID()}`)
+    mkdirSync(testDir, { recursive: true })
+    manifestPath = path.join(testDir, '.dlx-manifest.json')
+    manifest = new DlxManifest({ manifestPath })
+    vi.mocked(readFileUtf8Sync).mockClear()
+    vi.mocked(safeDeleteSync).mockClear()
+    vi.mocked(safeMkdirSync).mockClear()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('readManifest catch path', () => {
+    it('returns empty object when readFileUtf8Sync throws', () => {
+      // First seed a real manifest so existsSync passes.
+      writeFileSync(manifestPath, '{}', 'utf8')
+      vi.mocked(readFileUtf8Sync).mockImplementationOnce(() => {
+        throw makeFsError('EACCES')
+      })
+      // getAllPackages calls readManifest under the hood and swallows.
+      const result = manifest.getAllPackages()
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('clear() catch path', () => {
+    it('warns and returns when reading the manifest fails', async () => {
+      writeFileSync(manifestPath, '{"pkg-a":{}}', 'utf8')
+      vi.mocked(readFileUtf8Sync).mockImplementationOnce(() => {
+        throw makeFsError('EACCES')
+      })
+      // Should not throw — the catch swallows and warns.
+      await expect(manifest.clear('pkg-a')).resolves.toBeUndefined()
+    })
+  })
+
+  describe('clearAll() catch path', () => {
+    it('warns when safeDeleteSync fails', async () => {
+      writeFileSync(manifestPath, '{}', 'utf8')
+      vi.mocked(safeDeleteSync).mockImplementationOnce(() => {
+        throw makeFsError('EPERM')
+      })
+      await expect(manifest.clearAll()).resolves.toBeUndefined()
+    })
+  })
+
+  describe('set() catch paths', () => {
+    it('continues when readFileSync of existing manifest is malformed JSON', async () => {
+      // Write malformed JSON: the read succeeds but JSON.parse throws,
+      // exercising the catch branch that warns and treats as empty.
+      writeFileSync(manifestPath, 'not-valid-json', 'utf8')
+      const record = {
+        timestampFetch: Date.now(),
+        latestVersion: '1.0.0',
+      }
+      // Even with the malformed file on disk, set() should succeed
+      // (catches the parse error, treats as empty, writes its single
+      // entry). No throw is the assertion.
+      await expect(
+        manifest.set('pkg', record as never),
+      ).resolves.toBeUndefined()
+    })
+
+    it('warns and continues when safeMkdirSync fails', async () => {
+      vi.mocked(safeMkdirSync).mockImplementationOnce(() => {
+        throw makeFsError('EACCES')
+      })
+      // Even with the mkdir warn, set() proceeds to writeFileSync.
+      // If that succeeds (because the dir already exists from beforeEach),
+      // the operation completes normally.
+      await expect(
+        manifest.set('p', {
+          timestampFetch: Date.now(),
+          latestVersion: '1.0.0',
+        } as never),
+      ).resolves.toBeUndefined()
+    })
+  })
+
+  describe('writeManifest atomic-write catch path', () => {
+    it('cleans up temp file when rename fails (clear() path)', async () => {
+      writeFileSync(manifestPath, '{"a":{}}', 'utf8')
+      // safeDeleteSync inside the catch is the cleanup call.
+      // Force it to throw to exercise the inner catch (line 414).
+      vi.mocked(safeDeleteSync).mockImplementationOnce(() => {
+        throw makeFsError('EPERM')
+      })
+      // clear() will call writeManifest indirectly. Even if cleanup
+      // fails internally, clear() swallows via its own try/catch.
+      await expect(manifest.clear('a')).resolves.toBeUndefined()
+    })
+  })
+})