@socketsecurity/lib 0.0.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,270 @@
+# Changelog
+
+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).
+
+## [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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Socket Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,86 @@
 # @socketsecurity/lib
 
-Core utilities for Socket.dev security tools.
+[![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
+[![CI - SocketDev/socket-lib](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
 
-This package is currently a placeholder for setting up npm trusted publishing. Full documentation will be added in version 2.0.
+[![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 utilities, constants, and helper functions for Socket.dev security tools.
+
+## Installation
+
+```bash
+pnpm install @socketsecurity/lib
+```
+
+## Features
+
+- **Constants** — Access Node.js, npm, and package manager constants
+- **Type Definitions** — Full TypeScript support with comprehensive type exports
+- **Helper Utilities** — File system, path, package, and process utilities
+- **Environment Variables** — Typed access to environment variables
+- **Effects** — Visual effects for CLI applications
+
+## Usage
+
+### Constants
+
+Import Node.js and package manager constants:
+
+```typescript
+import {
+  NODE_MODULES,
+  PACKAGE_JSON,
+  PNPM_LOCK_YAML,
+  NPM_REGISTRY_URL,
+} from '@socketsecurity/lib/constants/packages'
+```
+
+### Environment Variables
+
+Access typed environment variables:
+
+```typescript
+import { getEnv } from '@socketsecurity/lib/env/getters'
+import { NODE_ENV } from '@socketsecurity/lib/env/node-env'
+
+const env = getEnv('NODE_ENV')
+console.log(NODE_ENV) // 'production' | 'development' | 'test'
+```
+
+For a complete list of available modules, see the [package.json exports](./package.json).
+
+## Type Definitions
+
+All types are exported for TypeScript projects:
+
+```typescript
+import type {
+  PackageJson,
+  TsConfig,
+  LockFile,
+} from '@socketsecurity/lib/types'
+```
+
+## Utilities
+
+Access utility modules for common operations:
+
+```typescript
+// File system utilities
+import { readJsonFile, writeJsonFile } from '@socketsecurity/lib/fs'
+
+// Package utilities
+import { parsePackageSpec } from '@socketsecurity/lib/packages'
+
+// Path utilities
+import { normalizePath } from '@socketsecurity/lib/paths'
+
+// And many more...
+```
+
+See the [exports map](./package.json) for all available utility modules.
 
 ## License
 

package/data/extensions.json

@@ -0,0 +1,28 @@
+{
+  "npm": [
+    [
+      "pkg:npm/%40socketregistry/packageurl-js@latest",
+      {
+        "categories": ["levelup"],
+        "engines": { "node": ">=18" },
+        "interop": ["cjs"],
+        "license": "MIT",
+        "name": "@socketregistry/packageurl-js",
+        "package": "packageurl-js",
+        "version": "latest"
+      }
+    ],
+    [
+      "pkg:npm/shell-quote@latest",
+      {
+        "categories": ["tuneup"],
+        "engines": { "node": ">=18" },
+        "interop": ["cjs"],
+        "license": "MIT",
+        "name": "shell-quote",
+        "package": "shell-quote",
+        "version": "latest"
+      }
+    ]
+  ]
+}

package/dist/abort.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Abort signal utilities.
+ */
+/**
+ * Create a composite AbortSignal from multiple signals.
+ */
+export declare function createCompositeAbortSignal(...signals: Array<AbortSignal | null | undefined>): AbortSignal;
+/**
+ * Create an AbortSignal that triggers after a timeout.
+ */
+export declare function createTimeoutSignal(ms: number): AbortSignal;

package/dist/abort.js

@@ -0,0 +1,62 @@
+/* Socket Lib - Built with esbuild */
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var abort_exports = {};
+__export(abort_exports, {
+  createCompositeAbortSignal: () => createCompositeAbortSignal,
+  createTimeoutSignal: () => createTimeoutSignal
+});
+module.exports = __toCommonJS(abort_exports);
+function createCompositeAbortSignal(...signals) {
+  const validSignals = signals.filter((s) => s != null);
+  if (validSignals.length === 0) {
+    return new AbortController().signal;
+  }
+  if (validSignals.length === 1) {
+    return validSignals[0];
+  }
+  const controller = new AbortController();
+  for (const signal of validSignals) {
+    if (signal.aborted) {
+      controller.abort();
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  return controller.signal;
+}
+function createTimeoutSignal(ms) {
+  if (typeof ms !== "number" || Number.isNaN(ms)) {
+    throw new TypeError("timeout must be a number");
+  }
+  if (!Number.isFinite(ms)) {
+    throw new TypeError("timeout must be a finite number");
+  }
+  if (ms <= 0) {
+    throw new TypeError("timeout must be a positive number");
+  }
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), ms);
+  return controller.signal;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCompositeAbortSignal,
+  createTimeoutSignal
+});
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/abort.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Abort signal utilities.\n */\n\n/**\n * Create a composite AbortSignal from multiple signals.\n */\nexport function createCompositeAbortSignal(\n  ...signals: Array<AbortSignal | null | undefined>\n): AbortSignal {\n  const validSignals = signals.filter(s => s != null) as AbortSignal[]\n\n  if (validSignals.length === 0) {\n    return new AbortController().signal\n  }\n\n  if (validSignals.length === 1) {\n    // biome-ignore lint/style/noNonNullAssertion: Length check ensures array has exactly one element.\n    return validSignals[0]!\n  }\n\n  const controller = new AbortController()\n\n  for (const signal of validSignals) {\n    if (signal.aborted) {\n      controller.abort()\n      return controller.signal\n    }\n    signal.addEventListener('abort', () => controller.abort(), { once: true })\n  }\n\n  return controller.signal\n}\n\n/**\n * Create an AbortSignal that triggers after a timeout.\n */\nexport function createTimeoutSignal(ms: number): AbortSignal {\n  if (typeof ms !== 'number' || Number.isNaN(ms)) {\n    throw new TypeError('timeout must be a number')\n  }\n  if (!Number.isFinite(ms)) {\n    throw new TypeError('timeout must be a finite number')\n  }\n  if (ms <= 0) {\n    throw new TypeError('timeout must be a positive number')\n  }\n  const controller = new AbortController()\n  setTimeout(() => controller.abort(), ms)\n  return controller.signal\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOO,SAAS,8BACX,SACU;AACb,QAAM,eAAe,QAAQ,OAAO,OAAK,KAAK,IAAI;AAElD,MAAI,aAAa,WAAW,GAAG;AAC7B,WAAO,IAAI,gBAAgB,EAAE;AAAA,EAC/B;AAEA,MAAI,aAAa,WAAW,GAAG;AAE7B,WAAO,aAAa,CAAC;AAAA,EACvB;AAEA,QAAM,aAAa,IAAI,gBAAgB;AAEvC,aAAW,UAAU,cAAc;AACjC,QAAI,OAAO,SAAS;AAClB,iBAAW,MAAM;AACjB,aAAO,WAAW;AAAA,IACpB;AACA,WAAO,iBAAiB,SAAS,MAAM,WAAW,MAAM,GAAG,EAAE,MAAM,KAAK,CAAC;AAAA,EAC3E;AAEA,SAAO,WAAW;AACpB;AAKO,SAAS,oBAAoB,IAAyB;AAC3D,MAAI,OAAO,OAAO,YAAY,OAAO,MAAM,EAAE,GAAG;AAC9C,UAAM,IAAI,UAAU,0BAA0B;AAAA,EAChD;AACA,MAAI,CAAC,OAAO,SAAS,EAAE,GAAG;AACxB,UAAM,IAAI,UAAU,iCAAiC;AAAA,EACvD;AACA,MAAI,MAAM,GAAG;AACX,UAAM,IAAI,UAAU,mCAAmC;AAAA,EACzD;AACA,QAAM,aAAa,IAAI,gBAAgB;AACvC,aAAW,MAAM,WAAW,MAAM,GAAG,EAAE;AACvC,SAAO,WAAW;AACpB;",
+  "names": []
+}

package/dist/agent.d.ts

@@ -0,0 +1,102 @@
+import type { SpawnOptions } from './spawn';
+/**
+ * Execute npm commands with optimized flags and settings.
+ *
+ * SECURITY: Uses array-based arguments to prevent command injection. All elements
+ * in the args array are properly escaped by Node.js when passed to spawn().
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function execNpm(args: string[], options?: SpawnOptions | undefined): import("./spawn").PromiseSpawnResult;
+export interface PnpmOptions extends SpawnOptions {
+    allowLockfileUpdate?: boolean;
+}
+/**
+ * Execute pnpm commands with optimized flags and settings.
+ *
+ * SECURITY: Uses array-based arguments to prevent command injection. All elements
+ * in the args array are properly escaped by Node.js when passed to execBin().
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function execPnpm(args: string[], options?: PnpmOptions | undefined): Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals;
+    stdout: string | Buffer<ArrayBufferLike>;
+    stderr: string | Buffer<ArrayBufferLike>;
+}>;
+/**
+ * Execute yarn commands with optimized flags and settings.
+ *
+ * SECURITY: Uses array-based arguments to prevent command injection. All elements
+ * in the args array are properly escaped by Node.js when passed to execBin().
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function execYarn(args: string[], options?: import('./spawn').SpawnOptions): Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals;
+    stdout: string | Buffer<ArrayBufferLike>;
+    stderr: string | Buffer<ArrayBufferLike>;
+}>;
+/**
+ * Check if a command argument is an npm audit flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isNpmAuditFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is an npm fund flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isNpmFundFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is an npm loglevel flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isNpmLoglevelFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is an npm node-options flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isNpmNodeOptionsFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is an npm progress flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isNpmProgressFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is a pnpm ignore-scripts flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is a pnpm frozen-lockfile flag.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isPnpmFrozenLockfileFlag(cmdArg: string): boolean;
+/**
+ * Check if a command argument is a pnpm install command.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isPnpmInstallCommand(cmdArg: string): boolean;
+/**
+ * Alias for isNpmLoglevelFlag for pnpm usage.
+ */
+export declare const isPnpmLoglevelFlag: typeof isNpmLoglevelFlag;
+/**
+ * Execute a package.json script using the appropriate package manager.
+ * Automatically detects pnpm, yarn, or npm based on lockfiles.
+ */
+export interface ExecScriptOptions extends SpawnOptions {
+    prepost?: boolean | undefined;
+}
+/*@__NO_SIDE_EFFECTS__*/
+export declare function execScript(scriptName: string, args?: string[] | readonly string[] | ExecScriptOptions | undefined, options?: ExecScriptOptions | undefined): Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals;
+    stdout: string | Buffer<ArrayBufferLike>;
+    stderr: string | Buffer<ArrayBufferLike>;
+}>;