@configjs/cli 1.1.16 → 1.1.18

package/dist/chunk-V2IBYLVH.js

@@ -0,0 +1,932 @@
+import {
+  getModuleLogger
+} from "./chunk-VN4XTFDK.js";
+
+// src/utils/package-manager.ts
+import { execa } from "execa";
+import fs from "fs-extra";
+import { resolve, join } from "path";
+
+// src/core/package-validator.ts
+var PACKAGE_NAME_REGEX = /^(@[a-z0-9]([a-z0-9._-]*[a-z0-9])?\/)?[a-z0-9]([a-z0-9._-]*[a-z0-9])?(@[~^>=<*\d.+-]+)?$/i;
+var FORBIDDEN_FLAGS = /* @__PURE__ */ new Set([
+  "--registry",
+  "--proxy",
+  "--https-proxy",
+  "--ca",
+  "--cafile",
+  "--cert",
+  "--key",
+  "--strict-ssl",
+  "--save",
+  "--save-dev",
+  "--save-optional",
+  "--save-exact",
+  "--save-bundle",
+  "--no-save",
+  "--no-save-dev",
+  "--no-save-optional",
+  "--force",
+  "--no-optional",
+  "--prefer-offline",
+  "--no-audit",
+  "--no-fund"
+]);
+function validatePackageName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    return false;
+  }
+  if (name.startsWith("--")) {
+    return false;
+  }
+  if (/[;&|`$()[\]{}<>\\]/.test(name)) {
+    return false;
+  }
+  if (FORBIDDEN_FLAGS.has(name.toLowerCase())) {
+    return false;
+  }
+  return PACKAGE_NAME_REGEX.test(name);
+}
+function validatePackageNames(names) {
+  return names.filter((name) => !validatePackageName(name));
+}
+function getPackageValidationErrorMessage(names) {
+  if (names.length === 0) {
+    return "No invalid package names";
+  }
+  const list = names.slice(0, 5).join(", ");
+  const suffix = names.length > 5 ? ` and ${names.length - 5} more` : "";
+  return `Invalid package name${names.length > 1 ? "s" : ""}: ${list}${suffix}`;
+}
+
+// src/core/rate-limiter.ts
+var RateLimiter = class {
+  perUserBuckets = /* @__PURE__ */ new Map();
+  globalBucket;
+  perUserLimit;
+  globalLimit;
+  refillInterval;
+  burstSize;
+  cooldownDuration;
+  constructor(config = {}) {
+    this.perUserLimit = config.perUserLimit ?? 1;
+    this.globalLimit = config.globalLimit ?? 10;
+    this.refillInterval = config.refillInterval ?? 1e3;
+    this.burstSize = config.burstSize ?? 3;
+    this.cooldownDuration = config.cooldownDuration ?? 5e3;
+    this.globalBucket = {
+      tokens: this.globalLimit * this.burstSize,
+      lastRefillTime: Date.now()
+    };
+  }
+  /**
+   * Check if a request is allowed for a specific user
+   * @param userId - Unique identifier for the user/client
+   * @returns RateLimitResult with status and timing info
+   */
+  checkUserLimit(userId) {
+    const now = Date.now();
+    if (!this.perUserBuckets.has(userId)) {
+      this.perUserBuckets.set(userId, {
+        tokens: this.perUserLimit * this.burstSize,
+        lastRefillTime: now
+      });
+    }
+    const userBucket = this.perUserBuckets.get(userId);
+    if (!userBucket) {
+      throw new Error(`Failed to get or create user bucket for ${userId}`);
+    }
+    const elapsedMs = now - userBucket.lastRefillTime;
+    const tokensToAdd = elapsedMs / this.refillInterval * this.perUserLimit;
+    userBucket.tokens = Math.min(
+      this.perUserLimit * this.burstSize,
+      userBucket.tokens + tokensToAdd
+    );
+    userBucket.lastRefillTime = now;
+    if (userBucket.tokens >= 1) {
+      userBucket.tokens -= 1;
+      const remainingTokens = Math.floor(userBucket.tokens);
+      return {
+        allowed: true,
+        remainingTokens,
+        resetTime: now + this.refillInterval,
+        cooldownMs: 0
+      };
+    }
+    const timeToNextToken = this.refillInterval;
+    return {
+      allowed: false,
+      remainingTokens: 0,
+      resetTime: now + timeToNextToken,
+      cooldownMs: this.cooldownDuration,
+      message: `Rate limit exceeded. Please wait ${(this.cooldownDuration / 1e3).toFixed(1)}s before retrying.`
+    };
+  }
+  /**
+   * Check if global rate limit is exceeded
+   * @returns RateLimitResult with status and timing info
+   */
+  checkGlobalLimit() {
+    const now = Date.now();
+    const elapsedMs = now - this.globalBucket.lastRefillTime;
+    const tokensToAdd = elapsedMs / this.refillInterval * this.globalLimit;
+    this.globalBucket.tokens = Math.min(
+      this.globalLimit * this.burstSize,
+      this.globalBucket.tokens + tokensToAdd
+    );
+    this.globalBucket.lastRefillTime = now;
+    if (this.globalBucket.tokens >= 1) {
+      this.globalBucket.tokens -= 1;
+      const remainingTokens = Math.floor(this.globalBucket.tokens);
+      return {
+        allowed: true,
+        remainingTokens,
+        resetTime: now + this.refillInterval,
+        cooldownMs: 0
+      };
+    }
+    const timeToNextToken = this.refillInterval;
+    return {
+      allowed: false,
+      remainingTokens: 0,
+      resetTime: now + timeToNextToken,
+      cooldownMs: this.cooldownDuration,
+      message: `Global rate limit exceeded. Service is temporarily throttled. Please wait ${(this.cooldownDuration / 1e3).toFixed(1)}s.`
+    };
+  }
+  /**
+   * Check both user and global rate limits
+   * @param userId - Unique identifier for the user/client
+   * @returns RateLimitResult - will be denied if EITHER limit is exceeded
+   */
+  checkRequest(userId) {
+    const userResult = this.checkUserLimit(userId);
+    if (!userResult.allowed) {
+      return userResult;
+    }
+    const globalResult = this.checkGlobalLimit();
+    if (!globalResult.allowed) {
+      return globalResult;
+    }
+    const userBucketTokens = this.perUserBuckets.get(userId)?.tokens ?? 0;
+    return {
+      allowed: true,
+      remainingTokens: Math.min(
+        Math.floor(userBucketTokens),
+        Math.floor(this.globalBucket.tokens)
+      ),
+      resetTime: Math.min(userResult.resetTime, globalResult.resetTime),
+      cooldownMs: 0
+    };
+  }
+  /**
+   * Middleware for Express/similar frameworks
+   * Adds rate limiting headers to response
+   * @param userId - Unique identifier for the user/client
+   * @returns Headers to add to HTTP response
+   */
+  getHeaders(userId) {
+    const result = this.checkUserLimit(userId);
+    return {
+      "X-RateLimit-Limit": String(this.perUserLimit),
+      "X-RateLimit-Remaining": String(result.remainingTokens),
+      "X-RateLimit-Reset": String(result.resetTime)
+    };
+  }
+  getStatus(userId) {
+    if (userId) {
+      const bucket = this.perUserBuckets.get(userId);
+      if (!bucket) {
+        return {
+          userId,
+          tokens: this.perUserLimit * this.burstSize,
+          lastRefillTime: Date.now()
+        };
+      }
+      return {
+        userId,
+        tokens: bucket.tokens,
+        lastRefillTime: bucket.lastRefillTime
+      };
+    }
+    return {
+      global: {
+        tokens: this.globalBucket.tokens,
+        lastRefillTime: this.globalBucket.lastRefillTime
+      },
+      users: Array.from(this.perUserBuckets.entries()).map(([id, bucket]) => ({
+        userId: id,
+        tokens: bucket.tokens,
+        lastRefillTime: bucket.lastRefillTime
+      }))
+    };
+  }
+  /**
+   * Reset rate limiter (useful for testing)
+   */
+  reset() {
+    this.perUserBuckets.clear();
+    this.globalBucket = {
+      tokens: this.globalLimit * this.burstSize,
+      lastRefillTime: Date.now()
+    };
+  }
+  /**
+   * Clean up old user buckets (older than 1 hour)
+   * Prevents memory leaks from abandoned sessions
+   */
+  cleanup(maxAge = 36e5) {
+    const now = Date.now();
+    const toDelete = [];
+    for (const [userId, bucket] of this.perUserBuckets.entries()) {
+      if (now - bucket.lastRefillTime > maxAge) {
+        toDelete.push(userId);
+      }
+    }
+    for (const userId of toDelete) {
+      this.perUserBuckets.delete(userId);
+    }
+    return toDelete.length;
+  }
+};
+var globalRateLimiter = null;
+function getGlobalRateLimiter(config) {
+  if (!globalRateLimiter) {
+    globalRateLimiter = new RateLimiter(config);
+  }
+  return globalRateLimiter;
+}
+
+// src/core/timeout-manager.ts
+var OPERATION_TIMEOUTS = {
+  /** Package installation maximum duration */
+  PACKAGE_INSTALL: 5 * 60 * 1e3,
+  // 5 minutes
+  /** Framework detection maximum duration */
+  FRAMEWORK_DETECT: 30 * 1e3,
+  // 30 seconds
+  /** Plugin configuration maximum duration */
+  PLUGIN_CONFIG: 60 * 1e3,
+  // 1 minute
+  /** Input validation maximum duration */
+  VALIDATION: 30 * 1e3,
+  // 30 seconds
+  /** General command execution */
+  COMMAND_EXEC: 2 * 60 * 1e3
+  // 2 minutes
+};
+var RESOURCE_LIMITS = {
+  /** Maximum stdout/stderr buffer (10MB) */
+  MAX_BUFFER: 10 * 1024 * 1024,
+  /** Maximum number of concurrent operations */
+  MAX_CONCURRENT: 4,
+  /** Maximum child processes per operation */
+  MAX_CHILD_PROCESSES: 1
+};
+function createTimeout(duration, operation) {
+  return new Promise((_, reject) => {
+    const timer = setTimeout(() => {
+      const error = new Error(
+        `Operation "${operation}" exceeded timeout of ${duration}ms`
+      );
+      error.code = "TIMEOUT";
+      error.operation = operation;
+      error.duration = duration;
+      error.maxDuration = duration;
+      reject(error);
+    }, duration);
+    timer.unref?.();
+  });
+}
+async function withTimeout(promise, timeout, operation) {
+  return Promise.race([promise, createTimeout(timeout, operation)]);
+}
+function getTimeoutErrorMessage(error, operation) {
+  const suggestions = [];
+  if (operation.includes("install") || operation.includes("npm")) {
+    suggestions.push("\u2022 Check your internet connection");
+    suggestions.push(
+      "\u2022 Try increasing npm timeout: `npm config set fetch-timeout 60000`"
+    );
+    suggestions.push(
+      "\u2022 Use a different npm registry: `npm config set registry https://registry.npmjs.org/`"
+    );
+  }
+  if (operation.includes("detect") || operation.includes("framework")) {
+    suggestions.push("\u2022 Your project may be very large");
+    suggestions.push("\u2022 Check for large node_modules or build artifacts");
+  }
+  const base = `${operation} timed out after ${error.duration}ms (max: ${error.maxDuration}ms)`;
+  const suffix = suggestions.length > 0 ? `
+
+Suggestions:
+${suggestions.join("\n")}` : "";
+  return base + suffix;
+}
+
+// src/core/integrity-checker.ts
+import { createHash } from "crypto";
+var IntegrityChecker = class {
+  /**
+   * Verify package-lock.json integrity
+   * Checks for:
+   * - Valid JSON structure
+   * - Required fields present
+   * - Integrity hashes present
+   * - No sign of tampering
+   *
+   * @param lockContent - Raw package-lock.json content
+   * @returns Validation result with errors/warnings
+   */
+  static verifyLockFile(lockContent) {
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      checksVerified: 0,
+      checksSkipped: 0,
+      packageCount: 0
+    };
+    try {
+      const lockFile = JSON.parse(lockContent);
+      if (!lockFile || typeof lockFile !== "object") {
+        result.valid = false;
+        result.errors.push("Lock file is not a valid JSON object");
+        return result;
+      }
+      if (!lockFile["lockfileVersion"]) {
+        result.warnings.push("Missing lockfileVersion field");
+      }
+      if (!lockFile["dependencies"] && !lockFile["packages"]) {
+        result.valid = false;
+        result.errors.push("Lock file missing both dependencies and packages");
+        return result;
+      }
+      const packages = lockFile["packages"] || lockFile["dependencies"] || {};
+      let packageCount = 0;
+      for (const [name, pkg] of Object.entries(packages)) {
+        if (name === "") continue;
+        packageCount++;
+        const pkgData = pkg;
+        const integrity = pkgData["integrity"] ?? void 0;
+        const resolved = pkgData["resolved"] ?? void 0;
+        if (!integrity) {
+          if (resolved && this.isRegistryPackage(resolved)) {
+            result.errors.push(
+              `Package ${name} missing integrity hash (registry package)`
+            );
+            result.valid = false;
+          } else {
+            result.warnings.push(
+              `Package ${name} missing integrity hash (git/file)`
+            );
+            result.checksSkipped++;
+          }
+        } else {
+          if (!this.isValidIntegrityFormat(integrity)) {
+            result.errors.push(
+              `Package ${name} has invalid integrity format: ${integrity}`
+            );
+            result.valid = false;
+          } else {
+            result.checksVerified++;
+          }
+        }
+      }
+      if (packageCount === 0) {
+        result.warnings.push("Lock file contains no packages");
+      }
+      result.packageCount = packageCount;
+      return result;
+    } catch (error) {
+      result.valid = false;
+      if (error instanceof SyntaxError) {
+        result.errors.push(`Invalid JSON in lock file: ${error.message}`);
+      } else {
+        result.errors.push(`Error parsing lock file: ${String(error)}`);
+      }
+      return result;
+    }
+  }
+  /**
+   * Verify integrity hash of a package
+   * Compares provided hash with calculated hash
+   *
+   * @param content - Package content (tarball)
+   * @param integrityString - Expected integrity string (e.g., "sha512-ABC...")
+   * @returns true if integrity is valid
+   */
+  static verifyPackageIntegrity(content, integrityString) {
+    try {
+      if (!content || !integrityString) {
+        return false;
+      }
+      const parts = integrityString.split("-");
+      const algorithm = parts[0];
+      const expectedHash = parts[1];
+      if (!algorithm || !expectedHash) {
+        return false;
+      }
+      const hash = createHash(algorithm);
+      hash.update(content);
+      const calculatedHash = hash.digest("base64");
+      return calculatedHash === expectedHash;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check if integrity format is valid
+   * Valid formats: sha512-ABC..., sha256-ABC..., sha1-ABC...
+   *
+   * @param integrityString - Integrity string to validate
+   * @returns true if format is valid
+   */
+  static isValidIntegrityFormat(integrityString) {
+    if (!integrityString || typeof integrityString !== "string") {
+      return false;
+    }
+    const parts = integrityString.split("-");
+    const algorithm = parts[0];
+    const hash = parts[1];
+    if (!algorithm || !hash) {
+      return false;
+    }
+    const validAlgorithms = ["sha512", "sha256", "sha1"];
+    if (!validAlgorithms.includes(algorithm)) {
+      return false;
+    }
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    return base64Regex.test(hash);
+  }
+  /**
+   * Check if a package is from npm registry
+   * Registry packages have resolved URLs pointing to registry
+   *
+   * @param resolvedUrl - Resolved URL from lock file
+   * @returns true if package is from npm registry
+   */
+  static isRegistryPackage(resolvedUrl) {
+    if (!resolvedUrl || typeof resolvedUrl !== "string") {
+      return false;
+    }
+    return resolvedUrl.includes("registry.npmjs.org") || resolvedUrl.includes("npm.pkg.github.com") || resolvedUrl.startsWith("https://") && !resolvedUrl.includes("github.com/");
+  }
+  /**
+   * Generate integrity hash for content
+   *
+   * @param content - Content to hash
+   * @param algorithm - Hash algorithm (sha512, sha256, sha1)
+   * @returns Integrity string (e.g., "sha512-ABC...")
+   */
+  static generateIntegrity(content, algorithm = "sha512") {
+    const hash = createHash(algorithm);
+    hash.update(content);
+    return `${algorithm}-${hash.digest("base64")}`;
+  }
+  /**
+   * Compare two integrity strings
+   *
+   * @param integrity1 - First integrity string
+   * @param integrity2 - Second integrity string
+   * @returns true if integrities match
+   */
+  static compareIntegrity(integrity1, integrity2) {
+    if (!integrity1 || !integrity2) {
+      return false;
+    }
+    const parts1 = integrity1.split("-");
+    const algo1 = parts1[0];
+    const hash1 = parts1[1];
+    const parts2 = integrity2.split("-");
+    const algo2 = parts2[0];
+    const hash2 = parts2[1];
+    if (!algo1 || !hash1 || !algo2 || !hash2) {
+      return false;
+    }
+    return algo1.toLowerCase() === algo2.toLowerCase() && hash1 === hash2;
+  }
+  /**
+   * Validate that package has not been modified
+   * Compares calculated hash with stored integrity
+   *
+   * @param content - Package content
+   * @param storedIntegrity - Integrity from lock file
+   * @returns true if package matches integrity
+   */
+  static validatePackageNotModified(content, storedIntegrity) {
+    try {
+      const parts = storedIntegrity.split("-");
+      const algorithm = parts[0];
+      const expectedHash = parts[1];
+      if (!algorithm || !expectedHash) {
+        return false;
+      }
+      const hash = createHash(algorithm);
+      hash.update(content);
+      const calculatedHash = hash.digest("base64");
+      return calculatedHash === expectedHash;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Extract algorithm and hash from integrity string
+   *
+   * @param integrityString - Integrity string to parse
+   * @returns Object with algorithm and hash, or null if invalid
+   */
+  static extractIntegrityInfo(integrityString) {
+    if (!integrityString) {
+      return null;
+    }
+    const parts = integrityString.split("-");
+    const algorithm = parts[0];
+    const hash = parts[1];
+    if (!algorithm || !hash) {
+      return null;
+    }
+    return { algorithm, hash };
+  }
+  /**
+   * Format verification report for display
+   *
+   * @param result - Verification result
+   * @returns Formatted report string
+   */
+  static formatReport(result) {
+    let report = `Package Integrity Report
+`;
+    report += `========================
+
+`;
+    report += `Status: ${result.valid ? "\u2713 VALID" : "\u2717 INVALID"}
+
+`;
+    if (result.packageCount !== void 0) {
+      report += `Packages Checked: ${result.packageCount}
+`;
+      report += `Verified: ${result.checksVerified}
+`;
+      report += `Skipped: ${result.checksSkipped}
+
+`;
+    }
+    if (result.errors.length > 0) {
+      report += `Errors (${result.errors.length}):
+`;
+      result.errors.forEach((error) => {
+        report += `  - ${error}
+`;
+      });
+      report += "\n";
+    }
+    if (result.warnings.length > 0) {
+      report += `\u26A0 Warnings (${result.warnings.length}):
+`;
+      result.warnings.forEach((warning) => {
+        report += `  - ${warning}
+`;
+      });
+    }
+    return report;
+  }
+};
+
+// src/utils/package-manager.ts
+var logger = getModuleLogger();
+var lockIntegrityCache = /* @__PURE__ */ new Map();
+function getLockIntegrityCacheKey(projectRoot, packageManager) {
+  return `${projectRoot}:${packageManager}`;
+}
+function invalidateLockFileIntegrityCache(projectRoot) {
+  for (const key of lockIntegrityCache.keys()) {
+    if (key.startsWith(`${projectRoot}:`)) {
+      lockIntegrityCache.delete(key);
+    }
+  }
+}
+var SAFE_NPM_FLAGS = /* @__PURE__ */ new Set([
+  "--prefer-offline",
+  "--no-save-exact",
+  "--save-exact",
+  "--audit",
+  "--save-dev",
+  "--save",
+  "--no-save",
+  "--legacy-peer-deps",
+  "--no-strict-ssl",
+  "--progress",
+  "--force",
+  "--no-fund",
+  "--fund"
+]);
+function hasControlCharacters(str) {
+  return /[\x00-\x1f]/.test(str);
+}
+function validateNpmArguments(args) {
+  for (const arg of args) {
+    if (arg.startsWith("--")) {
+      const flagName = arg.split("=")[0] ?? arg;
+      if (!SAFE_NPM_FLAGS.has(flagName)) {
+        return `Dangerous argument: ${arg}`;
+      }
+    }
+  }
+  return null;
+}
+function validateAdditionalArgs(args) {
+  if (!Array.isArray(args)) {
+    return "Additional arguments must be an array";
+  }
+  for (const arg of args) {
+    if (typeof arg !== "string") {
+      return `Invalid argument type: ${typeof arg} (expected string)`;
+    }
+    if (arg.length === 0) {
+      return "Arguments cannot be empty strings";
+    }
+    if (!arg.startsWith("--")) {
+      return `Invalid argument format: ${arg} (must start with --)`;
+    }
+    const equalsIndex = arg.indexOf("=");
+    const flagName = equalsIndex === -1 ? arg : arg.substring(0, equalsIndex);
+    if (/[;&|`$()[\]{}<>\\]/.test(flagName) || hasControlCharacters(flagName)) {
+      return `Invalid argument format: ${arg} contains dangerous characters`;
+    }
+    if (!SAFE_NPM_FLAGS.has(flagName)) {
+      return `Unknown or unsafe flag: ${flagName}`;
+    }
+    if (equalsIndex !== -1) {
+      const value = arg.substring(equalsIndex + 1);
+      if (value.length === 0) {
+        return `Flag ${flagName} has empty value`;
+      }
+      const hasShellChars = /[;&|`$()[\]{}\\<>'":\x00-\x1f]/.test(value);
+      const hasNonAscii = /[^\x20-\x7e\t\n-]/.test(value);
+      if (hasShellChars || hasNonAscii) {
+        return `Invalid argument format: ${arg} contains dangerous characters`;
+      }
+      if (value.includes("../") || value.includes("..\\")) {
+        return `Invalid argument format: ${arg} contains dangerous characters`;
+      }
+    }
+  }
+  return null;
+}
+function createSafeEnvironment() {
+  const SAFE_ENV_VARS = [
+    "PATH",
+    "HOME",
+    "NODE_ENV",
+    "LANG",
+    "LC_ALL",
+    "SHELL",
+    "USER",
+    "TMPDIR",
+    "TEMP",
+    "TMP"
+  ];
+  const safeEnv = {};
+  for (const key of SAFE_ENV_VARS) {
+    const value = process.env[key];
+    if (value) {
+      safeEnv[key] = value;
+    }
+  }
+  safeEnv["npm_config_yes"] = "true";
+  safeEnv["YARN_ENABLE_IMMUTABLE_INSTALLS"] = "false";
+  return safeEnv;
+}
+async function detectPackageManager(projectRoot, fsAdapter) {
+  const root = resolve(projectRoot);
+  const lockfiles = [
+    { file: "pnpm-lock.yaml", manager: "pnpm" },
+    { file: "yarn.lock", manager: "yarn" },
+    { file: "package-lock.json", manager: "npm" },
+    { file: "bun.lockb", manager: "bun" }
+  ];
+  for (const { file, manager } of lockfiles) {
+    const lockfilePath = join(root, file);
+    if (fsAdapter) {
+      if (await fsAdapter.pathExists(lockfilePath)) {
+        logger.debug(`Detected package manager: ${manager} (found ${file})`);
+        return manager;
+      }
+      continue;
+    }
+    if (await fs.pathExists(lockfilePath)) {
+      logger.debug(`Detected package manager: ${manager} (found ${file})`);
+      return manager;
+    }
+  }
+  logger.debug("No lockfile found, defaulting to npm");
+  return "npm";
+}
+async function verifyLockFileIntegrity(projectRoot, packageManager) {
+  const lockFiles = {
+    npm: "package-lock.json",
+    yarn: "yarn.lock",
+    pnpm: "pnpm-lock.yaml",
+    bun: "bun.lockb"
+  };
+  const lockFile = lockFiles[packageManager];
+  const lockPath = resolve(projectRoot, lockFile);
+  const cacheKey = getLockIntegrityCacheKey(projectRoot, packageManager);
+  if (!await fs.pathExists(lockPath)) {
+    logger.debug(`Lock file not found: ${lockFile}`);
+    lockIntegrityCache.set(cacheKey, {
+      result: null,
+      exists: false
+    });
+    return null;
+  }
+  try {
+    const stats = await fs.stat(lockPath);
+    const cached = lockIntegrityCache.get(cacheKey);
+    if (cached?.exists && cached.mtimeMs === stats.mtimeMs) {
+      return cached.result;
+    }
+    const lockContent = await fs.readFile(lockPath, "utf-8");
+    const result = IntegrityChecker.verifyLockFile(lockContent);
+    if (!result.valid) {
+      const errors = result.errors.join(", ");
+      const errorResult = `Lock file integrity check failed: ${errors}`;
+      lockIntegrityCache.set(cacheKey, {
+        result: errorResult,
+        mtimeMs: stats.mtimeMs,
+        exists: true
+      });
+      return errorResult;
+    }
+    logger.debug(
+      `Lock file integrity verified (${result.checksVerified} hashes checked)`
+    );
+    lockIntegrityCache.set(cacheKey, {
+      result: null,
+      mtimeMs: stats.mtimeMs,
+      exists: true
+    });
+    return null;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorResult = `Error reading lock file: ${errorMessage}`;
+    lockIntegrityCache.set(cacheKey, {
+      result: errorResult,
+      exists: true
+    });
+    return errorResult;
+  }
+}
+async function installPackages(packages, options) {
+  if (packages.length === 0) {
+    logger.warn("No packages to install");
+    return { success: true, packages: [] };
+  }
+  const invalidPackages = validatePackageNames(packages);
+  if (invalidPackages.length > 0) {
+    const errorMessage = getPackageValidationErrorMessage(invalidPackages);
+    logger.error(errorMessage);
+    return {
+      success: false,
+      packages,
+      error: errorMessage
+    };
+  }
+  const {
+    packageManager,
+    projectRoot,
+    dev = false,
+    exact = false,
+    silent = false,
+    additionalArgs = []
+  } = options;
+  logger.info(
+    `Installing ${packages.length} package(s) with ${packageManager}...`
+  );
+  const additionalArgsError = validateAdditionalArgs(additionalArgs);
+  if (additionalArgsError) {
+    logger.error(`Invalid additional arguments: ${additionalArgsError}`);
+    return {
+      success: false,
+      packages,
+      error: additionalArgsError
+    };
+  }
+  try {
+    const rateLimiter = getGlobalRateLimiter();
+    const rateLimitResult = rateLimiter.checkRequest(projectRoot);
+    if (!rateLimitResult.allowed) {
+      const message = rateLimitResult.message ?? "Rate limit exceeded. Please retry after cooldown.";
+      logger.warn(message);
+      return {
+        success: false,
+        packages,
+        error: message
+      };
+    }
+    const integrityError = await verifyLockFileIntegrity(
+      projectRoot,
+      packageManager
+    );
+    if (integrityError) {
+      logger.error(integrityError);
+      return {
+        success: false,
+        packages,
+        error: integrityError
+      };
+    }
+    const command = getInstallCommand(packageManager, packages, { dev, exact });
+    const cwd = resolve(projectRoot);
+    logger.debug(`Executing: ${command.join(" ")} in ${cwd}`);
+    const [cmd, ...args] = command;
+    if (!cmd) {
+      throw new Error("Command is empty");
+    }
+    const error = validateNpmArguments(args);
+    if (error) {
+      logger.error(error);
+      return {
+        success: false,
+        packages,
+        error
+      };
+    }
+    const securityArgs = ["--prefer-offline", "--no-save-exact"];
+    if (packageManager === "npm") {
+      args.push(...securityArgs);
+      args.push("--audit");
+    }
+    if (additionalArgs.length > 0) {
+      logger.debug(`Adding ${additionalArgs.length} additional argument(s)`);
+      args.push(...additionalArgs);
+    }
+    const resultPromise = execa(cmd, args, {
+      cwd,
+      stdio: silent ? "pipe" : "inherit",
+      maxBuffer: RESOURCE_LIMITS.MAX_BUFFER,
+      env: createSafeEnvironment()
+    });
+    const result = await withTimeout(
+      resultPromise,
+      OPERATION_TIMEOUTS.PACKAGE_INSTALL,
+      `npm install (${packages.length} packages)`
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(`Installation failed with exit code ${result.exitCode}`);
+    }
+    logger.success(`Successfully installed ${packages.length} package(s)`);
+    invalidateLockFileIntegrityCache(projectRoot);
+    return {
+      success: true,
+      packages
+    };
+  } catch (error) {
+    const isTimeout = error instanceof Error && "code" in error && error.code === "TIMEOUT";
+    const errorMessage = isTimeout ? getTimeoutErrorMessage(error, "Package installation") : error instanceof Error ? error.message : String(error);
+    logger.error(`Failed to install packages: ${errorMessage}`);
+    return {
+      success: false,
+      packages,
+      error: errorMessage
+    };
+  }
+}
+function getInstallCommand(packageManager, packages, options) {
+  const { dev, exact } = options;
+  switch (packageManager) {
+    case "pnpm":
+      return [
+        "pnpm",
+        "add",
+        ...dev ? ["-D"] : [],
+        ...exact ? ["--save-exact"] : [],
+        ...packages
+      ];
+    case "yarn":
+      return [
+        "yarn",
+        "add",
+        ...dev ? ["--dev"] : [],
+        ...exact ? ["--exact"] : [],
+        ...packages
+      ];
+    case "bun":
+      return ["bun", "add", ...dev ? ["--dev"] : [], ...packages];
+    case "npm":
+    default:
+      return [
+        "npm",
+        "install",
+        ...dev ? ["--save-dev"] : [],
+        ...exact ? ["--save-exact"] : [],
+        ...packages
+      ];
+  }
+}
+
+export {
+  detectPackageManager,
+  installPackages
+};