chore: minor fixes and updates

Miscellaneous code quality and consistency improvements.

Changes:
- Update src/bin.ts, src/debug.ts, src/effects/text-shimmer.ts, src/spinner.ts
- Update src/constants/packages.ts
- Update CLAUDE.md with v2 conventions and env system patterns

Author: jdalton

CLAUDE.md

@@ -160,8 +160,8 @@ Blank lines between groups, alphabetical within groups.
 
 #### Path Aliases Usage
 - **Internal imports**: Always use path aliases for internal modules
-  - ✅ `import { CI } from '#env/ci'`
-  - ❌ `import { CI } from '../env/ci'`
+  - ✅ `import { getCI } from '#env/ci'`
+  - ❌ `import { getCI } from '../env/ci'`
 - **External modules**: Regular imports
   - ✅ `import path from 'node:path'`
 
@@ -252,13 +252,37 @@ Use `pnpm run build:watch` or `pnpm run dev` for development with automatic rebu
 ### Common Patterns
 
 #### Environment Variables
-Access via typed helpers in `src/env/`:
+Access via typed getter functions in `src/env/`:
 ```typescript
-import { CI } from '#env/ci'
-import { NODE_ENV } from '#env/node-env'
-import { getEnv } from '#env/getters'
+import { getCI } from '#env/ci'
+import { getNodeEnv } from '#env/node-env'
+import { isTest } from '#env/test'
 ```
 
+Each env module exports a pure getter function that accesses only its own environment variable. For fallback logic, compose multiple getters:
+```typescript
+import { getHome } from '#env/home'
+import { getUserProfile } from '#env/userprofile'
+
+const homeDir = getHome() || getUserProfile()  // Cross-platform fallback
+```
+
+**Testing with rewiring:**
+Environment getters support test rewiring without modifying `process.env`:
+```typescript
+import { setEnv, clearEnv, resetEnv } from '#env/rewire'
+import { getCI } from '#env/ci'
+
+// In test
+setEnv('CI', '1')
+expect(getCI()).toBe(true)
+
+clearEnv('CI')  // Clear single override
+resetEnv()      // Clear all overrides (use in afterEach)
+```
+
+This allows isolated tests without polluting the global process.env state.
+
 #### File System Operations
 Use utilities from `#lib/fs`:
 ```typescript

src/bin.ts

@@ -3,10 +3,9 @@
  * Provides cross-platform bin path lookup, command execution, and path normalization.
  */
 
-import { APPDATA } from '#env/appdata'
-import { HOME } from '#env/home'
-import { LOCALAPPDATA } from '#env/localappdata'
-import { XDG_DATA_HOME } from '#env/xdg-data-home'
+import { getHome } from '#env/home'
+import { getAppdata, getLocalappdata } from '#env/windows'
+import { getXdgDataHome } from '#env/xdg'
 
 import { WIN32 } from '#constants/platform'
 import { readJsonSync } from './fs'
@@ -259,10 +258,10 @@ export function findRealPnpm(): string {
   const commonPaths = WIN32
     ? [
         // Windows common paths.
-        path?.join(APPDATA as string, 'npm', 'pnpm.cmd'),
-        path?.join(APPDATA as string, 'npm', 'pnpm'),
-        path?.join(LOCALAPPDATA as string, 'pnpm', 'pnpm.cmd'),
-        path?.join(LOCALAPPDATA as string, 'pnpm', 'pnpm'),
+        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'),
         'C:\\Program Files\\nodejs\\pnpm.cmd',
         'C:\\Program Files\\nodejs\\pnpm',
       ].filter(Boolean)
@@ -271,10 +270,10 @@ export function findRealPnpm(): string {
         '/usr/local/bin/pnpm',
         '/usr/bin/pnpm',
         path?.join(
-          (XDG_DATA_HOME as string) || `${HOME as string}/.local/share`,
+          (getXdgDataHome() as string) || `${getHome() as string}/.local/share`,
           'pnpm/pnpm',
         ),
-        path?.join(HOME as string, '.pnpm/pnpm'),
+        path?.join(getHome() as string, '.pnpm/pnpm'),
       ].filter(Boolean)
 
   return findRealBin('pnpm', commonPaths) ?? ''
@@ -290,8 +289,11 @@ export function findRealYarn(): string {
   const commonPaths = [
     '/usr/local/bin/yarn',
     '/usr/bin/yarn',
-    path?.join(HOME as string, '.yarn/bin/yarn'),
-    path?.join(HOME as string, '.config/yarn/global/node_modules/.bin/yarn'),
+    path?.join(getHome() as string, '.yarn/bin/yarn'),
+    path?.join(
+      getHome() as string,
+      '.config/yarn/global/node_modules/.bin/yarn',
+    ),
   ].filter(Boolean)
 
   return findRealBin('yarn', commonPaths) ?? ''
@@ -585,7 +587,7 @@ export function resolveBinPathSync(binPath: string): string {
 
     // Handle special case where pnpm path in CI has extra segments.
     // In setup-pnpm GitHub Action, the path might be malformed like:
-    // /home/runner/setup-pnpm/node_modules/.bin/pnpm/bin/pnpm.cjs
+    // /home/user/setup-pnpm/node_modules/.bin/pnpm/bin/pnpm.cjs
     // This happens when the shell script contains a relative path that
     // when resolved, creates an invalid nested structure.
     if (isPnpmOrYarn && binPath.includes('/.bin/pnpm/bin/')) {

src/constants/packages.ts

@@ -2,7 +2,7 @@
  * Package metadata, defaults, extensions, and lifecycle scripts.
  */
 
-import { npm_lifecycle_event } from '#env/npm-lifecycle-event'
+import { getNpmLifecycleEvent as getNpmLifecycleEventEnv } from '#env/npm'
 
 let _lifecycleScriptNames: string[]
 let _packageDefaultNodeRange: string | undefined
@@ -56,7 +56,7 @@ export function getPackageExtensions(): Iterable<[string, unknown]> {
 
 // NPM lifecycle event.
 export function getNpmLifecycleEvent(): string | undefined {
-  return npm_lifecycle_event
+  return getNpmLifecycleEventEnv()
 }
 
 // Lifecycle script names.

src/debug.ts

@@ -4,8 +4,8 @@
  */
 
 import { getSpinner } from '#constants/process'
-import { DEBUG } from '#env/debug'
-import { SOCKET_DEBUG } from '#env/socket-debug'
+import { getDebug } from '#env/debug'
+import { getSocketDebug } from '#env/socket'
 import isUnicodeSupported from './external/@socketregistry/is-unicode-supported'
 import debugJs from './external/debug'
 
@@ -48,8 +48,8 @@ function getDebugJsInstance(namespace: string) {
     return inst
   }
   if (
-    !DEBUG &&
-    SOCKET_DEBUG &&
+    !getDebug() &&
+    getSocketDebug() &&
     (namespace === 'error' || namespace === 'notice')
   ) {
     debugJs.enable(namespace)
@@ -166,7 +166,7 @@ function extractOptions(namespaces: NamespacesOrOptions): DebugOptions {
 /*@__NO_SIDE_EFFECTS__*/
 function isEnabled(namespaces: string | undefined) {
   // Check if debugging is enabled at all
-  if (!SOCKET_DEBUG) {
+  if (!getSocketDebug()) {
     return false
   }
   if (typeof namespaces !== 'string' || !namespaces || namespaces === '*') {
@@ -360,7 +360,7 @@ export function debugCache(
   key: string,
   meta?: unknown | undefined,
 ): void {
-  if (!SOCKET_DEBUG) {
+  if (!getSocketDebug()) {
     return
   }
   // Get caller info with stack offset of 3 (caller -> debugCache -> getCallerInfo).
@@ -381,7 +381,7 @@ export function debugCache(
  */
 /*@__NO_SIDE_EFFECTS__*/
 function isDebugNs(namespaces: string | undefined): boolean {
-  return !!SOCKET_DEBUG && isEnabled(namespaces)
+  return !!getSocketDebug() && isEnabled(namespaces)
 }
 
 /**
@@ -413,7 +413,7 @@ function debugLog(...args: unknown[]): void {
  */
 /*@__NO_SIDE_EFFECTS__*/
 function isDebug(): boolean {
-  return !!SOCKET_DEBUG
+  return !!getSocketDebug()
 }
 
 /**

src/effects/text-shimmer.ts

@@ -14,7 +14,7 @@
 
 import { ANSI_RESET, stripAnsi } from '../ansi'
 import { isArray } from '../arrays'
-import { CI } from '#env/ci'
+import { getCI } from '#env/ci'
 
 import type {
   ShimmerColorGradient,
@@ -252,7 +252,7 @@ export function applyShimmer(
   const plainText = stripAnsi(text)
 
   // No shimmer effect in CI or when direction is 'none'.
-  if (CI || !plainText || direction === DIR_NONE) {
+  if (getCI() || !plainText || direction === DIR_NONE) {
     const styleCode = stylesToAnsi(styles)
 
     // Support gradient colors (array of colors, one per character).

src/spinner.ts

@@ -6,7 +6,7 @@
 import type { Writable } from 'node:stream'
 
 // Note: getAbortSignal is imported lazily to avoid circular dependencies.
-import { CI } from '#env/ci'
+import { getCI } from '#env/ci'
 import { generateSocketSpinnerFrames } from './effects/pulse-frames'
 import type {
   ShimmerColorGradient,
@@ -1286,7 +1286,7 @@ export function Spinner(options?: SpinnerOptions | undefined): Spinner {
       warning: desc(_Spinner.prototype.warn),
       warningAndStop: desc(_Spinner.prototype.warnAndStop),
     })
-    _defaultSpinner = CI
+    _defaultSpinner = getCI()
       ? ciSpinner
       : (getCliSpinners('socket') as SpinnerStyle)
   }