@socketsecurity/cli-with-sentry 1.1.47 → 1.1.49

package/dist/utils.js

@@ -23,10 +23,13 @@ var require$$13 = require('../external/@socketsecurity/registry/lib/url');
 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 require$$0 = require('node:url');
+var require$$0$1 = require('node:url');
 var globs = require('../external/@socketsecurity/registry/lib/globs');
 var streams = require('../external/@socketsecurity/registry/lib/streams');
 var promises = require('node:timers/promises');
+var os = require('node:os');
+var process$1 = require('node:process');
+var require$$0 = require('node:crypto');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /**
@@ -545,7 +548,7 @@ function updateConfigValue(configKey, value) {
  * - Used for permission validation and help text
  */
 
-const require$3 = require$$5.createRequire((typeof document === 'undefined' ? require$$0.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
+const require$3 = require$$5.createRequire((typeof document === 'undefined' ? require$$0$1.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
 let _requirements;
 function getRequirements() {
   if (_requirements === undefined) {
@@ -561,6 +564,849 @@ function getRequirementsKey(cmdPath) {
   return cmdPath.replace(/^socket[: ]/, '').replace(/ +/g, ':');
 }
 
+/**
+ * Telemetry service for Socket CLI.
+ * Manages event collection, batching, and submission to Socket API.
+ *
+ * IMPORTANT: Telemetry is ALWAYS scoped to an organization.
+ * Cannot track telemetry without an org context.
+ *
+ * Features:
+ * - Singleton pattern (one instance per process)
+ * - Organization-scoped tracking (required)
+ * - Event batching (auto-flush at batch size)
+ * - Exit handlers (auto-flush on process exit)
+ * - Automatic session ID assignment
+ * - Explicit finalization via destroy() for controlled cleanup
+ * - Graceful degradation (errors don't block CLI)
+ *
+ * @example
+ * ```typescript
+ * // Get telemetry client (returns singleton instance)
+ * const telemetry = await TelemetryService.getTelemetryClient('my-org')
+ *
+ * // Track an event (session_id is auto-set)
+ * telemetry.track({
+ *   event_sender_created_at: new Date().toISOString(),
+ *   event_type: 'cli_start',
+ *   context: {
+ *     version: '2.2.15',
+ *     platform: process.platform,
+ *     node_version: process.version,
+ *     arch: process.arch,
+ *     argv: process.argv.slice(2)
+ *   }
+ * })
+ *
+ * // Flush happens automatically on batch size and exit
+ * // Can also be called manually if needed
+ * await telemetry.flush()
+ *
+ * // Always call destroy() before exit to flush remaining events
+ * await telemetry.destroy()
+ * ```
+ */
+
+/**
+ * Debug wrapper for telemetry service.
+ * Wraps debugFn to provide a simpler API.
+ */
+const debug$1 = message => {
+  require$$9.debugFn('socket:telemetry:service', message);
+};
+
+/**
+ * DebugDir wrapper for telemetry service.
+ */
+const debugDirWrapper = obj => {
+  require$$9.debugDir('socket:telemetry:service', obj);
+};
+
+/**
+ * Process-wide session ID.
+ * Generated once per CLI invocation and shared across all telemetry instances.
+ */
+const SESSION_ID = require$$0.randomUUID();
+
+/**
+ * Default telemetry configuration.
+ * Used as fallback if API config fetch fails.
+ */
+const DEFAULT_TELEMETRY_CONFIG = {
+  telemetry: {
+    enabled: false
+  }
+};
+
+/**
+ * Static configuration for telemetry service behavior.
+ */
+const TELEMETRY_SERVICE_CONFIG = {
+  batch_size: 10,
+  // Auto-flush when queue reaches this size.
+  flush_timeout: 2_000 // 2 second maximum for flush operations.
+};
+
+/**
+ * Singleton instance holder.
+ */
+
+/**
+ * Singleton telemetry service instance holder.
+ * Only one instance exists per process.
+ */
+const telemetryServiceInstance = {
+  current: null
+};
+
+/**
+ * Wrap a promise with a timeout.
+ * Rejects if promise doesn't resolve within timeout.
+ *
+ * @param promise Promise to wrap.
+ * @param timeoutMs Timeout in milliseconds.
+ * @param errorMessage Error message if timeout occurs.
+ * @returns Promise that resolves or times out.
+ */
+function withTimeout(promise, timeoutMs, errorMessage) {
+  return Promise.race([promise, new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(errorMessage));
+    }, timeoutMs);
+  })]);
+}
+
+/**
+ * Centralized telemetry service for Socket CLI.
+ * Telemetry is always scoped to an organization.
+ * Singleton pattern ensures only one instance exists per process.
+ *
+ * NOTE: Only one telemetry instance exists per process.
+ * If getTelemetryClient() is called with a different organization slug,
+ * it returns the existing instance for the original organization.
+ * Switching organizations mid-execution is not supported - the first
+ * organization to initialize telemetry will be used for the entire process.
+ *
+ * This is intended, since we can't switch an org during command execution.
+ */
+class TelemetryService {
+  config = null;
+  eventQueue = [];
+  isDestroyed = false;
+
+  /**
+   * Private constructor.
+   * Requires organization slug.
+   *
+   * @param orgSlug - Organization identifier.
+   */
+  constructor(orgSlug) {
+    this.orgSlug = orgSlug;
+    debug$1(`Telemetry service created for org '${orgSlug}' with session ID: ${SESSION_ID}`);
+  }
+
+  /**
+   * Get the current telemetry instance if one exists.
+   * Does not create a new instance.
+   *
+   * @returns Current telemetry instance or null if none exists.
+   */
+  static getCurrentInstance() {
+    return telemetryServiceInstance.current;
+  }
+
+  /**
+   * Get telemetry client for an organization.
+   * Creates and initializes client if it doesn't exist.
+   * Returns existing instance if already initialized.
+   *
+   * @param orgSlug - Organization identifier (required).
+   * @returns Initialized telemetry service instance.
+   */
+  static async getTelemetryClient(orgSlug) {
+    // Return existing instance if already initialized.
+    if (telemetryServiceInstance.current) {
+      debug$1(`Telemetry already initialized for org: ${telemetryServiceInstance.current.orgSlug}`);
+      return telemetryServiceInstance.current;
+    }
+    const instance = new TelemetryService(orgSlug);
+    try {
+      const sdkResult = await setupSdk();
+      if (!sdkResult.ok) {
+        debug$1('Failed to setup SDK for telemetry, using default config');
+        instance.config = DEFAULT_TELEMETRY_CONFIG;
+        telemetryServiceInstance.current = instance;
+        return instance;
+      }
+      const sdk = sdkResult.data;
+      const configResult = await sdk.getOrgTelemetryConfig(orgSlug);
+      if (configResult.success) {
+        instance.config = configResult.data;
+        debug$1(`Telemetry configuration fetched successfully: enabled=${instance.config.telemetry.enabled}`);
+        debugDirWrapper({
+          config: instance.config
+        });
+
+        // Periodic flush will start automatically when first event is tracked.
+      } else {
+        debug$1(`Failed to fetch telemetry config: ${configResult.error}`);
+        instance.config = DEFAULT_TELEMETRY_CONFIG;
+      }
+    } catch (e) {
+      debug$1(`Error initializing telemetry: ${e}`);
+      instance.config = DEFAULT_TELEMETRY_CONFIG;
+    }
+
+    // Only set singleton instance after full initialization.
+    telemetryServiceInstance.current = instance;
+    return instance;
+  }
+
+  /**
+   * Track a telemetry event.
+   * Adds event to queue for batching and eventual submission.
+   * Auto-flushes when batch size is reached.
+   *
+   * @param event - Telemetry event to track (session_id is optional and will be auto-set).
+   */
+  track(event) {
+    debug$1('Incoming track event request');
+    if (this.isDestroyed) {
+      debug$1('Telemetry service destroyed, ignoring event');
+      return;
+    }
+    if (!this.config?.telemetry.enabled) {
+      debug$1(`Telemetry disabled, skipping event: ${event.event_type}`);
+      return;
+    }
+
+    // Create complete event with session_id and org_slug.
+    const completeEvent = {
+      ...event,
+      session_id: SESSION_ID
+    };
+    debug$1(`Tracking telemetry event: ${completeEvent.event_type}`);
+    debugDirWrapper(completeEvent);
+    this.eventQueue.push(completeEvent);
+
+    // Auto-flush if batch size reached.
+    const batchSize = TELEMETRY_SERVICE_CONFIG.batch_size;
+    if (this.eventQueue.length >= batchSize) {
+      debug$1(`Batch size reached (${batchSize}), flushing events`);
+      void this.flush();
+    }
+  }
+
+  /**
+   * Flush all queued events to the API.
+   * Returns immediately if no events queued or telemetry disabled.
+   * Times out after configured flush_timeout to prevent blocking CLI exit.
+   */
+  async flush() {
+    if (this.isDestroyed) {
+      debug$1('Telemetry service destroyed, cannot flush');
+      return;
+    }
+    if (this.eventQueue.length === 0) {
+      return;
+    }
+    if (!this.config?.telemetry.enabled) {
+      debug$1('Telemetry disabled, clearing queue without sending');
+      this.eventQueue = [];
+      return;
+    }
+    const eventsToSend = [...this.eventQueue];
+    this.eventQueue = [];
+    debug$1(`Flushing ${eventsToSend.length} telemetry events`);
+    const flushStartTime = Date.now();
+    try {
+      await withTimeout(this.sendEvents(eventsToSend), TELEMETRY_SERVICE_CONFIG.flush_timeout, `Telemetry flush timed out after ${TELEMETRY_SERVICE_CONFIG.flush_timeout}ms`);
+      const flushDuration = Date.now() - flushStartTime;
+      debug$1(`Telemetry events sent successfully (${eventsToSend.length} events in ${flushDuration}ms)`);
+    } catch (e) {
+      const flushDuration = Date.now() - flushStartTime;
+      const errorMessage = e instanceof Error ? e.message : String(e);
+
+      // Check if this is a timeout error.
+      if (errorMessage.includes('timed out') || flushDuration >= TELEMETRY_SERVICE_CONFIG.flush_timeout) {
+        debug$1(`Telemetry flush timed out after ${TELEMETRY_SERVICE_CONFIG.flush_timeout}ms`);
+        debug$1(`Failed to send ${eventsToSend.length} events due to timeout`);
+      } else {
+        debug$1(`Error flushing telemetry: ${errorMessage}`);
+        debug$1(`Failed to send ${eventsToSend.length} events due to error`);
+      }
+      // Events are discarded on error to prevent infinite growth.
+    }
+  }
+
+  /**
+   * Send events to the API.
+   * Extracted as separate method for timeout wrapping.
+   *
+   * @param events Events to send.
+   */
+  async sendEvents(events) {
+    const sdkResult = await setupSdk();
+    if (!sdkResult.ok) {
+      debug$1('Failed to setup SDK for flush, events discarded');
+      return;
+    }
+    const sdk = sdkResult.data;
+
+    // Track flush statistics.
+    let successCount = 0;
+    let failureCount = 0;
+
+    // Send events in parallel for faster flush.
+    // Use allSettled to ensure all sends are attempted even if some fail.
+    const results = await Promise.allSettled(events.map(async event => {
+      const result = await sdk.postOrgTelemetry(this.orgSlug, event);
+      return {
+        event,
+        result
+      };
+    }));
+
+    // Log results and collect statistics.
+    for (const settledResult of results) {
+      if (settledResult.status === 'fulfilled') {
+        const {
+          event,
+          result
+        } = settledResult.value;
+        if (result.success) {
+          successCount++;
+          debug$1('Telemetry sent to telemetry:');
+          debugDirWrapper(event);
+        } else {
+          failureCount++;
+          debug$1(`Failed to send telemetry event: ${result.error}`);
+        }
+      } else {
+        failureCount++;
+        debug$1(`Telemetry request failed: ${settledResult.reason}`);
+      }
+    }
+
+    // Log flush statistics.
+    debug$1(`Flush stats: ${successCount} succeeded, ${failureCount} failed out of ${events.length} total`);
+  }
+
+  /**
+   * Destroy the telemetry service for this organization.
+   * Flushes remaining events and clears all state.
+   * Idempotent - safe to call multiple times.
+   */
+  async destroy() {
+    if (this.isDestroyed) {
+      debug$1('Telemetry service already destroyed, skipping');
+      return;
+    }
+    debug$1(`Destroying telemetry service for org: ${this.orgSlug}`);
+
+    // Mark as destroyed immediately to prevent concurrent destroy() calls.
+    this.isDestroyed = true;
+
+    // Flush remaining events with timeout.
+    const eventsToFlush = [...this.eventQueue];
+    this.eventQueue = [];
+    if (eventsToFlush.length > 0 && this.config?.telemetry.enabled) {
+      debug$1(`Flushing ${eventsToFlush.length} events before destroy`);
+      const flushStartTime = Date.now();
+      try {
+        await withTimeout(this.sendEvents(eventsToFlush), TELEMETRY_SERVICE_CONFIG.flush_timeout, `Telemetry flush during destroy timed out after ${TELEMETRY_SERVICE_CONFIG.flush_timeout}ms`);
+        const flushDuration = Date.now() - flushStartTime;
+        debug$1(`Events flushed successfully during destroy (${flushDuration}ms)`);
+      } catch (e) {
+        const flushDuration = Date.now() - flushStartTime;
+        const errorMessage = e instanceof Error ? e.message : String(e);
+
+        // Check if this is a timeout error.
+        if (errorMessage.includes('timed out') || flushDuration >= TELEMETRY_SERVICE_CONFIG.flush_timeout) {
+          debug$1(`Telemetry flush during destroy timed out after ${TELEMETRY_SERVICE_CONFIG.flush_timeout}ms`);
+          debug$1(`Failed to send ${eventsToFlush.length} events during destroy due to timeout`);
+        } else {
+          debug$1(`Error flushing telemetry during destroy: ${errorMessage}`);
+          debug$1(`Failed to send ${eventsToFlush.length} events during destroy due to error`);
+        }
+      }
+    }
+    this.config = null;
+
+    // Clear singleton instance.
+    telemetryServiceInstance.current = null;
+    debug$1(`Telemetry service destroyed for org: ${this.orgSlug}`);
+  }
+}
+
+/**
+ * Telemetry integration helpers for Socket CLI.
+ * Provides utilities for tracking common CLI events and subprocess executions.
+ *
+ * Usage:
+ * ```typescript
+ * import {
+ *   setupTelemetryExitHandlers,
+ *   finalizeTelemetry,
+ *   finalizeTelemetrySync,
+ *   trackCliStart,
+ *   trackCliEvent,
+ *   trackCliComplete,
+ *   trackCliError,
+ *   trackSubprocessStart,
+ *   trackSubprocessComplete,
+ *   trackSubprocessError
+ * } from './utils/telemetry/integration.mts'
+ *
+ * // Set up exit handlers once during CLI initialization.
+ * setupTelemetryExitHandlers()
+ *
+ * // Track main CLI execution.
+ * const startTime = await trackCliStart(process.argv)
+ * await trackCliComplete(process.argv, startTime, 0)
+ *
+ * // Track custom event with optional metadata.
+ * await trackCliEvent('custom_event', process.argv, { key: 'value' })
+ *
+ * // Track subprocess/forked CLI execution.
+ * const subStart = await trackSubprocessStart('npm', { cwd: '/path' })
+ * await trackSubprocessComplete('npm', subStart, 0, { stdout_length: 1234 })
+ *
+ * // On subprocess error.
+ * await trackSubprocessError('npm', subStart, error, 1)
+ *
+ * // Manual finalization (usually not needed if exit handlers are set up).
+ * await finalizeTelemetry() // Async version.
+ * finalizeTelemetrySync()    // Sync version (best-effort).
+ * ```
+ */
+/**
+ * Debug wrapper for telemetry integration.
+ */
+const debug = message => {
+  require$$9.debugFn('socket:telemetry:integration', message);
+};
+
+/**
+ * Finalize telemetry and clean up resources (async version).
+ * This should be called before process.exit to ensure telemetry is sent and resources are cleaned up.
+ * Use this in async contexts like beforeExit handlers.
+ *
+ * @returns Promise that resolves when finalization completes.
+ */
+async function finalizeTelemetry() {
+  const instance = TelemetryService.getCurrentInstance();
+  if (instance) {
+    debug('Flushing telemetry');
+    await instance.flush();
+  }
+}
+
+/**
+ * Finalize telemetry synchronously (best-effort).
+ * This triggers a flush without awaiting it.
+ * Use this in synchronous contexts like signal handlers where async operations are not possible.
+ *
+ * Note: This is best-effort only. Events may be lost if the process exits before flush completes.
+ * Prefer finalizeTelemetry() (async version) when possible.
+ */
+function finalizeTelemetrySync() {
+  const instance = TelemetryService.getCurrentInstance();
+  if (instance) {
+    debug('Triggering sync flush (best-effort)');
+    void instance.flush();
+  }
+}
+
+// Track whether exit handlers have been set up to prevent duplicate registration.
+let exitHandlersRegistered = false;
+
+/**
+ * Set up exit handlers for telemetry finalization.
+ * This registers handlers for both normal exits (beforeExit) and common fatal signals.
+ *
+ * Flushing strategy:
+ * - Batch-based: Auto-flush when queue reaches 10 events.
+ * - beforeExit: Async handler for clean shutdowns (when event loop empties).
+ * - Fatal signals (SIGINT, SIGTERM, SIGHUP): Best-effort sync flush.
+ * - Accepts that forced exits (SIGKILL, process.exit()) may lose final events.
+ *
+ * Call this once during CLI initialization to ensure telemetry is flushed on exit.
+ * Safe to call multiple times - only registers handlers once.
+ *
+ * @example
+ * ```typescript
+ * // In src/cli.mts
+ * setupTelemetryExitHandlers()
+ * ```
+ */
+function setupTelemetryExitHandlers() {
+  // Prevent duplicate handler registration.
+  if (exitHandlersRegistered) {
+    debug('Telemetry exit handlers already registered, skipping');
+    return;
+  }
+  exitHandlersRegistered = true;
+
+  // Use beforeExit for async finalization during clean shutdowns.
+  // This fires when the event loop empties but before process actually exits.
+  process$1.on('beforeExit', () => {
+    debug('beforeExit handler triggered');
+    void finalizeTelemetry();
+  });
+
+  // Register handlers for common fatal signals as best-effort fallback.
+  // These are synchronous contexts, so we can only trigger flush without awaiting.
+  const fatalSignals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  for (const signal of fatalSignals) {
+    try {
+      process$1.on(signal, () => {
+        debug(`Signal ${signal} received, attempting sync flush`);
+        finalizeTelemetrySync();
+      });
+    } catch (e) {
+      // Some signals may not be available on all platforms.
+      debug(`Failed to register handler for signal ${signal}: ${e}`);
+    }
+  }
+  debug('Telemetry exit handlers registered (beforeExit + common signals)');
+}
+
+/**
+ * Track subprocess exit and finalize telemetry.
+ * This is a convenience function that tracks completion/error based on exit code
+ * and ensures telemetry is flushed before returning.
+ *
+ * Note: Only tracks subprocess-level events. CLI-level events (cli_complete, cli_error)
+ * are tracked by the main CLI entry point in src/cli.mts.
+ *
+ * @param command - Command name (e.g., 'npm', 'pip').
+ * @param startTime - Start timestamp from trackSubprocessStart.
+ * @param exitCode - Process exit code (null treated as error).
+ * @returns Promise that resolves when tracking and flush complete.
+ *
+ * @example
+ * ```typescript
+ * await trackSubprocessExit(NPM, subprocessStartTime, code)
+ * ```
+ */
+async function trackSubprocessExit(command, startTime, exitCode) {
+  // Track subprocess completion or error based on exit code.
+  if (exitCode !== null && exitCode !== 0) {
+    const error = new Error(`${command} exited with code ${exitCode}`);
+    await trackSubprocessError(command, startTime, error, exitCode);
+  } else if (exitCode === 0) {
+    await trackSubprocessComplete(command, startTime, exitCode);
+  }
+
+  // Flush telemetry to ensure events are sent before exit.
+  await finalizeTelemetry();
+}
+
+// Add other subcommands
+const WRAPPER_CLI = new Set(['bun', 'npm', 'npx', 'pip', 'pnpm', 'vlt', 'yarn']);
+
+// Add other sensitive flags
+const API_TOKEN_FLAGS = new Set(['--api-token', '--token', '-t']);
+
+/**
+ * Calculate duration from start timestamp.
+ *
+ * @param startTime - Start timestamp from Date.now().
+ * @returns Duration in milliseconds.
+ */
+function calculateDuration(startTime) {
+  return Date.now() - startTime;
+}
+
+/**
+ * Normalize exit code to a number with default fallback.
+ *
+ * @param exitCode - Exit code (may be string, number, null, or undefined).
+ * @param defaultValue - Default value if exitCode is not a number.
+ * @returns Normalized exit code.
+ */
+function normalizeExitCode(exitCode, defaultValue) {
+  return typeof exitCode === 'number' ? exitCode : defaultValue;
+}
+
+/**
+ * Normalize error to Error object.
+ *
+ * @param error - Unknown error value.
+ * @returns Error object.
+ */
+function normalizeError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Build context for the current telemetry entry.
+ *
+ * The context contains the current execution context, in which all CLI invocation should have access to.
+ *
+ * @param argv Command line arguments.
+ * @returns Telemetry context object.
+ */
+function buildContext(argv) {
+  return {
+    arch: process$1.arch,
+    argv: sanitizeArgv(argv),
+    node_version: process$1.version,
+    platform: process$1.platform,
+    version: constants.default.ENV.INLINED_SOCKET_CLI_VERSION
+  };
+}
+
+/**
+ * Sanitize argv to remove sensitive information.
+ * Removes API tokens, file paths with usernames, and other PII.
+ * Also strips arguments after wrapper CLIs to avoid leaking package names.
+ *
+ * @param argv Raw command line arguments (full process.argv including execPath and script).
+ * @returns Sanitized argv array.
+ *
+ * @example
+ * // Input: ['node', 'socket', 'npm', 'install', '@my/private-package', '--token', 'sktsec_abc123']
+ * // Output: ['npm', 'install']
+ */
+function sanitizeArgv(argv) {
+  // Strip the first two values to drop the execPath and script.
+  const withoutPathAndScript = argv.slice(2);
+
+  // Then strip arguments after wrapper CLIs to avoid leaking package names.
+  const wrapperIndex = withoutPathAndScript.findIndex(arg => WRAPPER_CLI.has(arg));
+  let strippedArgv = withoutPathAndScript;
+  if (wrapperIndex !== -1) {
+    // Keep only wrapper + first command (e.g., ['npm']).
+    const endIndex = wrapperIndex + 1;
+    strippedArgv = withoutPathAndScript.slice(0, endIndex);
+  }
+
+  // Then sanitize remaining arguments.
+  return strippedArgv.map((arg, index) => {
+    // Check if previous arg was an API token flag.
+    if (index > 0) {
+      const prevArg = strippedArgv[index - 1];
+      if (prevArg && API_TOKEN_FLAGS.has(prevArg)) {
+        return '[REDACTED]';
+      }
+    }
+
+    // Redact anything that looks like a socket API token.
+    if (arg.startsWith('sktsec_') || arg.match(/^[a-f0-9]{32,}$/i)) {
+      return '[REDACTED]';
+    }
+
+    // Remove user home directory from file paths.
+    const homeDir = os.homedir();
+    if (homeDir) {
+      return arg.replace(new RegExp(regexps.escapeRegExp(homeDir), 'g'), '~');
+    }
+    return arg;
+  });
+}
+
+/**
+ * Sanitize error attribute to remove user specific paths.
+ * Replaces user home directory and other sensitive paths.
+ *
+ * @param input Raw input.
+ * @returns Sanitized input.
+ */
+function sanitizeErrorAttribute(input) {
+  if (!input) {
+    return undefined;
+  }
+
+  // Remove user home directory.
+  const homeDir = os.homedir();
+  if (homeDir) {
+    return input.replace(new RegExp(regexps.escapeRegExp(homeDir), 'g'), '~');
+  }
+  return input;
+}
+
+/**
+ * Generic event tracking function.
+ * Tracks any telemetry event with optional error details and explicit flush.
+ *
+ * Events are automatically flushed via batch size or exit handlers.
+ * Use the flush option only when immediate submission is required.
+ *
+ * @param eventType Type of event to track.
+ * @param context Event context.
+ * @param metadata Event metadata.
+ * @param options Optional configuration.
+ * @returns Promise that resolves when tracking completes.
+ */
+async function trackEvent(eventType, context, metadata = {}, options = {}) {
+  // Skip telemetry in test environments.
+  if (constants.default.ENV.VITEST) {
+    return;
+  }
+  try {
+    const orgSlug = getConfigValueOrUndef(constants.CONFIG_KEY_DEFAULT_ORG);
+    if (orgSlug) {
+      const telemetry = await TelemetryService.getTelemetryClient(orgSlug);
+      debug(`Got telemetry service for org: ${orgSlug}`);
+      const event = {
+        context,
+        event_sender_created_at: new Date().toISOString(),
+        event_type: eventType,
+        ...(Object.keys(metadata).length > 0 && {
+          metadata
+        }),
+        ...(options.error && {
+          error: {
+            message: sanitizeErrorAttribute(options.error.message),
+            stack: sanitizeErrorAttribute(options.error.stack),
+            type: options.error.constructor.name
+          }
+        })
+      };
+      telemetry.track(event);
+
+      // Flush events if requested.
+      if (options.flush) {
+        await telemetry.flush();
+      }
+    }
+  } catch (err) {
+    // Telemetry errors should never block CLI execution.
+    debug(`Failed to track event ${eventType}: ${err}`);
+  }
+}
+
+/**
+ * Track CLI initialization event.
+ * Should be called at the start of CLI execution.
+ *
+ * @param argv Command line arguments (process.argv).
+ * @returns Start timestamp for duration calculation.
+ */
+async function trackCliStart(argv) {
+  debug('Capture start of command');
+  const startTime = Date.now();
+  await trackEvent('cli_start', buildContext(argv));
+  return startTime;
+}
+
+/**
+ * Track a generic CLI event with optional metadata.
+ * Use this for tracking custom events during CLI execution.
+ *
+ * @param eventType Type of event to track.
+ * @param argv Command line arguments (process.argv).
+ * @param metadata Optional additional metadata to include with the event.
+ */
+async function trackCliEvent(eventType, argv, metadata) {
+  debug(`Tracking CLI event: ${eventType}`);
+  await trackEvent(eventType, buildContext(argv), metadata);
+}
+
+/**
+ * Track CLI completion event.
+ * Should be called on successful CLI exit.
+ * Flushes immediately since this is typically the last event before process exit.
+ *
+ * @param argv
+ * @param startTime Start timestamp from trackCliStart.
+ * @param exitCode Process exit code (default: 0).
+ */
+async function trackCliComplete(argv, startTime, exitCode) {
+  debug('Capture end of command');
+  await trackEvent('cli_complete', buildContext(argv), {
+    duration: calculateDuration(startTime),
+    exit_code: normalizeExitCode(exitCode, 0)
+  }, {
+    flush: true
+  });
+}
+
+/**
+ * Track CLI error event.
+ * Should be called when CLI exits with an error.
+ * Flushes immediately since this is typically the last event before process exit.
+ *
+ * @param argv
+ * @param startTime Start timestamp from trackCliStart.
+ * @param error Error that occurred.
+ * @param exitCode Process exit code (default: 1).
+ */
+async function trackCliError(argv, startTime, error, exitCode) {
+  debug('Capture error and stack trace of command');
+  await trackEvent('cli_error', buildContext(argv), {
+    duration: calculateDuration(startTime),
+    exit_code: normalizeExitCode(exitCode, 1)
+  }, {
+    error: normalizeError(error),
+    flush: true
+  });
+}
+
+/**
+ * Track subprocess/command start event.
+ *
+ * Use this when spawning external commands like npm, npx, coana, cdxgen, etc.
+ *
+ * @param command Command being executed (e.g., 'npm', 'npx', 'coana').
+ * @param metadata Optional additional metadata (e.g., cwd, purpose).
+ * @returns Start timestamp for duration calculation.
+ */
+async function trackSubprocessStart(command, metadata) {
+  debug(`Tracking subprocess start: ${command}`);
+  const startTime = Date.now();
+  await trackEvent('subprocess_start', buildContext(process$1.argv), {
+    command,
+    ...metadata
+  });
+  return startTime;
+}
+
+/**
+ * Track subprocess/command completion event.
+ *
+ * Should be called when spawned command completes successfully.
+ *
+ * @param command Command that was executed.
+ * @param startTime Start timestamp from trackSubprocessStart.
+ * @param exitCode Process exit code.
+ * @param metadata Optional additional metadata (e.g., stdout length, stderr length).
+ */
+async function trackSubprocessComplete(command, startTime, exitCode, metadata) {
+  debug(`Tracking subprocess complete: ${command}`);
+  await trackEvent('subprocess_complete', buildContext(process$1.argv), {
+    command,
+    duration: calculateDuration(startTime),
+    exit_code: normalizeExitCode(exitCode, 0),
+    ...metadata
+  });
+}
+
+/**
+ * Track subprocess/command error event.
+ *
+ * Should be called when spawned command fails or throws error.
+ *
+ * @param command Command that was executed.
+ * @param startTime Start timestamp from trackSubprocessStart.
+ * @param error Error that occurred.
+ * @param exitCode Process exit code.
+ * @param metadata Optional additional metadata.
+ */
+async function trackSubprocessError(command, startTime, error, exitCode, metadata) {
+  debug(`Tracking subprocess error: ${command}`);
+  await trackEvent('subprocess_error', buildContext(process$1.argv), {
+    command,
+    duration: calculateDuration(startTime),
+    exit_code: normalizeExitCode(exitCode, 1),
+    ...metadata
+  }, {
+    error: normalizeError(error)
+  });
+}
+
 /**
  * Socket SDK utilities for Socket CLI.
  * Manages SDK initialization and configuration for API communication.
@@ -673,17 +1519,54 @@ async function setupSdk(options) {
       version: constants.default.ENV.INLINED_SOCKET_CLI_VERSION,
       homepage: constants.default.ENV.INLINED_SOCKET_CLI_HOMEPAGE
     }),
-    // Add HTTP request hooks for debugging if SOCKET_CLI_DEBUG is enabled.
-    ...(constants.default.ENV.SOCKET_CLI_DEBUG ? {
-      hooks: {
-        onRequest: info => {
+    // Add HTTP request hooks for telemetry and debugging.
+    hooks: {
+      onRequest: info => {
+        // Skip tracking for telemetry submission endpoints to prevent infinite loop.
+        const isTelemetryEndpoint = info.url.includes('/telemetry');
+        if (constants.default.ENV.SOCKET_CLI_DEBUG) {
+          // Debug logging.
           debugApiRequest(info.method, info.url, info.timeout);
-        },
-        onResponse: info => {
+        }
+        if (!isTelemetryEndpoint) {
+          // Track API request event.
+          void trackCliEvent('api_request', process.argv, {
+            method: info.method,
+            timeout: info.timeout,
+            url: info.url
+          });
+        }
+      },
+      onResponse: info => {
+        // Skip tracking for telemetry submission endpoints to prevent infinite loop.
+        const isTelemetryEndpoint = info.url.includes('/telemetry');
+        if (!isTelemetryEndpoint) {
+          // Track API response event.
+          const metadata = {
+            duration: info.duration,
+            method: info.method,
+            status: info.status,
+            statusText: info.statusText,
+            url: info.url
+          };
+          if (info.error) {
+            // Track as error event if request failed.
+            void trackCliEvent('api_error', process.argv, {
+              ...metadata,
+              error_message: info.error.message,
+              error_type: info.error.constructor.name
+            });
+          } else {
+            // Track as successful response.
+            void trackCliEvent('api_response', process.argv, metadata);
+          }
+        }
+        if (constants.default.ENV.SOCKET_CLI_DEBUG) {
+          // Debug logging.
           debugApiResponse(info.method, info.url, info.status, info.error, info.duration, info.headers);
         }
       }
-    } : {})
+    }
   };
   if (constants.default.ENV.SOCKET_CLI_DEBUG) {
     logger.logger.info(`[DEBUG] ${new Date().toISOString()} SDK options: ${JSON.stringify(sdkOptions)}`);
@@ -3460,7 +4343,7 @@ function isYarnBerry() {
  * - Configures environment for third-party tools
  */
 
-const require$2 = require$$5.createRequire((typeof document === 'undefined' ? require$$0.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
+const require$2 = require$$5.createRequire((typeof document === 'undefined' ? require$$0$1.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
 const {
   PACKAGE_LOCK_JSON,
   PNPM_LOCK_YAML,
@@ -4329,10 +5212,11 @@ function isPnpmLockfileScanCommand(command) {
  * - PURL_Type: Package URL type from Socket SDK
  *
  * Supported Ecosystems:
- * - apk, bitbucket, cargo, chrome, cocoapods, composer
+ * - alpm, 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
+ * - maven, mlflow, npm, nuget, oci, pub, pypi, qpkg, rpm
+ * - swift, swid, unknown, vscode
  *
  * Usage:
  * - Validates ecosystem types
@@ -4340,7 +5224,15 @@ function isPnpmLockfileScanCommand(command) {
  * - 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'];
+
+// Temporarily commented out due to dependency version mismatch.
+// SDK has "alpm" but registry's EcosystemString doesn't yet.
+// type MissingInEcosystemString = Exclude<PURL_Type, EcosystemString>
+
+// export type _Check_EcosystemString_has_all_purl_types =
+//   ExpectNever<MissingInEcosystemString>
+
+const ALL_ECOSYSTEMS = ['alpm', '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', 'vscode'];
 new Set(ALL_ECOSYSTEMS);
 function getEcosystemChoicesForMeow() {
   return [...ALL_ECOSYSTEMS];
@@ -5191,7 +6083,7 @@ function isPnpmBinPathShadowed() {
  * - Preserves original binary functionality
  */
 
-const __filename$1 = require$$0.fileURLToPath((typeof document === 'undefined' ? require$$0.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
+const __filename$1 = require$$0$1.fileURLToPath((typeof document === 'undefined' ? require$$0$1.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
 const __dirname$1 = path.dirname(__filename$1);
 async function installNpmLinks(shadowBinPath) {
   // Find npm being shadowed by this process.
@@ -5472,7 +6364,7 @@ class ColorOrMarkdown {
   }
 }
 
-const require$1 = require$$5.createRequire((typeof document === 'undefined' ? require$$0.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
+const require$1 = require$$5.createRequire((typeof document === 'undefined' ? require$$0$1.pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('utils.js', document.baseURI).href)));
 let _translations;
 function getTranslations() {
   if (_translations === undefined) {
@@ -6124,6 +7016,7 @@ exports.fetchGhsaDetails = fetchGhsaDetails;
 exports.fetchOrganization = fetchOrganization;
 exports.fileLink = fileLink;
 exports.filterFlags = filterFlags;
+exports.finalizeTelemetry = finalizeTelemetry;
 exports.findUp = findUp;
 exports.formatErrorWithDetail = formatErrorWithDetail;
 exports.getAlertsMapFromPnpmLockfile = getAlertsMapFromPnpmLockfile;
@@ -6207,6 +7100,7 @@ exports.sendApiRequest = sendApiRequest;
 exports.serializeResultJson = serializeResultJson;
 exports.setGitRemoteGithubRepoUrl = setGitRemoteGithubRepoUrl;
 exports.setupSdk = setupSdk;
+exports.setupTelemetryExitHandlers = setupTelemetryExitHandlers;
 exports.socketDashboardLink = socketDashboardLink;
 exports.socketDevLink = socketDevLink;
 exports.socketDocsLink = socketDocsLink;
@@ -6217,9 +7111,14 @@ exports.spawnSynpDlx = spawnSynpDlx;
 exports.suggestOrgSlug = suggestOrgSlug;
 exports.tildify = tildify;
 exports.toFilterConfig = toFilterConfig;
+exports.trackCliComplete = trackCliComplete;
+exports.trackCliError = trackCliError;
+exports.trackCliStart = trackCliStart;
+exports.trackSubprocessExit = trackSubprocessExit;
+exports.trackSubprocessStart = trackSubprocessStart;
 exports.updateConfigValue = updateConfigValue;
 exports.walkNestedMap = walkNestedMap;
 exports.webLink = webLink;
 exports.writeSocketJson = writeSocketJson;
-//# debugId=16acc98b-82db-4f47-b14e-cc4d4625d581
+//# debugId=a083299b-d999-403d-b54b-00740d629c69
 //# sourceMappingURL=utils.js.map