v5.7.0

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

5.7.0 - 2026-02-12

Added

• env: Added isInEnv() helper function to check if an environment variable key exists, regardless of its value

  • Returns true even for empty strings, "false", "0", etc.
  • Follows same override resolution order as getEnvValue() (isolated overrides → shared overrides → process.env)
  • Useful for detecting presence of environment variables independent of their value

• dlx: Added new exported helper functions

  • downloadBinaryFile() - Downloads a binary file from a URL to the dlx cache directory
  • ensurePackageInstalled() - Ensures an npm package is installed and cached via Arborist
  • getBinaryCacheMetadataPath() - Gets the file path to dlx binary cache metadata (.dlx-metadata.json)
  • isBinaryCacheValid() - Checks if a cached dlx binary is still valid based on TTL and timestamp
  • makePackageBinsExecutable() - Makes npm package binaries executable on Unix systems
  • parsePackageSpec() - Parses npm package spec strings (e.g., pkg@1.0.0) into name and version
  • resolveBinaryPath() - Resolves the absolute path to a binary within an installed package
  • writeBinaryCacheMetadata() - Writes dlx binary cache metadata with integrity, size, and source info

• releases: Added createAssetMatcher() utility function for GitHub release asset pattern matching

  • Creates matcher functions that test strings against glob patterns, prefix/suffix, or RegExp
  • Used for dynamic asset discovery in GitHub releases (e.g., matching platform-specific binaries)

Changed

• env: Updated getCI() to use isInEnv() for more accurate CI detection
  • Now returns true whenever the CI key exists in the environment, not just when truthy
  • Matches standard CI detection behavior where the presence of the key (not its value) indicates a CI environment

Fixed

• github: Fixed JSON parsing crash vulnerability by adding try-catch around JSON.parse() in GitHub API responses

  • Prevents crashes on malformed, incomplete, or binary responses
  • Error messages now include the response URL for better debugging

• dlx/binary: Fixed clock skew vulnerabilities in cache validation

  • Cache entries with future timestamps (clock skew) are now treated as expired
  • Metadata writes now use atomic write-then-rename pattern to prevent corruption
  • Added TOCTOU race protection by re-checking binary existence after metadata read

• dlx/cache cleanup: Fixed handling of future timestamps during cache cleanup

  • Entries with future timestamps (due to clock skew) are now properly treated as expired

• dlx/package: Fixed scoped package parsing bug where @scope/package was incorrectly parsed

  • Changed condition from startsWith('@') to atIndex === 0 for more precise detection
  • Fixes installation failures for scoped packages like @socketregistry/lib

• cache-with-ttl: Added clock skew detection to TTL cache

  • Far-future expiresAt values (>2x TTL) are now treated as expired
  • Protects against cache poisoning from clock skew

• packages/specs: Fixed unconditional .git truncation in Git URL parsing

  • Now only removes .git suffix when URL actually ends with .git
  • Prevents incorrect truncation of URLs containing .git in the middle

• releases/github: Fixed TOCTOU race condition in binary download verification

  • Re-checks binary existence after reading version file
  • Ensures binary is re-downloaded if missing despite version file presence

• provenance: Fixed incorrect package name in provenance workflow

  • Changed from @socketregistry/lib to @socketsecurity/lib

5.6.0 - 2026-02-08

Added

• http-request: Added automatic default headers for JSON and text requests
  • httpJson() now automatically sets Accept: application/json header
  • httpJson() automatically sets Content-Type: application/json when body is present
  • httpText() now automatically sets Accept: text/plain header
  • httpText() automatically sets Content-Type: text/plain when body is present
  • User-provided headers always override defaults
  • Simplifies API usage - no need to manually set common headers

Changed

• http-request: Renamed HTTP helper functions to support all HTTP methods (BREAKING CHANGE)
  • httpGetJson() → httpJson() - Now supports GET, POST, PUT, DELETE, PATCH, etc.
  • httpGetText() → httpText() - Now supports all HTTP methods via method option
  • Functions now accept method parameter in options (defaults to 'GET')
  • More flexible API that matches modern fetch-style conventions
  • Migration: Replace httpGetJson() calls with httpJson() and httpGetText() with httpText()

Fixed

• http-request: Fixed Content-Type header incorrectly sent with empty string body
  • Empty string body ("") no longer triggers Content-Type header
  • Changed condition from if (body !== undefined) to if (body) for semantic correctness
  • Empty string represents "no content" and should not declare a Content-Type
  • Affects httpJson() and httpText() functions
  • Fixes potential API compatibility issues with servers expecting no Content-Type for empty bodies
  • Added comprehensive test coverage for empty string edge case

5.5.3 - 2026-01-20

Fixed

• deps: Added patch for execa@2.1.0 to fix signal-exit v4 compatibility. The package was using default import syntax with signal-exit v4, which now exports onExit as a named export.

5.5.2 - 2026-01-20

Changed

• dlx/package: Use getSocketCacacheDir() instead of getPacoteCachePath() for Arborist cache configuration
  • Ensures consistent use of Socket's shared cacache directory (~/.socket/_cacache)
  • Removes dependency on pacote cache path extraction which could fail
  • Simplifies cache configuration by using reliable Socket path utility

5.5.1 - 2026-01-12

Fixed

• Fixed dotenvx compatibility with pre-commit hooks
• Fixed empty releases being returned when finding latest release

5.5.0 - 2026-01-12

Added

• dlx/detect: Executable type detection utilities for DLX cache and local file paths
  • detectDlxExecutableType(): Detects Node.js packages vs native binaries in DLX cache by checking for node_modules/ directory
  • detectExecutableType(): Generic entry point that routes to appropriate detection strategy
  • detectLocalExecutableType(): Detects executables on local filesystem by checking package.json bin field or file extension
  • isJsFilePath(): Validates if a file path has .js, .mjs, or .cjs extension
  • isNativeBinary(): Simplified helper that returns true for native binary executables
  • isNodePackage(): Simplified helper that returns true for Node.js packages

Fixed

• releases/github: Sort releases by published_at to reliably find latest release instead of relying on creation order

5.4.1 - 2026-01-10

Fixed

• build: Removed debug module stub to bundle real debug package. The stub was missing enable() and disable() methods, causing errors when downstream projects re-bundled the lib.

5.4.0 - 2026-01-07

Added

• releases/github: Extended release functions to accept glob patterns for asset discovery

  • getReleaseAssetUrl() now accepts glob patterns: 'yoga-sync-*.mjs', 'models-*.tar.gz'
  • downloadReleaseAsset() now accepts glob patterns for automatic asset discovery
  • getLatestRelease() now accepts asset patterns to find releases with matching assets
  • Supports wildcards, brace expansion, RegExp patterns, and prefix/suffix objects
  • Uses picomatch for robust glob pattern matching

• releases/socket-btm: Extended downloadSocketBtmRelease() to accept glob patterns

  • asset parameter now accepts wildcards: 'yoga-sync-*.mjs', 'models-*.tar.gz'
  • Automatically discovers and downloads latest matching asset
  • Eliminates need for hardcoded asset names in build scripts

5.3.0 - 2026-01-07

Added

• releases/socket-btm: Exported helper functions for external use

  • detectLibc(): Detect musl vs glibc on Linux systems
  • getBinaryAssetName(): Get GitHub asset name for platform/arch
  • getBinaryName(): Get binary filename with platform-appropriate extension
  • getPlatformArch(): Get platform-arch identifier for directory structure

• releases/github: Exported getAuthHeaders() for GitHub API authentication

  • Returns headers with Accept, X-GitHub-Api-Version, and optional Authorization
  • Checks GH_TOKEN and GITHUB_TOKEN environment variables

5.2.1 - 2026-01-06

Fixed

• releases: Fixed "Text file busy" errors when executing downloaded binaries
  • Changed downloadGitHubRelease() to use synchronous chmodSync() instead of async chmod()
  • Ensures file system operations complete before binary execution
  • Prevents race conditions in CI/CD environments where async operations may not fully flush to disk

5.2.0 - 2026-01-06

Added

• releases: Added GitHub release download utilities for cross-project use
  • Added downloadGitHubRelease() for downloading releases from any GitHub repository
  • Added downloadSocketBtmRelease() specialized wrapper for socket-btm releases
  • Features version caching with .version files to avoid redundant downloads
  • Supports cross-platform binary downloads (darwin, linux, win32) with automatic platform/arch detection
  • Includes Linux musl/glibc support with musl as default for broader compatibility
  • Automatically removes macOS quarantine attributes from downloaded binaries
  • Supports generic asset downloads (WASM files, models, etc.)
  • API inspired by industry tools: brew, cargo, gh for intuitive usage
  • Package exports: @socketsecurity/lib/releases/github and @socketsecurity/lib/releases/socket-btm

5.1.4 - 2025-12-30

Fixed

• dependencies: Removed unnecessary http2 module dependency from @sigstore/sign@4.1.0
  • Added pnpm override to force @sigstore/sign@4.1.0 across all dependencies
  • Created patch to inline HTTP header and status constants instead of importing http2 module
  • Eliminates loading of Node.js http2 module for HTTP/1.1-only operations

5.1.3 - 2025-12-29

Fixed

• http-request: Fixed httpDownload() to properly handle HTTP redirects (3xx status codes)
  • Added followRedirects option (default: true) to enable automatic redirect following
  • Added maxRedirects option (default: 5) to limit redirect chain length
  • Now supports downloading from services that use CDN redirects, such as GitHub release assets
  • Prevents GitHub API quota exhaustion by following browser_download_url redirects instead of using API endpoints
  • Resolves "Request quota exhausted" errors when downloading GitHub release assets

5.1.2 - 2025-12-28

Fixed

• paths: Fixed missing getPathValue() caching in getSocketDlxDir()
  • Now uses getPathValue() for performance, consistent with getSocketUserDir() and getSocketCacacheDir()
  • Adds test override support via setPath('socket-dlx-dir', ...)
  • Test helper mockHomeDir() now properly invalidates path cache with resetPaths() calls
  • Resolves cache persistence issues in test environments

5.1.1 - 2025-12-28

Added

• paths: Added SOCKET_HOME environment variable support to customize Socket base directory
  • getSocketUserDir() now checks SOCKET_HOME before defaulting to ~/.socket
  • getSocketDlxDir() inherits SOCKET_HOME support (priority: SOCKET_DLX_DIR > SOCKET_HOME/_dlx > ~/.socket/_dlx)
  • Enables flexible directory configuration for restricted or custom environments

Changed

• paths: Enhanced directory resolution with temporary directory fallback
  • getUserHomeDir() now falls back to os.tmpdir() when home directory is unavailable
  • Improves resilience in containerized and restricted environments
  • Priority order: HOME > USERPROFILE > os.homedir() > os.tmpdir()

5.1.0 - 2025-12-17

Added

• types: Added ALPM and VSCODE to PURL_Type enum
  • ALPM: Arch Linux Package Manager ecosystem
  • VSCODE: Visual Studio Code extensions ecosystem

5.0.2 - 2025-12-15

Changed

• signal-exit: signals() now auto-initializes its internal state
  • Commit: 8cb0576

5.0.1 - 2025-12-11

Added

• http-request: Enhanced httpDownload() with automatic progress logging via Logger integration
  • New logger option: Pass a Logger instance for automatic progress tracking
  • New progressInterval option: Configure progress reporting frequency (default: 10%)
  • Progress format: Progress: XX% (Y.Y MB / Z.Z MB)
  • onProgress callback takes precedence over logger when both are provided
  • Commit: 91e5db5

5.0.0 - 2025-12-04

Added

• json/edit: New EditableJson base class for generic JSON file manipulation with formatting preservation

  • Extracted from EditablePackageJson to enable code reuse via composition pattern
  • Supports reading, modifying, and writing JSON files while preserving formatting
  • Export: @socketsecurity/lib/json/edit

• json/format: New JSON formatting utilities for consistent JSON manipulation

  • Functions for analyzing and preserving JSON formatting patterns
  • Export: @socketsecurity/lib/json/format

• json/parse: New JSON parsing utilities

  • isJsonPrimitive(): Check if value is a JSON primitive type
  • jsonParse(): Parse JSON with error handling
  • Export: @socketsecurity/lib/json/parse

• json/types: New JSON type definitions and interfaces

  • Export: @socketsecurity/lib/json/types

• dlx/cache: New DLX cache utilities

  • generateCacheKey(): Generate cache keys for DLX packages
  • Export: @socketsecurity/lib/dlx/cache

• dlx/dir: New DLX directory management utilities

  • clearDlx(), clearDlxSync(): Clear DLX directory
  • dlxDirExists(), dlxDirExistsAsync(): Check if DLX directory exists
  • ensureDlxDir(), ensureDlxDirSync(): Ensure DLX directory exists
  • Export: @socketsecurity/lib/dlx/dir

• dlx/packages: New DLX package management utilities

  • isDlxPackageInstalled(), isDlxPackageInstalledAsync(): Check if package is installed
  • listDlxPackages(), listDlxPackagesAsync(): List installed packages
  • removeDlxPackage(), removeDlxPackageSync(): Remove installed packages
  • Export: @socketsecurity/lib/dlx/packages

• dlx/paths: New DLX path utilities

  • getDlxPackageDir(): Get package directory path
  • getDlxInstalledPackageDir(): Get installed package directory path
  • getDlxPackageJsonPath(): Get package.json path
  • getDlxPackageNodeModulesDir(): Get node_modules directory path
  • isInSocketDlx(): Check if path is in DLX directory
  • Export: @socketsecurity/lib/dlx/paths

Changed

• BREAKING: Reorganized module paths for better structure and discoverability

  • @socketsecurity/lib/json/editable → @socketsecurity/lib/json/edit
  • @socketsecurity/lib/packages/editable → @socketsecurity/lib/packages/edit
  • @socketsecurity/lib/maintained-node-versions → @socketsecurity/lib/constants/maintained-node-versions
  • @socketsecurity/lib/package-default-node-range → @socketsecurity/lib/constants/package-default-node-range
  • @socketsecurity/lib/package-default-socket-categories → @socketsecurity/lib/constants/package-default-socket-categories
  • @socketsecurity/lib/lifecycle-script-names → @socketsecurity/lib/constants/lifecycle-script-names
  • @socketsecurity/lib/dlx → Split into @socketsecurity/lib/dlx/cache, @socketsecurity/lib/dlx/dir, @socketsecurity/lib/dlx/packages, @socketsecurity/lib/dlx/paths
  • @socketsecurity/lib/dlx-binary → @socketsecurity/lib/dlx/binary
  • @socketsecurity/lib/dlx-manifest → @socketsecurity/lib/dlx/manifest
  • @socketsecurity/lib/dlx-package → @socketsecurity/lib/dlx/package

• json: Reorganized JSON utilities into modular submodules (json/edit, json/format, json/parse, json/types)

  • Removed barrel index file in favor of direct submodule imports
  • Better separation of concerns and tree-shaking

• dlx: Split monolithic DLX module into focused submodules (cache, dir, packages, paths)

  • Improved modularity and maintainability
  • Better code organization and discoverability

4.4.0 - 2025-11-25

Added

• fs: Exported normalizeEncoding() function for robust encoding string normalization
  • Handles case-insensitive encoding names (e.g., 'UTF-8', 'utf8', 'UTF8')
  • Supports encoding aliases (e.g., 'binary' → 'latin1', 'ucs-2' → 'utf16le')
  • Fast-path optimization for common encodings
  • Defaults to 'utf8' for invalid or null encodings
  • Export: @socketsecurity/lib/fs

Fixed

• fs: safeReadFile() and safeReadFileSync() type signatures and encoding handling

  • Corrected type overloads: encoding: null → Buffer | undefined, no encoding → string | undefined (UTF-8 default)
  • Fixed implementation to properly handle encoding: null for Buffer returns

• suppress-warnings: withSuppressedWarnings() now properly restores warning state

  • Fixed state restoration to only remove warning types that were added by the function
  • Prevents accidental removal of warnings that were already suppressed
  • Ensures correct cleanup behavior when warning types are nested or reused

4.3.0 - 2025-11-20

Added

• globs: New glob() and globSync() wrapper functions for fast-glob
  • Provides convenient wrappers around fast-glob with normalized options
  • Maintains consistent API with existing glob functionality
  • Export: @socketsecurity/lib/globs

4.1.0 - 2025-11-17

Added

• constants/node: New version helper functions for cleaner version detection
  • getNodeMinorVersion(): Extract minor version number
  • getNodePatchVersion(): Extract patch version number

Fixed

• constants/node: Improve Node.js flag management in getNodeHardenFlags()
  • Properly guard --experimental-permission for Node 20-23 only
  • Properly guard --permission for Node 24+ only
  • Properly guard --force-node-api-uncaught-exceptions-policy for Node 22+ (was incorrectly applied to all versions)
  • Automatically include permission grants from getNodePermissionFlags() for Node 24+
  • Remove --experimental-policy flag (no policy file provided)

4.0.1 - 2025-11-17

Changed

• Removed # path imports and replaced with relative paths

4.0.0 - 2025-11-15

Changed

• paths: Reorganized path utilities into dedicated paths/* submodules for improved modularity
• imports: Converted lazy require() calls to ES6 static imports for better tree-shaking and bundler compatibility

3.5.0 - 2025-11-14

Added

• argv/quote: New utilities for quoting command-line arguments when using spawn() with shell: true
  • posixQuote(arg): Quote arguments for POSIX shells (bash, sh, zsh) using single quotes
  • win32Quote(arg): Quote arguments for Windows cmd.exe using double quotes

3.4.0 - 2025-11-14

Added

• Spinner: New skip() and skipAndStop() methods for displaying skipped operations

  • skip(text): Display skip message alongside spinner (e.g., "Skipping optional step...")
  • skipAndStop(text): Display skip message and stop spinner in one call
  • Uses cyan ↻ (refresh/reload) symbol with @ ASCII fallback
  • Normalizes text formatting consistently with other spinner methods
  • Useful for communicating skipped steps during long-running operations

• Logger: New skip() method and symbol for skipped operations

  • LOG_SYMBOLS.skip: New cyan ↻ symbol for skip output (@ ASCII fallback)
  • skip(message): Display skip messages with dedicated symbol
  • Complements existing info/step/success/error/warning/reason methods

3.3.11 - 2025-11-14

Fixed

• prompts: Fix "inquirerPrompt is not a function" error in interactive prompts
  • Properly handle inquirer modules with multiple exports (select, search)

3.3.10 - 2025-11-14

Fixed

• deps: Add string-width and wrap-ansi overrides for bundling compatibility
  • Forces string-width@8.1.0 and wrap-ansi@9.0.2 for compatibility with strip-ansi@7.1.2

3.3.9 - 2025-11-14

Fixed

• deps: Add strip-ansi override to fix bundling compatibility
  • Forces strip-ansi@7.1.2 for compatibility with ansi-regex@6.2.2

3.3.8 - 2025-11-14

Fixed

• spinner: Clear remaining artifacts after withSpinner stops
  • Fixed rogue spinner characters persisting after spinner completes

3.3.7 - 2025-11-13

Changed

• refactor: Add explicit .js extensions to external require calls
  • Improves module resolution clarity and compatibility with modern bundlers
  • Updated 18 require calls across 10 source files

3.3.6 - 2025-11-13

Changed

• deps: Add pnpm overrides to consolidate package versions
  • Force single versions: @npmcli/arborist@9.1.6, @npmcli/run-script@10.0.0, semver@7.7.2, ansi-regex@6.2.2, lru-cache@11.2.2
  • Update patch from @npmcli/run-script@9.1.0 to @npmcli/run-script@10.0.0
  • Reduces duplicate dependencies and potential version conflicts

3.3.5 - 2025-11-13

Fixed

• build: Add patches to prevent node-gyp bundling issues

3.3.4 - 2025-11-13

Fixed

• build: Mark node-gyp as external in npm-pack bundle

3.3.3 - 2025-11-13

Fixed

• build: Break node-gyp string to prevent bundler issues with ESM/CJS interop

3.3.2 - 2025-11-13

Changed

• dlx: Install package dependencies after download
• external: Optimize npm package bundle sizes (~3MB reduction)

3.3.1 - 2025-11-11

Added

• Added SOCKET_DOCS_CONTACT_URL constant for documentation contact support page
• Added checkbox prompt support

3.3.0 - 2025-11-07

Added

• Spinner: New reason() and reasonAndStop() methods for displaying working/thinking output

  • reason(text): Display reason text alongside spinner (e.g., "Analyzing dependencies...")
  • reasonAndStop(text): Display reason text and stop spinner in one call
  • Normalizes text formatting consistently with other spinner methods
  • Useful for communicating progress steps during long-running operations

• Logger: New reason() method and symbol for working/thinking output

  • LOG_SYMBOLS.reason: New symbol for reason output (distinct from info/step symbols)
  • reason(message): Display reason messages with dedicated symbol
  • Complements existing info/step/success/error/warning methods

3.2.8 - 2025-11-05

Fixed

• build: Fix CommonJS export script edge cases
  • Fixed stray semicolons after comment placeholders in transformed modules
  • Fixed incorrect transformation of module.exports.default to module.module.exports
  • Ensures external dependencies and default exports work correctly

3.2.7 - 2025-11-05

Fixed

• build-externals: Disable minification to preserve exports

  • External dependencies are no longer minified during bundling
  • Prevents export name mangling that breaks CommonJS interop
  • Fixes semver.parse() and semver.major() being undefined

• build: Fix CommonJS export interop for TypeScript default exports

  • Modules with export default now work without requiring .default accessor

Changed

• docs: Moved packages README to correct location (src/packages/README.md)

3.2.6 - 2025-11-05

Fixed

• logger: Replace yoctocolors-cjs rgb() with manual ANSI codes
  • The yoctocolors-cjs package doesn't have an rgb() method
  • Manually construct ANSI escape sequences for RGB colors (ESC[38;2;r;g;bm...ESC[39m)
  • Affects src/logger.ts and src/stdio/prompts.ts applyColor() functions

3.2.5 - 2025-11-05

Added

• scripts: Add path alias resolution script (fix-path-aliases.mjs)

  • Resolves internal path aliases (#lib/*, #constants/*, etc.) to relative paths in built CommonJS files

• build: Integrate path alias resolution into build pipeline

  • Add path alias plugin to esbuild config
  • Integrate fix-path-aliases.mjs into build process
  • Ensures path aliases work correctly in compiled CommonJS output

3.2.4 - 2025-11-04

Added

• Logger: New time() method for timing operations with automatic duration reporting
  • Starts a named timer and returns a stop() function
  • Automatically logs completion with formatted duration (e.g., "Operation completed in 1.23s")
  • Useful for performance monitoring and debugging

Fixed

• Spinner effects: Fixed star spinner frames by adding trailing space for consistent spacing
• Build system: Fixed external dependency bundling issues
  • Bundle @npmcli/package-json with subpath exports support
  • Use src/external files as bundle entry points for proper module resolution
  • Bundle libnpmexec from npm instead of using vendored version
  • Prevent circular dependencies with createForceNodeModulesPlugin() to force resolution from node_modules

3.2.3 - 2025-11-03

Internal

• Build system: Added stub infrastructure for external dependency bundling
  • Created organized scripts/build-externals/stubs/ directory with utility and active stubs
  • Added conservative stubs for unused dependencies: encoding/iconv-lite and debug
  • Reduces external bundle size by ~18KB (9KB from encoding stubs, 9KB from debug stubs)

3.2.2 - 2025-11-03

Added

• DLX: Binary permission management with chmod 0o755 for all package binaries

  • New makePackageBinsExecutable() function ensures all binaries in installed packages are executable
  • Aligns with npm's cmd-shim approach for binary permissions
  • Handles both single and multiple binary packages
  • No-op on Windows (permissions not needed)

• DLX: npm-compatible bin resolution via vendored getBinFromManifest

  • Cherry-picked getBinFromManifest from libnpmexec@10.1.8 (~1.5 KB)
  • Avoids 1.1 MB bundle by vendoring single function instead of full package
  • Provides battle-tested npm bin resolution strategy
  • Maintains user-friendly fallbacks for edge cases

Changed

• DLX: Enhanced findBinaryPath() with npm's resolution strategy
  • Primary: npm's getBinFromManifest (handles standard cases and aliases)
  • Fallback: user-provided binaryName parameter
  • Fallback: last segment of package name
  • Last resort: first binary in list

Performance

• Optimized package size: Reduced bundle size through strategic export minimization and vendoring
  • Vendored getBinFromManifest function instead of bundling full libnpmexec (~1.1 MB savings)
  • Minimized external module exports for better tree-shaking:
    • fast-sort: Now exports only { createNewSortInstance } (2.1 KB, 96% reduction from ~56 KB)
    • fast-glob: Now exports only { globStream } (82 KB bundle)
    • del: Now exports only { deleteAsync, deleteSync } (100 KB bundle)
    • streaming-iterables: Now exports only { parallelMap, transform } (11 KB, 93% reduction from ~168 KB)
  • Total savings: ~1.3 MB (1.1 MB from vendoring + 211 KB from minimized exports)
  • Establishes pattern for future external module additions

3.2.1 - 2025-11-02

Changed

• Logger/Spinner: Use module-level constants to prevent duplicate and rogue spinner indicators
  • Call getDefaultLogger() and getDefaultSpinner() once at module scope instead of repeated calls
  • Prevents multiple spinner instances that can cause duplicate or lingering indicators in terminal output
  • Applied in src/dlx-manifest.ts, src/stdio/mask.ts, and src/spinner.ts
  • Follows DRY principle and aligns with socket-registry/socket-sdk-js patterns

Fixed

• Scripts: Fixed undefined logger variable in update script
  • Replaced undefined log references with _logger throughout scripts/update.mjs
  • Resolves ESLint errors that blocked test execution
• Tests: Improved stdout test stability by checking call delta instead of absolute counts
  • Fixed flaky CI failures where spy call count was 101 instead of expected 100
  • More robust approach handles potential state leakage between tests
• Tests: Removed unnecessary 10ms delay in cache-with-ttl test
  • Cache with memoization enabled updates in-memory storage synchronously
  • Delay was insufficient in CI and unnecessary given synchronous behavior
  • Resolves flaky CI failures where cached values returned undefined

3.2.0 - 2025-11-02

Added

• DLX: Unified manifest for packages and binaries
  • Centralized manifest system for tracking DLX-compatible packages
  • Simplifies package and binary lookups for dependency-free execution

3.1.3 - 2025-11-02

Changed

• Dependencies: Updated @socketregistry/packageurl-js to 1.3.5

3.1.2 - 2025-11-02

Fixed

• External dependencies: Fixed incorrectly marked external dependencies to use wrapper pattern
  • Updated src/constants/agents.ts to use require('../external/which') instead of direct imports
  • Updated src/zod.ts to export from ./external/zod' instead of direct imports
  • Maintains zero dependencies policy by ensuring all runtime dependencies go through the external wrapper pattern
• Spinner: Fixed undefined properties in setShimmer by handling defaults correctly

3.1.1 - 2025-11-02

Fixed

• Cache TTL: Fixed flaky test by handling persistent cache write failures gracefully
  • Wrapped cacache.put in try/catch to prevent failures when persistent cache writes fail or are slow
  • In-memory cache is updated synchronously before the persistent write, so immediate reads succeed regardless of persistent cache state
  • Improves reliability in test environments and when cache directory has issues

3.1.0 - 2025-11-01

Changed

• File system utilities: safeMkdir and safeMkdirSync now default to recursive: true
  • Nested directories are created by default, simplifying common usage patterns

3.0.6 - 2025-11-01

Added

• Build validation: Added guard against link: protocol dependencies in package.json
  • New validate-no-link-deps.mjs script automatically runs during pnpm run check
  • Prevents accidental publication with link: dependencies which can cause issues
  • Recommends using workspace: for monorepos or catalog: for centralized version management
  • Validates all dependency fields: dependencies, devDependencies, peerDependencies, optionalDependencies

Changed

• Dependencies: Updated @socketregistry/packageurl-js to 1.3.3
• Git hooks: Committed pre-commit and pre-push hook configurations for version control
• Scripts: Removed shebang from validate-no-link-deps script (Node.js script, not shell)

3.0.5 - 2025-11-01

Fixed

• Critical: Prompts API breaking changes: Restored working prompts implementation that was accidentally replaced with non-functional stub in v3.0.0
  • Consolidated all prompts functionality into src/stdio/prompts.ts
  • Removed unimplemented stub from src/prompts/ that was throwing "not yet implemented" errors
  • Removed ./prompts package export (use @socketsecurity/lib/stdio/prompts instead)
  • Restored missing exports: password, search, Separator, and added createSeparator() helper
  • Fixed Choice type to use correct name property (matching @inquirer API, not erroneous label)

Added

• Theme integration for prompts: Prompts now automatically use the active theme colors

  • Prompt messages styled with colors.prompt
  • Descriptions and disabled items styled with colors.textDim
  • Answers and highlights styled with colors.primary
  • Error messages styled with colors.error
  • Success indicators styled with colors.success
  • Exported createInquirerTheme() function for converting Socket themes to @InQuirer format
  • Consistent visual experience with Logger and Spinner theme integration

• Theme parameter support: Logger, Prompts, and text effects now accept optional theme parameter

  • Pass theme names ('socket', 'sunset', 'terracotta', 'lush', 'ultra') or Theme objects
  • Logger: new Logger({ theme: 'sunset' }) - uses theme-specific symbol colors
  • Prompts: await input({ message: 'Name:', theme: 'ultra' }) - uses theme for prompt styling
  • Text effects: applyShimmer(text, state, { theme: 'terracotta' }) - uses theme for shimmer colors
  • Instance-specific themes override global theme context when provided
  • Falls back to global theme context when no instance theme specified
  • Note: Spinner already had theme parameter support in v3.0.0

Removed

• Unused index entrypoint: Removed src/index.ts and package exports for "." and "./index"
  • This was a leftover from socket-registry and not needed for this library
  • Users should import specific modules directly (e.g., @socketsecurity/lib/logger)
  • Breaking: import { getDefaultLogger } from '@socketsecurity/lib' no longer works
  • Use: import { getDefaultLogger } from '@socketsecurity/lib/logger' instead

3.0.4 - 2025-11-01

Changed

• Sunset theme: Updated colors from azure blue to warm orange/purple gradient matching Coana branding
• Terracotta theme: Renamed from brick to terracotta for better clarity

3.0.3 - 2025-11-01

Fixed

• Critical: Node.js ESM/CJS interop completely fixed: Disabled minification to ensure proper ESM named import detection
  • Root cause: esbuild minification was breaking Node.js ESM's CJS named export detection
  • Solution: Disabled minification entirely (minify: false in esbuild config)
  • Libraries should not be minified - consumers minify during their own build process
  • Unminified esbuild output uses clear __export patterns that Node.js ESM natively understands
  • Removed fix-commonjs-exports.mjs build script - no longer needed with unminified code
  • ESM imports now work reliably: import { getDefaultLogger } from '@socketsecurity/lib/logger'
  • Verified with real-world ESM module testing (.mjs files importing from CJS .js dist)

3.0.2 - 2025-11-01

Fixed

• Critical: Node.js ESM named imports from CommonJS: Fixed build output to ensure Node.js ESM can properly detect named exports from CommonJS modules
  • Previously, esbuild's minified export pattern placed module.exports before variable definitions, causing "Cannot access before initialization" errors
  • Build script now uses @babel/parser + magic-string for safe AST parsing and transformation
  • Exports are now correctly placed at end of files after all variable definitions
  • Enables proper ESM named imports: import { getDefaultLogger, Logger } from '@socketsecurity/lib/logger'
  • Fixes socket-cli issue where named imports were failing with obscure initialization errors

3.0.1 - 2025-11-01

Added

• Convenience exports from main index: Added logger and spinner exports to ease v2→v3 migration
  • Logger: getDefaultLogger(), Logger, LOG_SYMBOLS now available from @socketsecurity/lib
  • Spinner: getDefaultSpinner(), Spinner now available from @socketsecurity/lib
  • Both main index (@socketsecurity/lib) and subpath (@socketsecurity/lib/logger, @socketsecurity/lib/spinner) imports now work
  • Both import paths return the same singleton instances

Fixed

• Critical: Spinner crashes when calling logger: Fixed spinner internal calls to use getDefaultLogger() instead of removed logger export
  • Spinner methods (start(), stop(), success(), fail(), etc.) no longer crash with "logger is not defined" errors
  • All 5 internal logger access points updated to use the correct v3 API
  • Resolves runtime errors when using spinners with hoisted variables

Changed

• Migration path improvement: Users can now import logger/spinner from either main index or subpaths, reducing breaking change impact from v3.0.0

3.0.0 - 2025-11-01

Added

• Theme system with 5 built-in themes: socket, sunset, terracotta, lush, ultra
• setTheme(), getTheme(), withTheme(), withThemeSync() for theme management
• createTheme(), extendTheme(), resolveColor() helper functions
• onThemeChange() event listener for theme reactivity
• link() function for themed terminal hyperlinks in @socketsecurity/lib/links
• Logger and spinner now inherit theme colors automatically
• Spinner methods: enableShimmer(), disableShimmer(), setShimmer(), updateShimmer()
• DLX cross-platform binary resolution (.cmd, .bat, .ps1 on Windows)
• DLX programmatic options aligned with CLI conventions (force, quiet, package)

Changed

• Theme context uses AsyncLocalStorage instead of manual stack management
• Promise retry options renamed: factor → backoffFactor, minTimeout → baseDelayMs, maxTimeout → maxDelayMs

Removed

BREAKING CHANGES:

• pushTheme() and popTheme() - use withTheme() or withThemeSync() instead
• logger export - use getDefaultLogger() instead
• spinner export - use getDefaultSpinner() instead
• download-lock.ts - use process-lock.ts instead
• Promise option aliases: factor, minTimeout, maxTimeout

---

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

2.10.3 - 2025-10-31

Fixed

• Updated @socketregistry/packageurl-js to 1.3.1 to resolve an unintended external dependency
• Documentation: Corrected JSDoc @example import paths from @socketsecurity/registry to @socketsecurity/lib across utility modules
  • Updated examples in memoization.ts, performance.ts, spinner.ts, suppress-warnings.ts, and tables.ts
  • Ensures documentation reflects correct package name after v1.0.0 rename

2.10.2 - 2025-10-31

Changed

• Package spec parsing: Refactored to use official npm-package-arg library for robust handling of all npm package specification formats (versions, ranges, tags, git URLs)
  • Improves reliability when parsing complex package specs
  • Better handles edge cases in version ranges and scoped packages
  • Falls back to simple parsing if npm-package-arg fails

Fixed

• Scoped package version parsing: Fixed critical bug where parsePackageSpec was stripping the @ prefix from scoped packages with versions
  • Example: @coana-tech/cli@~14.12.51 was incorrectly parsed as coana-tech/cli@~14.12.51
  • Caused package installation failures for scoped packages in DLX system

2.10.1 - 2025-10-31

Fixed

• Process lock directory creation: Use recursive mkdir to ensure parent directories exist when creating lock directory
• Node.js debug flags: Remove buggy getNodeDebugFlags() function that returned debug flags without required argument values

2.10.0 - 2025-10-30

Added

• Unified DLX metadata schema: Standardized .dlx-metadata.json format across TypeScript and C++ implementations
  • Exported DlxMetadata interface as canonical schema reference
  • Core fields: version, cache_key, timestamp, checksum, checksum_algorithm, platform, arch, size, source
  • Support for source tracking (download vs decompression origin)
  • Reserved extra field for implementation-specific data
  • Comprehensive documentation with examples for both download and decompression use cases

Changed

• DLX binary metadata structure: Updated writeBinaryCacheMetadata() to use unified schema with additional fields
  • Now includes cache_key (first 16 chars of SHA-512 hash)
  • Added size field for cached binary size
  • Added checksum_algorithm field (currently "sha256")
  • Restructured to use source.type and source.url for origin tracking
  • Maintains backward compatibility in listDlxCache() reader

2.9.1 - 2025-10-30

Added

• Smart binary detection in dlxPackage: Automatically finds the correct binary even when package name doesn't match binary name
  • If package has single binary, uses it automatically regardless of name
  • Resolves packages like @socketsecurity/cli (binary: socket) without manual configuration
  • Falls back to intelligent name matching for multi-binary packages
• Optional binaryName parameter: Added binaryName option to DlxPackageOptions for explicit binary selection when auto-detection isn't sufficient

Fixed

• Binary resolution for scoped packages: Fixed issue where dlxPackage couldn't find binaries when package name didn't match binary name (e.g., @socketsecurity/cli with bin: { socket: '...' })

2.9.0 - 2025-10-30

Added

• Socket.dev URL constants: Added centralized URL constants for Socket.dev services
  • SOCKET_WEBSITE_URL: Main Socket.dev website
  • SOCKET_CONTACT_URL: Contact page
  • SOCKET_DASHBOARD_URL: Dashboard homepage
  • SOCKET_API_TOKENS_URL: API tokens settings page
  • SOCKET_PRICING_URL: Pricing information
  • SOCKET_STATUS_URL: Service status page
  • SOCKET_DOCS_URL: Documentation site
  • Available via @socketsecurity/lib/constants/socket

Changed

• Enhanced error messages across library: Comprehensive audit and improvement of error handling
  • Added actionable error messages with resolution steps throughout modules
  • Improved file system operation errors (permissions, read-only filesystems, path issues)
  • Enhanced DLX error messages with clear troubleshooting guidance
  • Better error context in process locking, binary downloads, and package operations
  • Consistent error formatting with helpful user guidance
• Consolidated process locking: Standardized on directory-based lock format across all modules
  • All locking operations now use process-lock module exclusively
  • Lock directories provide atomic guarantees across all filesystems including NFS
  • Consistent mtime-based stale detection with 5-second timeout (aligned with npm npx)
  • Automatic cleanup on process exit with proper signal handling

2.8.4 - 2025-10-30

Added

• DLX binary helper functions mirror dlx-package pattern
  • downloadBinary: Download binary with caching (without execution)
  • executeBinary: Execute cached binary without re-downloading
  • Renamed internal downloadBinary to downloadBinaryFile to avoid naming conflicts
  • Maintains feature parity with downloadPackage/executePackage from dlx-package

2.8.3 - 2025-10-30

Fixed

• Logger now fully defers all console access for Node.js internal bootstrap compatibility: Completed lazy initialization to prevent ERR_CONSOLE_WRITABLE_STREAM errors
  • Deferred Object.getOwnPropertySymbols(console) call until first logger use
  • Deferred kGroupIndentationWidth symbol lookup
  • Deferred Object.entries(console) and prototype method initialization
  • Ensures logger can be safely imported in Node.js internal bootstrap contexts (e.g., lib/internal/bootstrap/*.js) before stdout is initialized
  • Builds on v2.8.2 console deferring to complete early bootstrap compatibility

2.8.2 - 2025-10-29

Changed

• Enhanced Logger class to defer Console creation until first use
  • Eliminates early bootstrap errors when importing logger before stdout is ready
  • Enables safe logger imports during Node.js early initialization phase
  • Simplified internal storage with WeakMap-only pattern for constructor args

2.8.1 - 2025-10-29

Changed

• Consolidated DLX cache key generation: Extracted generateCacheKey function to shared dlx.ts module
  • Eliminates code duplication between dlx-binary.ts and dlx-package.ts
  • Enables consistent cache key generation across the Socket ecosystem
  • Exports function for use in dependent packages (e.g., socket-cli)
  • Maintains SHA-512 truncated to 16 chars strategy from v2.8.0

2.8.0 - 2025-10-29

Changed

• Enhanced DLX cache key generation with npm/npx compatibility: Updated cache key strategy to align with npm/npx ecosystem patterns
  • Changed from SHA-256 (64 chars) to SHA-512 truncated to 16 chars (matching npm/npx)
  • Optimized for Windows MAX_PATH compatibility (260 character limit)
  • Accepts collision risk for shorter paths (~1 in 18 quintillion with 1000 entries)
  • Added support for PURL-style package specifications (e.g., npm:prettier@3.0.0, pypi:requests@2.31.0)
  • Documented Socket's shorthand format (without pkg: prefix) handled by @socketregistry/packageurl-js
  • References npm/cli v11.6.2 implementation for consistency

2.7.0 - 2025-10-28

Added

• DLX cache locking for concurrent installation protection: Added process-lock protection to dlx-package installation operations
  • Lock file created at ~/.socket/_dlx/<hash>/.lock (similar to npm npx's concurrency.lock)
  • Prevents concurrent installations from corrupting the same package cache
  • Uses 5-second stale timeout and 2-second periodic touching (aligned with npm npx)
  • Double-check pattern verifies installation after acquiring lock to avoid redundant work
  • Completes 100% alignment with npm's npx locking strategy

2.6.0 - 2025-10-28

Changed

• Process locking aligned with npm npx: Enhanced process-lock module to match npm's npx locking strategy
  • Reduced stale timeout from 10 seconds to 5 seconds (matches npm npx)
  • Added periodic lock touching (2-second interval) to prevent false stale detection during long operations
  • Implemented second-level granularity for mtime comparison to avoid APFS floating-point precision issues
  • Added automatic touch timer cleanup on process exit
  • Timers use unref() to prevent keeping process alive
  • Aligns with npm's npx implementation per npm/cli#8512

2.5.0 - 2025-10-28

Added

• Process locking utilities: Added ProcessLockManager class providing cross-platform inter-process synchronization using file-system based locks
  • Atomic lock acquisition via mkdir() for thread-safe operations
  • Stale lock detection with automatic cleanup (default 10 seconds, aligned with npm's npx strategy)
  • Exponential backoff with jitter for retry attempts
  • Process exit handlers for guaranteed cleanup even on abnormal termination
  • Three main APIs: acquire(), release(), and withLock() (recommended)
  • Comprehensive test suite with describe.sequential for proper isolation
  • Export: @socketsecurity/lib/process-lock

Changed

• Script refactoring: Renamed spinner.succeed() to spinner.success() for consistency
• Script cleanup: Removed redundant spinner cleanup in interactive-runner

2.4.0 - 2025-10-28

Changed

• Download locking aligned with npm: Reduced default staleTimeout in downloadWithLock() from 300 seconds to 10 seconds to align with npm's npx locking strategy
  • Prevents stale locks from blocking downloads for extended periods
  • Matches npm's battle-tested timeout range (5-10 seconds)
  • Binary downloads now protected against concurrent corruption
• Binary download protection: dlxBinary.downloadBinary() now uses downloadWithLock() to prevent corruption when multiple processes download the same binary concurrently
  • Eliminates race conditions during parallel binary downloads
  • Maintains checksum verification and executable permissions

2.3.0 - 2025-10-28

Added

• Binary utility wrapper functions: Added which() and whichSync() wrapper functions to bin module
  • Cross-platform binary lookup that respects PATH environment variable
  • Synchronous and asynchronous variants for different use cases
  • Integrates with existing binary resolution utilities

2.2.1 - 2025-10-28

Fixed

• Logger write() method: Fixed write() to bypass Console formatting when outputting raw text
  • Previously, write() used Console's internal _stdout stream which applied unintended formatting like group indentation
  • Now stores a reference to the original stdout stream in a dedicated private field (#originalStdout) during construction
  • The write() method uses this stored reference to write directly to the raw stream, bypassing all Console formatting layers
  • Ensures raw text output without any formatting applied, fixing test failures in CI environments where writes after indent() were unexpectedly formatted

2.2.0 - 2025-10-28

Added

• Logger step symbol: logger.step() now displays a cyan arrow symbol (→ or > in ASCII) before step messages for improved visual separation
  • New LOG_SYMBOLS.step symbol added to the symbol palette
  • Automatic stripping of existing symbols from step messages
  • Maintains existing blank line behavior for clear step separation

2.1.0 - 2025-10-28

Added

• Package manager detection utilities (detectPackageManager(), getPackageManagerInfo(), getPackageManagerUserAgent())
• isInSocketDlx() utility to check if file path is within ~/.socket/_dlx/
• downloadPackage() and executePackage() functions for separate download and execution of packages

2.0.0 - 2025-10-27

Breaking Changes

Environment Variable System Refactor

This release completely refactors the environment variable system, consolidating 60+ individual env constant files into grouped getter modules with AsyncLocalStorage-based test rewiring.

Consolidated env files - Individual files replaced with grouped modules:

• env/github.ts - All GitHub-related env vars (GITHUB_TOKEN, GH_TOKEN, GITHUB_API_URL, etc.)
• env/socket.ts - Socket-specific env vars (SOCKET_API_TOKEN, SOCKET_CACACHE_DIR, etc.)
• env/socket-cli.ts - Socket CLI env vars (SOCKET_CLI_API_TOKEN, SOCKET_CLI_CONFIG, etc.)
• env/npm.ts - NPM-related env vars
• env/locale.ts - Locale env vars (LANG, LC_ALL, LC_MESSAGES)
• env/windows.ts - Windows-specific env vars (USERPROFILE, LOCALAPPDATA, APPDATA, COMSPEC)
• env/xdg.ts - XDG base directory env vars
• env/temp-dir.ts - Temp directory env vars (TEMP, TMP, TMPDIR)
• env/test.ts - Test framework env vars (VITEST, JEST_WORKER_ID)

Constants → Getter functions - All env constants converted to functions:

// Before (v1.x):
import { GITHUB_TOKEN } from '#env/github-token'

// After (v2.x):
import { getGithubToken } from '#env/github'

Deleted files - Removed 60+ individual env constant files:

• env/github-token.ts, env/socket-api-token.ts, etc. → Consolidated into grouped files
• env/getters.ts → Functions moved to their respective grouped files

Added

AsyncLocalStorage-Based Test Rewiring

New env/rewire.ts and path/rewire.ts modules provides context-isolated environment variable overrides for testing:

import { withEnv, setEnv, resetEnv, getEnvValue } from '#env/rewire'

// Option 1: Isolated context with AsyncLocalStorage
await withEnv({ CI: '1', NODE_ENV: 'test' }, async () => {
  // CI env var is '1' only within this block
  // Concurrent tests don't interfere
})

// Option 2: Traditional beforeEach/afterEach pattern
beforeEach(() => {
  setEnv('CI', '1')
})

afterEach(() => {
  resetEnv()
})

Features:

• Allows toggling between snapshot and live behavior
• Compatible with vi.stubEnv() as fallback

Changed

• Updated all dynamic require() statements to use path aliases (#constants/*, #packages/*)
• Improved logger blank line tracking per stream (separate stderr/stdout tracking)
• Exported getCacache() function for external use

1.3.6 - 2025-10-26

Fixed

• Fixed debug module functions being incorrectly tree-shaken as no-ops in bundled output
  • Removed incorrect /*@__NO_SIDE_EFFECTS__*/ annotations from debug(), debugDir(), debugLog(), and their *Ns variants
  • These functions have side effects (logging output, spinner manipulation) and should not be removed by bundlers
  • Fixes issue where debugLog() and debugDir() were compiled to empty no-op functions

1.3.5 - 2025-10-26

Added

• Added createEnvProxy() utility function to env module for Windows-compatible environment variable access
  • Provides case-insensitive environment variable access (e.g., PATH, Path, path all work)
  • Smart priority system: overrides > exact match > case-insensitive fallback
  • Full Proxy implementation with proper handlers for get, set, has, ownKeys, getOwnPropertyDescriptor
  • Opt-in helper for users who need Windows env var compatibility
  • Well-documented with usage examples and performance notes
• Added findCaseInsensitiveEnvKey() utility function to env module
  • Searches for environment variable keys using case-insensitive matching
  • Optimized with length fast path to minimize expensive toUpperCase() calls
  • Useful for cross-platform env var access where case may vary (e.g., PATH vs Path vs path)
• Added comprehensive test suite for env module with 71 tests
  • Covers envAsBoolean(), envAsNumber(), envAsString() conversion utilities
  • Tests createEnvProxy() with Windows environment variables and edge cases
  • Validates findCaseInsensitiveEnvKey() optimization and behavior

Fixed

• Fixed spawn module to preserve Windows process.env Proxy behavior
  • When no custom environment variables are provided, use process.env directly instead of spreading it
  • Preserves Windows case-insensitive environment variable access (PATH vs Path)
  • Fixes empty CLI output issue on Windows CI runners
  • Only spreads process.env when merging custom environment variables

1.3.4 - 2025-10-26

Added

• Added Node.js SIGUSR1 signal handler prevention utilities in constants/node module
  • supportsNodeDisableSigusr1Flag(): Detects if Node supports --disable-sigusr1 flag (v22.14+, v23.7+, v24.8+)
  • getNodeDisableSigusr1Flags(): Returns appropriate flags to prevent debugger attachment
    • Returns ['--disable-sigusr1'] on supported versions (prevents Signal I/O Thread creation)
    • Falls back to ['--no-inspect'] on Node 18+ (blocks debugger but still creates thread)
  • Enables production CLI environments to prevent SIGUSR1 debugger signal handling for security

1.3.3 - 2025-10-24

Fixed

• Fixed lazy getter bug in objects module where defineGetter, defineLazyGetter, and defineLazyGetters had incorrect /*@__NO_SIDE_EFFECTS__*/ annotations
  • These functions mutate objects by defining properties, so marking them as side-effect-free caused esbuild to incorrectly tree-shake the calls during bundling
  • Lazy getters were returning undefined instead of their computed values
  • Removed double wrapping in defineLazyGetters where createLazyGetter was being called unnecessarily

1.3.2 - 2025-10-24

Fixed

• Continued fixing of broken external dependency bundling

1.3.1 - 2025-10-24

Fixed

• Fixed @InQuirer modules (input, password, search) not being properly bundled into dist/external/
  • Resolves build failures in downstream packages (socket-cli) that depend on socket-lib
  • Added missing packages to bundling configuration in scripts/build-externals.mjs
  • All @InQuirer packages now ship as zero-dependency bundles

Added

• Added tests to prevent rogue external stubs in dist/external/
  • Detects stub re-export patterns that indicate incomplete bundling
  • Verifies all @InQuirer modules are properly bundled (> 1KB)
  • Catches bundling regressions early in CI pipeline

1.3.0 - 2025-10-23

Added

• Added validateFiles() utility function to fs module for defensive file access validation
  • Returns ValidateFilesResult with validPaths and invalidPaths arrays
  • Filters out unreadable files before processing (common with Yarn Berry PnP virtual filesystem, pnpm symlinks)
  • Prevents ENOENT errors when files exist in glob results but are not accessible
  • Comprehensive test coverage for all validation scenarios

1.2.0 - 2025-10-23

Added

• Added dlx-package module for installing and executing npm packages directly
  • Content-addressed caching using SHA256 hash (like npm's _npx)
  • Auto-force for version ranges (^, ~, >, <) to get latest within range
  • Cross-platform support with comprehensive tests (30 tests)
  • Parses scoped and unscoped package specs correctly
  • Resolves binaries from package.json bin field

Changed

• Unified DLX storage under ~/.socket/_dlx/ directory
  • Binary downloads now use ~/.socket/_dlx/ instead of non-existent cache path
  • Both npm packages and binaries share parent directory with content-addressed hashing
• Updated paths.ts documentation to clarify unified directory structure

[1.1.2] - 2025-10-23

Fixed

• Fixed broken relative import paths in packages/isolation.ts and packages/provenance.ts that prevented bundling by external tools

[1.1.1] - 2025-10-23

Fixed

• Fixed shimmer text effects not respecting CI environment detection (now disabled in CI to prevent ANSI escape codes in logs)

[1.1.0] - 2025-10-23

Added

• Added filterOutput option to stdio/mask for filtering output chunks before display/buffering
• Added overrideExitCode option to stdio/mask for customizing exit codes based on captured output
• Added comprehensive JSDoc documentation across entire library for enhanced VSCode IntelliSense
  • Detailed @param, @returns, @template, @throws tags
  • Practical @example blocks with real-world usage patterns
  • @default tags showing default values
  • Enhanced interface property documentation

Changed

• Improved TypeScript type hints and tooltips throughout library
• Enhanced documentation for all core utilities (arrays, fs, git, github, http-request, json, logger, objects, path, promises, spawn, spinner, strings)
• Enhanced documentation for stdio utilities (clear, divider, footer, header, mask, progress, prompts, stderr, stdout)
• Enhanced documentation for validation utilities (json-parser, types)

[1.0.5] - 2025-10-22

Added

• Added support for custom retry delays from onRetry callback

[1.0.4] - 2025-10-21

Fixed

• Fixed external dependency paths in root-level source files (corrected require paths from ../external/ to ./external/ in bin, cacache, fs, globs, spawn, spinner, and streams modules)

[1.0.3] - 2025-10-21

Fixed

• Fixed external dependency import paths in packages and stdio modules (corrected require paths from ../../external/ to ../external/)

[1.0.2] - 2025-10-21

Fixed

• Fixed module resolution error in packages/normalize module (corrected require path from ../../constants/socket to ../constants/socket)

[1.0.1] - 2025-10-21

Fixed

• Fixed relative import paths in compiled CommonJS output (changed require("../external/...") to require("./external/...") for root-level dist files)

[1.0.0] - 2025-10-20

Changed

• Consolidated parseArgs into argv/parse module

---

Historical Entries: The entries below are from when this package was named @socketsecurity/registry. This package was renamed to @socketsecurity/lib starting with version 1.0.0.

---

[1.5.3] - 2025-10-07

Added

• Fix bad build and add validation to prevent in future

[1.5.2] - 2025-10-07

Added

• Added coverage utilities to parse v8 and type coverage reports

Fixed

• Fixed isPath function to exclude URLs with protocols
• Fixed isolatePackage to handle file: URLs and npm-package-arg paths correctly

[1.5.1] - 2025-10-05

Added

• Added isolatePackage to lib/packages/isolation for creating isolated package test environments

Changed

• Removed dependencies/index barrel file to prevent eager loading of all dependency modules

[1.5.0] - 2025-10-05

Added

• Added support for testing local development packages in addition to socket-registry packages
• Exposed isolation module as part of public API via lib/packages

Changed

• Renamed setupPackageTest to isolatePackage for clearer intent
• Refactored installPackageForTesting to accept explicit sourcePath and packageName parameters
• Simplified package installation logic by removing path detection from low-level function
• Consolidated setupPackageTest and setupMultiEntryTest into single isolatePackage function with options

[1.4.6] - 2025-10-05

Added

• Added comprehensive package.json exports validation tests

[1.4.5] - 2025-10-05

Added

• Added performance monitoring utilities with timer, measurement, and reporting functions
• Added memoization utilities with LRU, TTL, weak references, and promise deduplication support
• Added table formatting utilities (formatTable, formatSimpleTable) for CLI output
• Added progress tracking to spinner with updateProgress() and incrementProgress() methods
• Added isDir and safeStats async helpers to fs module

Changed

• Removed platform and arch options from dlxBinary function as cross-platform binary execution is not supported

Fixed

• Fixed Windows shell execution in dlxBinary by adding cache directory to PATH

[1.4.4] - 2025-10-05

Fixed

• Fixed subpath exports

[1.4.3] - 2025-10-04

Added

• Spinner lifecycle utilities (withSpinner, withSpinnerRestore, withSpinnerSync) for automatic spinner cleanup with try/finally blocks

[1.4.2] - 2025-10-04

Added

• Added GITHUB_API_BASE_URL constant for GitHub API endpoint configuration
• Added SOCKET_API_BASE_URL constant for Socket API endpoint configuration
• Added generic TTL cache utility (createTtlCache) with in-memory memoization and persistent storage support

Changed

• Refactored GitHub caching to use the new cache-with-ttl utility for better performance and consistency

[1.4.1] - 2025-10-04

Changed

• Update maintained Node.js versions of constants.maintainedNodeVersions

[1.4.0] - 2025-10-04

Added

• Added PromiseQueue utility for controlled concurrency operations
• Added lazy dependency loaders and test utilities
• Added HTTP utilities with retry logic and download locking
• Added .claude directory for scratch documents
• Added noUnusedLocals and noUnusedParameters to TypeScript config

Changed

• Refactored all library functions to use options objects for better API consistency
  • lib/strings.ts - String manipulation functions
  • lib/url.ts - URL handling functions
  • lib/words.ts - Word manipulation functions
• Refactored lib/packages module into specialized submodules for improved code organization
  • lib/packages/editable.ts - Package editing functionality
  • lib/packages/exports.ts - Export resolution utilities
  • lib/packages/licenses.ts - License handling and validation
  • lib/packages/manifest.ts - Manifest data operations
  • lib/packages/normalize.ts - Path normalization utilities
  • lib/packages/operations.ts - Package installation and modification operations
  • lib/packages/paths.ts - Package path utilities
  • lib/packages/provenance.ts - Package provenance verification
  • lib/packages/specs.ts - Package spec parsing
  • lib/packages/validation.ts - Package validation utilities
• Moved configuration files (vitest, eslint, knip, oxlint, taze) to .config directory
• Replaced fetch() with Node.js native http/https modules for better reliability
• Replaced any types with meaningful types across library utilities
• Improved pnpm security with build script allowlist
• Updated vitest coverage thresholds to 80%
• Consolidated test files to reduce duplication
• Note: Public API remains unchanged; these are internal organizational improvements

Fixed

• Fixed resource leaks and race conditions in socket-registry
• Fixed yarn-cache-path constant to return string type consistently
• Fixed Yarn Windows temp path detection in shouldSkipShadow
• Fixed path normalization for Windows compatibility across all path utilities
• Fixed cache path tests for Windows case sensitivity
• Fixed type errors in promises, parse-args, logger, and specs tests
• Fixed GitHub tests to mock httpRequest correctly
• Fixed SEA build tests to mock httpRequest
• Decoded URL percent-encoding in pathLikeToString fallback

[1.3.10] - 2025-10-03

Added

• New utility modules for DLX, shadow, SEA, cacache, and versions functionality
• getSocketHomePath alias to paths module
• del dependency and external wrapper for safer file deletion
• @fileoverview tags to lib modules
• camelCase expansion for kebab-case arguments in parseArgs
• Coerce and configuration options to parseArgs

Changed

• Updated file removal to use del package for safer deletion
• Normalized path returns in fs and Socket directory utilities
• Removed default exports from git and parse-args modules
• Enhanced test coverage across multiple modules (parse-args, prompts, strings, env, spawn, json)

[1.3.9] - 2025-10-03

Changed

• Internal build and distribution updates

[1.3.8] - 2025-10-03

Added

• Added unified directory structure for Socket ecosystem tools
• New path utilities module for cross-platform directory resolution
• Directory structure constants for Socket CLI, Registry, Firewall, and DLX

[1.3.7] - 2025-10-02

Changed

• Updated manifest.json entries

[1.3.6] - 2025-10-01

Fixed

• Fixed indent-string interoperability with older v1 and v2 versions

[1.3.5] - 2025-10-01

Added

• Added lib/git utilities module

Fixed

• Fixed invalid manifest entries
• Fixed parseArgs strip-aliased bug

[1.3.4] - 2025-10-01

Changed

• Updated various package override versions

[1.3.3] - 2025-10-01

Fixed

• Fixed normalizePath collapsing multiple leading .. segments incorrectly

[1.3.2] - 2025-10-01

Added

• Added 'sfw' to isBlessedPackageName method check
• Added ENV.DEBUG normalization for debug package compatibility
  • DEBUG='1' or DEBUG='true' automatically expands to DEBUG='*' (enables all namespaces)
  • DEBUG='0' or DEBUG='false' automatically converts to empty string (disables all output)
  • Namespace patterns like DEBUG='app:*' are preserved unchanged

[1.3.1] - 2025-09-30

Changed

• Renamed debug functions from *Complex to *Ns

Fixed

• Fixed regression with lib/prompts module imports

[1.3.0] - 2025-09-29

Changed

• Updated registry subpath exports

Fixed

• Fixed Node.js built-in module imports in CommonJS output

[1.2.2] - 2025-09-29

Changed

• Internal improvements to module structure

[1.2.1] - 2025-09-29

Changed

• Restructured constants module with new architecture
• Updated build configuration and package exports