@socketsecurity/lib 5.7.0 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.8.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.8.0) - 2026-03-10
+
+### Added
+
+- **archives**: Added secure archive extraction utilities with support for ZIP, TAR, TAR.GZ, and TGZ formats
+  - Configurable limits: `maxFileSize` (default 100MB), `maxTotalSize` (default 1GB)
+  - Cross-platform path normalization
+  - External dependencies: adm-zip@0.5.16, tar-fs@3.1.2 (bundled, +212KB)
+  - Security features: path traversal protection, file size limits, total size limits, symlink blocking
+  - Strip option to remove leading path components (like tar `--strip-components`)
+  - `detectArchiveFormat()` - Detect archive type from file extension
+  - `extractArchive()` - Generic extraction with auto-format detection
+  - `extractTar()`, `extractTarGz()`, `extractZip()` - Format-specific extractors
+
+- **releases/github**: Added archive extraction support for GitHub releases
+  - Auto-detects format from asset filename
+  - Enhanced `downloadAndExtractZip()` to use generic archive helpers
+  - Supports ZIP, TAR, TAR.GZ, and TGZ assets
+  - `downloadAndExtractArchive()` - Generic archive download and extraction
+
+### Changed
+
+- **dependencies**: Deduplicated 14 external bundle packages to single versions using pnpm overrides and patches
+
 ## [5.7.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.7.0) - 2026-02-12
 
 ### Added
@@ -67,7 +91,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **provenance**: Fixed incorrect package name in provenance workflow
   - Changed from `@socketregistry/lib` to `@socketsecurity/lib`
 
-
 ## [5.6.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.6.0) - 2026-02-08
 
 ### Added
@@ -1073,6 +1096,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This release completely refactors the environment variable system, consolidating 60+ individual env constant files into grouped getter modules with AsyncLocalStorage-based test rewiring.
 
 **Consolidated env files** - Individual files replaced with grouped modules:
+
 - `env/github.ts` - All GitHub-related env vars (GITHUB_TOKEN, GH_TOKEN, GITHUB_API_URL, etc.)
 - `env/socket.ts` - Socket-specific env vars (SOCKET_API_TOKEN, SOCKET_CACACHE_DIR, etc.)
 - `env/socket-cli.ts` - Socket CLI env vars (SOCKET_CLI_API_TOKEN, SOCKET_CLI_CONFIG, etc.)
@@ -1084,6 +1108,7 @@ This release completely refactors the environment variable system, consolidating
 - `env/test.ts` - Test framework env vars (VITEST, JEST_WORKER_ID)
 
 **Constants → Getter functions** - All env constants converted to functions:
+
 ```typescript
 // Before (v1.x):
 import { GITHUB_TOKEN } from '#env/github-token'
@@ -1093,6 +1118,7 @@ import { getGithubToken } from '#env/github'
 ```
 
 **Deleted files** - Removed 60+ individual env constant files:
+
 - `env/github-token.ts`, `env/socket-api-token.ts`, etc. → Consolidated into grouped files
 - `env/getters.ts` → Functions moved to their respective grouped files
 
@@ -1122,6 +1148,7 @@ afterEach(() => {
 ```
 
 **Features:**
+
 - Allows toggling between snapshot and live behavior
 - Compatible with `vi.stubEnv()` as fallback
 
@@ -1224,7 +1251,7 @@ afterEach(() => {
 ### Added
 
 - Added `dlx-package` module for installing and executing npm packages directly
-  - Content-addressed caching using SHA256 hash (like npm's _npx)
+  - Content-addressed caching using SHA256 hash (like npm's \_npx)
   - Auto-force for version ranges (^, ~, >, <) to get latest within range
   - Cross-platform support with comprehensive tests (30 tests)
   - Parses scoped and unscoped package specs correctly

package/README.md

@@ -7,47 +7,219 @@
 [![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 library for [Socket.dev](https://socket.dev/) tools.
+Core infrastructure library for [Socket.dev](https://socket.dev/) security tools. Provides utilities for file system operations, process spawning, HTTP requests, environment detection, logging, spinners, and more.
+
+## Prerequisites
+
+**Node.js 22 or higher** is required.
 
 ## Install
 
 ```bash
+# Using pnpm (recommended)
 pnpm add @socketsecurity/lib
+
+# Using npm
+npm install @socketsecurity/lib
+
+# Using yarn
+yarn add @socketsecurity/lib
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-// Tree-shakeable exports
 import { Spinner } from '@socketsecurity/lib/spinner'
-import { readJsonFile } from '@socketsecurity/lib/fs'
-import { NODE_MODULES } from '@socketsecurity/lib/constants/packages'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { readJson } from '@socketsecurity/lib/fs'
+
+const logger = getDefaultLogger()
+const spinner = Spinner({ text: 'Loading package.json...' })
 
-const spinner = Spinner({ text: 'Loading...' })
 spinner.start()
-const pkg = await readJsonFile('./package.json')
-spinner.stop()
+const pkg = await readJson('./package.json')
+spinner.successAndStop('Loaded successfully')
+
+logger.success(`Package: ${pkg.name}@${pkg.version}`)
 ```
 
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) - Prerequisites, installation, and first examples
+- [Visual Effects](./docs/visual-effects.md) - Spinners, loggers, themes, and progress indicators
+- [File System](./docs/file-system.md) - File operations, globs, paths, and safe deletion
+- [HTTP Utilities](./docs/http-utilities.md) - Making requests, downloading files, and retry logic
+- [Process Utilities](./docs/process-utilities.md) - Spawning processes, IPC, and locks
+- [Package Management](./docs/package-management.md) - npm/pnpm/yarn detection and operations
+- [Environment](./docs/environment.md) - CI detection, env getters, and platform checks
+- [Constants](./docs/constants.md) - Node versions, npm URLs, and platform values
+- [Examples](./docs/examples.md) - Real-world usage patterns
+- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+
 ## What's Inside
 
-- **Visual Effects** → logger, spinner, themes
-- **File System** → fs, globs, paths
-- **Package Management** → dlx, npm, pnpm, yarn
-- **Process & Spawn** → process spawning
-- **Environment** → env getters
-- **Constants** → node, npm, platform
-- **Utilities** → arrays, objects, promises, strings
+### Visual Effects
+
+Spinners, colored loggers, themes, progress bars, and terminal output formatting.
+
+- `Spinner` - Animated CLI spinners with progress tracking
+- `getDefaultLogger()` - Colored console logger with symbols
+- `LOG_SYMBOLS` - Colored terminal symbols (✓, ✗, ⚠, ℹ, →)
+- `setTheme()` - Customize colors across the library
+
+### File System
+
+Cross-platform file operations with safe deletion and convenient wrappers.
+
+- `readFileUtf8()`, `readFileBinary()` - Read files as text or binary
+- `readJson()`, `writeJson()` - Parse and format JSON files
+- `safeDelete()` - Protected deletion with safety checks
+- `findUp()`, `findUpSync()` - Traverse up to find files
+- `safeMkdir()` - Create directories without EEXIST errors
+- `validateFiles()` - Check file readability (useful for Yarn PnP, pnpm)
+
+### HTTP Utilities
+
+Native Node.js HTTP/HTTPS requests with retry logic and redirects.
+
+- `httpJson()` - Fetch and parse JSON from APIs
+- `httpText()` - Fetch text/HTML content
+- `httpDownload()` - Download files with progress callbacks
+- `httpRequest()` - Full control over requests and responses
+- Automatic redirects, exponential backoff retries, timeout support
+
+### Process Management
+
+Spawn child processes safely with cross-platform support.
+
+- `spawn()` - Promise-based process spawning with output capture
+- `spawnSync()` - Synchronous version for blocking operations
+- Array-based arguments prevent command injection
+- Automatic Windows `.cmd`/`.bat` handling
+- `ProcessLock` - Ensure only one instance runs at a time
+- `setupIPC()` - Inter-process communication
+
+### Environment Detection
+
+Type-safe environment variable access and platform detection.
+
+- `getCI()` - Detect CI environment
+- `getNodeEnv()` - Get NODE_ENV value
+- `isTest()` - Check if running tests
+- `getHome()` - Home directory (Unix/Linux/macOS)
+- Test rewiring with `setEnv()`, `resetEnv()`
+
+### Package Management
+
+Detect and work with npm, pnpm, and yarn.
+
+- `detectPackageManager()` - Identify package manager from lock files
+- Package manifest operations
+- Lock file management
+
+### Constants
+
+Pre-defined values for Node.js, npm, and platform detection.
+
+- `getNodeMajorVersion()` - Get current Node.js major version
+- `WIN32`, `DARWIN` - Platform booleans (use `!WIN32 && !DARWIN` for Linux)
+- `getAbortSignal()` - Global abort signal
+
+### Utilities
+
+Helpers for arrays, objects, strings, promises, sorting, and more.
+
+- Arrays, objects, strings manipulation
+- Promise utilities and queues
+- Natural sorting
+- Version comparison
+- Error handling with causes
+
+## Features
+
+- **Tree-shakeable exports** - Import only what you need
+- **Cross-platform** - Works on Windows, macOS, and Linux
+- **TypeScript-first** - Full type safety with .d.ts files
+- **Zero dependencies** (for core HTTP - uses Node.js native modules)
+- **Well-tested** - 84% coverage with comprehensive test suite
+- **Security-focused** - Safe defaults, command injection protection
+- **CommonJS output** - Compatible with Node.js tooling
+
+## Common Use Cases
+
+### Running Shell Commands
+
+```typescript
+import { spawn } from '@socketsecurity/lib/spawn'
+
+const result = await spawn('git', ['status'])
+console.log(result.stdout)
+```
+
+### Making API Requests
+
+```typescript
+import { httpJson } from '@socketsecurity/lib/http-request'
+
+const data = await httpJson('https://api.example.com/data')
+```
+
+### Visual Feedback
+
+```typescript
+import { Spinner } from '@socketsecurity/lib/spinner'
+
+const spinner = Spinner({ text: 'Processing...' })
+spinner.start()
+// ... do work ...
+spinner.successAndStop('Complete!')
+```
+
+### Safe File Deletion
+
+```typescript
+import { safeDelete } from '@socketsecurity/lib/fs'
+
+// Protected against deleting parent directories
+await safeDelete('./build')
+```
+
+## Troubleshooting
+
+**Module not found**: Verify you're importing from the correct path:
+
+```typescript
+// Correct
+import { Spinner } from '@socketsecurity/lib/spinner'
+
+// Wrong
+import { Spinner } from '@socketsecurity/lib'
+```
+
+**Node version error**: This library requires Node.js 22+. Check your version:
+
+```bash
+node --version
+```
+
+For more issues, see the [Troubleshooting Guide](./docs/troubleshooting.md).
 
 ## Development
 
 ```bash
-pnpm install    # Install
-pnpm build      # Build
-pnpm test       # Test
+pnpm install    # Install dependencies
+pnpm build      # Build the library
+pnpm test       # Run tests
+pnpm run cover  # Run tests with coverage
 pnpm dev        # Watch mode
+pnpm run lint   # Check code style
+pnpm run fix    # Fix formatting issues
 ```
 
+## Contributing
+
+Contributions are welcome! Please read the [CLAUDE.md](./CLAUDE.md) file for development guidelines and coding standards.
+
 ## License
 
 MIT

package/dist/archives.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Archive format type.
+ */
+export type ArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip';
+/**
+ * Options for archive extraction.
+ */
+export interface ExtractOptions {
+    /** Suppress log messages */
+    quiet?: boolean;
+    /** Strip leading path components (like tar --strip-components) */
+    strip?: number;
+    /** Maximum size of a single extracted file in bytes (default: 100MB) */
+    maxFileSize?: number;
+    /** Maximum total extracted size in bytes (default: 1GB) */
+    maxTotalSize?: number;
+}
+/**
+ * Detect archive format from file path.
+ *
+ * @param filePath - Path to archive file
+ * @returns Archive format or null if unknown
+ */
+export declare function detectArchiveFormat(filePath: string): ArchiveFormat | null;
+/**
+ * Extract a tar archive to a directory.
+ *
+ * @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.
+ *
+ * @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>;
+/**
+ * Extract a zip archive to a directory.
+ *
+ * @param archivePath - Path to zip file
+ * @param outputDir - Directory to extract to
+ * @param options - Extraction options
+ */
+export declare function extractZip(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
+/**
+ * Extract an archive to a directory.
+ * Automatically detects format from file extension.
+ *
+ * @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.js

@@ -0,0 +1,313 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+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 archives_exports = {};
+__export(archives_exports, {
+  detectArchiveFormat: () => detectArchiveFormat,
+  extractArchive: () => extractArchive,
+  extractTar: () => extractTar,
+  extractTarGz: () => extractTarGz,
+  extractZip: () => extractZip
+});
+module.exports = __toCommonJS(archives_exports);
+var import_node_fs = require("node:fs");
+var import_promises = require("node:stream/promises");
+var import_node_zlib = require("node:zlib");
+var import_adm_zip = __toESM(require("./external/adm-zip.js"));
+var import_tar_fs = __toESM(require("./external/tar-fs.js"));
+var import_fs = require("./fs.js");
+var import_normalize = require("./paths/normalize.js");
+let _path;
+// @__NO_SIDE_EFFECTS__
+function getPath() {
+  if (_path === void 0) {
+    _path = require("path");
+  }
+  return _path;
+}
+const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_SIZE = 1024 * 1024 * 1024;
+function validatePathWithinBase(targetPath, baseDir, entryName) {
+  const path = /* @__PURE__ */ getPath();
+  const resolvedTarget = path.resolve(targetPath);
+  const resolvedBase = path.resolve(baseDir);
+  if (!resolvedTarget.startsWith(resolvedBase + path.sep) && resolvedTarget !== resolvedBase) {
+    throw new Error(
+      `Path traversal attempt detected: entry "${entryName}" would extract to "${resolvedTarget}" outside target directory "${resolvedBase}"`
+    );
+  }
+}
+function detectArchiveFormat(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith(".tar.gz")) {
+    return "tar.gz";
+  }
+  if (lower.endsWith(".tgz")) {
+    return "tgz";
+  }
+  if (lower.endsWith(".tar")) {
+    return "tar";
+  }
+  if (lower.endsWith(".zip")) {
+    return "zip";
+  }
+  return null;
+}
+async function extractTar(archivePath, outputDir, options = {}) {
+  const {
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    maxTotalSize = DEFAULT_MAX_TOTAL_SIZE,
+    strip = 0
+  } = options;
+  const normalizedOutputDir = (0, import_normalize.normalizePath)(outputDir);
+  await (0, import_fs.safeMkdir)(normalizedOutputDir);
+  let totalExtractedSize = 0;
+  let destroyScheduled = false;
+  const extractStream = import_tar_fs.default.extract(normalizedOutputDir, {
+    map: (header) => {
+      if (destroyScheduled) {
+        return header;
+      }
+      if (header.type === "symlink" || header.type === "link") {
+        destroyScheduled = true;
+        process.nextTick(() => {
+          extractStream.destroy(
+            new Error(
+              `Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size && header.size > maxFileSize) {
+        destroyScheduled = true;
+        process.nextTick(() => {
+          extractStream.destroy(
+            new Error(
+              `File size exceeds limit: ${header.name} (${header.size} bytes > ${maxFileSize} bytes)`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size) {
+        totalExtractedSize += header.size;
+        if (totalExtractedSize > maxTotalSize) {
+          destroyScheduled = true;
+          process.nextTick(() => {
+            extractStream.destroy(
+              new Error(
+                `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`
+              )
+            );
+          });
+          return header;
+        }
+      }
+      return header;
+    },
+    strip
+  });
+  extractStream.on("error", () => {
+  });
+  const readStream = (0, import_node_fs.createReadStream)(archivePath);
+  try {
+    await (0, import_promises.pipeline)(readStream, extractStream);
+  } catch (error) {
+    readStream.destroy();
+    throw error;
+  }
+}
+async function extractTarGz(archivePath, outputDir, options = {}) {
+  const {
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    maxTotalSize = DEFAULT_MAX_TOTAL_SIZE,
+    strip = 0
+  } = options;
+  const normalizedOutputDir = (0, import_normalize.normalizePath)(outputDir);
+  await (0, import_fs.safeMkdir)(normalizedOutputDir);
+  let totalExtractedSize = 0;
+  let destroyScheduled = false;
+  const extractStream = import_tar_fs.default.extract(normalizedOutputDir, {
+    map: (header) => {
+      if (destroyScheduled) {
+        return header;
+      }
+      if (header.type === "symlink" || header.type === "link") {
+        destroyScheduled = true;
+        process.nextTick(() => {
+          extractStream.destroy(
+            new Error(
+              `Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size && header.size > maxFileSize) {
+        destroyScheduled = true;
+        process.nextTick(() => {
+          extractStream.destroy(
+            new Error(
+              `File size exceeds limit: ${header.name} (${header.size} bytes > ${maxFileSize} bytes)`
+            )
+          );
+        });
+        return header;
+      }
+      if (header.size) {
+        totalExtractedSize += header.size;
+        if (totalExtractedSize > maxTotalSize) {
+          destroyScheduled = true;
+          process.nextTick(() => {
+            extractStream.destroy(
+              new Error(
+                `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`
+              )
+            );
+          });
+          return header;
+        }
+      }
+      return header;
+    },
+    strip
+  });
+  extractStream.on("error", () => {
+  });
+  const readStream = (0, import_node_fs.createReadStream)(archivePath);
+  try {
+    await (0, import_promises.pipeline)(readStream, (0, import_node_zlib.createGunzip)(), extractStream);
+  } catch (error) {
+    readStream.destroy();
+    throw error;
+  }
+}
+async function extractZip(archivePath, outputDir, options = {}) {
+  const {
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    maxTotalSize = DEFAULT_MAX_TOTAL_SIZE,
+    strip = 0
+  } = options;
+  const normalizedOutputDir = (0, import_normalize.normalizePath)(outputDir);
+  await (0, import_fs.safeMkdir)(normalizedOutputDir);
+  const zip = new import_adm_zip.default(archivePath);
+  const path = /* @__PURE__ */ getPath();
+  const entries = zip.getEntries();
+  let totalExtractedSize = 0;
+  for (const entry of entries) {
+    if (entry.isDirectory) {
+      continue;
+    }
+    const uncompressedSize = entry.header.size;
+    if (uncompressedSize > maxFileSize) {
+      throw new Error(
+        `File size exceeds limit: ${entry.entryName} (${uncompressedSize} bytes > ${maxFileSize} bytes)`
+      );
+    }
+    totalExtractedSize += uncompressedSize;
+    if (totalExtractedSize > maxTotalSize) {
+      throw new Error(
+        `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`
+      );
+    }
+    const parts = entry.entryName.split("/");
+    if (parts.length <= strip) {
+      continue;
+    }
+    const strippedPath = parts.slice(strip).join("/");
+    const targetPath = path.join(normalizedOutputDir, strippedPath);
+    validatePathWithinBase(targetPath, normalizedOutputDir, entry.entryName);
+  }
+  if (strip === 0) {
+    for (const entry of entries) {
+      if (!entry.isDirectory) {
+        const targetPath = path.join(normalizedOutputDir, entry.entryName);
+        validatePathWithinBase(targetPath, normalizedOutputDir, entry.entryName);
+      }
+    }
+    zip.extractAllTo(normalizedOutputDir, true);
+  } else {
+    const path2 = /* @__PURE__ */ getPath();
+    const entries2 = zip.getEntries();
+    const dirsToCreate = /* @__PURE__ */ new Set();
+    for (const entry of entries2) {
+      if (entry.isDirectory) {
+        continue;
+      }
+      const parts = entry.entryName.split("/");
+      if (parts.length <= strip) {
+        continue;
+      }
+      const strippedPath = parts.slice(strip).join("/");
+      const targetPath = path2.join(normalizedOutputDir, strippedPath);
+      dirsToCreate.add(path2.dirname(targetPath));
+    }
+    await Promise.all(Array.from(dirsToCreate).map((dir) => (0, import_fs.safeMkdir)(dir)));
+    for (const entry of entries2) {
+      if (entry.isDirectory) {
+        continue;
+      }
+      const parts = entry.entryName.split("/");
+      if (parts.length <= strip) {
+        continue;
+      }
+      const strippedPath = parts.slice(strip).join("/");
+      const targetPath = path2.join(normalizedOutputDir, strippedPath);
+      zip.extractEntryTo(entry, path2.dirname(targetPath), false, true);
+    }
+  }
+}
+async function extractArchive(archivePath, outputDir, options = {}) {
+  const format = detectArchiveFormat(archivePath);
+  if (!format) {
+    const path = /* @__PURE__ */ getPath();
+    const ext = path.extname(archivePath).toLowerCase();
+    throw new Error(
+      `Unsupported archive format${ext ? ` (extension: ${ext})` : ""}: ${archivePath}. Supported formats: .zip, .tar, .tar.gz, .tgz`
+    );
+  }
+  switch (format) {
+    case "zip":
+      return await extractZip(archivePath, outputDir, options);
+    case "tar":
+      return await extractTar(archivePath, outputDir, options);
+    case "tar.gz":
+    case "tgz":
+      return await extractTarGz(archivePath, outputDir, options);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  detectArchiveFormat,
+  extractArchive,
+  extractTar,
+  extractTarGz,
+  extractZip
+});

package/dist/arrays.js

@@ -57,10 +57,9 @@ function arrayChunk(arr, size) {
     throw new Error("Chunk size must be greater than 0");
   }
   const { length } = arr;
-  const actualChunkSize = Math.min(length, chunkSize);
   const chunks = [];
-  for (let i = 0; i < length; i += actualChunkSize) {
-    chunks.push(arr.slice(i, i + actualChunkSize));
+  for (let i = 0; i < length; i += chunkSize) {
+    chunks.push(arr.slice(i, i + chunkSize));
   }
   return chunks;
 }