@socketsecurity/lib 5.21.0 → 5.23.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.23.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.23.0) - 2026-04-22
+
+### Added
+
+- `@socketsecurity/lib/errors` `isError(value)` — spec-compliant ES2025 [`Error.isError`](https://tc39.es/ecma262/#sec-error.iserror) with an `@@toStringTag`-based shim for older engines. Recognizes cross-realm Errors (worker threads, vm contexts, iframes) that same-realm `instanceof Error` misses
+- `@socketsecurity/lib/errors` `errorMessage(value)` — extracts a readable message from any caught value (Error with cause chain via `messageWithCauses`, primitive, plain object, or nullish) with the shared `UNKNOWN_ERROR` (`'Unknown error'`) fallback. Replaces the `e instanceof Error ? e.message : String(e)` pattern
+- `@socketsecurity/lib/errors` `errorStack(value)` — companion helper returning the cause-aware stack for Error instances (via `stackWithCauses`) and `undefined` otherwise
+- `@socketsecurity/lib/errors` `isErrnoException(value)` — narrows to `NodeJS.ErrnoException` (an Error with a non-empty uppercase-prefixed `.code`, matching the libuv `UV_E*` / Node `ERR_*` conventions), cross-realm safe
+- `@socketsecurity/lib/errors` re-exports `UNKNOWN_ERROR` from `constants/core` so callers don't need a separate import
+
+### Changed
+
+- `@socketsecurity/lib/errors` pony-cause `messageWithCauses` / `stackWithCauses` / `findCauseByReference` / `getErrorCause` — patched to use `isError` internally so cross-realm Errors are recognized (previously returned `''` for any Error thrown in a different realm)
+
+## [5.22.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.22.0) - 2026-04-21
+
+### Changed
+
+- `@socketsecurity/lib/releases/socket-btm` `getPlatformArch()` / `getBinaryAssetName()` — aligned with pnpm pack-app's `<os>-<arch>[-<libc>]` target format. The Windows OS segment is now `win32` (was `win`); `getPlatformArch('win32', 'x64')` returns `'win32-x64'` and `getBinaryAssetName('node', 'win32', 'x64')` returns `'node-win32-x64.exe'`. Callers that string-match on the output need updates
+
 ## [5.21.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.21.0) - 2026-04-20
 
 ### Added

package/README.md

@@ -7,219 +7,62 @@
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
 
-Core infrastructure library for [Socket.dev](https://socket.dev/) security tools. Provides utilities for file system operations, process spawning, HTTP requests, environment detection, logging, spinners, and more.
-
-## Prerequisites
-
-**Node.js 22 or higher** is required.
+Core utilities for [Socket.dev](https://socket.dev/) tools: file system, processes, HTTP, env detection, logging, spinners, and more. Tree-shakeable, TypeScript-first, cross-platform.
 
 ## Install
 
 ```bash
-# Using pnpm (recommended)
 pnpm add @socketsecurity/lib
-
-# Using npm
-npm install @socketsecurity/lib
-
-# Using yarn
-yarn add @socketsecurity/lib
 ```
 
 ## Quick Start
 
 ```typescript
 import { Spinner } from '@socketsecurity/lib/spinner'
-import { getDefaultLogger } from '@socketsecurity/lib/logger'
 import { readJson } from '@socketsecurity/lib/fs'
 
-const logger = getDefaultLogger()
-const spinner = Spinner({ text: 'Loading package.json...' })
-
+const spinner = Spinner({ text: 'Loading…' })
 spinner.start()
 const pkg = await readJson('./package.json')
-spinner.successAndStop('Loaded successfully')
-
-logger.success(`Package: ${pkg.name}@${pkg.version}`)
+spinner.successAndStop(`Loaded ${pkg.name}@${pkg.version}`)
 ```
 
-## Documentation
-
-- [API Index](./docs/api-index.md) - Every subpath export with a one-line description (start here)
-- [Getting Started](./docs/getting-started.md) - Prerequisites, installation, and first examples
-- [Visual Effects](./docs/visual-effects.md) - Spinners, loggers, themes, and progress indicators
-- [File System](./docs/file-system.md) - File operations, globs, paths, and safe deletion
-- [HTTP Utilities](./docs/http-utilities.md) - Making requests, downloading files, and retry logic
-- [Process Utilities](./docs/process-utilities.md) - Spawning processes, IPC, and locks
-- [Package Management](./docs/package-management.md) - npm/pnpm/yarn detection and operations
-- [Environment](./docs/environment.md) - CI detection, env getters, and platform checks
-- [Constants](./docs/constants.md) - Node versions, npm URLs, and platform values
-- [Examples](./docs/examples.md) - Real-world usage patterns
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
-
-## What's Inside
-
-### Visual Effects
-
-Spinners, colored loggers, themes, progress bars, and terminal output formatting.
-
-- `Spinner` - Animated CLI spinners with progress tracking
-- `getDefaultLogger()` - Colored console logger with symbols
-- `LOG_SYMBOLS` - Colored terminal symbols (✓, ✗, ⚠, ℹ, →)
-- `setTheme()` - Customize colors across the library
-
-### File System
-
-Cross-platform file operations with safe deletion and convenient wrappers.
-
-- `readFileUtf8()`, `readFileBinary()` - Read files as text or binary
-- `readJson()`, `writeJson()` - Parse and format JSON files
-- `safeDelete()` - Protected deletion with safety checks
-- `findUp()`, `findUpSync()` - Traverse up to find files
-- `safeMkdir()` - Create directories without EEXIST errors
-- `validateFiles()` - Check file readability (useful for Yarn PnP, pnpm)
-
-### HTTP Utilities
-
-Native Node.js HTTP/HTTPS requests with retry logic and redirects.
-
-- `httpJson()` - Fetch and parse JSON from APIs
-- `httpText()` - Fetch text/HTML content
-- `httpDownload()` - Download files with progress callbacks
-- `httpRequest()` - Full control over requests and responses
-- Automatic redirects, exponential backoff retries, timeout support
-
-### Process Management
-
-Spawn child processes safely with cross-platform support.
-
-- `spawn()` - Promise-based process spawning with output capture
-- `spawnSync()` - Synchronous version for blocking operations
-- Array-based arguments prevent command injection
-- Automatic Windows `.cmd`/`.bat` handling
-- `processLock.withLock()` / `processLock.acquire()` / `processLock.release()` - Ensure only one instance runs at a time
-- `writeIpcStub()` / `getIpcStubPath()` - Filesystem-based inter-process data handoff
-
-### Environment Detection
-
-Type-safe environment variable access and platform detection.
-
-- `getCI()` - Detect CI environment
-- `getNodeEnv()` - Get NODE_ENV value
-- `isTest()` - Check if running tests
-- `getHome()` - Home directory (cross-platform, with Windows `USERPROFILE` fallback)
-- Test rewiring with `setEnv()`, `resetEnv()`
-
-### Package Management
-
-Detect and work with npm, pnpm, and yarn.
-
-- `detectPackageManager()` - Identify running package manager from `npm_config_user_agent` / binary path
-- Package manifest operations
-- Lock file management
-
-### Constants
-
-Pre-defined values for Node.js, npm, and platform detection.
-
-- `getNodeMajorVersion()` - Get current Node.js major version
-- `WIN32`, `DARWIN` - Platform booleans (use `!WIN32 && !DARWIN` for Linux)
-- `getAbortSignal()` - Global abort signal
-
-### Utilities
-
-Helpers for arrays, objects, strings, promises, sorting, and more.
-
-- Arrays, objects, strings manipulation
-- Promise utilities and queues
-- Natural sorting
-- Version comparison
-- Error handling with causes
-
-## Features
-
-- **Tree-shakeable exports** - Import only what you need
-- **Cross-platform** - Works on Windows, macOS, and Linux
-- **TypeScript-first** - Full type safety with .d.ts files
-- **Zero dependencies** (for core HTTP - uses Node.js native modules)
-- **Well-tested** - 6000+ tests across 139+ test files
-- **Security-focused** - Safe defaults, command injection protection
-- **CommonJS output** - Compatible with Node.js tooling
-
-## Common Use Cases
-
-### Running Shell Commands
+Every export lives under a subpath — pick what you need:
 
 ```typescript
 import { spawn } from '@socketsecurity/lib/spawn'
-
-const result = await spawn('git', ['status'])
-console.log(result.stdout)
-```
-
-### Making API Requests
-
-```typescript
 import { httpJson } from '@socketsecurity/lib/http-request'
-
-const data = await httpJson('https://api.example.com/data')
-```
-
-### Visual Feedback
-
-```typescript
-import { Spinner } from '@socketsecurity/lib/spinner'
-
-const spinner = Spinner({ text: 'Processing...' })
-spinner.start()
-// ... do work ...
-spinner.successAndStop('Complete!')
-```
-
-### Safe File Deletion
-
-```typescript
 import { safeDelete } from '@socketsecurity/lib/fs'
-
-// Protected against deleting parent directories
-await safeDelete('./build')
-```
-
-## Troubleshooting
-
-**Module not found**: Verify you're importing from the correct path:
-
-```typescript
-// Correct
-import { Spinner } from '@socketsecurity/lib/spinner'
-
-// Wrong
-import { Spinner } from '@socketsecurity/lib'
 ```
 
-**Node version error**: This library requires Node.js 22+. Check your version:
+## Documentation
 
-```bash
-node --version
-```
+Start with the [API Index](./docs/api-index.md) — every subpath export with a one-line description.
 
-For more issues, see the [Troubleshooting Guide](./docs/troubleshooting.md).
+- [Getting Started](./docs/getting-started.md) – install + first examples
+- [Visual Effects](./docs/visual-effects.md) – spinners, loggers, themes
+- [File System](./docs/file-system.md) – files, globs, paths, safe deletion
+- [HTTP Utilities](./docs/http-utilities.md) – requests, downloads, retries
+- [Process Utilities](./docs/process-utilities.md) – spawn, IPC, locks
+- [Package Management](./docs/package-management.md) – npm/pnpm/yarn detection
+- [Environment](./docs/environment.md) – CI/platform detection, env getters
+- [Constants](./docs/constants.md) – Node versions, npm URLs, platform values
+- [Examples](./docs/examples.md) – real-world patterns
+- [Troubleshooting](./docs/troubleshooting.md) – common issues
 
 ## Development
 
 ```bash
-pnpm install    # Install dependencies
-pnpm build      # Build the library
-pnpm test       # Run tests
-pnpm run cover  # Run tests with coverage
-pnpm dev        # Watch mode
-pnpm run lint   # Check code style
-pnpm run fix    # Fix formatting issues
+pnpm install          # install
+pnpm build            # build
+pnpm test             # run tests
+pnpm run cover        # tests with coverage
+pnpm dev              # watch mode
+pnpm run lint         # check style
+pnpm run fix          # auto-fix formatting
 ```
 
-## Contributing
-
-Contributions are welcome! Please read the [CLAUDE.md](./CLAUDE.md) file for development guidelines and coding standards.
+See [CLAUDE.md](./CLAUDE.md) for contributor guidelines.
 
 ## License
 

package/dist/constants/socket.js

@@ -77,7 +77,7 @@ const SOCKET_FIREWALL_APP_NAME = "sfw";
 const SOCKET_REGISTRY_APP_NAME = "registry";
 const SOCKET_APP_PREFIX = "_";
 const SOCKET_LIB_NAME = "@socketsecurity/lib";
-const SOCKET_LIB_VERSION = "5.21.0";
+const SOCKET_LIB_VERSION = "5.23.0";
 const SOCKET_LIB_URL = "https://github.com/SocketDev/socket-lib";
 const SOCKET_LIB_USER_AGENT = `socketsecurity-lib/${SOCKET_LIB_VERSION} (${SOCKET_LIB_URL})`;
 const SOCKET_IPC_HANDSHAKE = "SOCKET_IPC_HANDSHAKE";

package/dist/dlx/manifest.js

@@ -26,6 +26,7 @@ __export(manifest_exports, {
   isPackageEntry: () => isPackageEntry
 });
 module.exports = __toCommonJS(manifest_exports);
+var import_errors = require("../errors");
 var import_fs = require("../fs");
 var import_logger = require("../logger");
 var import_socket = require("../paths/socket");
@@ -79,9 +80,7 @@ class DlxManifest {
       }
       return JSON.parse(content);
     } catch (error) {
-      logger.warn(
-        `Failed to read manifest: ${error instanceof Error ? error.message : String(error)}`
-      );
+      logger.warn(`Failed to read manifest: ${(0, import_errors.errorMessage)(error)}`);
       return { __proto__: null };
     }
   }
@@ -94,9 +93,7 @@ class DlxManifest {
     try {
       (0, import_fs.safeMkdirSync)(manifestDir, { recursive: true });
     } catch (error) {
-      logger.warn(
-        `Failed to create manifest directory: ${error instanceof Error ? error.message : String(error)}`
-      );
+      logger.warn(`Failed to create manifest directory: ${(0, import_errors.errorMessage)(error)}`);
     }
     const content = JSON.stringify(data, null, 2);
     const tempPath = `${this.manifestPath}.tmp`;
@@ -130,9 +127,7 @@ class DlxManifest {
         delete data[name];
         await this.writeManifest(data);
       } catch (error) {
-        logger.warn(
-          `Failed to clear cache for ${name}: ${error instanceof Error ? error.message : String(error)}`
-        );
+        logger.warn(`Failed to clear cache for ${name}: ${(0, import_errors.errorMessage)(error)}`);
       }
     });
   }
@@ -146,9 +141,7 @@ class DlxManifest {
           fs.unlinkSync(this.manifestPath);
         }
       } catch (error) {
-        logger.warn(
-          `Failed to clear all cache: ${error instanceof Error ? error.message : String(error)}`
-        );
+        logger.warn(`Failed to clear all cache: ${(0, import_errors.errorMessage)(error)}`);
       }
     });
   }
@@ -180,9 +173,7 @@ class DlxManifest {
       const data = JSON.parse(content);
       return Object.keys(data);
     } catch (error) {
-      logger.warn(
-        `Failed to get package list: ${error instanceof Error ? error.message : String(error)}`
-      );
+      logger.warn(`Failed to get package list: ${(0, import_errors.errorMessage)(error)}`);
       return [];
     }
   }
@@ -224,9 +215,7 @@ class DlxManifest {
           }
         }
       } catch (error) {
-        logger.warn(
-          `Failed to read existing manifest: ${error instanceof Error ? error.message : String(error)}`
-        );
+        logger.warn(`Failed to read existing manifest: ${(0, import_errors.errorMessage)(error)}`);
       }
       data[name] = record;
       const manifestDir = path.dirname(this.manifestPath);
@@ -234,7 +223,7 @@ class DlxManifest {
         (0, import_fs.safeMkdirSync)(manifestDir, { recursive: true });
       } catch (error) {
         logger.warn(
-          `Failed to create manifest directory: ${error instanceof Error ? error.message : String(error)}`
+          `Failed to create manifest directory: ${(0, import_errors.errorMessage)(error)}`
         );
       }
       const content = JSON.stringify(data, null, 2);

package/dist/dlx/package.js

@@ -43,6 +43,7 @@ __export(package_exports, {
 module.exports = __toCommonJS(package_exports);
 var import_platform = require("../constants/platform");
 var import_socket = require("../constants/socket");
+var import_errors = require("../errors");
 var import_arborist = __toESM(require("../external/@npmcli/arborist"));
 var import_libnpmexec = __toESM(require("../external/libnpmexec"));
 var import_npm_package_arg = __toESM(require("../external/npm-package-arg"));
@@ -276,7 +277,7 @@ Ensure the filesystem is writable or set SOCKET_DLX_DIR to a writable location.`
         await checkFirewallPurls(arb, packageName);
         await arb.reify({ save: true });
       } catch (e) {
-        if (e instanceof Error && e.message.startsWith("Socket Firewall blocked")) {
+        if ((0, import_errors.isError)(e) && e.message.startsWith("Socket Firewall blocked")) {
           throw e;
         }
         const code = e?.code;

package/dist/env/socket-cli.d.ts

@@ -63,9 +63,10 @@ export declare function getSocketCliApiProxy(): string | undefined;
  */
 export declare function getSocketCliApiTimeout(): number;
 /**
- * Socket CLI API authentication token (alternative name).
- * Checks SOCKET_CLI_API_TOKEN, SOCKET_CLI_API_KEY, SOCKET_SECURITY_API_TOKEN, SOCKET_SECURITY_API_KEY.
- * Maintains full v1.x backward compatibility.
+ * Socket CLI API authentication token.
+ * Checks SOCKET_API_TOKEN (canonical), then the legacy names
+ * SOCKET_CLI_API_TOKEN, SOCKET_CLI_API_KEY, SOCKET_SECURITY_API_TOKEN,
+ * SOCKET_SECURITY_API_KEY. Maintains full v1.x backward compatibility.
  *
  * @returns API token or undefined
  *

package/dist/env/socket-cli.js

@@ -56,7 +56,7 @@ function getSocketCliApiTimeout() {
 }
 // @__NO_SIDE_EFFECTS__
 function getSocketCliApiToken() {
-  return (0, import_rewire.getEnvValue)("SOCKET_CLI_API_TOKEN") || (0, import_rewire.getEnvValue)("SOCKET_CLI_API_KEY") || (0, import_rewire.getEnvValue)("SOCKET_SECURITY_API_TOKEN") || (0, import_rewire.getEnvValue)("SOCKET_SECURITY_API_KEY");
+  return (0, import_rewire.getEnvValue)("SOCKET_API_TOKEN") || (0, import_rewire.getEnvValue)("SOCKET_CLI_API_TOKEN") || (0, import_rewire.getEnvValue)("SOCKET_CLI_API_KEY") || (0, import_rewire.getEnvValue)("SOCKET_SECURITY_API_TOKEN") || (0, import_rewire.getEnvValue)("SOCKET_SECURITY_API_KEY");
 }
 // @__NO_SIDE_EFFECTS__
 function getSocketCliBootstrapCacheDir() {

package/dist/errors.d.ts

@@ -1,6 +1,100 @@
 /**
  * @fileoverview Error utilities with cause chain support.
- * Provides helpers for working with error causes and stack traces.
+ *
+ * Provides:
+ *   - `isError(value)` — cross-realm-safe Error check (ES2025 `Error.isError`
+ *     when available, `@@toStringTag` fallback otherwise).
+ *   - `errorMessage(value)` — read the message (with cause chain) from any
+ *     caught value, falling back to the shared `UNKNOWN_ERROR` sentinel.
+ *   - `errorStack(value)` — read the stack (with cause chain) from any
+ *     caught value, or `undefined` for non-Errors.
+ *
+ * `messageWithCauses` / `stackWithCauses` are re-exported from pony-cause;
+ * a patched copy recognizes cross-realm Errors via `isError`.
  */
+import { UNKNOWN_ERROR } from './constants/core';
 import { messageWithCauses, stackWithCauses } from './external/pony-cause';
-export { messageWithCauses, stackWithCauses };
+export { UNKNOWN_ERROR, messageWithCauses, stackWithCauses };
+/**
+ * Spec-compliant [`Error.isError`](https://tc39.es/ecma262/#sec-error.iserror)
+ * with a fallback shim for engines that don't ship it yet.
+ *
+ * Returns `true` for Errors from any realm (worker threads, vm contexts,
+ * iframes) — things same-realm `instanceof Error` misses. Plain objects
+ * with `name` + `message` properties are **not** recognized.
+ *
+ * @example
+ * try {
+ *   await doWork()
+ * } catch (e) {
+ *   if (isError(e)) {
+ *     logger.error(e.message)
+ *   } else {
+ *     logger.error(String(e))
+ *   }
+ * }
+ */
+/**
+ * `Error.isError` fallback shim — the in-language approximation used
+ * when the native ES2025 method isn't available.
+ *
+ * Exported separately so test suites on engines that ship the native
+ * method can still exercise the shim branch directly. Consumers should
+ * prefer {@link isError}, which picks the native method when present.
+ */
+export declare function isErrorShim(value: unknown): value is Error;
+/**
+ * Reference to the native ES2025 `Error.isError` when the running
+ * engine ships it, otherwise `undefined`. Exposed separately so tests
+ * and callers can detect the fast-path without re-probing.
+ */
+export declare const isErrorBuiltin: ((value: unknown) => value is Error) | undefined;
+/**
+ * Prefer the native ES2025 `Error.isError` when available (exact
+ * `[[ErrorData]]` slot check, cross-realm-safe); fall back to
+ * {@link isErrorShim} otherwise.
+ */
+export declare const isError: (value: unknown) => value is Error;
+/**
+ * Narrow a caught value to a Node.js `ErrnoException` — an Error with a
+ * `.code` string set by libuv/syscall failures (e.g. `'ENOENT'`,
+ * `'EACCES'`, `'EBUSY'`, `'EPERM'`). Cross-realm safe (builds on
+ * {@link isError}), and checks that `code` is a string so a merely
+ * branded Error without a real errno code returns `false`.
+ *
+ * @example
+ * try {
+ *   await fsPromises.readFile(path)
+ * } catch (e) {
+ *   if (isErrnoException(e) && e.code === 'ENOENT') {
+ *     // … retry, or return default …
+ *   } else {
+ *     throw e
+ *   }
+ * }
+ */
+export declare function isErrnoException(value: unknown): value is NodeJS.ErrnoException;
+/**
+ * Extract a human-readable message from any caught value.
+ *
+ * Walks the `cause` chain for Errors (via {@link messageWithCauses});
+ * coerces primitives and objects to string; returns
+ * {@link UNKNOWN_ERROR} for `null`, `undefined`, empty strings,
+ * `[object Object]`, or Errors with no message.
+ *
+ * @example
+ * try {
+ *   await readConfig(path)
+ * } catch (e) {
+ *   throw new Error(`Failed to read ${path}: ${errorMessage(e)}`, { cause: e })
+ * }
+ */
+export declare function errorMessage(value: unknown): string;
+/**
+ * Extract a stack trace (with causes) from any caught value.
+ *
+ * Returns the cause-aware stack via {@link stackWithCauses} for Errors;
+ * returns `undefined` for non-Error values, so callers can
+ * `logger.error(msg, { stack: errorStack(e) })` safely.
+ */
+export declare function errorStack(value: unknown): string | undefined;

package/dist/errors.js

@@ -20,13 +20,68 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var errors_exports = {};
 __export(errors_exports, {
+  UNKNOWN_ERROR: () => import_core.UNKNOWN_ERROR,
+  errorMessage: () => errorMessage,
+  errorStack: () => errorStack,
+  isErrnoException: () => isErrnoException,
+  isError: () => isError,
+  isErrorBuiltin: () => isErrorBuiltin,
+  isErrorShim: () => isErrorShim,
   messageWithCauses: () => import_pony_cause.messageWithCauses,
   stackWithCauses: () => import_pony_cause.stackWithCauses
 });
 module.exports = __toCommonJS(errors_exports);
+var import_core = require("./constants/core");
 var import_pony_cause = require("./external/pony-cause");
+const ObjectPrototypeToString = Object.prototype.toString;
+const ReflectApply = Reflect.apply;
+function isErrorShim(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  return ReflectApply(ObjectPrototypeToString, value, []) === "[object Error]";
+}
+const isErrorBuiltin = Error.isError;
+const isError = isErrorBuiltin ?? isErrorShim;
+function isErrnoException(value) {
+  if (!isError(value)) {
+    return false;
+  }
+  const code = value.code;
+  if (typeof code !== "string" || code.length === 0) {
+    return false;
+  }
+  const first = code.charCodeAt(0);
+  return first >= 65 && first <= 90;
+}
+function errorMessage(value) {
+  if (isError(value)) {
+    return (0, import_pony_cause.messageWithCauses)(value) || import_core.UNKNOWN_ERROR;
+  }
+  if (value === null || value === void 0) {
+    return import_core.UNKNOWN_ERROR;
+  }
+  const s = String(value);
+  if (s === "" || s === "[object Object]") {
+    return import_core.UNKNOWN_ERROR;
+  }
+  return s;
+}
+function errorStack(value) {
+  if (isError(value)) {
+    return (0, import_pony_cause.stackWithCauses)(value);
+  }
+  return void 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  UNKNOWN_ERROR,
+  errorMessage,
+  errorStack,
+  isErrnoException,
+  isError,
+  isErrorBuiltin,
+  isErrorShim,
   messageWithCauses,
   stackWithCauses
 });

package/dist/external/pony-cause.js

@@ -11,9 +11,9 @@ var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 
-// node_modules/.pnpm/pony-cause@2.1.11/node_modules/pony-cause/lib/error-with-cause.js
+// node_modules/.pnpm/pony-cause@2.1.11_patch_hash=39b2eb2567818b7c60126d03e252dbbabd8738082fca850582300d45b0a8cfb8/node_modules/pony-cause/lib/error-with-cause.js
 var require_error_with_cause = __commonJS({
-  "node_modules/.pnpm/pony-cause@2.1.11/node_modules/pony-cause/lib/error-with-cause.js"(exports2, module2) {
+  "node_modules/.pnpm/pony-cause@2.1.11_patch_hash=39b2eb2567818b7c60126d03e252dbbabd8738082fca850582300d45b0a8cfb8/node_modules/pony-cause/lib/error-with-cause.js"(exports2, module2) {
     "use strict";
     var ErrorWithCause = class _ErrorWithCause extends Error {
       static {
@@ -41,13 +41,14 @@ var require_error_with_cause = __commonJS({
   }
 });
 
-// node_modules/.pnpm/pony-cause@2.1.11/node_modules/pony-cause/lib/helpers.js
+// node_modules/.pnpm/pony-cause@2.1.11_patch_hash=39b2eb2567818b7c60126d03e252dbbabd8738082fca850582300d45b0a8cfb8/node_modules/pony-cause/lib/helpers.js
 var require_helpers = __commonJS({
-  "node_modules/.pnpm/pony-cause@2.1.11/node_modules/pony-cause/lib/helpers.js"(exports2, module2) {
+  "node_modules/.pnpm/pony-cause@2.1.11_patch_hash=39b2eb2567818b7c60126d03e252dbbabd8738082fca850582300d45b0a8cfb8/node_modules/pony-cause/lib/helpers.js"(exports2, module2) {
     "use strict";
+    var isError = typeof Error.isError === "function" ? Error.isError : (v) => v !== null && typeof v === "object" && Object.prototype.toString.call(v) === "[object Error]";
     var findCauseByReference = /* @__PURE__ */ __name((err, reference) => {
       if (!err || !reference) return;
-      if (!(err instanceof Error)) return;
+      if (!isError(err)) return;
       if (!(reference.prototype instanceof Error) && // @ts-ignore
       reference !== Error) return;
       const seen = /* @__PURE__ */ new Set();
@@ -66,13 +67,13 @@ var require_helpers = __commonJS({
       }
       if (typeof err.cause === "function") {
         const causeResult = err.cause();
-        return causeResult instanceof Error ? causeResult : void 0;
+        return isError(causeResult) ? causeResult : void 0;
       } else {
-        return err.cause instanceof Error ? err.cause : void 0;
+        return isError(err.cause) ? err.cause : void 0;
       }
     }, "getErrorCause");
     var _stackWithCauses = /* @__PURE__ */ __name((err, seen) => {
-      if (!(err instanceof Error)) return "";
+      if (!isError(err)) return "";
       const stack = err.stack || "";
       if (seen.has(err)) {
         return stack + "\ncauses have become circular...";
@@ -87,7 +88,7 @@ var require_helpers = __commonJS({
     }, "_stackWithCauses");
     var stackWithCauses = /* @__PURE__ */ __name((err) => _stackWithCauses(err, /* @__PURE__ */ new Set()), "stackWithCauses");
     var _messageWithCauses = /* @__PURE__ */ __name((err, seen, skip) => {
-      if (!(err instanceof Error)) return "";
+      if (!isError(err)) return "";
       const message = skip ? "" : err.message || "";
       if (seen.has(err)) {
         return message + ": ...";
@@ -116,9 +117,9 @@ var require_helpers = __commonJS({
   }
 });
 
-// node_modules/.pnpm/pony-cause@2.1.11/node_modules/pony-cause/index.js
+// node_modules/.pnpm/pony-cause@2.1.11_patch_hash=39b2eb2567818b7c60126d03e252dbbabd8738082fca850582300d45b0a8cfb8/node_modules/pony-cause/index.js
 var require_pony_cause = __commonJS({
-  "node_modules/.pnpm/pony-cause@2.1.11/node_modules/pony-cause/index.js"(exports2, module2) {
+  "node_modules/.pnpm/pony-cause@2.1.11_patch_hash=39b2eb2567818b7c60126d03e252dbbabd8738082fca850582300d45b0a8cfb8/node_modules/pony-cause/index.js"(exports2, module2) {
     "use strict";
     var { ErrorWithCause } = require_error_with_cause();
     var {

package/dist/github.js

@@ -45,6 +45,7 @@ var import_node_process = __toESM(require("node:process"));
 var import_cache_with_ttl = require("./cache-with-ttl");
 var import_github = require("./env/github");
 var import_socket_cli = require("./env/socket-cli");
+var import_errors = require("./errors");
 var import_http_request = require("./http-request");
 var import_spawn = require("./spawn");
 const GITHUB_API_BASE_URL = "https://api.github.com";
@@ -80,7 +81,7 @@ async function fetchRefSha(owner, repo, ref, options) {
         return commitData.sha;
       } catch (e) {
         throw new Error(
-          `failed to resolve ref "${ref}" for ${owner}/${repo}: ${e instanceof Error ? e.message : String(e)}`
+          `failed to resolve ref "${ref}" for ${owner}/${repo}: ${(0, import_errors.errorMessage)(e)}`
         );
       }
     }
@@ -165,7 +166,7 @@ async function fetchGitHub(url, options) {
     return JSON.parse(response.body.toString("utf8"));
   } catch (error) {
     throw new Error(
-      `Failed to parse GitHub API response: ${error instanceof Error ? error.message : String(error)}
+      `Failed to parse GitHub API response: ${(0, import_errors.errorMessage)(error)}
 URL: ${url}
 Response may be malformed or incomplete.`,
       { cause: error }

package/dist/json/edit.js

@@ -35,6 +35,7 @@ __export(edit_exports, {
 module.exports = __toCommonJS(edit_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_promises = require("node:timers/promises");
+var import_errors = require("../errors");
 var import_format = require("./format");
 const identSymbol = import_format.INDENT_SYMBOL;
 const newlineSymbol = import_format.NEWLINE_SYMBOL;
@@ -59,7 +60,7 @@ async function readFile(filepath) {
       return await fsPromises.readFile(filepath, "utf8");
     } catch (err) {
       const isLastAttempt = attempt === maxRetries;
-      const isEnoent = err instanceof Error && "code" in err && err.code === "ENOENT";
+      const isEnoent = (0, import_errors.isErrnoException)(err) && err.code === "ENOENT";
       if (!isEnoent || isLastAttempt) {
         throw err;
       }
@@ -92,7 +93,7 @@ async function retryWrite(filepath, content, retries = 3, baseDelay = 10) {
       return;
     } catch (err) {
       const isLastAttempt = attempt === retries;
-      const isRetriableError = err instanceof Error && "code" in err && (err.code === "EPERM" || err.code === "EBUSY" || err.code === "ENOENT");
+      const isRetriableError = (0, import_errors.isErrnoException)(err) && (err.code === "EPERM" || err.code === "EBUSY" || err.code === "ENOENT");
       if (!isRetriableError || isLastAttempt) {
         throw err;
       }

package/dist/packages/isolation.js

@@ -35,6 +35,7 @@ __export(isolation_exports, {
 module.exports = __toCommonJS(isolation_exports);
 var import_npm_package_arg = __toESM(require("../external/npm-package-arg"));
 var import_platform = require("../constants/platform");
+var import_errors = require("../errors");
 var import_normalize = require("../paths/normalize");
 var import_socket = require("../paths/socket");
 var import_spawn = require("../spawn");
@@ -69,10 +70,9 @@ async function mergePackageJson(pkgJsonPath, originalPkgJson) {
   try {
     pkgJson = JSON.parse(await fs.promises.readFile(pkgJsonPath, "utf8"));
   } catch (error) {
-    throw new Error(
-      `Failed to parse ${pkgJsonPath}: ${error instanceof Error ? error.message : String(error)}`,
-      { cause: error }
-    );
+    throw new Error(`Failed to parse ${pkgJsonPath}: ${(0, import_errors.errorMessage)(error)}`, {
+      cause: error
+    });
   }
   const mergedPkgJson = originalPkgJson ? { ...originalPkgJson, ...pkgJson } : pkgJson;
   return mergedPkgJson;

package/dist/performance.js

@@ -44,6 +44,7 @@ __export(performance_exports, {
 module.exports = __toCommonJS(performance_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_debug = require("./debug");
+var import_errors = require("./errors");
 const performanceMetrics = [];
 function isPerfEnabled() {
   return import_node_process.default.env["DEBUG"]?.includes("perf") || false;
@@ -128,7 +129,7 @@ async function measure(operation, fn, metadata) {
   } catch (e) {
     stop({
       success: false,
-      error: e instanceof Error ? e.message : "Unknown"
+      error: (0, import_errors.errorMessage)(e)
     });
     throw e;
   }
@@ -143,7 +144,7 @@ function measureSync(operation, fn, metadata) {
   } catch (e) {
     stop({
       success: false,
-      error: e instanceof Error ? e.message : "Unknown"
+      error: (0, import_errors.errorMessage)(e)
     });
     throw e;
   }

package/dist/process-lock.js

@@ -23,6 +23,7 @@ __export(process_lock_exports, {
   processLock: () => processLock
 });
 module.exports = __toCommonJS(process_lock_exports);
+var import_errors = require("./errors");
 var import_fs = require("./fs");
 var import_logger = require("./logger");
 var import_promises = require("./promises");
@@ -87,9 +88,7 @@ class ProcessLockManager {
         fs.utimesSync(lockPath, now, now);
       }
     } catch (error) {
-      logger.warn(
-        `Failed to touch lock ${lockPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
+      logger.warn(`Failed to touch lock ${lockPath}: ${(0, import_errors.errorMessage)(error)}`);
     }
   }
   /**
@@ -277,9 +276,7 @@ To resolve:
       }
       this.activeLocks.delete(lockPath);
     } catch (error) {
-      logger.warn(
-        `Failed to release lock ${lockPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
+      logger.warn(`Failed to release lock ${lockPath}: ${(0, import_errors.errorMessage)(error)}`);
     }
   }
   /**

package/dist/releases/github.js

@@ -43,6 +43,7 @@ module.exports = __toCommonJS(github_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_picomatch = __toESM(require("../external/picomatch"));
 var import_archives = require("../archives");
+var import_errors = require("../errors");
 var import_fs = require("../fs");
 var import_http_request = require("../http-request");
 var import_logger = require("../logger");
@@ -341,7 +342,7 @@ async function getLatestRelease(toolPrefix, repoConfig, options = {}) {
             `Retry attempt ${attempt + 1}/${RETRY_CONFIG.retries + 1} for ${toolPrefix} release...`
           );
           logger.warn(
-            `Attempt ${attempt + 1}/${RETRY_CONFIG.retries + 1} failed: ${error instanceof Error ? error.message : String(error)}`
+            `Attempt ${attempt + 1}/${RETRY_CONFIG.retries + 1} failed: ${(0, import_errors.errorMessage)(error)}`
           );
         }
         return void 0;
@@ -395,7 +396,7 @@ async function getReleaseAssetUrl(tag, assetPattern, repoConfig, options = {}) {
             `Retry attempt ${attempt + 1}/${RETRY_CONFIG.retries + 1} for asset URL...`
           );
           logger.warn(
-            `Attempt ${attempt + 1}/${RETRY_CONFIG.retries + 1} failed: ${error instanceof Error ? error.message : String(error)}`
+            `Attempt ${attempt + 1}/${RETRY_CONFIG.retries + 1} failed: ${(0, import_errors.errorMessage)(error)}`
           );
         }
         return void 0;

package/dist/releases/socket-btm.d.ts

@@ -126,18 +126,74 @@ export declare function getBinaryAssetName(binaryBaseName: string, platform: Pla
  */
 export declare function getBinaryName(binaryBaseName: string, platform: Platform): string;
 /**
- * Get platform-arch identifier for directory structure.
- * Uses 'win' instead of 'win32' for file/folder names.
+ * Get platform-arch identifier for directory structure and asset names.
+ *
+ * # Format: `<os>-<arch>[-<libc>]`
+ *
+ * The OS segment is `process.platform` verbatim: `darwin` / `linux` /
+ * `win32`. The arch segment is `process.arch` verbatim: `x64` / `arm64`.
+ * The optional libc suffix is `-musl` (Linux only; the glibc default is
+ * unsuffixed to match Node.js's own linuxstatic convention).
+ *
+ * # Why these specific conventions
+ *
+ * ## Why `win32`, not `win`
+ *
+ * `win32` is what `process.platform` returns on every Windows host. Every
+ * npm package whose install-time platform filter uses the standard
+ * `os` / `cpu` / `libc` manifest fields must match `process.platform`
+ * strings exactly (npm compares them verbatim — there's no shorthand
+ * layer). Using `win` internally here would have forced a translation
+ * every time we constructed an install filter or a target triple, and
+ * reviewers would have to remember "we abbreviate on disk but not in
+ * package filters." Since the two now match, there's no translation
+ * step to get wrong.
+ *
+ * pnpm's pack-app (v11+) accepts `<os>-<arch>[-<libc>]` target strings
+ * and its shards are `@pnpm/exe.<os>-<arch>` (with `win32`, not `win` —
+ * see pnpm#11314). Our naming matches so asset names we emit can flow
+ * directly into pack-app's `--target` arg, `pnpm.app.targets` config,
+ * and sibling-package-name construction without a translation map.
+ *
+ * ## Why `-musl` is the suffix (and glibc is unsuffixed)
+ *
+ * Node.js's own linuxstatic tarballs historically used the unqualified
+ * `linux` for glibc and a separate download channel for musl. The pnpm
+ * ecosystem codified that as `linux-<arch>` (glibc, default) and
+ * `linux-<arch>-musl` (the libc outlier), matching the asymmetric
+ * reality of Linux distros — glibc is the majority case, musl is
+ * Alpine-and-similar. Adding `-glibc` for the default would be
+ * redundant noise in the name.
+ *
+ * ## Why libc is only appended for Linux
+ *
+ * macOS and Windows have exactly one system libc each (Apple libSystem,
+ * Microsoft UCRT). A hypothetical `darwin-arm64-libsystem` conveys no
+ * information. Node.js, npm, and pnpm all treat libc as a Linux-only
+ * axis; we follow the same convention so callers don't have to special-
+ * case `'darwin-arm64'.startsWith('darwin-arm64')` style matches.
+ *
+ * ## Why this function exists at all (vs. inlining)
+ *
+ * Two upstream APIs that socket-btm consumers end up calling — the
+ * npm manifest filter (`os`/`cpu`/`libc`) and pnpm's pack-app
+ * `--target` — both need the exact same triple format. Centralizing
+ * the construction here means a future schema change (e.g. Node
+ * introducing `riscv64`) gets one edit, and the error message for an
+ * unsupported platform is uniform across downloaders, pack-app
+ * invocations, and the `@socketbin/*` resolver logic.
  *
  * @param platform - Target platform
  * @param arch - Target architecture
- * @param libc - Linux libc variant (optional)
- * @returns Platform-arch identifier (e.g., 'darwin-arm64', 'linux-x64-musl', 'win-x64')
+ * @param libc - Linux libc variant (optional; non-linux platforms ignore)
+ * @returns Platform-arch identifier (e.g., 'darwin-arm64', 'linux-x64-musl', 'win32-x64')
  *
  * @example
  * ```typescript
  * getPlatformArch('linux', 'x64', 'musl')  // 'linux-x64-musl'
- * getPlatformArch('darwin', 'arm64')  // 'darwin-arm64'
+ * getPlatformArch('darwin', 'arm64')       // 'darwin-arm64'
+ * getPlatformArch('win32', 'x64')          // 'win32-x64'
+ * getPlatformArch('darwin', 'x64', 'musl') // 'darwin-x64' — libc ignored
  * ```
  */
 export declare function getPlatformArch(platform: Platform, arch: Arch, libc?: Libc | undefined): string;

package/dist/releases/socket-btm.js

@@ -38,7 +38,7 @@ const PLATFORM_MAP = {
   __proto__: null,
   darwin: "darwin",
   linux: "linux",
-  win32: "win"
+  win32: "win32"
 };
 const ARCH_MAP = {
   __proto__: null,
@@ -185,7 +185,7 @@ function getBinaryAssetName(binaryBaseName, platform, arch, libc) {
     return `${binaryBaseName}-linux-${mappedArch}${muslSuffix}${ext}`;
   }
   if (platform === "win32") {
-    return `${binaryBaseName}-win-${mappedArch}${ext}`;
+    return `${binaryBaseName}-win32-${mappedArch}${ext}`;
   }
   throw new Error(`Unsupported platform: ${platform}`);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.21.0",
-  "packageManager": "pnpm@11.0.0-rc.2",
+  "version": "5.23.0",
+  "packageManager": "pnpm@11.0.0-rc.5",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
   "keywords": [
@@ -724,7 +724,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.4.2",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.20.1",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.21.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20260415.1",
     "@vitest/coverage-v8": "4.0.3",