fix: cross-platform correctness in home/git/bin/process-lock

- env/home.ts: fall back to $USERPROFILE when $HOME is unset. HOME is
  typically unset on Windows; previously getHome() returned undefined
  there, breaking downstream pnpm/yarn path resolution.
- git.ts: split git output on /\r?\n/ so Windows (CRLF) is handled.
  Wrap realpathSync in try/catch that falls back to the input path for
  EACCES/EPERM/EIO (container/overlay FS) while still re-throwing
  ENOENT/ENOTDIR so missing-path errors remain visible.
- bin.ts: findRealNpm/Pnpm/Yarn now branch on WIN32 and guard every
  env-derived path against undefined. Previously path.join(getHome()
  as string, ...) would throw TypeError when HOME was unset.
- process-lock.ts: replace Math.max(lastIndexOf('/'), '\\') with
  path.dirname() so parent-dir resolution works for mixed or absent
  separators. Hoist the fs destructure out of module scope (was
  subverting the lazy-require pattern). Use Date.now()/1000 for
  utimesSync to avoid allocating a Date on every touch tick.

Covered by a new home.test.mts regression for the USERPROFILE
fallback; existing git/process-lock/bin suites already exercise the
changed code paths.

Author: jdalton

src/bin.ts

@@ -207,16 +207,28 @@ export function findRealNpm(): string {
   const fs = getFs()
   const path = getPath()
 
-  // Try to find npm in the same directory as the node executable.
+  // Try to find npm alongside the node executable. On Windows this is
+  // npm.cmd; on POSIX it's the bare npm shim.
   const nodeDir = path.dirname(process.execPath)
-  const npmInNodeDir = path.join(nodeDir, 'npm')
-
-  if (fs.existsSync(npmInNodeDir)) {
-    return npmInNodeDir
+  const nodeDirCandidates = WIN32
+    ? [path.join(nodeDir, 'npm.cmd'), path.join(nodeDir, 'npm')]
+    : [path.join(nodeDir, 'npm')]
+  for (const candidate of nodeDirCandidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate
+    }
   }
 
-  // Try common npm locations.
-  const commonPaths = ['/usr/local/bin/npm', '/usr/bin/npm']
+  // Try common npm locations per platform.
+  const appdata = getAppdata()
+  const commonPaths = WIN32
+    ? [
+        appdata ? path.join(appdata, 'npm', 'npm.cmd') : '',
+        appdata ? path.join(appdata, 'npm', 'npm') : '',
+        'C:\\Program Files\\nodejs\\npm.cmd',
+        'C:\\Program Files\\nodejs\\npm',
+      ].filter(Boolean)
+    : ['/usr/local/bin/npm', '/usr/bin/npm']
   const result = findRealBin('npm', commonPaths)
 
   // If we found a valid path, return it.
@@ -246,27 +258,31 @@ export function findRealNpm(): string {
  */
 export function findRealPnpm(): string {
   const path = getPath()
+  const home = getHome()
+  const appdata = getAppdata()
+  const localappdata = getLocalappdata()
+  const xdgDataHome = getXdgDataHome()
 
-  // Try common pnpm locations.
+  // Try common pnpm locations. Guard each env-derived path with its
+  // existence — getHome()/getAppdata()/etc. can all return undefined.
   const commonPaths = WIN32
     ? [
-        // Windows common paths.
-        path.join(getAppdata() as string, 'npm', 'pnpm.cmd'),
-        path.join(getAppdata() as string, 'npm', 'pnpm'),
-        path.join(getLocalappdata() as string, 'pnpm', 'pnpm.cmd'),
-        path.join(getLocalappdata() as string, 'pnpm', 'pnpm'),
+        appdata ? path.join(appdata, 'npm', 'pnpm.cmd') : '',
+        appdata ? path.join(appdata, 'npm', 'pnpm') : '',
+        localappdata ? path.join(localappdata, 'pnpm', 'pnpm.cmd') : '',
+        localappdata ? path.join(localappdata, 'pnpm', 'pnpm') : '',
         'C:\\Program Files\\nodejs\\pnpm.cmd',
         'C:\\Program Files\\nodejs\\pnpm',
       ].filter(Boolean)
     : [
-        // Unix common paths.
         '/usr/local/bin/pnpm',
         '/usr/bin/pnpm',
-        path.join(
-          (getXdgDataHome() as string) || `${getHome() as string}/.local/share`,
-          'pnpm/pnpm',
-        ),
-        path.join(getHome() as string, '.pnpm/pnpm'),
+        xdgDataHome
+          ? path.join(xdgDataHome, 'pnpm/pnpm')
+          : home
+            ? path.join(home, '.local/share/pnpm/pnpm')
+            : '',
+        home ? path.join(home, '.pnpm/pnpm') : '',
       ].filter(Boolean)
 
   return findRealBin('pnpm', commonPaths) ?? ''
@@ -283,17 +299,28 @@ export function findRealPnpm(): string {
  */
 export function findRealYarn(): string {
   const path = getPath()
+  const home = getHome()
+  const appdata = getAppdata()
 
-  // Try common yarn locations.
-  const commonPaths = [
-    '/usr/local/bin/yarn',
-    '/usr/bin/yarn',
-    path.join(getHome() as string, '.yarn/bin/yarn'),
-    path.join(
-      getHome() as string,
-      '.config/yarn/global/node_modules/.bin/yarn',
-    ),
-  ].filter(Boolean)
+  // Try common yarn locations per platform. Guard env-derived paths with
+  // existence checks — getHome()/getAppdata() can return undefined.
+  const commonPaths = WIN32
+    ? [
+        appdata ? path.join(appdata, 'npm', 'yarn.cmd') : '',
+        appdata ? path.join(appdata, 'npm', 'yarn') : '',
+        home ? path.join(home, '.yarn/bin/yarn.cmd') : '',
+        home ? path.join(home, '.yarn/bin/yarn') : '',
+        'C:\\Program Files\\nodejs\\yarn.cmd',
+        'C:\\Program Files\\nodejs\\yarn',
+      ].filter(Boolean)
+    : [
+        '/usr/local/bin/yarn',
+        '/usr/bin/yarn',
+        home ? path.join(home, '.yarn/bin/yarn') : '',
+        home
+          ? path.join(home, '.config/yarn/global/node_modules/.bin/yarn')
+          : '',
+      ].filter(Boolean)
 
   return findRealBin('yarn', commonPaths) ?? ''
 }

src/env/home.ts

@@ -1,24 +1,34 @@
 /**
- * HOME environment variable getter.
- * Points to the user's home directory.
+ * @fileoverview HOME environment variable getter with Windows fallback.
+ * Returns the user's home directory. On Windows, HOME is typically unset —
+ * fall back to USERPROFILE before giving up, matching the resolution order
+ * used by npm, git, and Node's os.homedir().
  */
 
 import { getEnvValue } from './rewire'
 
 /**
- * Returns the value of the HOME environment variable.
+ * Returns the user's home directory path.
  *
- * @returns The user's home directory path, or `undefined` if not set
+ * Resolution order:
+ *   1. `$HOME` (POSIX, and sometimes set on Windows by shells like Git Bash)
+ *   2. `$USERPROFILE` (Windows default, e.g. `C:\Users\alice`)
+ *
+ * Returns `undefined` only when neither is set, which on modern systems is
+ * exceedingly rare outside of sandboxed or minimal-env test harnesses.
+ *
+ * @returns The user's home directory path, or `undefined` if not resolvable
  *
  * @example
  * ```typescript
  * import { getHome } from '@socketsecurity/lib/env/home'
  *
  * const home = getHome()
- * // e.g. '/tmp/user' or undefined
+ * // POSIX: '/Users/alice'
+ * // Windows: 'C:\\Users\\alice'
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getHome(): string | undefined {
-  return getEnvValue('HOME')
+  return getEnvValue('HOME') ?? getEnvValue('USERPROFILE')
 }

src/git.ts

@@ -185,6 +185,12 @@ const gitRootCache = new Map<string, string>()
 /**
  * Get the real path with caching to avoid repeated filesystem calls.
  * Validates cache with existsSync() which is cheaper than realpathSync().
+ *
+ * ENOENT/ENOTDIR are re-thrown because the caller explicitly passed a path
+ * they expect to exist — swallowing these would turn "file not found" into
+ * a silent no-op. Other errors (EACCES, EPERM, EIO) fall back to the input
+ * path since they can happen on container/overlay filesystems where the
+ * path exists but realpath resolution is restricted.
  * @private
  */
 function getCachedRealpath(pathname: string): string {
@@ -197,7 +203,16 @@ function getCachedRealpath(pathname: string): string {
     // Cached path no longer exists, remove stale entry.
     realpathCache.delete(pathname)
   }
-  const resolved = fs.realpathSync(pathname)
+  let resolved: string
+  try {
+    resolved = fs.realpathSync(pathname)
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      throw error
+    }
+    resolved = pathname
+  }
   realpathCache.set(pathname, resolved)
   return resolved
 }
@@ -241,7 +256,7 @@ function getGitPath(): string {
  * ```
  */
 function getCwd(): string {
-  return getFs().realpathSync(process.cwd())
+  return getCachedRealpath(process.cwd())
 }
 
 /**
@@ -259,7 +274,7 @@ function getCwd(): string {
  * @returns Object containing spawn arguments for all, unstaged, and staged operations.
  */
 function getGitDiffSpawnArgs(cwd?: string | undefined): GitDiffSpawnArgs {
-  const resolvedCwd = cwd ? getFs().realpathSync(cwd) : getCwd()
+  const resolvedCwd = cwd ? getCachedRealpath(cwd) : getCwd()
   return {
     all: [
       getGitPath(),
@@ -495,9 +510,10 @@ function parseGitDiffStdout(
     cwdOption === defaultRoot ? defaultRoot : getCachedRealpath(cwdOption)
   const rootPath = defaultRoot
   // Split into lines without trimming to preserve leading spaces in porcelain format.
+  // Handle both LF (POSIX) and CRLF (Windows) — git on Windows emits CRLF by default.
   let rawFiles = stdout
     ? stripAnsi(stdout)
-        .split('\n')
+        .split(/\r?\n/)
         .map(line => line.trimEnd())
         .filter(line => line)
     : []

src/process-lock.ts

@@ -40,6 +40,11 @@
  * - Automatic cleanup on process exit
  */
 
+import { safeDeleteSync } from './fs'
+import { getDefaultLogger } from './logger'
+import { pRetry } from './promises'
+import { onExit } from './signal-exit'
+
 let _fs: typeof import('node:fs') | undefined
 /**
  * Lazily load the fs module to avoid Webpack errors.
@@ -53,13 +58,18 @@ function getFs() {
   return _fs as typeof import('node:fs')
 }
 
-import { safeDeleteSync } from './fs'
-import { getDefaultLogger } from './logger'
-import { pRetry } from './promises'
-import { onExit } from './signal-exit'
-
-const fs = getFs()
-const { existsSync, mkdirSync, statSync, utimesSync } = fs
+let _path: typeof import('node:path') | undefined
+/**
+ * Lazily load the path module to avoid Webpack errors.
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getPath() {
+  if (_path === undefined) {
+    _path = /*@__PURE__*/ require('node:path')
+  }
+  return _path as typeof import('node:path')
+}
 
 const logger = getDefaultLogger()
 
@@ -128,9 +138,10 @@ class ProcessLockManager {
       this.touchTimers.clear()
 
       // Clean up all active locks.
+      const fs = getFs()
       for (const lockPath of this.activeLocks) {
         try {
-          if (existsSync(lockPath)) {
+          if (fs.existsSync(lockPath)) {
             safeDeleteSync(lockPath, { recursive: true })
           }
         } catch {
@@ -150,9 +161,12 @@ class ProcessLockManager {
    */
   private touchLock(lockPath: string): void {
     try {
-      if (existsSync(lockPath)) {
-        const now = new Date()
-        utimesSync(lockPath, now, now)
+      const fs = getFs()
+      if (fs.existsSync(lockPath)) {
+        // utimesSync accepts numeric timestamps (seconds). Pass Date.now() / 1000
+        // to avoid the Date allocation on every touch tick.
+        const now = Date.now() / 1000
+        fs.utimesSync(lockPath, now, now)
       }
     } catch (error) {
       logger.warn(
@@ -209,7 +223,7 @@ class ProcessLockManager {
     try {
       // Use single statSync call instead of existsSync + statSync.
       // throwIfNoEntry: false returns undefined if path doesn't exist.
-      const stats = statSync(lockPath, { throwIfNoEntry: false })
+      const stats = getFs().statSync(lockPath, { throwIfNoEntry: false })
       if (!stats) {
         return false
       }
@@ -275,23 +289,24 @@ class ProcessLockManager {
           }
 
           // Check if lock already exists before creating.
-          if (existsSync(lockPath)) {
+          const fs = getFs()
+          if (fs.existsSync(lockPath)) {
             throw new Error(`Lock already exists: ${lockPath}`)
           }
 
-          // Ensure parent directory exists.
-          const lastSlash = Math.max(
-            lockPath.lastIndexOf('/'),
-            lockPath.lastIndexOf('\\'),
-          )
-          if (lastSlash > 0) {
-            mkdirSync(lockPath.slice(0, lastSlash), { recursive: true })
+          // Ensure parent directory exists. Use path.dirname() so that both
+          // POSIX and Windows separators (and mixed-separator inputs) are
+          // handled correctly — the previous Math.max(lastIndexOf('/'), '\\')
+          // approach failed on relative paths and mixed-separator inputs.
+          const parent = getPath().dirname(lockPath)
+          if (parent && parent !== '.' && parent !== lockPath) {
+            fs.mkdirSync(parent, { recursive: true })
           }
 
           // Atomic lock acquisition via mkdir (without recursive).
           // Without recursive, mkdirSync throws EEXIST if another process
           // created the directory between the existsSync check and here.
-          mkdirSync(lockPath)
+          fs.mkdirSync(lockPath)
 
           // Track lock for cleanup.
           this.activeLocks.add(lockPath)
@@ -398,7 +413,7 @@ class ProcessLockManager {
     this.stopTouchTimer(lockPath)
 
     try {
-      if (existsSync(lockPath)) {
+      if (getFs().existsSync(lockPath)) {
         safeDeleteSync(lockPath, { recursive: true })
       }
       this.activeLocks.delete(lockPath)

test/unit/env/home.test.mts

@@ -1,10 +1,10 @@
 /**
  * @fileoverview Unit tests for HOME environment variable getter.
  *
- * Tests getHome() which retrieves the user's home directory path via HOME env var.
- * Returns home path string or undefined if not set. Unix/Linux standard.
- * On Windows, use getUserprofile() instead (USERPROFILE env var).
- * Uses rewire for isolated testing. Critical for resolving user-specific paths.
+ * Tests getHome(), which resolves the user's home directory. It reads $HOME
+ * first (POSIX + most shells), then falls back to $USERPROFILE for Windows
+ * environments where $HOME is typically unset. Uses rewire for isolated
+ * testing. Critical for resolving user-specific paths cross-platform.
  */
 
 import { getHome } from '@socketsecurity/lib/env/home'
@@ -150,5 +150,17 @@ describe('env/home', () => {
       setEnv('HOME', '/home/user/snap/app/common')
       expect(getHome()).toBe('/home/user/snap/app/common')
     })
+
+    it('should fall back to USERPROFILE when HOME is unset (Windows)', () => {
+      setEnv('HOME', undefined)
+      setEnv('USERPROFILE', 'C:\\Users\\alice')
+      expect(getHome()).toBe('C:\\Users\\alice')
+    })
+
+    it('should prefer HOME over USERPROFILE when both are set', () => {
+      setEnv('HOME', '/Users/alice')
+      setEnv('USERPROFILE', 'C:\\Users\\alice')
+      expect(getHome()).toBe('/Users/alice')
+    })
   })
 })