@socketsecurity/lib 4.3.0 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,95 @@ 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.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.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](https://github.com/SocketDev/socket-lib/releases/tag/v4.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](https://github.com/SocketDev/socket-lib/releases/tag/v4.3.0) - 2025-11-20
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
 [![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-84.12%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-83.78%25-brightgreen)
 
 [![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)

package/dist/constants/node.js

@@ -41,7 +41,7 @@ __export(node_exports, {
   supportsProcessSend: () => supportsProcessSend
 });
 module.exports = __toCommonJS(node_exports);
-var import_maintained_node_versions = require("../maintained-node-versions");
+var import_maintained_node_versions = require("./maintained-node-versions");
 const NODE_VERSION = process.version;
 function getNodeVersion() {
   return NODE_VERSION;

package/dist/{package-default-node-range.js → constants/package-default-node-range.js}

@@ -33,7 +33,7 @@ __export(package_default_node_range_exports, {
 });
 module.exports = __toCommonJS(package_default_node_range_exports);
 var import_maintained_node_versions = require("./maintained-node-versions");
-var semver = __toESM(require("./external/semver.js"));
+var semver = __toESM(require("../external/semver.js"));
 const packageDefaultNodeRange = `>=${semver.parse(import_maintained_node_versions.maintainedNodeVersions.last).major}`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/constants/packages.js

@@ -43,9 +43,9 @@ __export(packages_exports, {
 });
 module.exports = __toCommonJS(packages_exports);
 var import_npm = require("../env/npm");
-var import_lifecycle_script_names = require("../lifecycle-script-names");
-var import_package_default_node_range = require("../package-default-node-range");
-var import_package_default_socket_categories = require("../package-default-socket-categories");
+var import_lifecycle_script_names = require("./lifecycle-script-names");
+var import_package_default_node_range = require("./package-default-node-range");
+var import_package_default_socket_categories = require("./package-default-socket-categories");
 var import_package_extensions = require("../package-extensions");
 var import_pacote = __toESM(require("../external/pacote"));
 var import_normalize = require("../paths/normalize");

package/dist/{dlx-binary.d.ts → dlx/binary.d.ts}

@@ -1,5 +1,5 @@
-import type { SpawnExtra, SpawnOptions } from './spawn';
-import { spawn } from './spawn';
+import type { SpawnExtra, SpawnOptions } from '../spawn';
+import { spawn } from '../spawn';
 export interface DlxBinaryOptions {
     /**
      * URL to download the binary from.

package/dist/{dlx-binary.js → dlx/binary.js}

@@ -27,8 +27,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var dlx_binary_exports = {};
-__export(dlx_binary_exports, {
+var binary_exports = {};
+__export(binary_exports, {
   cleanDlxCache: () => cleanDlxCache,
   dlxBinary: () => dlxBinary,
   downloadBinary: () => downloadBinary,
@@ -36,21 +36,21 @@ __export(dlx_binary_exports, {
   getDlxCachePath: () => getDlxCachePath,
   listDlxCache: () => listDlxCache
 });
-module.exports = __toCommonJS(dlx_binary_exports);
+module.exports = __toCommonJS(binary_exports);
 var import_crypto = require("crypto");
 var import_os = __toESM(require("os"));
 var import_path = __toESM(require("path"));
-var import_platform = require("./constants/platform");
-var import_time = require("./constants/time");
-var import_dlx = require("./dlx");
-var import_dlx_manifest = require("./dlx-manifest");
-var import_http_request = require("./http-request");
-var import_fs = require("./fs");
-var import_objects = require("./objects");
-var import_normalize = require("./paths/normalize");
-var import_socket = require("./paths/socket");
-var import_process_lock = require("./process-lock");
-var import_spawn = require("./spawn");
+var import_platform = require("../constants/platform");
+var import_time = require("../constants/time");
+var import_cache = require("./cache");
+var import_manifest = require("./manifest");
+var import_http_request = require("../http-request");
+var import_fs = require("../fs");
+var import_objects = require("../objects");
+var import_normalize = require("../paths/normalize");
+var import_socket = require("../paths/socket");
+var import_process_lock = require("../process-lock");
+var import_spawn = require("../spawn");
 let _fs;
 // @__NO_SIDE_EFFECTS__
 function getFs() {
@@ -152,7 +152,7 @@ async function writeMetadata(cacheEntryPath, cacheKey, url, binaryName, checksum
   await fs.promises.writeFile(metaPath, JSON.stringify(metadata, null, 2));
   try {
     const spec = `${url}:${binaryName}`;
-    await import_dlx_manifest.dlxManifest.setBinaryEntry(spec, cacheKey, {
+    await import_manifest.dlxManifest.setBinaryEntry(spec, cacheKey, {
       checksum,
       checksum_algorithm: "sha256",
       platform: import_os.default.platform(),
@@ -219,7 +219,7 @@ async function dlxBinary(args, options, spawnExtra) {
   const cacheDir = getDlxCachePath();
   const binaryName = name || `binary-${process.platform}-${import_os.default.arch()}`;
   const spec = `${url}:${binaryName}`;
-  const cacheKey = (0, import_dlx.generateCacheKey)(spec);
+  const cacheKey = (0, import_cache.generateCacheKey)(spec);
   const cacheEntryDir = import_path.default.join(cacheDir, cacheKey);
   const binaryPath = (0, import_normalize.normalizePath)(import_path.default.join(cacheEntryDir, binaryName));
   const fs = /* @__PURE__ */ getFs();
@@ -302,7 +302,7 @@ async function downloadBinary(options) {
   const cacheDir = getDlxCachePath();
   const binaryName = name || `binary-${process.platform}-${import_os.default.arch()}`;
   const spec = `${url}:${binaryName}`;
-  const cacheKey = (0, import_dlx.generateCacheKey)(spec);
+  const cacheKey = (0, import_cache.generateCacheKey)(spec);
   const cacheEntryDir = import_path.default.join(cacheDir, cacheKey);
   const binaryPath = (0, import_normalize.normalizePath)(import_path.default.join(cacheEntryDir, binaryName));
   const fs = /* @__PURE__ */ getFs();

package/dist/dlx/cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Generate a cache directory name using npm/npx approach.
+ * Uses first 16 characters of SHA-512 hash (like npm/npx).
+ *
+ * Rationale for SHA-512 truncated (vs full SHA-256):
+ * - Matches npm/npx ecosystem behavior
+ * - Shorter paths for Windows MAX_PATH compatibility (260 chars)
+ * - 16 hex chars = 64 bits = acceptable collision risk for local cache
+ * - Collision probability ~1 in 18 quintillion with 1000 entries
+ *
+ * Input strategy (aligned with npx):
+ * - npx uses package spec strings (e.g., '@scope/pkg@1.0.0', 'prettier@3.0.0')
+ * - Caller provides complete spec string with version for accurate cache keying
+ * - For package installs: Use PURL-style spec with version
+ *   Examples: 'npm:prettier@3.0.0', 'pypi:requests@2.31.0', 'gem:rails@7.0.0'
+ *   Note: Socket uses shorthand format without 'pkg:' prefix
+ *   (handled by @socketregistry/packageurl-js)
+ * - For binary downloads: Use URL:name for uniqueness
+ *
+ * Reference: npm/cli v11.6.2 libnpmexec/lib/index.js#L233-L244
+ * https://github.com/npm/cli/blob/v11.6.2/workspaces/libnpmexec/lib/index.js#L233-L244
+ * Implementation: packages.map().sort().join('\n') → SHA-512 → slice(0,16)
+ * npx hashes the package spec (name@version), not just name
+ */
+export declare function generateCacheKey(spec: string): string;

package/dist/dlx/cache.js

@@ -0,0 +1,32 @@
+"use strict";
+/* 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 cache_exports = {};
+__export(cache_exports, {
+  generateCacheKey: () => generateCacheKey
+});
+module.exports = __toCommonJS(cache_exports);
+var import_node_crypto = require("node:crypto");
+function generateCacheKey(spec) {
+  return (0, import_node_crypto.createHash)("sha512").update(spec).digest("hex").substring(0, 16);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateCacheKey
+});

package/dist/dlx/dir.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Clear all DLX package installations.
+ */
+export declare function clearDlx(): Promise<void>;
+/**
+ * Clear all DLX package installations synchronously.
+ */
+export declare function clearDlxSync(): void;
+/**
+ * Check if the DLX directory exists.
+ */
+export declare function dlxDirExists(): boolean;
+/**
+ * Check if the DLX directory exists asynchronously.
+ */
+export declare function dlxDirExistsAsync(): Promise<boolean>;
+/**
+ * Ensure the DLX directory exists, creating it if necessary.
+ */
+export declare function ensureDlxDir(): Promise<void>;
+/**
+ * Ensure the DLX directory exists synchronously, creating it if necessary.
+ */
+export declare function ensureDlxDirSync(): void;

package/dist/dlx/dir.js

@@ -0,0 +1,79 @@
+"use strict";
+/* 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 dir_exports = {};
+__export(dir_exports, {
+  clearDlx: () => clearDlx,
+  clearDlxSync: () => clearDlxSync,
+  dlxDirExists: () => dlxDirExists,
+  dlxDirExistsAsync: () => dlxDirExistsAsync,
+  ensureDlxDir: () => ensureDlxDir,
+  ensureDlxDirSync: () => ensureDlxDirSync
+});
+module.exports = __toCommonJS(dir_exports);
+var import_fs = require("../fs");
+var import_socket = require("../paths/socket");
+var import_promises = require("../promises");
+var import_packages = require("./packages");
+let _fs;
+// @__NO_SIDE_EFFECTS__
+function getFs() {
+  if (_fs === void 0) {
+    _fs = require("node:fs");
+  }
+  return _fs;
+}
+async function clearDlx() {
+  const packages = await (0, import_packages.listDlxPackagesAsync)();
+  await (0, import_promises.pEach)(packages, (pkg) => (0, import_packages.removeDlxPackage)(pkg));
+}
+function clearDlxSync() {
+  const packages = (0, import_packages.listDlxPackages)();
+  for (const pkg of packages) {
+    (0, import_packages.removeDlxPackageSync)(pkg);
+  }
+}
+function dlxDirExists() {
+  const fs = /* @__PURE__ */ getFs();
+  return fs.existsSync((0, import_socket.getSocketDlxDir)());
+}
+async function dlxDirExistsAsync() {
+  const fs = /* @__PURE__ */ getFs();
+  try {
+    await fs.promises.access((0, import_socket.getSocketDlxDir)());
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDlxDir() {
+  await (0, import_fs.safeMkdir)((0, import_socket.getSocketDlxDir)());
+}
+function ensureDlxDirSync() {
+  (0, import_fs.safeMkdirSync)((0, import_socket.getSocketDlxDir)());
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearDlx,
+  clearDlxSync,
+  dlxDirExists,
+  dlxDirExistsAsync,
+  ensureDlxDir,
+  ensureDlxDirSync
+});

package/dist/{dlx-manifest.js → dlx/manifest.js}

@@ -27,20 +27,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var dlx_manifest_exports = {};
-__export(dlx_manifest_exports, {
+var manifest_exports = {};
+__export(manifest_exports, {
   DlxManifest: () => DlxManifest,
   dlxManifest: () => dlxManifest,
   isBinaryEntry: () => isBinaryEntry,
   isPackageEntry: () => isPackageEntry
 });
-module.exports = __toCommonJS(dlx_manifest_exports);
+module.exports = __toCommonJS(manifest_exports);
 var import_fs = require("fs");
 var import_path = __toESM(require("path"));
-var import_fs2 = require("./fs");
-var import_logger = require("./logger");
-var import_socket = require("./paths/socket");
-var import_process_lock = require("./process-lock");
+var import_fs2 = require("../fs");
+var import_logger = require("../logger");
+var import_socket = require("../paths/socket");
+var import_process_lock = require("../process-lock");
 const logger = (0, import_logger.getDefaultLogger)();
 const MANIFEST_FILE_NAME = ".dlx-manifest.json";
 function isPackageEntry(entry) {

package/dist/{dlx-package.d.ts → dlx/package.d.ts}

@@ -1,5 +1,5 @@
-import type { SpawnExtra, SpawnOptions } from './spawn';
-import { spawn } from './spawn';
+import type { SpawnExtra, SpawnOptions } from '../spawn';
+import { spawn } from '../spawn';
 export interface DownloadPackageResult {
     /** Path to the installed package directory. */
     packageDir: string;

package/dist/{dlx-package.js → dlx/package.js}

@@ -27,27 +27,27 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var dlx_package_exports = {};
-__export(dlx_package_exports, {
+var package_exports = {};
+__export(package_exports, {
   dlxPackage: () => dlxPackage,
   downloadPackage: () => downloadPackage,
   executePackage: () => executePackage
 });
-module.exports = __toCommonJS(dlx_package_exports);
+module.exports = __toCommonJS(package_exports);
 var import_node_fs = __toESM(require("node:fs"));
 var import_path = __toESM(require("path"));
-var import_platform = require("./constants/platform");
-var import_packages = require("./constants/packages");
-var import_dlx = require("./dlx");
-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"));
-var import_pacote = __toESM(require("./external/pacote"));
-var import_fs = require("./fs");
-var import_normalize = require("./paths/normalize");
-var import_socket = require("./paths/socket");
-var import_process_lock = require("./process-lock");
-var import_spawn = require("./spawn");
+var import_platform = require("../constants/platform");
+var import_packages = require("../constants/packages");
+var import_cache = require("./cache");
+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"));
+var import_pacote = __toESM(require("../external/pacote"));
+var import_fs = require("../fs");
+var import_normalize = require("../paths/normalize");
+var import_socket = require("../paths/socket");
+var import_process_lock = require("../process-lock");
+var import_spawn = require("../spawn");
 const rangeOperatorsRegExp = /[~^><=xX* ]|\|\|/;
 function parsePackageSpec(spec) {
   try {
@@ -69,7 +69,7 @@ function parsePackageSpec(spec) {
   }
 }
 async function ensurePackageInstalled(packageName, packageSpec, force) {
-  const cacheKey = (0, import_dlx.generateCacheKey)(packageSpec);
+  const cacheKey = (0, import_cache.generateCacheKey)(packageSpec);
   const packageDir = (0, import_normalize.normalizePath)(import_path.default.join((0, import_socket.getSocketDlxDir)(), cacheKey));
   const installedDir = (0, import_normalize.normalizePath)(
     import_path.default.join(packageDir, "node_modules", packageName)

package/dist/dlx/packages.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Check if a package is installed in DLX.
+ */
+export declare function isDlxPackageInstalled(packageName: string): boolean;
+/**
+ * Check if a package is installed in DLX asynchronously.
+ */
+export declare function isDlxPackageInstalledAsync(packageName: string): Promise<boolean>;
+/**
+ * List all packages installed in DLX.
+ */
+export declare function listDlxPackages(): string[];
+/**
+ * List all packages installed in DLX asynchronously.
+ */
+export declare function listDlxPackagesAsync(): Promise<string[]>;
+/**
+ * Remove a DLX package installation.
+ */
+export declare function removeDlxPackage(packageName: string): Promise<void>;
+/**
+ * Remove a DLX package installation synchronously.
+ */
+export declare function removeDlxPackageSync(packageName: string): void;

package/dist/dlx/packages.js

@@ -0,0 +1,125 @@
+"use strict";
+/* 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 packages_exports = {};
+__export(packages_exports, {
+  isDlxPackageInstalled: () => isDlxPackageInstalled,
+  isDlxPackageInstalledAsync: () => isDlxPackageInstalledAsync,
+  listDlxPackages: () => listDlxPackages,
+  listDlxPackagesAsync: () => listDlxPackagesAsync,
+  removeDlxPackage: () => removeDlxPackage,
+  removeDlxPackageSync: () => removeDlxPackageSync
+});
+module.exports = __toCommonJS(packages_exports);
+var import_fs = require("../fs");
+var import_socket = require("../paths/socket");
+var import_paths = require("./paths");
+let _fs;
+// @__NO_SIDE_EFFECTS__
+function getFs() {
+  if (_fs === void 0) {
+    _fs = require("node:fs");
+  }
+  return _fs;
+}
+function isDlxPackageInstalled(packageName) {
+  const fs = /* @__PURE__ */ getFs();
+  return fs.existsSync((0, import_paths.getDlxInstalledPackageDir)(packageName));
+}
+async function isDlxPackageInstalledAsync(packageName) {
+  const fs = /* @__PURE__ */ getFs();
+  try {
+    await fs.promises.access((0, import_paths.getDlxInstalledPackageDir)(packageName));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listDlxPackages() {
+  try {
+    return (0, import_fs.readDirNamesSync)((0, import_socket.getSocketDlxDir)(), { sort: true });
+  } catch {
+    return [];
+  }
+}
+async function listDlxPackagesAsync() {
+  const fs = /* @__PURE__ */ getFs();
+  try {
+    const entries = await fs.promises.readdir((0, import_socket.getSocketDlxDir)(), {
+      withFileTypes: true
+    });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+async function removeDlxPackage(packageName) {
+  const packageDir = (0, import_paths.getDlxPackageDir)(packageName);
+  try {
+    await (0, import_fs.safeDelete)(packageDir, { recursive: true, force: true });
+  } catch (e) {
+    throw new Error(`Failed to remove DLX package "${packageName}"`, {
+      cause: e
+    });
+  }
+}
+function removeDlxPackageSync(packageName) {
+  const fs = /* @__PURE__ */ getFs();
+  const packageDir = (0, import_paths.getDlxPackageDir)(packageName);
+  try {
+    fs.rmSync(packageDir, { recursive: true, force: true });
+  } catch (e) {
+    const code = e.code;
+    if (code === "EACCES" || code === "EPERM") {
+      throw new Error(
+        `Permission denied removing DLX package "${packageName}"
+Directory: ${packageDir}
+To resolve:
+  1. Check file/directory permissions
+  2. Close any programs using files in this directory
+  3. Try running with elevated privileges if necessary
+  4. Manually remove: rm -rf "${packageDir}"`,
+        { cause: e }
+      );
+    }
+    if (code === "EROFS") {
+      throw new Error(
+        `Cannot remove DLX package "${packageName}" from read-only filesystem
+Directory: ${packageDir}
+The filesystem is mounted read-only.`,
+        { cause: e }
+      );
+    }
+    throw new Error(
+      `Failed to remove DLX package "${packageName}"
+Directory: ${packageDir}
+Check permissions and ensure no programs are using this directory.`,
+      { cause: e }
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isDlxPackageInstalled,
+  isDlxPackageInstalledAsync,
+  listDlxPackages,
+  listDlxPackagesAsync,
+  removeDlxPackage,
+  removeDlxPackageSync
+});

package/dist/dlx/paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Get the installed package directory within DLX node_modules.
+ */
+export declare function getDlxInstalledPackageDir(packageName: string): string;
+/**
+ * Get the DLX installation directory for a specific package.
+ */
+export declare function getDlxPackageDir(packageName: string): string;
+/**
+ * Get the package.json path for a DLX installed package.
+ */
+export declare function getDlxPackageJsonPath(packageName: string): string;
+/**
+ * Get the node_modules directory for a DLX package installation.
+ */
+export declare function getDlxPackageNodeModulesDir(packageName: string): string;
+/**
+ * Check if a file path is within the Socket DLX directory.
+ * This is useful for determining if a binary or file is managed by Socket's DLX system.
+ *
+ * @param filePath - Absolute or relative path to check
+ * @returns true if the path is within ~/.socket/_dlx/, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isInSocketDlx('/home/user/.socket/_dlx/abc123/bin/socket') // true
+ * isInSocketDlx('/usr/local/bin/socket') // false
+ * isInSocketDlx(process.argv[0]) // Check if current binary is in DLX
+ * ```
+ */
+export declare function isInSocketDlx(filePath: string): boolean;