@socketsecurity/cli-with-sentry 1.1.17 → 1.1.19

package/dist/utils.js

@@ -18,17 +18,263 @@ var prompts = require('../external/@socketsecurity/registry/lib/prompts');
 var spawn = require('../external/@socketsecurity/registry/lib/spawn');
 var fs = require('../external/@socketsecurity/registry/lib/fs');
 var require$$5 = require('node:module');
-var shadowNpmBin = require('./shadow-npm-bin.js');
 var fs$1 = require('node:fs');
 var require$$13 = require('../external/@socketsecurity/registry/lib/url');
-var promises = require('node:timers/promises');
 var agent = require('../external/@socketsecurity/registry/lib/agent');
 var bin = require('../external/@socketsecurity/registry/lib/bin');
 var packages = require('../external/@socketsecurity/registry/lib/packages');
+var promises = require('node:timers/promises');
 var globs = require('../external/@socketsecurity/registry/lib/globs');
 var streams = require('../external/@socketsecurity/registry/lib/streams');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+/**
+ * Debug utilities for Socket CLI.
+ * Provides structured debugging with categorized levels and helpers.
+ *
+ * Debug Categories:
+ * DEFAULT (shown with SOCKET_CLI_DEBUG=1):
+ * - 'error': Critical errors that prevent operation
+ * - 'warn': Important warnings that may affect behavior
+ * - 'notice': Notable events and state changes
+ * - 'silly': Very verbose debugging info
+ *
+ * OPT-IN ONLY (require explicit DEBUG='category' even with SOCKET_CLI_DEBUG=1):
+ * - 'inspect': Detailed object inspection (DEBUG='inspect' or DEBUG='*')
+ * - 'stdio': Command execution logs (DEBUG='stdio' or DEBUG='*')
+ *
+ * These opt-in categories are intentionally excluded from default debug output
+ * to reduce noise. Enable them explicitly when needed for deep debugging.
+ */
+
+
+/**
+ * Debug an API response.
+ * Logs essential info without exposing sensitive data.
+ */
+function debugApiResponse(endpoint, status, error) {
+  if (error) {
+    require$$9.debugDir('error', {
+      endpoint,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    });
+  } else if (status && status >= 400) {
+    require$$9.debugFn('warn', `API ${endpoint}: HTTP ${status}`);
+  } else if (require$$9.isDebug('notice')) {
+    require$$9.debugFn('notice', `API ${endpoint}: ${status || 'pending'}`);
+  }
+}
+
+/**
+ * Debug file operation.
+ * Logs file operations with appropriate level.
+ */
+function debugFileOp(operation, filepath, error) {
+  if (error) {
+    require$$9.debugDir('warn', {
+      operation,
+      filepath,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    });
+  } else if (require$$9.isDebug('silly')) {
+    require$$9.debugFn('silly', `File ${operation}: ${filepath}`);
+  }
+}
+
+/**
+ * Debug package scanning.
+ * Provides insight into security scanning.
+ */
+function debugScan(phase, packageCount, details) {
+  switch (phase) {
+    case 'start':
+      if (packageCount) {
+        require$$9.debugFn('notice', `Scanning ${packageCount} packages`);
+      }
+      break;
+    case 'progress':
+      if (require$$9.isDebug('silly') && packageCount) {
+        require$$9.debugFn('silly', `Scan progress: ${packageCount} packages processed`);
+      }
+      break;
+    case 'complete':
+      require$$9.debugFn('notice', `Scan complete${packageCount ? `: ${packageCount} packages` : ''}`);
+      break;
+    case 'error':
+      require$$9.debugDir('error', {
+        phase: 'scan_error',
+        details
+      });
+      break;
+  }
+}
+
+/**
+ * Debug configuration loading.
+ */
+function debugConfig(source, found, error) {
+  if (error) {
+    require$$9.debugDir('warn', {
+      source,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    });
+  } else if (found) {
+    require$$9.debugFn('notice', `Config loaded: ${source}`);
+  } else if (require$$9.isDebug('silly')) {
+    require$$9.debugFn('silly', `Config not found: ${source}`);
+  }
+}
+
+/**
+ * Debug git operations.
+ * Only logs important git operations, not every command.
+ */
+function debugGit(operation, success, details) {
+  if (!success) {
+    require$$9.debugDir('warn', {
+      git_op: operation,
+      ...details
+    });
+  } else if (require$$9.isDebug('notice') && operation.includes('push') || operation.includes('commit')) {
+    // Only log important operations like push and commit.
+    require$$9.debugFn('notice', `Git ${operation} succeeded`);
+  } else if (require$$9.isDebug('silly')) {
+    require$$9.debugFn('silly', `Git ${operation}`);
+  }
+}
+
+/**
+ * Error utilities for Socket CLI.
+ * Provides consistent error handling, formatting, and message extraction.
+ *
+ * Key Classes:
+ * - AuthError: Authentication failures (401/403 responses)
+ * - InputError: User input validation failures
+ *
+ * Key Functions:
+ * - captureException: Send errors to Sentry for monitoring
+ * - formatErrorWithDetail: Format errors with detailed context
+ * - getErrorCause: Get error cause with fallback to UNKNOWN_ERROR
+ * - getErrorMessage: Extract error message from any thrown value
+ *
+ * Error Handling Strategy:
+ * - Always prefer specific error types over generic errors
+ * - Use formatErrorWithDetail for user-facing error messages
+ * - Log errors to Sentry in production for monitoring
+ */
+
+const {
+  kInternalsSymbol,
+  [kInternalsSymbol]: {
+    getSentry
+  }
+} = constants.default;
+class AuthError extends Error {}
+class InputError extends Error {
+  constructor(message, body) {
+    super(message);
+    this.body = body;
+  }
+}
+async function captureException(exception, hint) {
+  const result = captureExceptionSync(exception, hint);
+  // "Sleep" for a second, just in case, hopefully enough time to initiate fetch.
+  await promises.setTimeout(1000);
+  return result;
+}
+function captureExceptionSync(exception, hint) {
+  const Sentry = getSentry();
+  if (!Sentry) {
+    return '';
+  }
+  require$$9.debugFn('notice', 'send: exception to Sentry');
+  return Sentry.captureException(exception, hint);
+}
+
+/**
+ * Extracts an error message from an unknown value.
+ * Returns the message if it's an Error object, otherwise returns undefined.
+ *
+ * @param error - The error object to extract message from
+ * @returns The error message or undefined
+ */
+function getErrorMessage(error) {
+  return error?.message;
+}
+
+/**
+ * Extracts an error message from an unknown value with a fallback.
+ * Returns the message if it's an Error object, otherwise returns the fallback.
+ *
+ * @param error - The error object to extract message from
+ * @param fallback - The fallback message if no error message is found
+ * @returns The error message or fallback
+ *
+ * @example
+ * getErrorMessageOr(error, 'Unknown error occurred')
+ * // Returns: "ENOENT: no such file or directory" or "Unknown error occurred"
+ */
+function getErrorMessageOr(error, fallback) {
+  return getErrorMessage(error) || fallback;
+}
+
+/**
+ * Extracts an error cause from an unknown value.
+ * Returns the error message if available, otherwise UNKNOWN_ERROR.
+ * Commonly used for creating CResult error causes.
+ *
+ * @param error - The error object to extract message from
+ * @returns The error message or UNKNOWN_ERROR constant
+ *
+ * @example
+ * return { ok: false, message: 'Operation failed', cause: getErrorCause(e) }
+ */
+function getErrorCause(error) {
+  return getErrorMessageOr(error, constants.UNKNOWN_ERROR);
+}
+
+/**
+ * Formats an error message with an optional error detail appended.
+ * Extracts the message from an unknown error value and appends it
+ * to the base message if available.
+ *
+ * @param baseMessage - The base message to display
+ * @param error - The error object to extract message from
+ * @returns Formatted message with error detail if available
+ *
+ * @example
+ * formatErrorWithDetail('Failed to delete file', error)
+ * // Returns: "Failed to delete file: ENOENT: no such file or directory"
+ * // Or just: "Failed to delete file" if no error message
+ */
+function formatErrorWithDetail(baseMessage, error) {
+  const errorMessage = getErrorMessage(error);
+  return `${baseMessage}${errorMessage ? `: ${errorMessage}` : ''}`;
+}
+
+/**
+ * Configuration utilities for Socket CLI.
+ * Manages CLI configuration including API tokens, org settings, and preferences.
+ *
+ * Configuration Hierarchy (highest priority first):
+ * 1. Environment variables (SOCKET_CLI_*)
+ * 2. Command-line --config flag
+ * 3. Persisted config file (base64 encoded JSON)
+ *
+ * Supported Config Keys:
+ * - apiBaseUrl: Socket API endpoint URL
+ * - apiProxy: Proxy for API requests
+ * - apiToken: Authentication token for Socket API
+ * - defaultOrg/org: Default organization slug
+ * - enforcedOrgs: Organizations with enforced security policies
+ *
+ * Key Functions:
+ * - findSocketYmlSync: Locate socket.yml configuration file
+ * - getConfigValue: Retrieve configuration value by key
+ * - overrideCachedConfig: Apply temporary config overrides
+ * - updateConfigValue: Persist configuration changes
+ */
+
 const sensitiveConfigKeyLookup = new Set([constants.CONFIG_KEY_API_TOKEN]);
 const supportedConfig = new Map([[constants.CONFIG_KEY_API_BASE_URL, 'Base URL of the Socket API endpoint'], [constants.CONFIG_KEY_API_PROXY, 'A proxy through which to access the Socket API'], [constants.CONFIG_KEY_API_TOKEN, 'The Socket API token required to access most Socket API endpoints'], [constants.CONFIG_KEY_DEFAULT_ORG, 'The default org slug to use; usually the org your Socket API token has access to. When set, all orgSlug arguments are implied to be this value.'], [constants.CONFIG_KEY_ENFORCED_ORGS, 'Orgs in this list have their security policies enforced on this machine'], ['skipAskToPersistDefaultOrg', 'This flag prevents the Socket CLI from asking you to persist the org slug when you selected one interactively'], [constants.CONFIG_KEY_ORG, 'Alias for defaultOrg']]);
 const supportedConfigEntries = [...supportedConfig.entries()].sort((a, b) => sorts.naturalCompare(a[0], b[0]));
@@ -45,8 +291,10 @@ function getConfigValues() {
       if (raw) {
         try {
           Object.assign(_cachedConfig, JSON.parse(Buffer.from(raw, 'base64').toString()));
-        } catch {
+          debugConfig(socketAppDataPath, true);
+        } catch (e) {
           logger.logger.warn(`Failed to parse config at ${socketAppDataPath}`);
+          debugConfig(socketAppDataPath, false, e);
         }
         // Normalize apiKey to apiToken and persist it.
         // This is a one time migration per user.
@@ -100,13 +348,12 @@ function findSocketYmlSync(dir = process.cwd()) {
           }
         };
       } catch (e) {
-        require$$9.debugDir('inspect', {
-          error: e
-        });
+        require$$9.debugFn('error', `Failed to parse config file: ${ymlPath}`);
+        require$$9.debugDir('error', e);
         return {
           ok: false,
           message: `Found file but was unable to parse ${ymlPath}`,
-          cause: e instanceof Error ? e.message : String(e)
+          cause: getErrorCause(e)
         };
       }
     }
@@ -267,6 +514,20 @@ function updateConfigValue(configKey, value) {
   };
 }
 
+/**
+ * Requirements configuration utilities for Socket CLI.
+ * Manages API permissions and quota requirements for commands.
+ *
+ * Key Functions:
+ * - getRequirements: Load requirements configuration
+ * - getRequirementsKey: Convert command path to requirements key
+ *
+ * Configuration:
+ * - Loads from requirements.json
+ * - Maps command paths to permission requirements
+ * - Used for permission validation and help text
+ */
+
 const require$3 = require$$5.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
 let _requirements;
 function getRequirements() {
@@ -283,6 +544,32 @@ function getRequirementsKey(cmdPath) {
   return cmdPath.replace(/^socket[: ]/, '').replace(/ +/g, ':');
 }
 
+/**
+ * Socket SDK utilities for Socket CLI.
+ * Manages SDK initialization and configuration for API communication.
+ *
+ * Authentication:
+ * - Interactive password prompt for missing tokens
+ * - Supports environment variable (SOCKET_CLI_API_TOKEN)
+ * - Validates token format and presence
+ *
+ * Proxy Support:
+ * - Automatic proxy agent selection
+ * - HTTP/HTTPS proxy configuration
+ * - Respects SOCKET_CLI_API_PROXY environment variable
+ *
+ * SDK Setup:
+ * - createSocketSdk: Create configured SDK instance
+ * - getDefaultApiToken: Retrieve API token from config/env
+ * - getDefaultProxyUrl: Retrieve proxy URL from config/env
+ * - getPublicApiToken: Get public API token constant
+ * - setupSdk: Initialize Socket SDK with authentication
+ *
+ * User Agent:
+ * - Automatic user agent generation from package.json
+ * - Includes CLI version and platform information
+ */
+
 const TOKEN_PREFIX = 'sktsec_';
 const TOKEN_PREFIX_LENGTH = TOKEN_PREFIX.length;
 const TOKEN_VISIBLE_LENGTH = 5;
@@ -375,6 +662,27 @@ async function setupSdk(options) {
   };
 }
 
+/**
+ * API utilities for Socket CLI.
+ * Provides consistent API communication with error handling and permissions management.
+ *
+ * Key Functions:
+ * - getDefaultApiBaseUrl: Get configured API endpoint
+ * - getErrorMessageForHttpStatusCode: User-friendly HTTP error messages
+ * - handleApiCall: Execute Socket SDK API calls with error handling
+ * - handleApiCallNoSpinner: Execute API calls without UI spinner
+ * - queryApi: Execute raw API queries with text response
+ *
+ * Error Handling:
+ * - Automatic permission requirement logging for 403 errors
+ * - Detailed error messages for common HTTP status codes
+ * - Integration with debug helpers for API response logging
+ *
+ * Configuration:
+ * - Respects SOCKET_CLI_API_BASE_URL environment variable
+ * - Falls back to configured apiBaseUrl or default API_V0_URL
+ */
+
 const NO_ERROR_MESSAGE = 'No error message returned';
 /**
  * Get command requirements from requirements.json based on command path.
@@ -469,13 +777,10 @@ async function handleApiCall(value, options) {
     };
     if (description) {
       logger.logger.fail(`An error was thrown while requesting ${description}`);
-      require$$9.debugFn('error', `caught: ${description} error`);
+      debugApiResponse(description, undefined, e);
     } else {
-      require$$9.debugFn('error', `caught: Socket API request error`);
+      debugApiResponse('Socket API', undefined, e);
     }
-    require$$9.debugDir('inspect', {
-      error: e
-    });
     require$$9.debugDir('inspect', {
       socketSdkErrorResult
     });
@@ -484,7 +789,8 @@ async function handleApiCall(value, options) {
 
   // Note: TS can't narrow down the type of result due to generics.
   if (sdkResult.success === false) {
-    require$$9.debugFn('error', `fail:${description ? ` ${description}` : ''} bad response`);
+    const endpoint = description || 'Socket API';
+    debugApiResponse(endpoint, sdkResult.status);
     require$$9.debugDir('inspect', {
       sdkResult
     });
@@ -519,10 +825,8 @@ async function handleApiCallNoSpinner(value, description) {
   try {
     sdkResult = await value;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${description} error`);
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', `API request failed: ${description}`);
+    require$$9.debugDir('error', e);
     const errStr = e ? String(e).trim() : '';
     const message = 'Socket API error';
     const rawCause = errStr || NO_ERROR_MESSAGE;
@@ -604,10 +908,8 @@ async function queryApiSafeText(path, description, commandPath) {
     if (description) {
       spinner.failAndStop(`An error was thrown while requesting ${description}.`);
     }
-    require$$9.debugFn('error', 'caught: await queryApi() error');
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', 'Query API request failed');
+    require$$9.debugDir('error', e);
     const errStr = e ? String(e).trim() : '';
     const message = 'API request failed';
     const rawCause = errStr || NO_ERROR_MESSAGE;
@@ -640,10 +942,8 @@ async function queryApiSafeText(path, description, commandPath) {
       data
     };
   } catch (e) {
-    require$$9.debugFn('error', 'caught: await result.text() error');
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', 'Failed to read API response text');
+    require$$9.debugDir('error', e);
     return {
       ok: false,
       message: 'API request failed',
@@ -728,10 +1028,8 @@ async function sendApiRequest(path, options) {
     if (description) {
       spinner.failAndStop(`An error was thrown while requesting ${description}.`);
     }
-    require$$9.debugFn('error', `caught: await fetch() ${method} error`);
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', `API ${method} request failed`);
+    require$$9.debugDir('error', e);
     const errStr = e ? String(e).trim() : '';
     const message = 'API request failed';
     const rawCause = errStr || NO_ERROR_MESSAGE;
@@ -768,10 +1066,8 @@ async function sendApiRequest(path, options) {
       data: data
     };
   } catch (e) {
-    require$$9.debugFn('error', 'caught: await result.json() error');
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', 'Failed to parse API response JSON');
+    require$$9.debugDir('error', e);
     return {
       ok: false,
       message: 'API request failed',
@@ -786,6 +1082,24 @@ function failMsgWithBadge(badge, message) {
   return `${prefix}${postfix}`;
 }
 
+/**
+ * Markdown utilities for Socket CLI.
+ * Generates formatted markdown output for reports and documentation.
+ *
+ * Key Functions:
+ * - mdTableStringNumber: Create markdown table with string keys and number values
+ *
+ * Table Features:
+ * - Auto-sizing columns based on content
+ * - Proper alignment for headers and data
+ * - Clean markdown-compliant formatting
+ *
+ * Usage:
+ * - Analytics reports
+ * - Scan result tables
+ * - Statistical summaries
+ */
+
 function mdTableStringNumber(title1, title2, obj) {
   // | Date        | Counts |
   // | ----------- | ------ |
@@ -904,9 +1218,8 @@ function serializeResultJson(data) {
     process.exitCode = 1;
     const message = 'There was a problem converting the data set to JSON. Please try again without --json';
     logger.logger.fail(message);
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', 'JSON serialization failed');
+    require$$9.debugDir('error', e);
 
     // This could be caused by circular references, which is an "us" problem.
     return `${JSON.stringify({
@@ -965,6 +1278,24 @@ function checkCommandInput(outputKind, ...checks) {
   return false;
 }
 
+/**
+ * Output format detection utilities for Socket CLI.
+ * Determines output format based on command flags.
+ *
+ * Key Functions:
+ * - getOutputKind: Determine output format from flags
+ *
+ * Supported Formats:
+ * - JSON: Machine-readable JSON output
+ * - Markdown: Formatted markdown for reports
+ * - Text: Plain text for terminal display
+ *
+ * Usage:
+ * - Processes --json and --markdown flags
+ * - Returns appropriate output format constant
+ * - Defaults to text format for terminal display
+ */
+
 function getOutputKind(json, markdown) {
   if (json) {
     return constants.OUTPUT_JSON;
@@ -975,10 +1306,44 @@ function getOutputKind(json, markdown) {
   return constants.OUTPUT_TEXT;
 }
 
+/**
+ * String manipulation utilities for Socket CLI.
+ * Provides common string transformations and formatting.
+ *
+ * Key Functions:
+ * - camelToKebab: Convert camelCase to kebab-case
+ *
+ * Usage:
+ * - Command name transformations
+ * - Flag name conversions
+ * - Consistent string formatting
+ */
+
 function camelToKebab(str) {
   return str === '' ? '' : str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
 }
 
+/**
+ * Output formatting utilities for Socket CLI.
+ * Provides consistent formatting for help text and command output.
+ *
+ * Key Functions:
+ * - getFlagApiRequirementsOutput: Format API requirements for flags
+ * - getHelpListOutput: Format help text lists with descriptions
+ * - getFlagsHelpOutput: Generate formatted help for command flags
+ *
+ * Formatting Features:
+ * - Automatic indentation and alignment
+ * - Flag description formatting
+ * - Requirements and permissions display
+ * - Hidden flag filtering
+ *
+ * Usage:
+ * - Used by command help systems
+ * - Provides consistent terminal output formatting
+ * - Handles kebab-case conversion for flags
+ */
+
 function getFlagApiRequirementsOutput(cmdPath, options) {
   const {
     indent = 6
@@ -1049,8 +1414,19 @@ function getHelpListOutput(list, options) {
   return result.trim() || '(none)';
 }
 
-// Replace the start of a path with ~/ when it starts with your home dir.
-// A common way to abbreviate the user home dir (though not strictly posix).
+/**
+ * Path tildification utilities for Socket CLI.
+ * Abbreviates home directory paths with tilde notation.
+ *
+ * Key Functions:
+ * - tildify: Replace home directory with ~ in paths
+ *
+ * Usage:
+ * - Shortens absolute paths for display
+ * - Converts /Users/name/... to ~/...
+ * - Common Unix convention for home directory
+ */
+
 function tildify(cwd) {
   return cwd.replace(new RegExp(`^${regexps.escapeRegExp(constants.default.homePath)}(?:${path.sep}|$)`, 'i'), '~/');
 }
@@ -1269,10 +1645,15 @@ async function meowWithSubcommands(subcommands, options) {
     // We want to detect whether a bool flag is given at all.
     booleanDefault: undefined
   });
-  const noSpinner = cli1.flags['spinner'] === false;
-  const orgFlag = String(cli1.flags['org'] || '') || undefined;
+  const {
+    config: configFlag,
+    org: orgFlag,
+    spinner: spinnerFlag
+  } = cli1.flags;
+  const noSpinner = spinnerFlag === false || require$$9.isDebug();
 
-  // Use CI spinner style when --no-spinner is passed.
+  // Use CI spinner style when --no-spinner is passed or debug mode is enabled.
+  // This prevents the spinner from interfering with debug output.
   if (noSpinner) {
     constants.default.spinner.spinner = spinner.getCliSpinners('ci');
   }
@@ -1282,8 +1663,8 @@ async function meowWithSubcommands(subcommands, options) {
   let configOverrideResult;
   if (constants.default.ENV.SOCKET_CLI_CONFIG) {
     configOverrideResult = overrideCachedConfig(constants.default.ENV.SOCKET_CLI_CONFIG);
-  } else if (cli1.flags['config']) {
-    configOverrideResult = overrideCachedConfig(cli1.flags['config']);
+  } else if (configFlag) {
+    configOverrideResult = overrideCachedConfig(configFlag);
   }
   if (constants.default.ENV.SOCKET_CLI_NO_API_TOKEN) {
     // This overrides the config override and even the explicit token env var.
@@ -1479,9 +1860,10 @@ function meowOrExit({
     spinner: spinnerFlag,
     version: versionFlag
   } = cli.flags;
-  const noSpinner = spinnerFlag === false;
+  const noSpinner = spinnerFlag === false || require$$9.isDebug();
 
   // Use CI spinner style when --no-spinner is passed.
+  // This prevents the spinner from interfering with debug output.
   if (noSpinner) {
     constants.default.spinner.spinner = spinner.getCliSpinners('ci');
   }
@@ -1520,6 +1902,8 @@ function meowOrExit({
     console.error('Unknown flag\n--version');
     // eslint-disable-next-line n/no-process-exit
     process.exit(2);
+    // This line is never reached in production, but helps tests.
+    throw new Error('process.exit called');
   }
 
   // Now test for help state. Run Meow again. If it exits now, it must be due
@@ -1753,6 +2137,33 @@ async function getDefaultOrgSlug() {
   };
 }
 
+/**
+ * Git utilities for Socket CLI.
+ * Provides git operations for repository management, branch handling, and commits.
+ *
+ * Branch Operations:
+ * - gitCheckoutBranch: Switch to branch
+ * - gitCreateBranch: Create new local branch
+ * - gitDeleteBranch: Delete local branch
+ * - gitDeleteRemoteBranch: Delete remote branch
+ * - gitPushBranch: Push branch to remote with --force
+ *
+ * Commit Operations:
+ * - gitCleanFdx: Remove untracked files
+ * - gitCommit: Stage files and create commit
+ * - gitEnsureIdentity: Configure git user.name/email
+ * - gitResetHard: Reset to branch/commit
+ *
+ * Remote URL Parsing:
+ * - parseGitRemoteUrl: Extract owner/repo from SSH or HTTPS URLs
+ *
+ * Repository Information:
+ * - detectDefaultBranch: Find default branch (main/master/develop/etc)
+ * - getBaseBranch: Determine base branch (respects GitHub Actions env)
+ * - getRepoInfo: Extract owner/repo from git remote URL
+ * - gitBranch: Get current branch or commit hash
+ */
+
 // Listed in order of check preference.
 const COMMON_DEFAULT_BRANCH_NAMES = [
 // Modern default (GitHub, GitLab, Bitbucket have switched to this).
@@ -1796,22 +2207,21 @@ async function getBaseBranch(cwd = process.cwd()) {
 }
 async function getRepoInfo(cwd = process.cwd()) {
   let info;
-  const quotedCmd = '`git remote get-url origin`';
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     const remoteUrl = (await spawn.spawn('git', ['remote', 'get-url', 'origin'], {
       cwd
     })).stdout;
     info = parseGitRemoteUrl(remoteUrl);
     if (!info) {
-      require$$9.debugFn('error', 'git: unmatched git remote URL format');
-      require$$9.debugDir('inspect', {
+      require$$9.debugFn('warn', `Unmatched git remote URL format: ${remoteUrl}`);
+      require$$9.debugDir('warn', {
         remoteUrl
       });
     }
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
+    // Expected failure when not in a git repo.
     require$$9.debugDir('inspect', {
+      message: 'git remote get-url failed',
       error: e
     });
   }
@@ -1825,41 +2235,29 @@ async function gitBranch(cwd = process.cwd()) {
   const stdioPipeOptions = {
     cwd
   };
-  let quotedCmd = '`git symbolic-ref --short HEAD`';
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   // Try symbolic-ref first which returns the branch name or fails in a
   // detached HEAD state.
   try {
     const gitSymbolicRefResult = await spawn.spawn('git', ['symbolic-ref', '--short', 'HEAD'], stdioPipeOptions);
-    require$$9.debugDir('stdio', {
-      gitSymbolicRefResult
-    });
     return gitSymbolicRefResult.stdout;
   } catch (e) {
-    if (require$$9.isDebug('stdio')) {
-      require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-      require$$9.debugDir('inspect', {
-        error: e
-      });
-    }
+    // Expected in detached HEAD state, fallback to rev-parse.
+    require$$9.debugDir('inspect', {
+      message: 'In detached HEAD state',
+      error: e
+    });
   }
   // Fallback to using rev-parse to get the short commit hash in a
   // detached HEAD state.
-  quotedCmd = '`git rev-parse --short HEAD`';
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     const gitRevParseResult = await spawn.spawn('git', ['rev-parse', '--short', 'HEAD'], stdioPipeOptions);
-    require$$9.debugDir('stdio', {
-      gitRevParseResult
-    });
     return gitRevParseResult.stdout;
   } catch (e) {
-    if (require$$9.isDebug('stdio')) {
-      require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-      require$$9.debugDir('inspect', {
-        error: e
-      });
-    }
+    // Both methods failed, likely not in a git repo.
+    require$$9.debugDir('inspect', {
+      message: 'Unable to determine git branch',
+      error: e
+    });
   }
   return undefined;
 }
@@ -1890,14 +2288,12 @@ async function gitCleanFdx(cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = '`git clean -fdx`';
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     await spawn.spawn('git', ['clean', '-fdx'], stdioIgnoreOptions);
+    debugGit('clean -fdx', true);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-    require$$9.debugDir('inspect', {
+    debugGit('clean -fdx', false, {
       error: e
     });
   }
@@ -1908,14 +2304,12 @@ async function gitCheckoutBranch(branch, cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = `\`git checkout ${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     await spawn.spawn('git', ['checkout', branch], stdioIgnoreOptions);
+    debugGit(`checkout ${branch}`, true);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-    require$$9.debugDir('inspect', {
+    debugGit(`checkout ${branch}`, false, {
       error: e
     });
   }
@@ -1929,14 +2323,12 @@ async function gitCreateBranch(branch, cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = `\`git branch ${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     await spawn.spawn('git', ['branch', branch], stdioIgnoreOptions);
+    debugGit(`branch ${branch}`, true);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-    require$$9.debugDir('inspect', {
+    debugGit(`branch ${branch}`, false, {
       error: e
     });
   }
@@ -1947,19 +2339,22 @@ async function gitPushBranch(branch, cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = `\`git push --force --set-upstream origin ${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     await spawn.spawn('git', ['push', '--force', '--set-upstream', 'origin', branch], stdioIgnoreOptions);
+    debugGit(`push ${branch}`, true);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
     if (spawn.isSpawnError(e) && e.code === 128) {
-      require$$9.debugFn('error', "denied: token requires write permissions for 'contents' and 'pull-requests'");
+      require$$9.debugFn('error', "Push denied: token requires write permissions for 'contents' and 'pull-requests'");
+      require$$9.debugDir('error', e);
+      require$$9.debugDir('inspect', {
+        branch
+      });
+    } else {
+      debugGit(`push ${branch}`, false, {
+        error: e
+      });
     }
-    require$$9.debugDir('inspect', {
-      error: e
-    });
   }
   return false;
 }
@@ -1981,26 +2376,31 @@ async function gitCommit(commitMsg, filepaths, options) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedAddCmd = `\`git add ${filepaths.join(' ')}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedAddCmd}`);
   try {
     await spawn.spawn('git', ['add', ...filepaths], stdioIgnoreOptions);
+    debugGit('add', true, {
+      count: filepaths.length
+    });
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedAddCmd} failed`);
-    require$$9.debugDir('inspect', {
+    debugGit('add', false, {
       error: e
     });
+    require$$9.debugDir('inspect', {
+      filepaths
+    });
+    return false;
   }
-  const quotedCommitCmd = `\`git commit -m ${commitMsg}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCommitCmd}`);
   try {
     await spawn.spawn('git', ['commit', '-m', commitMsg], stdioIgnoreOptions);
+    debugGit('commit', true);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCommitCmd} failed`);
-    require$$9.debugDir('inspect', {
+    debugGit('commit', false, {
       error: e
     });
+    require$$9.debugDir('inspect', {
+      commitMsg
+    });
   }
   return false;
 }
@@ -2009,19 +2409,16 @@ async function gitDeleteBranch(branch, cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = `\`git branch -D ${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     // Will throw with exit code 1 if branch does not exist.
     await spawn.spawn('git', ['branch', '-D', branch], stdioIgnoreOptions);
     return true;
   } catch (e) {
-    if (require$$9.isDebug('stdio')) {
-      require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-      require$$9.debugDir('inspect', {
-        error: e
-      });
-    }
+    // Expected failure when branch doesn't exist.
+    require$$9.debugDir('inspect', {
+      message: `Branch deletion failed (may not exist): ${branch}`,
+      error: e
+    });
   }
   return false;
 }
@@ -2035,41 +2432,30 @@ async function gitEnsureIdentity(name, email, cwd = process.cwd()) {
     1: value
   }) => {
     let configValue;
-    {
-      const quotedCmd = `\`git config --get ${prop}\``;
-      require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
-      try {
-        // Will throw with exit code 1 if the config property is not set.
-        const gitConfigResult = await spawn.spawn('git', ['config', '--get', prop], stdioPipeOptions);
-        require$$9.debugDir('stdio', {
-          gitConfigResult
-        });
-        configValue = gitConfigResult.stdout;
-      } catch (e) {
-        if (require$$9.isDebug('stdio')) {
-          require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-          require$$9.debugDir('inspect', {
-            error: e
-          });
-        }
-      }
+    try {
+      // Will throw with exit code 1 if the config property is not set.
+      const gitConfigResult = await spawn.spawn('git', ['config', '--get', prop], stdioPipeOptions);
+      configValue = gitConfigResult.stdout;
+    } catch (e) {
+      // Expected when config property is not set.
+      require$$9.debugDir('inspect', {
+        message: `Git config property not set: ${prop}`,
+        error: e
+      });
     }
     if (configValue !== value) {
       const stdioIgnoreOptions = {
         cwd,
         stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
       };
-      const quotedCmd = `\`git config ${prop} ${value}\``;
-      require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
       try {
         await spawn.spawn('git', ['config', prop, value], stdioIgnoreOptions);
       } catch (e) {
-        if (require$$9.isDebug('stdio')) {
-          require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-          require$$9.debugDir('inspect', {
-            error: e
-          });
-        }
+        require$$9.debugFn('warn', `Failed to set git config: ${prop}`);
+        require$$9.debugDir('warn', e);
+        require$$9.debugDir('inspect', {
+          value
+        });
       }
     }
   }));
@@ -2079,19 +2465,12 @@ async function gitLocalBranchExists(branch, cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = `\`git show-ref --quiet refs/heads/${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     // Will throw with exit code 1 if the branch does not exist.
     await spawn.spawn('git', ['show-ref', constants.FLAG_QUIET, `refs/heads/${branch}`], stdioIgnoreOptions);
     return true;
-  } catch (e) {
-    if (require$$9.isDebug('stdio')) {
-      require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-      require$$9.debugDir('inspect', {
-        error: e
-      });
-    }
+  } catch {
+    // Expected when branch doesn't exist - no logging needed.
   }
   return false;
 }
@@ -2099,21 +2478,15 @@ async function gitRemoteBranchExists(branch, cwd = process.cwd()) {
   const stdioPipeOptions = {
     cwd
   };
-  const quotedCmd = `\`git ls-remote --heads origin ${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     const lsRemoteResult = await spawn.spawn('git', ['ls-remote', '--heads', 'origin', branch], stdioPipeOptions);
-    require$$9.debugDir('stdio', {
-      lsRemoteResult
-    });
     return lsRemoteResult.stdout.length > 0;
   } catch (e) {
-    if (require$$9.isDebug('stdio')) {
-      require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-      require$$9.debugDir('inspect', {
-        error: e
-      });
-    }
+    // Expected when remote is not accessible or branch doesn't exist.
+    require$$9.debugDir('inspect', {
+      message: `Remote branch check failed: ${branch}`,
+      error: e
+    });
   }
   return false;
 }
@@ -2128,14 +2501,12 @@ async function gitResetHard(branch = 'HEAD', cwd = process.cwd()) {
     cwd,
     stdio: require$$9.isDebug('stdio') ? 'inherit' : 'ignore'
   };
-  const quotedCmd = `\`git reset --hard ${branch}\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     await spawn.spawn('git', ['reset', '--hard', branch], stdioIgnoreOptions);
+    debugGit(`reset --hard ${branch}`, true);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-    require$$9.debugDir('inspect', {
+    debugGit(`reset --hard ${branch}`, false, {
       error: e
     });
   }
@@ -2145,13 +2516,8 @@ async function gitUnstagedModifiedFiles(cwd = process.cwd()) {
   const stdioPipeOptions = {
     cwd
   };
-  const quotedCmd = `\`git diff --name-only\``;
-  require$$9.debugFn('stdio', `spawn: ${quotedCmd}`);
   try {
     const gitDiffResult = await spawn.spawn('git', ['diff', '--name-only'], stdioPipeOptions);
-    require$$9.debugDir('stdio', {
-      gitDiffResult
-    });
     const changedFilesDetails = gitDiffResult.stdout;
     const relPaths = changedFilesDetails.split('\n');
     return {
@@ -2159,10 +2525,8 @@ async function gitUnstagedModifiedFiles(cwd = process.cwd()) {
       data: relPaths.map(p => path$1.normalizePath(p))
     };
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', 'Failed to get unstaged modified files');
+    require$$9.debugDir('error', e);
     return {
       ok: false,
       message: 'Git Error',
@@ -2210,16 +2574,82 @@ function parseGitRemoteUrl(remoteUrl) {
   } : result;
 }
 
-function getPurlObject(purl, options) {
+/**
+ * Package URL (PURL) utilities for Socket CLI.
+ * Implements the PURL specification for universal package identification.
+ *
+ * PURL Format:
+ * pkg:type/namespace/name@version?qualifiers#subpath
+ *
+ * Key Functions:
+ * - createPurlObject: Create PURL from components
+ * - isPurl: Check if string is valid PURL
+ * - normalizePurl: Normalize PURL format
+ * - parsePurl: Parse PURL string to object
+ * - purlToString: Convert PURL object to string
+ *
+ * Supported Types:
+ * - cargo: Rust packages
+ * - gem: Ruby packages
+ * - go: Go modules
+ * - maven: Java packages
+ * - npm: Node.js packages
+ * - pypi: Python packages
+ *
+ * See: https://github.com/package-url/purl-spec
+ */
+
+function createPurlObject(type, name, options) {
+  let opts;
+  if (require$$11.isObjectObject(type)) {
+    opts = {
+      __proto__: null,
+      ...type
+    };
+    type = opts.type;
+    name = opts.name;
+  } else if (require$$11.isObjectObject(name)) {
+    opts = {
+      __proto__: null,
+      ...name
+    };
+    name = opts.name;
+  } else {
+    opts = {
+      __proto__: null,
+      ...options
+    };
+    if (typeof name !== 'string') {
+      name = opts.name;
+    }
+  }
   const {
-    throws
-  } = {
-    __proto__: null,
-    ...options
-  };
+    namespace,
+    qualifiers,
+    subpath,
+    throws,
+    version
+  } = opts;
   const shouldThrow = throws === undefined || !!throws;
   try {
-    return typeof purl === 'string' ? vendor.packageurlJsExports.PackageURL.fromString(normalizePurl(purl)) : purl;
+    return new vendor.packageurlJsExports.PackageURL(type, namespace, name, version, qualifiers, subpath);
+  } catch (e) {
+    if (shouldThrow) {
+      throw e;
+    }
+  }
+  return undefined;
+}
+function getPurlObject(purl, options) {
+  const {
+    throws
+  } = {
+    __proto__: null,
+    ...options
+  };
+  const shouldThrow = throws === undefined || !!throws;
+  try {
+    return typeof purl === 'string' ? vendor.packageurlJsExports.PackageURL.fromString(normalizePurl(purl)) : purl;
   } catch (e) {
     if (shouldThrow) {
       throw e;
@@ -2231,6 +2661,26 @@ function normalizePurl(rawPurl) {
   return rawPurl.startsWith('pkg:') ? rawPurl : `pkg:${rawPurl}`;
 }
 
+/**
+ * Socket.dev URL utilities for Socket CLI.
+ * Generates URLs for Socket.dev website features and resources.
+ *
+ * Key Functions:
+ * - getPkgFullNameFromPurl: Extract full package name from PURL
+ * - getSocketDevAlertUrl: Generate alert type documentation URL
+ * - getSocketDevPackageOverviewUrl: Generate package overview URL
+ * - getSocketDevPackageOverviewUrlFromPurl: Generate overview URL from PURL
+ * - getSocketDevPackageUrl: Generate package detail URL
+ * - getSocketDevPackageUrlFromPurl: Generate package URL from PURL
+ * - getSocketDevReportUrl: Generate scan report URL
+ *
+ * URL Generation:
+ * - Package overview and detail pages
+ * - Security alert documentation
+ * - Scan report links
+ * - Ecosystem-specific URL formatting
+ */
+
 function getPkgFullNameFromPurl(purl) {
   const purlObj = getPurlObject(purl);
   const {
@@ -2273,6 +2723,19 @@ function* walkNestedMap(map, keys = []) {
   }
 }
 
+/**
+ * Coana integration utilities for Socket CLI.
+ * Manages reachability analysis via Coana tech CLI.
+ *
+ * Key Functions:
+ * - extractTier1ReachabilityScanId: Extract scan ID from socket facts file
+ *
+ * Integration:
+ * - Works with @coana-tech/cli for reachability analysis
+ * - Processes socket facts JSON files
+ * - Extracts tier 1 reachability scan identifiers
+ */
+
 function extractTier1ReachabilityScanId(socketFactsFile) {
   const json = fs.readJsonSync(socketFactsFile, {
     throws: false
@@ -2281,6 +2744,25 @@ function extractTier1ReachabilityScanId(socketFactsFile) {
   return tier1ReachabilityScanId.length > 0 ? tier1ReachabilityScanId : undefined;
 }
 
+/**
+ * File system utilities for Socket CLI.
+ * Provides file and directory search functionality.
+ *
+ * Key Functions:
+ * - findUp: Search for files/directories up the directory tree
+ *
+ * Features:
+ * - Upward directory traversal
+ * - Supports file and directory searching
+ * - Abort signal support for cancellation
+ * - Multiple name search support
+ *
+ * Usage:
+ * - Finding configuration files (package.json, lockfiles)
+ * - Locating project root directories
+ * - Searching for specific files in parent directories
+ */
+
 async function findUp(name, options) {
   const opts = {
     __proto__: null,
@@ -2622,13 +3104,15 @@ function exitWithBinPathError$2(binName) {
   // could not be found.
   // eslint-disable-next-line n/no-process-exit
   process.exit(127);
+  // This line is never reached in production, but helps tests.
+  throw new Error('process.exit called');
 }
 let _yarnBinPath;
 function getYarnBinPath() {
   if (_yarnBinPath === undefined) {
     _yarnBinPath = getYarnBinPathDetails().path;
     if (!_yarnBinPath) {
-      exitWithBinPathError$2(constants.default.YARN);
+      exitWithBinPathError$2(constants.YARN);
     }
   }
   return _yarnBinPath;
@@ -2636,7 +3120,7 @@ function getYarnBinPath() {
 let _yarnBinPathDetails;
 function getYarnBinPathDetails() {
   if (_yarnBinPathDetails === undefined) {
-    _yarnBinPathDetails = findBinPathDetailsSync(constants.default.YARN);
+    _yarnBinPathDetails = findBinPathDetailsSync(constants.YARN);
   }
   return _yarnBinPathDetails;
 }
@@ -2668,202 +3152,25 @@ function isYarnBerry() {
   return _isYarnBerry;
 }
 
-function exitWithBinPathError$1(binName) {
-  logger.logger.fail(`Socket unable to locate ${binName}; ensure it is available in the PATH environment variable`);
-  // The exit code 127 indicates that the command or binary being executed
-  // could not be found.
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(127);
-}
-let _npmBinPath;
-function getNpmBinPath() {
-  if (_npmBinPath === undefined) {
-    _npmBinPath = getNpmBinPathDetails().path;
-    if (!_npmBinPath) {
-      exitWithBinPathError$1(constants.NPM);
-    }
-  }
-  return _npmBinPath;
-}
-let _npmBinPathDetails;
-function getNpmBinPathDetails() {
-  if (_npmBinPathDetails === undefined) {
-    _npmBinPathDetails = findBinPathDetailsSync(constants.NPM);
-  }
-  return _npmBinPathDetails;
-}
-let _npmDirPath;
-function getNpmDirPath() {
-  if (_npmDirPath === undefined) {
-    const npmBinPath = getNpmBinPath();
-    _npmDirPath = npmBinPath ? findNpmDirPathSync(npmBinPath) : undefined;
-    if (!_npmDirPath) {
-      _npmDirPath = constants.default.ENV.SOCKET_CLI_NPM_PATH || undefined;
-    }
-    if (!_npmDirPath) {
-      let message = 'Unable to find npm CLI install directory.';
-      if (npmBinPath) {
-        message += `\nSearched parent directories of ${path.dirname(npmBinPath)}.`;
-      }
-      message += '\n\nThis is may be a bug with socket-npm related to changes to the npm CLI.';
-      message += `\nPlease report to ${constants.default.SOCKET_CLI_ISSUES_URL}.`;
-      logger.logger.fail(message);
-      // The exit code 127 indicates that the command or binary being executed
-      // could not be found.
-      // eslint-disable-next-line n/no-process-exit
-      process.exit(127);
-    }
-  }
-  return _npmDirPath;
-}
-let _npmRequire;
-function getNpmRequire() {
-  if (_npmRequire === undefined) {
-    const npmDirPath = getNpmDirPath();
-    const npmNmPath = path.join(npmDirPath, `${constants.NODE_MODULES}/npm`);
-    _npmRequire = require$$5.createRequire(path.join(fs$1.existsSync(npmNmPath) ? npmNmPath : npmDirPath, '<dummy-basename>'));
-  }
-  return _npmRequire;
-}
-let _npxBinPath;
-function getNpxBinPath() {
-  if (_npxBinPath === undefined) {
-    _npxBinPath = getNpxBinPathDetails().path;
-    if (!_npxBinPath) {
-      exitWithBinPathError$1('npx');
-    }
-  }
-  return _npxBinPath;
-}
-let _npxBinPathDetails;
-function getNpxBinPathDetails() {
-  if (_npxBinPathDetails === undefined) {
-    _npxBinPathDetails = findBinPathDetailsSync('npx');
-  }
-  return _npxBinPathDetails;
-}
-function isNpmBinPathShadowed() {
-  return getNpmBinPathDetails().shadowed;
-}
-function isNpxBinPathShadowed() {
-  return getNpxBinPathDetails().shadowed;
-}
-
-const helpFlags = new Set([constants.FLAG_HELP, '-h']);
-
 /**
- * Convert command arguments to a properly formatted string representation.
+ * DLX execution utilities for Socket CLI.
+ * Manages package execution via npx/pnpm dlx/yarn dlx commands.
+ *
+ * Key Functions:
+ * - spawnCdxgenDlx: Execute CycloneDX generator via dlx
+ * - spawnCoanaDlx: Execute Coana CLI tool via dlx
+ * - spawnDlx: Execute packages using dlx-style commands
+ * - spawnSynpDlx: Execute Synp converter via dlx
+ *
+ * Package Manager Detection:
+ * - Auto-detects npm, pnpm, or yarn based on lockfiles
+ * - Supports force-refresh and silent execution modes
+ *
+ * Integration:
+ * - Works with shadow binaries for security scanning
+ * - Handles version pinning and cache management
+ * - Configures environment for third-party tools
  */
-function cmdFlagsToString(args) {
-  const result = [];
-  for (let i = 0, {
-      length
-    } = args; i < length; i += 1) {
-    const arg = args[i].trim();
-    if (arg.startsWith('--')) {
-      const nextArg = i + 1 < length ? args[i + 1].trim() : undefined;
-      // Check if the next item exists and is NOT another flag.
-      if (nextArg && !nextArg.startsWith('--')) {
-        result.push(`${arg}=${nextArg}`);
-        i += 1;
-      } else {
-        result.push(arg);
-      }
-    }
-  }
-  return result.join(' ');
-}
-
-/**
- * Convert flag values to array format for processing.
- */
-function cmdFlagValueToArray(value) {
-  if (typeof value === 'string') {
-    return value.trim().split(/, */).filter(Boolean);
-  }
-  if (Array.isArray(value)) {
-    return value.flatMap(cmdFlagValueToArray);
-  }
-  return [];
-}
-
-/**
- * Add command name prefix to message text.
- */
-function cmdPrefixMessage(cmdName, text) {
-  const cmdPrefix = cmdName ? `${cmdName}: ` : '';
-  return `${cmdPrefix}${text}`;
-}
-
-/**
- * Filter out Socket flags from argv before passing to subcommands.
- */
-function filterFlags(argv, flagsToFilter, exceptions) {
-  const filtered = [];
-
-  // Build set of flags to filter from the provided flag objects.
-  const flagsToFilterSet = new Set();
-  const flagsWithValueSet = new Set();
-  for (const [flagName, flag] of Object.entries(flagsToFilter)) {
-    const longFlag = `--${camelToKebab(flagName)}`;
-    // Special case for negated booleans.
-    if (flagName === 'spinner' || flagName === 'banner') {
-      flagsToFilterSet.add(`--no-${flagName}`);
-    } else {
-      flagsToFilterSet.add(longFlag);
-    }
-    if (flag?.shortFlag) {
-      flagsToFilterSet.add(`-${flag.shortFlag}`);
-    }
-    // Track flags that take values.
-    if (flag.type !== 'boolean') {
-      flagsWithValueSet.add(longFlag);
-      if (flag?.shortFlag) {
-        flagsWithValueSet.add(`-${flag.shortFlag}`);
-      }
-    }
-  }
-  for (let i = 0, {
-      length
-    } = argv; i < length; i += 1) {
-    const arg = argv[i];
-    // Check if this flag should be kept as an exception.
-    if (exceptions?.includes(arg)) {
-      filtered.push(arg);
-      // Handle flags that take values.
-      if (flagsWithValueSet.has(arg)) {
-        // Include the next argument (the flag value).
-        i += 1;
-        if (i < length) {
-          filtered.push(argv[i]);
-        }
-      }
-    } else if (flagsToFilterSet.has(arg)) {
-      // Skip flags that take values.
-      if (flagsWithValueSet.has(arg)) {
-        // Skip the next argument (the flag value).
-        i += 1;
-      }
-      // Skip boolean flags (no additional argument to skip).
-    } else if (arg && Array.from(flagsWithValueSet).some(flag => arg.startsWith(`${flag}=`))) {
-      // Skip --flag=value format for Socket flags unless it's an exception.
-      if (exceptions?.some(exc => arg.startsWith(`${exc}=`))) {
-        filtered.push(arg);
-      }
-      // Otherwise skip it.
-    } else {
-      filtered.push(arg);
-    }
-  }
-  return filtered;
-}
-
-/**
- * Check if argument is a help flag.
- */
-function isHelpFlag(cmdArg) {
-  return helpFlags.has(cmdArg);
-}
 
 const require$2 = require$$5.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
 const {
@@ -2919,10 +3226,8 @@ async function spawnDlx(packageSpec, args, options, spawnExtra) {
   const packageString = `${packageSpec.name}@${packageSpec.version}`;
 
   // Build command args based on package manager.
-  let binName;
   let spawnArgs;
   if (pm === constants.PNPM) {
-    binName = constants.PNPM;
     spawnArgs = ['dlx'];
     if (force) {
       // For pnpm, set dlx-cache-max-age to 0 via env to force fresh download.
@@ -2949,7 +3254,6 @@ async function spawnDlx(packageSpec, args, options, spawnExtra) {
     const shadowPnpmBin = /*@__PURE__*/require$2(constants.default.shadowPnpmBinPath);
     return await shadowPnpmBin(spawnArgs, finalShadowOptions, spawnExtra);
   } else if (pm === constants.YARN && isYarnBerry()) {
-    binName = constants.YARN;
     spawnArgs = ['dlx'];
     // Yarn dlx runs in a temporary environment by design and should always fetch fresh.
     if (silent) {
@@ -2961,7 +3265,6 @@ async function spawnDlx(packageSpec, args, options, spawnExtra) {
   } else {
     // Use npm exec/npx.
     // For consistency, we'll use npx which is more commonly used for one-off execution.
-    binName = 'npx';
     spawnArgs = ['--yes'];
     if (force) {
       // Use --force to bypass cache and get latest within range.
@@ -2971,7 +3274,8 @@ async function spawnDlx(packageSpec, args, options, spawnExtra) {
       spawnArgs.push(constants.FLAG_SILENT);
     }
     spawnArgs.push(packageString, ...args);
-    return await shadowNpmBin(binName, spawnArgs, finalShadowOptions, spawnExtra);
+    const shadowNpxBin = /*@__PURE__*/require$2(constants.default.shadowNpxBinPath);
+    return await shadowNpxBin(spawnArgs, finalShadowOptions, spawnExtra);
   }
 }
 
@@ -3036,8 +3340,8 @@ async function spawnCoanaDlx(args, orgSlug, options, spawnExtra) {
     };
   } catch (e) {
     const stderr = e?.stderr;
-    const cause = e?.message || constants.UNKNOWN_ERROR;
-    const message = stderr ? stderr : cause;
+    const cause = getErrorCause(e);
+    const message = stderr || cause;
     return {
       ok: false,
       data: e,
@@ -3084,6 +3388,26 @@ function hasEnterpriseOrgPlan(orgs) {
   return orgs.some(o => o.plan === 'enterprise');
 }
 
+/**
+ * Socket JSON utilities for Socket CLI.
+ * Manages .socket/socket.json configuration and scan metadata.
+ *
+ * Key Functions:
+ * - loadDotSocketDirectory: Load .socket directory configuration
+ * - saveSocketJson: Persist scan configuration to .socket/socket.json
+ * - validateSocketJson: Validate socket.json structure
+ *
+ * File Structure:
+ * - Contains scan metadata and configuration
+ * - Stores scan IDs and repository information
+ * - Tracks CLI version and scan timestamps
+ *
+ * Directory Management:
+ * - Creates .socket directory as needed
+ * - Handles nested directory structures
+ * - Supports both read and write operations
+ */
+
 function readOrDefaultSocketJson(cwd) {
   const jsonCResult = readSocketJsonSync(cwd, true);
   return jsonCResult.ok ? jsonCResult.data :
@@ -3129,35 +3453,31 @@ function readSocketJsonSync(cwd, defaultOnError = false) {
   } catch (e) {
     if (defaultOnError) {
       logger.logger.warn(`Failed to read ${constants.SOCKET_JSON}, using default`);
-      require$$9.debugDir('inspect', {
-        error: e
-      });
+      require$$9.debugFn('warn', `Failed to read ${constants.SOCKET_JSON} sync`);
+      require$$9.debugDir('warn', e);
       return {
         ok: true,
         data: getDefaultSocketJson()
       };
     }
-    const cause = e?.message;
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    const cause = formatErrorWithDetail(`An error occurred while trying to read ${constants.SOCKET_JSON}`, e);
+    require$$9.debugFn('error', `Failed to read ${constants.SOCKET_JSON} sync`);
+    require$$9.debugDir('error', e);
     return {
       ok: false,
       message: `Failed to read ${constants.SOCKET_JSON}`,
-      cause: `An error occurred while trying to read ${constants.SOCKET_JSON}${cause ? `: ${cause}` : ''}`
+      cause
     };
   }
   let jsonObj;
   try {
     jsonObj = JSON.parse(jsonContent);
   } catch (e) {
-    require$$9.debugFn('error', 'caught: JSON.parse error');
+    require$$9.debugFn('error', `Failed to parse ${constants.SOCKET_JSON} as JSON (sync)`);
     require$$9.debugDir('inspect', {
       jsonContent
     });
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugDir('error', e);
     if (defaultOnError) {
       logger.logger.warn(`Failed to parse ${constants.SOCKET_JSON}, using default`);
       return {
@@ -3191,11 +3511,11 @@ async function writeSocketJson(cwd, sockJson) {
   try {
     jsonContent = JSON.stringify(sockJson, null, 2);
   } catch (e) {
-    require$$9.debugFn('error', 'caught: JSON.stringify error');
+    require$$9.debugFn('error', `Failed to serialize ${constants.SOCKET_JSON} to JSON`);
     require$$9.debugDir('inspect', {
-      error: e,
       sockJson
     });
+    require$$9.debugDir('error', e);
     return {
       ok: false,
       message: 'Failed to serialize to JSON',
@@ -3210,6 +3530,32 @@ async function writeSocketJson(cwd, sockJson) {
   };
 }
 
+/**
+ * GitHub utilities for Socket CLI.
+ * Provides GitHub API integration for repository operations and GHSA vulnerability data.
+ *
+ * Authentication:
+ * - getGitHubToken: Retrieve GitHub token from env/git config
+ * - getOctokit: Get authenticated Octokit instance
+ * - getOctokitGraphql: Get authenticated GraphQL client
+ *
+ * Caching:
+ * - 5-minute TTL for API responses
+ * - Automatic cache invalidation
+ * - Persistent cache in node_modules/.cache
+ *
+ * GHSA Operations:
+ * - cacheFetch: Cache API responses with TTL
+ * - fetchGhsaDetails: Fetch GitHub Security Advisory details
+ * - getGhsaUrl: Generate GHSA advisory URL
+ * - readCache/writeCache: Persistent cache operations
+ *
+ * Repository Operations:
+ * - GraphQL queries for complex operations
+ * - Integration with Octokit REST API
+ * - Support for GitHub Actions environment variables
+ */
+
 async function readCache(key,
 // 5 minute in milliseconds time to live (TTL).
 ttlMs = 5 * 60 * 1000) {
@@ -3289,11 +3635,8 @@ async function fetchGhsaDetails(ids) {
       }
     }
   } catch (e) {
-    const cause = e?.message;
-    require$$9.debugFn('error', `Failed to fetch GHSA details${cause ? `: ${cause}` : ''}`);
-    require$$9.debugDir('inspect', {
-      error: e
-    });
+    require$$9.debugFn('error', formatErrorWithDetail('Failed to fetch GHSA details', e));
+    require$$9.debugDir('error', e);
   }
   return results;
 }
@@ -3397,12 +3740,153 @@ async function setGitRemoteGithubRepoUrl(owner, repo, token, cwd = process.cwd()
     await spawn.spawn('git', ['remote', 'set-url', 'origin', url], stdioIgnoreOptions);
     return true;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
+    require$$9.debugFn('error', `Git command failed: ${quotedCmd}`);
     require$$9.debugDir('inspect', {
-      error: e
+      cmd: quotedCmd
     });
+    require$$9.debugDir('error', e);
+  }
+  return false;
+}
+
+/**
+ * Command-line utilities for Socket CLI.
+ * Handles argument parsing, flag processing, and command formatting.
+ *
+ * Argument Handling:
+ * - Handles both long (--flag) and short (-f) formats
+ * - Preserves special characters and escaping
+ * - Properly quotes arguments containing spaces
+ *
+ * Command Names:
+ * - commandNameFromCamel: Convert camelCase to kebab-case command names
+ * - commandNameFromKebab: Convert kebab-case to camelCase
+ *
+ * Flag Processing:
+ * - cmdFlagsToString: Format arguments for display with proper escaping
+ * - cmdPrefixMessage: Generate command prefix message
+ * - stripConfigFlags: Remove --config flags from argument list
+ * - stripDebugFlags: Remove debug-related flags
+ * - stripHelpFlags: Remove help flags (-h, --help)
+ */
+
+const helpFlags = new Set([constants.FLAG_HELP, '-h']);
+
+/**
+ * Convert command arguments to a properly formatted string representation.
+ */
+function cmdFlagsToString(args) {
+  const result = [];
+  for (let i = 0, {
+      length
+    } = args; i < length; i += 1) {
+    const arg = args[i].trim();
+    if (arg.startsWith('--')) {
+      const nextArg = i + 1 < length ? args[i + 1].trim() : undefined;
+      // Check if the next item exists and is NOT another flag.
+      if (nextArg && !nextArg.startsWith('--') && !nextArg.startsWith('-')) {
+        result.push(`${arg}=${nextArg}`);
+        i += 1;
+      } else {
+        result.push(arg);
+      }
+    } else {
+      // Include non-flag arguments (commands, package names, etc.).
+      result.push(arg);
+    }
+  }
+  return result.join(' ');
+}
+
+/**
+ * Convert flag values to array format for processing.
+ */
+function cmdFlagValueToArray(value) {
+  if (typeof value === 'string') {
+    return value.trim().split(/, */).filter(Boolean);
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap(cmdFlagValueToArray);
+  }
+  return [];
+}
+
+/**
+ * Add command name prefix to message text.
+ */
+function cmdPrefixMessage(cmdName, text) {
+  const cmdPrefix = cmdName ? `${cmdName}: ` : '';
+  return `${cmdPrefix}${text}`;
+}
+
+/**
+ * Filter out Socket flags from argv before passing to subcommands.
+ */
+function filterFlags(argv, flagsToFilter, exceptions) {
+  const filtered = [];
+
+  // Build set of flags to filter from the provided flag objects.
+  const flagsToFilterSet = new Set();
+  const flagsWithValueSet = new Set();
+  for (const [flagName, flag] of Object.entries(flagsToFilter)) {
+    const longFlag = `--${camelToKebab(flagName)}`;
+    // Special case for negated booleans.
+    if (flagName === 'spinner' || flagName === 'banner') {
+      flagsToFilterSet.add(`--no-${flagName}`);
+    } else {
+      flagsToFilterSet.add(longFlag);
+    }
+    if (flag?.shortFlag) {
+      flagsToFilterSet.add(`-${flag.shortFlag}`);
+    }
+    // Track flags that take values.
+    if (flag.type !== 'boolean') {
+      flagsWithValueSet.add(longFlag);
+      if (flag?.shortFlag) {
+        flagsWithValueSet.add(`-${flag.shortFlag}`);
+      }
+    }
+  }
+  for (let i = 0, {
+      length
+    } = argv; i < length; i += 1) {
+    const arg = argv[i];
+    // Check if this flag should be kept as an exception.
+    if (exceptions?.includes(arg)) {
+      filtered.push(arg);
+      // Handle flags that take values.
+      if (flagsWithValueSet.has(arg)) {
+        // Include the next argument (the flag value).
+        i += 1;
+        if (i < length) {
+          filtered.push(argv[i]);
+        }
+      }
+    } else if (flagsToFilterSet.has(arg)) {
+      // Skip flags that take values.
+      if (flagsWithValueSet.has(arg)) {
+        // Skip the next argument (the flag value).
+        i += 1;
+      }
+      // Skip boolean flags (no additional argument to skip).
+    } else if (arg && Array.from(flagsWithValueSet).some(flag => arg.startsWith(`${flag}=`))) {
+      // Skip --flag=value format for Socket flags unless it's an exception.
+      if (exceptions?.some(exc => arg.startsWith(`${exc}=`))) {
+        filtered.push(arg);
+      }
+      // Otherwise skip it.
+    } else {
+      filtered.push(arg);
+    }
   }
-  return false;
+  return filtered;
+}
+
+/**
+ * Check if argument is a help flag.
+ */
+function isHelpFlag(cmdArg) {
+  return helpFlags.has(cmdArg);
 }
 
 /**
@@ -3429,7 +3913,7 @@ async function convertCveToGhsa(cveId) {
   } catch (e) {
     return {
       ok: false,
-      message: `Failed to convert CVE to GHSA: ${e instanceof Error ? e.message : 'Unknown error'}`
+      message: `Failed to convert CVE to GHSA: ${getErrorCause(e)}`
     };
   }
 }
@@ -3493,7 +3977,7 @@ async function convertPurlToGhsas(purl) {
   } catch (e) {
     return {
       ok: false,
-      message: `Failed to convert PURL to GHSA: ${e instanceof Error ? e.message : constants.UNKNOWN_ERROR}`
+      message: `Failed to convert PURL to GHSA: ${getErrorCause(e)}`
     };
   }
 }
@@ -3564,39 +4048,100 @@ fi
   };
 }
 
-const {
-  kInternalsSymbol,
-  [kInternalsSymbol]: {
-    getSentry
+/**
+ * Safe wrapper for npm-package-arg that doesn't throw.
+ * Returns undefined if parsing fails.
+ */
+function safeNpa$1(...args) {
+  try {
+    return Reflect.apply(vendor.npaExports, undefined, args);
+  } catch {}
+  return undefined;
+}
+
+function exitWithBinPathError$1(binName) {
+  logger.logger.fail(`Socket unable to locate ${binName}; ensure it is available in the PATH environment variable`);
+  // The exit code 127 indicates that the command or binary being executed
+  // could not be found.
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(127);
+  // This line is never reached in production, but helps tests.
+  throw new Error('process.exit called');
+}
+let _npmBinPath;
+function getNpmBinPath() {
+  if (_npmBinPath === undefined) {
+    _npmBinPath = getNpmBinPathDetails().path;
+    if (!_npmBinPath) {
+      exitWithBinPathError$1(constants.NPM);
+    }
   }
-} = constants.default;
-class AuthError extends Error {}
-class InputError extends Error {
-  constructor(message, body) {
-    super(message);
-    this.body = body;
+  return _npmBinPath;
+}
+let _npmBinPathDetails;
+function getNpmBinPathDetails() {
+  if (_npmBinPathDetails === undefined) {
+    _npmBinPathDetails = findBinPathDetailsSync(constants.NPM);
   }
+  return _npmBinPathDetails;
 }
-async function captureException(exception, hint) {
-  const result = captureExceptionSync(exception, hint);
-  // "Sleep" for a second, just in case, hopefully enough time to initiate fetch.
-  await promises.setTimeout(1000);
-  return result;
+let _npmDirPath;
+function getNpmDirPath() {
+  if (_npmDirPath === undefined) {
+    const npmBinPath = getNpmBinPath();
+    _npmDirPath = npmBinPath ? findNpmDirPathSync(npmBinPath) : undefined;
+    if (!_npmDirPath) {
+      _npmDirPath = constants.default.ENV.SOCKET_CLI_NPM_PATH || undefined;
+    }
+    if (!_npmDirPath) {
+      let message = 'Unable to find npm CLI install directory.';
+      if (npmBinPath) {
+        message += `\nSearched parent directories of ${path.dirname(npmBinPath)}.`;
+      }
+      message += '\n\nThis is may be a bug with socket-npm related to changes to the npm CLI.';
+      message += `\nPlease report to ${constants.default.SOCKET_CLI_ISSUES_URL}.`;
+      logger.logger.fail(message);
+      // The exit code 127 indicates that the command or binary being executed
+      // could not be found.
+      // eslint-disable-next-line n/no-process-exit
+      process.exit(127);
+      // This line is never reached in production, but helps tests.
+      throw new Error('process.exit called');
+    }
+  }
+  return _npmDirPath;
 }
-function captureExceptionSync(exception, hint) {
-  const Sentry = getSentry();
-  if (!Sentry) {
-    return '';
+let _npmRequire;
+function getNpmRequire() {
+  if (_npmRequire === undefined) {
+    const npmDirPath = getNpmDirPath();
+    const npmNmPath = path.join(npmDirPath, `${constants.NODE_MODULES}/npm`);
+    _npmRequire = require$$5.createRequire(path.join(fs$1.existsSync(npmNmPath) ? npmNmPath : npmDirPath, '<dummy-basename>'));
   }
-  require$$9.debugFn('notice', 'send: exception to Sentry');
-  return Sentry.captureException(exception, hint);
+  return _npmRequire;
 }
-
-function npa(...args) {
-  try {
-    return Reflect.apply(vendor.npaExports, undefined, args);
-  } catch {}
-  return undefined;
+let _npxBinPath;
+function getNpxBinPath() {
+  if (_npxBinPath === undefined) {
+    _npxBinPath = getNpxBinPathDetails().path;
+    if (!_npxBinPath) {
+      exitWithBinPathError$1('npx');
+    }
+  }
+  return _npxBinPath;
+}
+let _npxBinPathDetails;
+function getNpxBinPathDetails() {
+  if (_npxBinPathDetails === undefined) {
+    _npxBinPathDetails = findBinPathDetailsSync('npx');
+  }
+  return _npxBinPathDetails;
+}
+function isNpmBinPathShadowed() {
+  return getNpmBinPathDetails().shadowed;
+}
+function isNpxBinPathShadowed() {
+  return getNpxBinPathDetails().shadowed;
 }
 
 function shadowNpmInstall(options) {
@@ -3662,6 +4207,24 @@ function shadowNpmInstall(options) {
   return spawnPromise;
 }
 
+/**
+ * Package manager agent utilities for Socket CLI.
+ * Manages package installation via different package managers.
+ *
+ * Key Functions:
+ * - runAgentInstall: Execute package installation with detected agent
+ *
+ * Supported Agents:
+ * - npm: Node Package Manager
+ * - pnpm: Fast, disk space efficient package manager
+ * - yarn: Alternative package manager
+ *
+ * Features:
+ * - Automatic agent detection
+ * - Shadow installation for security scanning
+ * - Spinner support for progress indication
+ */
+
 function runAgentInstall(pkgEnvDetails, options) {
   const {
     agent,
@@ -3706,6 +4269,32 @@ function runAgentInstall(pkgEnvDetails, options) {
   });
 }
 
+/**
+ * Package environment detection utilities for Socket CLI.
+ * Analyzes project environment and package manager configuration.
+ *
+ * Key Functions:
+ * - getPackageEnvironment: Detect package manager and project details
+ * - makeConcurrentExecLimit: Calculate concurrent execution limits
+ *
+ * Environment Detection:
+ * - Detects npm, pnpm, yarn, bun package managers
+ * - Analyzes lockfiles for version information
+ * - Determines Node.js and engine requirements
+ * - Identifies workspace configurations
+ *
+ * Features:
+ * - Browser target detection via browserslist
+ * - Engine compatibility checking
+ * - Package manager version detection
+ * - Workspace and monorepo support
+ *
+ * Usage:
+ * - Auto-detecting appropriate package manager
+ * - Validating environment compatibility
+ * - Configuring concurrent execution limits
+ */
+
 const {
   BUN,
   BUN_LOCK,
@@ -3833,10 +4422,11 @@ async function getAgentVersion(agent, agentExecPath, cwd) {
       shell: constants.default.WIN32
     })).stdout) ?? undefined;
   } catch (e) {
-    require$$9.debugFn('error', `caught: ${quotedCmd} failed`);
+    require$$9.debugFn('error', `Package manager command failed: ${quotedCmd}`);
     require$$9.debugDir('inspect', {
-      error: e
+      cmd: quotedCmd
     });
+    require$$9.debugDir('error', e);
   }
   return result;
 }
@@ -4065,39 +4655,47 @@ async function detectAndValidatePackageEnvironment(cwd, options) {
   };
 }
 
+/**
+ * Ecosystem type utilities for Socket CLI.
+ * Manages package ecosystem identifiers and mappings.
+ *
+ * Constants:
+ * - ALL_ECOSYSTEMS: Complete list of supported ecosystems
+ * - ECOSYSTEM_MAP: Map ecosystem strings to PURL types
+ *
+ * Type Definitions:
+ * - PURL_Type: Package URL type from Socket SDK
+ *
+ * Supported Ecosystems:
+ * - apk, bitbucket, cargo, chrome, cocoapods, composer
+ * - conan, conda, cran, deb, docker, gem, generic
+ * - github, gitlab, go, hackage, hex, huggingface
+ * - maven, mlflow, npm, nuget, oci, pub, pypi, rpm, swift
+ *
+ * Usage:
+ * - Validates ecosystem types
+ * - Maps between different ecosystem representations
+ * - Ensures type safety for ecosystem operations
+ */
+
 const ALL_ECOSYSTEMS = ['apk', 'bitbucket', 'cargo', 'chrome', 'cocoapods', 'composer', 'conan', 'conda', 'cran', 'deb', 'docker', 'gem', 'generic', 'github', 'golang', 'hackage', 'hex', 'huggingface', 'maven', 'mlflow', constants.NPM, 'nuget', 'oci', 'pub', 'pypi', 'qpkg', 'rpm', 'swift', 'swid', 'unknown'];
 new Set(ALL_ECOSYSTEMS);
 function getEcosystemChoicesForMeow() {
   return [...ALL_ECOSYSTEMS];
 }
 
-function exitWithBinPathError(binName) {
-  logger.logger.fail(`Socket unable to locate ${binName}; ensure it is available in the PATH environment variable`);
-  // The exit code 127 indicates that the command or binary being executed
-  // could not be found.
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(127);
-}
-let _pnpmBinPath;
-function getPnpmBinPath() {
-  if (_pnpmBinPath === undefined) {
-    _pnpmBinPath = getPnpmBinPathDetails().path;
-    if (!_pnpmBinPath) {
-      exitWithBinPathError('pnpm');
-    }
-  }
-  return _pnpmBinPath;
-}
-let _pnpmBinPathDetails;
-function getPnpmBinPathDetails() {
-  if (_pnpmBinPathDetails === undefined) {
-    _pnpmBinPathDetails = findBinPathDetailsSync('pnpm');
-  }
-  return _pnpmBinPathDetails;
-}
-function isPnpmBinPathShadowed() {
-  return getPnpmBinPathDetails().shadowed;
-}
+/**
+ * Filter configuration utilities for Socket CLI.
+ * Manages filter configuration normalization for security scanning.
+ *
+ * Key Functions:
+ * - toFilterConfig: Normalize filter configuration objects
+ *
+ * Usage:
+ * - Normalizes user-provided filter objects
+ * - Ensures proper structure for filter configuration
+ * - Validates boolean and array values
+ */
 
 function toFilterConfig(obj) {
   const normalized = {
@@ -4197,6 +4795,30 @@ const ALERT_SEVERITY = createEnum({
   low: 'low'
 });
 
+/**
+ * Color and markdown formatting utilities for Socket CLI.
+ * Provides dual-mode formatting for terminal colors or markdown output.
+ *
+ * Key Class:
+ * - ColorOrMarkdown: Dual-mode formatter for terminal/markdown output
+ *
+ * Formatting Methods:
+ * - bold: Bold text formatting
+ * - codeBlock: Code block formatting
+ * - codeInline: Inline code formatting
+ * - header: Section headers
+ * - hyperlink: Clickable links
+ * - indent: Text indentation
+ * - italic: Italic text formatting
+ * - list: Bullet list formatting
+ * - table: Table formatting
+ *
+ * Usage:
+ * - Switches between terminal colors and markdown based on output format
+ * - Supports both interactive terminal and report generation
+ * - Handles hyperlink fallbacks for terminals without link support
+ */
+
 class ColorOrMarkdown {
   constructor(useMarkdown) {
     this.useMarkdown = !!useMarkdown;
@@ -4242,6 +4864,28 @@ function getTranslations() {
   return _translations;
 }
 
+/**
+ * Socket package alert utilities for Socket CLI.
+ * Handles security alerts, vulnerabilities, and package risk assessment.
+ *
+ * Key Functions:
+ * - addArtifactToAlertsMap: Add security alert to package map
+ * - logAlertsMap: Display alerts in formatted output
+ * - shouldSkipPackageAlert: Filter alerts based on criteria
+ *
+ * Alert Types:
+ * - CVE: Common Vulnerabilities and Exposures
+ * - GHSA: GitHub Security Advisories
+ * - Package quality issues
+ * - Supply chain risks
+ *
+ * Features:
+ * - Alert severity classification (critical/high/medium/low)
+ * - Fix type detection (major/minor/patch/none)
+ * - Alert filtering and suppression
+ * - Colorized terminal output
+ */
+
 const ALERT_SEVERITY_COLOR = createEnum({
   critical: 'magenta',
   high: 'red',
@@ -4586,6 +5230,26 @@ function logAlertsMap(alertsMap, options) {
   output.write('\n');
 }
 
+/**
+ * Alerts map utilities for Socket CLI.
+ * Manages security alerts and vulnerability mappings for packages.
+ *
+ * Key Functions:
+ * - getAlertsMapFromPnpmLockfile: Extract alerts from pnpm lockfile
+ * - getAlertsMapFromPurls: Get alerts for specific package URLs
+ * - processAlertsApiResponse: Process API response into alerts map
+ *
+ * Alert Processing:
+ * - Filters alerts based on socket.yml configuration
+ * - Maps package URLs to security vulnerabilities
+ * - Supports batch processing for performance
+ *
+ * Integration:
+ * - Works with pnpm lockfiles for dependency scanning
+ * - Uses Socket API for vulnerability data
+ * - Respects filter configurations from socket.yml
+ */
+
 async function getAlertsMapFromPnpmLockfile(lockfile, options) {
   const purls = await extractPurlsFromPnpmLockfile(lockfile);
   return await getAlertsMapFromPurls(purls, {
@@ -4686,6 +5350,183 @@ async function getAlertsMapFromPurls(purls, options) {
   return alertsByPurl;
 }
 
+/**
+ * npm package specification utilities for Socket CLI.
+ * Parses and handles various npm package specification formats.
+ *
+ * Supported Formats:
+ * - Regular packages: lodash, lodash@4.17.21
+ * - Scoped packages: @types/node, @types/node@20.0.0
+ * - Version ranges: lodash@^4.0.0, lodash@~4.17.0
+ * - Git URLs: git+https://github.com/user/repo.git
+ * - File paths: file:../local-package
+ * - Aliases: my-alias@npm:real-package@1.0.0
+ *
+ * Key Functions:
+ * - safeNpa: Safe wrapper for npm-package-arg
+ * - safeNpmSpecToPurl: Convert npm spec to PURL
+ * - safeParseNpmSpec: Parse npm spec to name/version
+ *
+ * Error Handling:
+ * - Returns undefined for invalid specs
+ * - Fallback parsing for edge cases
+ * - Safe against malformed input
+ */
+
+
+// @ts-expect-error - Result is re-exported below.
+
+/**
+ * Safe wrapper for npm-package-arg that doesn't throw.
+ * Returns undefined if parsing fails.
+ */
+function safeNpa(...args) {
+  try {
+    return Reflect.apply(vendor.npaExports, undefined, args);
+  } catch {}
+  return undefined;
+}
+
+/**
+ * Parse npm package specification into name and version.
+ * Uses npm-package-arg for proper handling of various spec formats:
+ * - Regular packages: lodash, lodash@4.17.21
+ * - Scoped packages: @types/node, @types/node@20.0.0
+ * - Version ranges: lodash@^4.0.0
+ * - Git URLs, file paths, etc.
+ *
+ * Returns undefined if parsing fails.
+ */
+function safeParseNpmSpec(pkgSpec) {
+  // Use npm-package-arg for proper spec parsing.
+  const parsed = safeNpa(pkgSpec);
+  if (!parsed) {
+    // Fallback to simple parsing if npm-package-arg fails.
+    // Handle scoped packages first to avoid confusion with version delimiter.
+    if (pkgSpec.startsWith('@')) {
+      const scopedMatch = pkgSpec.match(/^(@[^/@]+\/[^/@]+)(?:@(.+))?$/);
+      if (scopedMatch) {
+        return {
+          name: scopedMatch[1],
+          version: scopedMatch[2]
+        };
+      }
+    }
+
+    // Handle regular packages.
+    const atIndex = pkgSpec.indexOf('@');
+    if (atIndex === -1) {
+      return {
+        name: pkgSpec,
+        version: undefined
+      };
+    }
+    return {
+      name: pkgSpec.slice(0, atIndex),
+      version: pkgSpec.slice(atIndex + 1)
+    };
+  }
+
+  // Extract name and version from parsed spec.
+  const name = parsed.name || pkgSpec;
+  let version;
+
+  // Handle different spec types from npm-package-arg.
+  if (parsed.type === 'tag' || parsed.type === 'version' || parsed.type === 'range') {
+    // For npm registry packages:
+    // - type 'tag': latest, beta, etc.
+    // - type 'version': exact version like 1.0.0
+    // - type 'range': version range like ^1.0.0, ~1.0.0, or * for bare names
+    // Don't include '*' as a version - it means "any version".
+    if (parsed.fetchSpec && parsed.fetchSpec !== '*') {
+      version = parsed.fetchSpec;
+    } else if (parsed.rawSpec && parsed.rawSpec !== '*' && parsed.rawSpec !== parsed.name) {
+      version = parsed.rawSpec;
+    }
+  } else if (parsed.type === 'git' || parsed.type === 'remote' || parsed.type === 'file') {
+    // For non-registry specs, use rawSpec if different from name.
+    if (parsed.rawSpec && parsed.rawSpec !== parsed.name) {
+      version = parsed.rawSpec;
+    }
+  }
+  return {
+    name,
+    version
+  };
+}
+
+/**
+ * Convert npm package spec to PURL string.
+ * Handles various npm spec formats and converts them to standardized PURLs.
+ * Returns undefined if conversion fails.
+ */
+function safeNpmSpecToPurl(pkgSpec) {
+  const parsed = safeParseNpmSpec(pkgSpec);
+  if (!parsed) {
+    return undefined;
+  }
+  const {
+    name,
+    version
+  } = parsed;
+
+  // Create PURL object to ensure proper formatting.
+  const purlObj = createPurlObject({
+    type: constants.NPM,
+    name,
+    version,
+    throws: false
+  });
+  return purlObj?.toString() ?? `pkg:${constants.NPM}/${name}${version ? `@${version}` : ''}`;
+}
+
+/**
+ * PNPM path resolution utilities for Socket CLI.
+ * Locates and caches PNPM binary paths.
+ *
+ * Key Functions:
+ * - getPnpmBinPath: Get cached PNPM binary path
+ * - getPnpmBinPathDetails: Get detailed PNPM path information
+ *
+ * Error Handling:
+ * - Exits with code 127 if PNPM not found
+ * - Provides clear error messages for missing binaries
+ *
+ * Caching:
+ * - Caches binary path lookups for performance
+ * - Prevents repeated PATH searches
+ */
+
+function exitWithBinPathError(binName) {
+  logger.logger.fail(`Socket unable to locate ${binName}; ensure it is available in the PATH environment variable`);
+  // The exit code 127 indicates that the command or binary being executed
+  // could not be found.
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(127);
+  // This line is never reached in production, but helps tests.
+  throw new Error('process.exit called');
+}
+let _pnpmBinPath;
+function getPnpmBinPath() {
+  if (_pnpmBinPath === undefined) {
+    _pnpmBinPath = getPnpmBinPathDetails().path;
+    if (!_pnpmBinPath) {
+      exitWithBinPathError('pnpm');
+    }
+  }
+  return _pnpmBinPath;
+}
+let _pnpmBinPathDetails;
+function getPnpmBinPathDetails() {
+  if (_pnpmBinPathDetails === undefined) {
+    _pnpmBinPathDetails = findBinPathDetailsSync('pnpm');
+  }
+  return _pnpmBinPathDetails;
+}
+function isPnpmBinPathShadowed() {
+  return getPnpmBinPathDetails().shadowed;
+}
+
 exports.AuthError = AuthError;
 exports.COMPLETION_CMD_PREFIX = COMPLETION_CMD_PREFIX;
 exports.InputError = InputError;
@@ -4699,6 +5540,8 @@ exports.cmdPrefixMessage = cmdPrefixMessage;
 exports.convertCveToGhsa = convertCveToGhsa;
 exports.convertPurlToGhsas = convertPurlToGhsas;
 exports.createEnum = createEnum;
+exports.debugFileOp = debugFileOp;
+exports.debugScan = debugScan;
 exports.detectAndValidatePackageEnvironment = detectAndValidatePackageEnvironment;
 exports.detectDefaultBranch = detectDefaultBranch;
 exports.determineOrgSlug = determineOrgSlug;
@@ -4709,6 +5552,7 @@ exports.fetchGhsaDetails = fetchGhsaDetails;
 exports.fetchOrganization = fetchOrganization;
 exports.filterFlags = filterFlags;
 exports.findUp = findUp;
+exports.formatErrorWithDetail = formatErrorWithDetail;
 exports.getAlertsMapFromPnpmLockfile = getAlertsMapFromPnpmLockfile;
 exports.getAlertsMapFromPurls = getAlertsMapFromPurls;
 exports.getBaseBranch = getBaseBranch;
@@ -4718,6 +5562,7 @@ exports.getConfigValueOrUndef = getConfigValueOrUndef;
 exports.getDefaultOrgSlug = getDefaultOrgSlug;
 exports.getEcosystemChoicesForMeow = getEcosystemChoicesForMeow;
 exports.getEnterpriseOrgs = getEnterpriseOrgs;
+exports.getErrorCause = getErrorCause;
 exports.getFlagApiRequirementsOutput = getFlagApiRequirementsOutput;
 exports.getFlagListOutput = getFlagListOutput;
 exports.getMajor = getMajor;
@@ -4773,7 +5618,6 @@ exports.meowOrExit = meowOrExit;
 exports.meowWithSubcommands = meowWithSubcommands;
 exports.msAtHome = msAtHome;
 exports.normalizePurl = normalizePurl;
-exports.npa = npa;
 exports.parsePnpmLockfile = parsePnpmLockfile;
 exports.queryApiSafeJson = queryApiSafeJson;
 exports.queryApiSafeText = queryApiSafeText;
@@ -4782,6 +5626,8 @@ exports.readOrDefaultSocketJsonUp = readOrDefaultSocketJsonUp;
 exports.readPnpmLockfile = readPnpmLockfile;
 exports.readSocketJsonSync = readSocketJsonSync;
 exports.runAgentInstall = runAgentInstall;
+exports.safeNpa = safeNpa$1;
+exports.safeNpmSpecToPurl = safeNpmSpecToPurl;
 exports.sendApiRequest = sendApiRequest;
 exports.serializeResultJson = serializeResultJson;
 exports.setGitRemoteGithubRepoUrl = setGitRemoteGithubRepoUrl;
@@ -4795,5 +5641,5 @@ exports.toFilterConfig = toFilterConfig;
 exports.updateConfigValue = updateConfigValue;
 exports.walkNestedMap = walkNestedMap;
 exports.writeSocketJson = writeSocketJson;
-//# debugId=4f982f8d-ea52-46a2-a41c-84d9eac292ab
+//# debugId=cf6fa269-bd5d-472d-ba3c-ad112752f863
 //# sourceMappingURL=utils.js.map