@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/fs/safe.js

@@ -0,0 +1,182 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 safe_exports = {};
+__export(safe_exports, {
+  getDel: () => getDel,
+  safeDelete: () => safeDelete,
+  safeDeleteSync: () => safeDeleteSync,
+  safeMkdir: () => safeMkdir,
+  safeMkdirSync: () => safeMkdirSync
+});
+module.exports = __toCommonJS(safe_exports);
+var import_predicates = require("../arrays/predicates");
+var import_predicates2 = require("../errors/predicates");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_mutate = require("../objects/mutate");
+var import_normalize = require("../paths/normalize");
+var import_array = require("../primordials/array");
+var import_globals = require("../primordials/globals");
+var import_string = require("../primordials/string");
+var import_retry = require("../promises/retry");
+var import_internal = require("./_internal");
+var import_path_cache = require("./path-cache");
+const defaultRemoveOptions = (0, import_mutate.objectFreeze)({
+  __proto__: null,
+  force: true,
+  maxRetries: 3,
+  recursive: true,
+  retryDelay: 200
+});
+let _del;
+// @__NO_SIDE_EFFECTS__
+function getDel() {
+  if (_del === void 0) {
+    _del = require("../external/del");
+  }
+  return _del;
+}
+async function safeDelete(filepath, options) {
+  const opts = { __proto__: null, ...options };
+  const patterns = (0, import_predicates.isArray)(filepath) ? filepath.map(import_normalize.pathLikeToString) : [(0, import_normalize.pathLikeToString)(filepath)];
+  let shouldForce = opts.force !== false;
+  if (!shouldForce && patterns.length > 0) {
+    const path = (0, import_path.getNodePath)();
+    const allowedDirs = (0, import_internal.getAllowedDirectories)();
+    const allInAllowedDirs = patterns.every((pattern) => {
+      const resolvedPath = path.resolve(pattern);
+      for (const allowedDir of allowedDirs) {
+        const isInAllowedDir = (0, import_string.StringPrototypeStartsWith)(resolvedPath, allowedDir + path.sep) || resolvedPath === allowedDir;
+        const relativePath = path.relative(allowedDir, resolvedPath);
+        const isGoingBackward = (0, import_string.StringPrototypeStartsWith)(relativePath, "..");
+        if (isInAllowedDir && !isGoingBackward) {
+          return true;
+        }
+      }
+      return false;
+    });
+    if (allInAllowedDirs) {
+      shouldForce = true;
+    }
+  }
+  const maxRetries = opts.maxRetries ?? defaultRemoveOptions.maxRetries;
+  const retryDelay = opts.retryDelay ?? defaultRemoveOptions.retryDelay;
+  const del = /* @__PURE__ */ getDel();
+  await (0, import_retry.pRetry)(
+    async () => {
+      await del.deleteAsync(patterns, {
+        dryRun: false,
+        force: shouldForce,
+        onlyFiles: false
+      });
+    },
+    {
+      retries: maxRetries,
+      baseDelayMs: retryDelay,
+      backoffFactor: 2,
+      signal: opts.signal
+    }
+  );
+}
+function safeDeleteSync(filepath, options) {
+  const opts = { __proto__: null, ...options };
+  const patterns = (0, import_predicates.isArray)(filepath) ? filepath.map(import_normalize.pathLikeToString) : [(0, import_normalize.pathLikeToString)(filepath)];
+  let shouldForce = opts.force !== false;
+  if (!shouldForce && patterns.length > 0) {
+    const path = (0, import_path.getNodePath)();
+    const allowedDirs = (0, import_internal.getAllowedDirectories)();
+    const allInAllowedDirs = patterns.every((pattern) => {
+      const resolvedPath = path.resolve(pattern);
+      for (const allowedDir of allowedDirs) {
+        const isInAllowedDir = (0, import_string.StringPrototypeStartsWith)(resolvedPath, allowedDir + path.sep) || resolvedPath === allowedDir;
+        const relativePath = path.relative(allowedDir, resolvedPath);
+        const isGoingBackward = (0, import_string.StringPrototypeStartsWith)(relativePath, "..");
+        if (isInAllowedDir && !isGoingBackward) {
+          return true;
+        }
+      }
+      return false;
+    });
+    if (allInAllowedDirs) {
+      shouldForce = true;
+    }
+  }
+  const maxRetries = opts.maxRetries ?? defaultRemoveOptions.maxRetries;
+  const retryDelay = opts.retryDelay ?? defaultRemoveOptions.retryDelay;
+  const del = /* @__PURE__ */ getDel();
+  let lastError;
+  let delay = retryDelay;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      del.deleteSync(patterns, {
+        dryRun: false,
+        force: shouldForce,
+        onlyFiles: false
+      });
+      return;
+    } catch (e) {
+      lastError = e;
+      if (attempt < maxRetries) {
+        const waitMs = delay;
+        (0, import_array.AtomicsWait)(
+          new import_array.Int32ArrayCtor(new import_globals.SharedArrayBufferCtor(4)),
+          0,
+          0,
+          waitMs
+        );
+        delay *= 2;
+      }
+    }
+  }
+  if (lastError) {
+    throw lastError;
+  }
+}
+async function safeMkdir(path, options) {
+  const fs = (0, import_fs.getNodeFs)();
+  const opts = { __proto__: null, recursive: true, ...options };
+  try {
+    await fs.promises.mkdir(path, opts);
+  } catch (e) {
+    if (!(0, import_predicates2.isErrnoException)(e) || e.code !== "EEXIST") {
+      throw e;
+    }
+  }
+}
+function safeMkdirSync(path, options) {
+  const fs = (0, import_fs.getNodeFs)();
+  const opts = { __proto__: null, recursive: true, ...options };
+  try {
+    fs.mkdirSync(path, opts);
+  } catch (e) {
+    if (!(0, import_predicates2.isErrnoException)(e) || e.code !== "EEXIST") {
+      throw e;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getDel,
+  safeDelete,
+  safeDeleteSync,
+  safeMkdir,
+  safeMkdirSync
+});

package/dist/fs/types.d.ts

@@ -0,0 +1,277 @@
+/**
+ * @file Public type surface for `fs/*` modules — option shapes, encoding union,
+ *   and result records. Pure types only; no runtime side effects so this module
+ *   stays cheap to import everywhere.
+ */
+import type { Abortable } from 'node:events';
+import type { ObjectEncodingOptions, OpenMode } from 'node:fs';
+import type { JsonReviver } from '../json/types';
+import type { Remap } from '../objects/types';
+/**
+ * Supported text encodings for Node.js Buffers. Includes ASCII, UTF-8/16,
+ * base64, binary, and hexadecimal encodings.
+ */
+export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
+/**
+ * Options for asynchronous `findUp` operations.
+ */
+export interface FindUpOptions {
+    /**
+     * Starting directory for the search.
+     *
+     * @default process.cwd()
+     */
+    cwd?: string | undefined;
+    /**
+     * Only match directories, not files.
+     *
+     * @default false
+     */
+    onlyDirectories?: boolean | undefined;
+    /**
+     * Only match files, not directories.
+     *
+     * @default true
+     */
+    onlyFiles?: boolean | undefined;
+    /**
+     * Abort signal to cancel the search operation.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Options for synchronous `findUpSync` operations.
+ */
+export interface FindUpSyncOptions {
+    /**
+     * Starting directory for the search.
+     *
+     * @default process.cwd()
+     */
+    cwd?: string | undefined;
+    /**
+     * Directory to stop searching at (inclusive). When provided, search will stop
+     * at this directory even if the root hasn't been reached.
+     */
+    stopAt?: string | undefined;
+    /**
+     * Only match directories, not files.
+     *
+     * @default false
+     */
+    onlyDirectories?: boolean | undefined;
+    /**
+     * Only match files, not directories.
+     *
+     * @default true
+     */
+    onlyFiles?: boolean | undefined;
+}
+/**
+ * Options for checking if a directory is empty.
+ */
+export interface IsDirEmptyOptions {
+    /**
+     * Glob patterns for files to ignore when checking emptiness. Files matching
+     * these patterns are not counted.
+     *
+     * @default defaultIgnore
+     */
+    ignore?: string[] | readonly string[] | undefined;
+}
+/**
+ * Represents any valid JSON content type.
+ */
+export type JsonContent = unknown;
+/**
+ * Options for reading directories with filtering and sorting.
+ */
+export interface ReadDirOptions {
+    /**
+     * Glob patterns for directories to ignore.
+     *
+     * @default undefined
+     */
+    ignore?: string[] | readonly string[] | undefined;
+    /**
+     * Include empty directories in results. When `false`, empty directories are
+     * filtered out.
+     *
+     * @default true
+     */
+    includeEmpty?: boolean | undefined;
+    /**
+     * Sort directory names alphabetically using natural sort order.
+     *
+     * @default true
+     */
+    sort?: boolean | undefined;
+}
+/**
+ * Options for reading files with encoding and abort support. Can be either an
+ * options object, an encoding string, or null.
+ */
+export type ReadFileOptions = Remap<ObjectEncodingOptions & Abortable & {
+    flag?: OpenMode | undefined;
+}> | BufferEncoding | null;
+/**
+ * Options for reading and parsing JSON files.
+ */
+export type ReadJsonOptions = Remap<ReadFileOptions & {
+    /**
+     * Whether to throw errors on parse failure. When `false`, returns
+     * `undefined` on error instead of throwing.
+     *
+     * @default true
+     */
+    throws?: boolean | undefined;
+    /**
+     * JSON reviver function to transform parsed values. Same as the second
+     * parameter to `JSON.parse()`.
+     */
+    reviver?: Parameters<typeof JSON.parse>[1] | undefined;
+}>;
+/**
+ * Options for read operations with abort support.
+ */
+export interface ReadOptions extends Abortable {
+    /**
+     * Character encoding to use for reading.
+     *
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding | string | undefined;
+    /**
+     * File system flag for reading behavior.
+     *
+     * @default 'r'
+     */
+    flag?: string | undefined;
+}
+/**
+ * Options for file/directory removal operations.
+ */
+export interface RemoveOptions {
+    /**
+     * Force deletion even outside normally safe directories. When `false`,
+     * prevents deletion outside temp, cacache, and ~/.socket.
+     *
+     * @default true for safe directories, false otherwise
+     */
+    force?: boolean | undefined;
+    /**
+     * Maximum number of retry attempts on failure.
+     *
+     * @default 3
+     */
+    maxRetries?: number | undefined;
+    /**
+     * Recursively delete directories and contents.
+     *
+     * @default true
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Delay in milliseconds between retry attempts.
+     *
+     * @default 200
+     */
+    retryDelay?: number | undefined;
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Options for safe read operations that don't throw on errors.
+ */
+export interface SafeReadOptions extends ReadOptions {
+    /**
+     * Default value to return on read failure. If not provided, `undefined` is
+     * returned on error.
+     */
+    defaultValue?: unknown | undefined;
+}
+/**
+ * Result of file readability validation. Contains lists of valid and invalid
+ * file paths.
+ */
+export interface ValidateFilesResult {
+    /**
+     * File paths that passed validation and are readable.
+     */
+    validPaths: string[];
+    /**
+     * File paths that failed validation (unreadable, permission denied, or
+     * non-existent). Common with Yarn Berry PnP virtual filesystem, pnpm
+     * symlinks, or filesystem race conditions.
+     */
+    invalidPaths: string[];
+}
+/**
+ * Options for writing JSON files with formatting control.
+ */
+export interface WriteJsonOptions extends WriteOptions {
+    /**
+     * End-of-line sequence to use.
+     *
+     * @example
+     *   ;```ts
+     *   // Windows-style line endings
+     *   writeJson('data.json', data, { EOL: '\r\n' })
+     *   ```
+     *
+     * @default '\n'
+     */
+    EOL?: string | undefined;
+    /**
+     * Whether to add a final newline at end of file.
+     *
+     * @default true
+     */
+    finalEOL?: boolean | undefined;
+    /**
+     * JSON replacer function to transform values during stringification. Same as
+     * the second parameter to `JSON.stringify()`.
+     */
+    replacer?: JsonReviver | undefined;
+    /**
+     * Number of spaces for indentation, or string to use for indentation.
+     *
+     * @example
+     *   ;```ts
+     *   // Use tabs instead of spaces
+     *   writeJson('data.json', data, { spaces: '\t' })
+     *
+     *   // Use 4 spaces for indentation
+     *   writeJson('data.json', data, { spaces: 4 })
+     *   ```
+     *
+     * @default 2
+     */
+    spaces?: number | string | undefined;
+}
+/**
+ * Options for write operations with encoding and mode control.
+ */
+export interface WriteOptions extends Abortable {
+    /**
+     * Character encoding for writing.
+     *
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding | string | undefined;
+    /**
+     * File mode (permissions) to set. Uses standard Unix permission bits (e.g.,
+     * 0o644).
+     *
+     * @default 0o666 (read/write for all, respecting umask)
+     */
+    mode?: number | undefined;
+    /**
+     * File system flag for write behavior.
+     *
+     * @default 'w' (create or truncate)
+     */
+    flag?: string | undefined;
+}

package/dist/fs/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/fs/unique.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Generate a unique filepath by appending `-1`, `-2`, … before the
+ *   extension until the path is free. Useful for "save next to existing" flows
+ *   where overwriting silently would be wrong (PDF reports, exports, etc.).
+ */
+import type { PathLike } from 'node:fs';
+/**
+ * Generate a unique filepath by adding number suffix if the path exists.
+ * Appends `-1`, `-2`, etc. before the file extension until a non-existent path
+ * is found. Useful for creating files without overwriting existing ones.
+ *
+ * @example
+ *   ;```ts
+ *   // If 'report.pdf' exists, returns 'report-1.pdf'
+ *   const uniquePath = uniqueSync('./report.pdf')
+ *
+ *   // If 'data.json' and 'data-1.json' exist, returns 'data-2.json'
+ *   const path = uniqueSync('./data.json')
+ *
+ *   // If 'backup' doesn't exist, returns 'backup' unchanged
+ *   const backupPath = uniqueSync('./backup')
+ *   ```
+ *
+ * @param filepath - Desired file path.
+ *
+ * @returns Normalized unique filepath (original if it doesn't exist, or with
+ *   number suffix)
+ */
+export declare function uniqueSync(filepath: PathLike): string;

package/dist/fs/unique.js

@@ -0,0 +1,51 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 unique_exports = {};
+__export(unique_exports, {
+  uniqueSync: () => uniqueSync
+});
+module.exports = __toCommonJS(unique_exports);
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_normalize = require("../paths/normalize");
+// @__NO_SIDE_EFFECTS__
+function uniqueSync(filepath) {
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  const filepathStr = String(filepath);
+  if (!fs.existsSync(filepathStr)) {
+    return (0, import_normalize.normalizePath)(filepathStr);
+  }
+  const dirname = path.dirname(filepathStr);
+  const ext = path.extname(filepathStr);
+  const basename = path.basename(filepathStr, ext);
+  let counter = 1;
+  let uniquePath;
+  do {
+    uniquePath = path.join(dirname, `${basename}-${counter}${ext}`);
+    counter++;
+  } while (fs.existsSync(uniquePath));
+  return (0, import_normalize.normalizePath)(uniquePath);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  uniqueSync
+});

package/dist/fs/validate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Pre-flight readability check for file lists. Used to filter out paths
+ *   that exist in glob results but cannot be opened — Yarn Berry PnP virtual
+ *   filesystem entries, pnpm symlinks pointing into a missing
+ *   content-addressable store, or filesystem races during CI runs.
+ */
+import type { ValidateFilesResult } from './types';
+/**
+ * Validate that file paths are readable before processing. Filters out files
+ * from glob results that cannot be accessed (common with Yarn Berry PnP virtual
+ * filesystem, pnpm content-addressable store symlinks, or filesystem race
+ * conditions in CI/CD environments).
+ *
+ * This defensive pattern prevents ENOENT errors when files exist in glob
+ * results but are not accessible via standard filesystem operations.
+ *
+ * @example
+ *   ```ts
+ *   import { validateFiles } from '@socketsecurity/lib/fs/validate'
+ *
+ *   const files = ['package.json', '.pnp.cjs/virtual-file.json']
+ *   const { validPaths, invalidPaths } = validateFiles(files)
+ *
+ *   console.log(`Valid: ${validPaths.length}`)
+ *   console.log(`Invalid: ${invalidPaths.length}`)
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // Typical usage in Socket CLI commands
+ *   const packagePaths = await getPackageFilesForScan(targets)
+ *   const { validPaths } = validateFiles(packagePaths)
+ *   await sdk.uploadManifestFiles(orgSlug, validPaths)
+ *   ```
+ *
+ * @param filepaths - Array of file paths to validate.
+ *
+ * @returns Object with `validPaths` (readable) and `invalidPaths` (unreadable)
+ */
+export declare function validateFiles(filepaths: string[] | readonly string[]): ValidateFilesResult;

package/dist/fs/validate.js

@@ -0,0 +1,46 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 validate_exports = {};
+__export(validate_exports, {
+  validateFiles: () => validateFiles
+});
+module.exports = __toCommonJS(validate_exports);
+var import_fs = require("../node/fs");
+// @__NO_SIDE_EFFECTS__
+function validateFiles(filepaths) {
+  const fs = (0, import_fs.getNodeFs)();
+  const validPaths = [];
+  const invalidPaths = [];
+  const { R_OK } = fs.constants;
+  for (const filepath of filepaths) {
+    try {
+      fs.accessSync(filepath, R_OK);
+      validPaths.push(filepath);
+    } catch {
+      invalidPaths.push(filepath);
+    }
+  }
+  return { __proto__: null, validPaths, invalidPaths };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  validateFiles
+});