@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/ai/worktree.js

@@ -0,0 +1,200 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var worktree_exports = {};
+__export(worktree_exports, {
+  currentBranch: () => currentBranch,
+  git: () => git,
+  hasCommittedChanges: () => hasCommittedChanges,
+  hasStagedOrUnstaged: () => hasStagedOrUnstaged,
+  runOne: () => runOne,
+  spawnAiAgentsInWorktrees: () => spawnAiAgentsInWorktrees,
+  tryGit: () => tryGit
+});
+module.exports = __toCommonJS(worktree_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"), 1);
+var import_message = require("../errors/message");
+var import_child = require("../process/spawn/child");
+var import_errors = require("../process/spawn/errors");
+const DEFAULT_CONCURRENCY = 4;
+const MAX_CONCURRENCY = 8;
+function currentBranch(repo) {
+  return git(repo, "symbolic-ref", "--short", "HEAD");
+}
+function git(cwd, ...args) {
+  const result = (0, import_child.spawnSync)("git", args, {
+    cwd,
+    stdio: "pipe",
+    stdioString: true
+  });
+  return String(result.stdout ?? "").trim();
+}
+function hasCommittedChanges(worktree, baseBranch) {
+  const log = tryGit(worktree, "log", "--oneline", `${baseBranch}..HEAD`);
+  if (!log.ok) {
+    return false;
+  }
+  return log.output.trim().length > 0;
+}
+function hasStagedOrUnstaged(worktree) {
+  const status = tryGit(worktree, "status", "--porcelain");
+  return status.ok && status.output.trim().length > 0;
+}
+async function runOne(item, index, worktreeBranch, worktreePath, baseRepo, branch, cleanup, fn) {
+  const add = tryGit(
+    baseRepo,
+    "worktree",
+    "add",
+    "-b",
+    worktreeBranch,
+    worktreePath,
+    branch
+  );
+  if (!add.ok) {
+    return {
+      cleanup: "kept",
+      error: new Error(`git worktree add failed: ${add.output}`),
+      merged: false,
+      status: "rejected",
+      worktreePath
+    };
+  }
+  let value;
+  let error;
+  try {
+    value = await fn(item, { branch: worktreeBranch, cwd: worktreePath, index });
+  } catch (e) {
+    error = e;
+  }
+  const hasCommitted = hasCommittedChanges(worktreePath, branch);
+  const hasUncommitted = hasStagedOrUnstaged(worktreePath);
+  let merged = false;
+  if (error === void 0 && hasCommitted) {
+    const merge = tryGit(baseRepo, "merge", "--ff-only", worktreeBranch);
+    if (merge.ok) {
+      merged = true;
+    } else {
+      error = new Error(`git merge --ff-only failed: ${merge.output}`);
+    }
+  }
+  let didCleanup = "kept";
+  const shouldCleanup = error === void 0 && (cleanup === "always" || cleanup === "on-empty" && !hasCommitted && !hasUncommitted);
+  if (shouldCleanup) {
+    const remove = tryGit(baseRepo, "worktree", "remove", worktreePath);
+    if (remove.ok) {
+      didCleanup = "removed";
+      tryGit(baseRepo, "branch", "-D", worktreeBranch);
+    }
+  }
+  if (error !== void 0) {
+    return {
+      cleanup: didCleanup,
+      error,
+      merged,
+      status: "rejected",
+      worktreePath
+    };
+  }
+  return {
+    cleanup: didCleanup,
+    merged,
+    status: "fulfilled",
+    value,
+    worktreePath
+  };
+}
+async function spawnAiAgentsInWorktrees(items, fn, options) {
+  const cleanup = options.cleanup ?? "always";
+  const namePrefix = options.namePrefix ?? "agent-task";
+  const concurrency = Math.max(
+    1,
+    Math.min(options.concurrency ?? DEFAULT_CONCURRENCY, MAX_CONCURRENCY)
+  );
+  const baseRepo = options.baseRepo;
+  if (!(0, import_node_fs.existsSync)(import_node_path.default.join(baseRepo, ".git"))) {
+    throw new Error(
+      `spawnAiAgentsInWorktrees: baseRepo is not a git checkout: ${baseRepo}`
+    );
+  }
+  const branch = options.branch ?? currentBranch(baseRepo);
+  const worktreeRoot = options.worktreeRoot ?? import_node_path.default.join(
+    process.platform === "win32" ? process.env["TEMP"] ?? "." : "/tmp",
+    `${namePrefix}-${Date.now()}`
+  );
+  const settled = [];
+  let cursor = 0;
+  async function worker() {
+    for (; ; ) {
+      const idx = cursor;
+      cursor += 1;
+      if (idx >= items.length) {
+        return;
+      }
+      const item = items[idx];
+      const worktreeBranch = `${namePrefix}-${idx}-${Date.now()}`;
+      const worktreePath = import_node_path.default.join(worktreeRoot, `${namePrefix}-${idx}`);
+      const result = await runOne(
+        item,
+        idx,
+        worktreeBranch,
+        worktreePath,
+        baseRepo,
+        branch,
+        cleanup,
+        fn
+      );
+      settled[idx] = result;
+    }
+  }
+  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+  return settled;
+}
+function tryGit(cwd, ...args) {
+  try {
+    const output = git(cwd, ...args);
+    return { ok: true, output };
+  } catch (e) {
+    if ((0, import_errors.isSpawnError)(e)) {
+      return { ok: false, output: String(e.stderr ?? e.stdout ?? "") };
+    }
+    return { ok: false, output: (0, import_message.errorMessage)(e) };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  currentBranch,
+  git,
+  hasCommittedChanges,
+  hasStagedOrUnstaged,
+  runOne,
+  spawnAiAgentsInWorktrees,
+  tryGit
+});

package/dist/ansi/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file ANSI escape code constants. Commonly used terminal formatting sequences
+ *   for bold, dim, italic, reset, strikethrough, and underline.
+ */
+export declare const ANSI_BOLD = "\u001B[1m";
+export declare const ANSI_DIM = "\u001B[2m";
+export declare const ANSI_ITALIC = "\u001B[3m";
+export declare const ANSI_RESET = "\u001B[0m";
+export declare const ANSI_STRIKETHROUGH = "\u001B[9m";
+export declare const ANSI_UNDERLINE = "\u001B[4m";

package/dist/ansi/constants.js

@@ -0,0 +1,45 @@
+"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 constants_exports = {};
+__export(constants_exports, {
+  ANSI_BOLD: () => ANSI_BOLD,
+  ANSI_DIM: () => ANSI_DIM,
+  ANSI_ITALIC: () => ANSI_ITALIC,
+  ANSI_RESET: () => ANSI_RESET,
+  ANSI_STRIKETHROUGH: () => ANSI_STRIKETHROUGH,
+  ANSI_UNDERLINE: () => ANSI_UNDERLINE
+});
+module.exports = __toCommonJS(constants_exports);
+const ANSI_BOLD = "\x1B[1m";
+const ANSI_DIM = "\x1B[2m";
+const ANSI_ITALIC = "\x1B[3m";
+const ANSI_RESET = "\x1B[0m";
+const ANSI_STRIKETHROUGH = "\x1B[9m";
+const ANSI_UNDERLINE = "\x1B[4m";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANSI_BOLD,
+  ANSI_DIM,
+  ANSI_ITALIC,
+  ANSI_RESET,
+  ANSI_STRIKETHROUGH,
+  ANSI_UNDERLINE
+});

package/dist/ansi/strip.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file ANSI escape-code regex factory and stripping helper. Provides
+ *   `ansiRegex()` for matching CSI/OSC sequences and `stripAnsi()` for removing
+ *   ANSI formatting from terminal output.
+ */
+/**
+ * Create a regular expression for matching ANSI escape codes.
+ *
+ * Inlined ansi-regex: https://socket.dev/npm/package/ansi-regexp/overview/6.2.2
+ * MIT License Copyright (c) Sindre Sorhus
+ * [sindresorhus@gmail.com](mailto:sindresorhus@gmail.com)
+ * (https://sindresorhus.com)
+ *
+ * @example
+ *   ;```typescript
+ *   const regex = ansiRegex()
+ *   '\u001b[31mHello\u001b[0m'.match(regex) // ['\u001b[31m', '\u001b[0m']
+ *   ansiRegex({ onlyFirst: true }) // matches only the first code
+ *   ```
+ */
+export declare function ansiRegex(options?: {
+    onlyFirst?: boolean;
+}): RegExp;
+/**
+ * Strip ANSI escape codes from text. Uses the inlined ansi-regex for matching.
+ *
+ * @example
+ *   ;```typescript
+ *   stripAnsi('\u001b[31mError\u001b[0m') // 'Error'
+ *   stripAnsi('\u001b[1mBold\u001b[0m') // 'Bold'
+ *   ```
+ */
+export declare function stripAnsi(text: string): string;

package/dist/{ansi.js → ansi/strip.js}

@@ -18,25 +18,14 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var ansi_exports = {};
-__export(ansi_exports, {
-  ANSI_BOLD: () => ANSI_BOLD,
-  ANSI_DIM: () => ANSI_DIM,
-  ANSI_ITALIC: () => ANSI_ITALIC,
-  ANSI_RESET: () => ANSI_RESET,
-  ANSI_STRIKETHROUGH: () => ANSI_STRIKETHROUGH,
-  ANSI_UNDERLINE: () => ANSI_UNDERLINE,
+var strip_exports = {};
+__export(strip_exports, {
   ansiRegex: () => ansiRegex,
   stripAnsi: () => stripAnsi
 });
-module.exports = __toCommonJS(ansi_exports);
-var import_primordials = require("./primordials");
-const ANSI_BOLD = "\x1B[1m";
-const ANSI_DIM = "\x1B[2m";
-const ANSI_ITALIC = "\x1B[3m";
-const ANSI_RESET = "\x1B[0m";
-const ANSI_STRIKETHROUGH = "\x1B[9m";
-const ANSI_UNDERLINE = "\x1B[4m";
+module.exports = __toCommonJS(strip_exports);
+var import_regexp = require("../primordials/regexp");
+var import_string = require("../primordials/string");
 const ANSI_REGEX = /\x1b\[[0-9;]*m/g;
 // @__NO_SIDE_EFFECTS__
 function ansiRegex(options) {
@@ -45,20 +34,14 @@ function ansiRegex(options) {
   const osc = `(?:\\u001B\\][\\s\\S]*?${ST})`;
   const csi = "[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]";
   const pattern = `${osc}|${csi}`;
-  return new import_primordials.RegExpCtor(pattern, onlyFirst ? void 0 : "g");
+  return new import_regexp.RegExpCtor(pattern, onlyFirst ? void 0 : "g");
 }
 // @__NO_SIDE_EFFECTS__
 function stripAnsi(text) {
-  return (0, import_primordials.StringPrototypeReplace)(text, ANSI_REGEX, "");
+  return (0, import_string.StringPrototypeReplace)(text, ANSI_REGEX, "");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ANSI_BOLD,
-  ANSI_DIM,
-  ANSI_ITALIC,
-  ANSI_RESET,
-  ANSI_STRIKETHROUGH,
-  ANSI_UNDERLINE,
   ansiRegex,
   stripAnsi
 });

package/dist/archives/_internal.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Private internals for `archives/*` modules — defaults, lazy module
+ *   accessors (adm-zip, tar-fs, node:path), shared pre-extraction validators
+ *   (`assertArchiveExists`, `validatePathWithinBase`).
+ */
+import type tarFsType from '../external/tar-fs';
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+export declare const DEFAULT_MAX_TOTAL_SIZE: number;
+export declare const DEFAULT_MAX_ENTRIES = 100000;
+export { getNodePath as getPath } from '../node/path';
+/**
+ * Assert that an archive file exists on disk before handing it to the
+ * underlying extractor. Normalizes the "missing archive" surface across all
+ * three extractors (zip/tar/tar.gz): each now throws a Node-style `ENOENT`
+ * error with the archive path. Without this preflight, `zip` goes through
+ * adm-zip and surfaces as `"Invalid filename"`, while `tar`/`tar.gz` surface
+ * the raw Node `ENOENT` — inconsistent, and adm-zip's message didn't include
+ * the path.
+ *
+ * @private
+ *
+ * @throws Error with `code: 'ENOENT'` if archivePath doesn't exist.
+ */
+export declare function assertArchiveExists(archivePath: string): void;
+export declare function getAdmZip(): import("../external/adm-zip").AdmZipConstructor;
+export declare function getTarFs(): typeof tarFsType;
+/**
+ * Validate that a resolved path is within the target directory. Prevents path
+ * traversal attacks.
+ *
+ * @private
+ *
+ * @param targetPath - The resolved path to validate.
+ * @param baseDir - The base directory that should contain the path.
+ * @param entryName - Original entry name for error reporting.
+ *
+ * @throws Error if path is outside the base directory
+ */
+export declare function validatePathWithinBase(targetPath: string, baseDir: string, entryName: string): void;

package/dist/archives/_internal.js

@@ -0,0 +1,87 @@
+"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 internal_exports = {};
+__export(internal_exports, {
+  DEFAULT_MAX_ENTRIES: () => DEFAULT_MAX_ENTRIES,
+  DEFAULT_MAX_FILE_SIZE: () => DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_MAX_TOTAL_SIZE: () => DEFAULT_MAX_TOTAL_SIZE,
+  assertArchiveExists: () => assertArchiveExists,
+  getAdmZip: () => getAdmZip,
+  getPath: () => import_path2.getNodePath,
+  getTarFs: () => getTarFs,
+  validatePathWithinBase: () => validatePathWithinBase
+});
+module.exports = __toCommonJS(internal_exports);
+var import_node_fs = require("node:fs");
+var import_error = require("../primordials/error");
+var import_string = require("../primordials/string");
+var import_path = require("../node/path");
+var import_path2 = require("../node/path");
+const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_SIZE = 1024 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 1e5;
+let _AdmZip;
+let _tarFs;
+function assertArchiveExists(archivePath) {
+  if (!(0, import_node_fs.existsSync)(archivePath)) {
+    const err = new import_error.ErrorCtor(
+      `ENOENT: no such file or directory, open '${archivePath}'`
+    );
+    err.code = "ENOENT";
+    err.path = archivePath;
+    throw err;
+  }
+}
+// @__NO_SIDE_EFFECTS__
+function getAdmZip() {
+  if (_AdmZip === void 0) {
+    _AdmZip = require("../external/adm-zip.js");
+  }
+  return _AdmZip;
+}
+// @__NO_SIDE_EFFECTS__
+function getTarFs() {
+  if (_tarFs === void 0) {
+    _tarFs = require("../external/tar-fs.js");
+  }
+  return _tarFs;
+}
+function validatePathWithinBase(targetPath, baseDir, entryName) {
+  const path = (0, import_path.getNodePath)();
+  const resolvedTarget = path.resolve(targetPath);
+  const resolvedBase = path.resolve(baseDir);
+  if (!(0, import_string.StringPrototypeStartsWith)(resolvedTarget, resolvedBase + path.sep) && resolvedTarget !== resolvedBase) {
+    throw new import_error.ErrorCtor(
+      `Path traversal attempt detected: entry "${entryName}" would extract to "${resolvedTarget}" outside target directory "${resolvedBase}"`
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_MAX_ENTRIES,
+  DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_MAX_TOTAL_SIZE,
+  assertArchiveExists,
+  getAdmZip,
+  getPath,
+  getTarFs,
+  validatePathWithinBase
+});

package/dist/archives/detect.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Format detection by file extension.
+ */
+import type { ArchiveFormat } from './types';
+/**
+ * Detect archive format from file path.
+ *
+ * @example
+ *   ;```typescript
+ *   detectArchiveFormat('package.tar.gz') // 'tar.gz'
+ *   detectArchiveFormat('archive.zip') // 'zip'
+ *   detectArchiveFormat('data.csv') // undefined
+ *   ```
+ *
+ * @param filePath - Path to archive file.
+ *
+ * @returns Archive format or undefined if unknown
+ */
+export declare function detectArchiveFormat(filePath: string): ArchiveFormat | undefined;

package/dist/archives/detect.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 detect_exports = {};
+__export(detect_exports, {
+  detectArchiveFormat: () => detectArchiveFormat
+});
+module.exports = __toCommonJS(detect_exports);
+var import_string = require("../primordials/string");
+function detectArchiveFormat(filePath) {
+  const lower = filePath.toLowerCase();
+  if ((0, import_string.StringPrototypeEndsWith)(lower, ".tar.gz")) {
+    return "tar.gz";
+  }
+  if ((0, import_string.StringPrototypeEndsWith)(lower, ".tgz")) {
+    return "tgz";
+  }
+  if ((0, import_string.StringPrototypeEndsWith)(lower, ".tar")) {
+    return "tar";
+  }
+  if ((0, import_string.StringPrototypeEndsWith)(lower, ".zip")) {
+    return "zip";
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  detectArchiveFormat
+});

package/dist/archives/extract.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file `extractArchive` — format-detecting dispatcher that routes to
+ *   `extractTar` / `extractTarGz` / `extractZip`.
+ */
+import type { ExtractOptions } from './types';
+/**
+ * Extract an archive to a directory. Automatically detects format from file
+ * extension.
+ *
+ * @example
+ *   ;```typescript
+ *   await extractArchive('/tmp/package.tar.gz', '/tmp/output')
+ *   await extractArchive('/tmp/release.zip', '/tmp/output', { strip: 1 })
+ *   ```
+ *
+ * @param archivePath - Path to archive file.
+ * @param outputDir - Directory to extract to.
+ * @param options - Extraction options.
+ *
+ * @throws Error if archive format is not supported
+ */
+export declare function extractArchive(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;

package/dist/archives/extract.js

@@ -0,0 +1,53 @@
+"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 extract_exports = {};
+__export(extract_exports, {
+  extractArchive: () => extractArchive
+});
+module.exports = __toCommonJS(extract_exports);
+var import_error = require("../primordials/error");
+var import_detect = require("./detect");
+var import_internal = require("./_internal");
+var import_tar = require("./tar");
+var import_zip = require("./zip");
+async function extractArchive(archivePath, outputDir, options = {}) {
+  const format = (0, import_detect.detectArchiveFormat)(archivePath);
+  if (!format) {
+    const path = (0, import_internal.getPath)();
+    const ext = path.extname(archivePath).toLowerCase();
+    throw new import_error.ErrorCtor(
+      `Unsupported archive format${ext ? ` (extension: ${ext})` : ""}: ${archivePath}. Supported formats: .zip, .tar, .tar.gz, .tgz`
+    );
+  }
+  switch (format) {
+    case "zip":
+      return await (0, import_zip.extractZip)(archivePath, outputDir, options);
+    case "tar":
+      return await (0, import_tar.extractTar)(archivePath, outputDir, options);
+    case "tar.gz":
+    case "tgz":
+      return await (0, import_tar.extractTarGz)(archivePath, outputDir, options);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractArchive
+});

package/dist/archives/tar.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Tar / tar.gz extraction with security limits and symlink rejection.
+ *   Both functions share a `map(header)` callback that enforces:
+ *
+ *   - max entry count (inode-exhaustion DoS guard)
+ *   - max single-file size
+ *   - max total extracted size
+ *   - rejection of null bytes in entry names
+ *   - rejection of symlink / hardlink entries The duplicate map() bodies are
+ *     intentional: the surrounding state (entryCount, totalExtractedSize,
+ *     destroyScheduled) is per-call, so a shared helper would require threading
+ *     state through closures and obscure the security-defense intent.
+ */
+import type { ExtractOptions } from './types';
+/**
+ * Extract a tar archive to a directory.
+ *
+ * @example
+ *   ;```typescript
+ *   await extractTar('/tmp/archive.tar', '/tmp/output')
+ *   await extractTar('/tmp/archive.tar', '/tmp/output', { strip: 1 })
+ *   ```
+ *
+ * @param archivePath - Path to tar file.
+ * @param outputDir - Directory to extract to.
+ * @param options - Extraction options.
+ */
+export declare function extractTar(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
+/**
+ * Extract a gzipped tar archive to a directory.
+ *
+ * @example
+ *   ;```typescript
+ *   await extractTarGz('/tmp/archive.tar.gz', '/tmp/output')
+ *   await extractTarGz('/tmp/archive.tgz', '/tmp/output', { strip: 1 })
+ *   ```
+ *
+ * @param archivePath - Path to tar.gz or tgz file.
+ * @param outputDir - Directory to extract to.
+ * @param options - Extraction options.
+ */
+export declare function extractTarGz(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;