feat(telemetry): adding initial telemetry functionality to the cli (#956)

* feat(telemetry): adding initial telemetry functionality to the cli

* feat(cr): cr

---------

Co-authored-by: John-David Dalton <jdalton@users.noreply.github.com>

Author: billxinli

package.json

@@ -122,7 +122,7 @@
     "@socketregistry/packageurl-js": "1.0.9",
     "@socketsecurity/config": "3.0.1",
     "@socketsecurity/registry": "1.1.17",
-    "@socketsecurity/sdk": "1.4.94",
+    "@socketsecurity/sdk": "1.4.95",
     "@types/blessed": "0.1.25",
     "@types/cmd-shim": "5.0.2",
     "@types/js-yaml": "4.0.9",

pnpm-lock.yaml

@@ -18,11 +18,27 @@ import { AuthError, InputError, captureException } from './utils/errors.mts'
 import { failMsgWithBadge } from './utils/fail-msg-with-badge.mts'
 import { meowWithSubcommands } from './utils/meow-with-subcommands.mts'
 import { serializeResultJson } from './utils/serialize-result-json.mts'
+import {
+  finalizeTelemetry,
+  setupTelemetryExitHandlers,
+  trackCliComplete,
+  trackCliError,
+  trackCliStart,
+} from './utils/telemetry/integration.mts'
 import { socketPackageLink } from './utils/terminal-link.mts'
 
 const __filename = fileURLToPath(import.meta.url)
 
+// Capture CLI start time at module level for global error handlers.
+const cliStartTime = Date.now()
+
+// Set up telemetry exit handlers early to catch all exit scenarios.
+setupTelemetryExitHandlers()
+
 void (async () => {
+  // Track CLI start for telemetry.
+  await trackCliStart(process.argv)
+
   const registryUrl = lookupRegistryUrl()
   await updateNotifier({
     authInfo: lookupRegistryAuthToken(registryUrl, { recursive: true }),
@@ -50,8 +66,14 @@ void (async () => {
       },
       { aliases: rootAliases },
     )
+
+    // Track successful CLI completion.
+    await trackCliComplete(process.argv, cliStartTime, process.exitCode)
   } catch (e) {
     process.exitCode = 1
+
+    // Track CLI error for telemetry.
+    await trackCliError(process.argv, cliStartTime, e, process.exitCode)
     debugFn('error', 'CLI uncaught error')
     debugDir('error', e)
 
@@ -105,4 +127,45 @@ void (async () => {
 
     await captureException(e)
   }
-})()
+})().catch(async err => {
+  // Fatal error in main async function.
+  console.error('Fatal error:', err)
+
+  // Track CLI error for fatal exceptions.
+  await trackCliError(process.argv, cliStartTime, err, 1)
+
+  // Finalize telemetry before fatal exit.
+  await finalizeTelemetry()
+
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(1)
+})
+
+// Handle uncaught exceptions.
+process.on('uncaughtException', async err => {
+  console.error('Uncaught exception:', err)
+
+  // Track CLI error for uncaught exception.
+  await trackCliError(process.argv, cliStartTime, err, 1)
+
+  // Finalize telemetry before exit.
+  await finalizeTelemetry()
+
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(1)
+})
+
+// Handle unhandled promise rejections.
+process.on('unhandledRejection', async (reason, promise) => {
+  console.error('Unhandled rejection at:', promise, 'reason:', reason)
+
+  // Track CLI error for unhandled rejection.
+  const error = reason instanceof Error ? reason : new Error(String(reason))
+  await trackCliError(process.argv, cliStartTime, error, 1)
+
+  // Finalize telemetry before exit.
+  await finalizeTelemetry()
+
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(1)
+})

src/cli.mts

@@ -12,6 +12,10 @@ import { commonFlags, outputFlags } from '../../flags.mts'
 import { filterFlags } from '../../utils/cmd.mts'
 import { meowOrExit } from '../../utils/meow-with-subcommands.mts'
 import { getFlagApiRequirementsOutput } from '../../utils/output-formatting.mts'
+import {
+  trackSubprocessExit,
+  trackSubprocessStart,
+} from '../../utils/telemetry/integration.mts'
 
 import type {
   CliCommandConfig,
@@ -86,20 +90,29 @@ async function run(
   const argsToForward = filterFlags(argv, { ...commonFlags, ...outputFlags }, [
     FLAG_JSON,
   ])
+
+  // Track subprocess start.
+  const subprocessStartTime = await trackSubprocessStart(NPM)
+
   const { spawnPromise } = await shadowNpmBin(argsToForward, {
     stdio: 'inherit',
   })
 
+  // Handle exit codes and signals using event-based pattern.
   // See https://nodejs.org/api/child_process.html#event-exit.
   spawnPromise.process.on(
     'exit',
-    (code: string | null, signalName: NodeJS.Signals | null) => {
-      if (signalName) {
-        process.kill(process.pid, signalName)
-      } else if (typeof code === 'number') {
-        // eslint-disable-next-line n/no-process-exit
-        process.exit(code)
-      }
+    (code: number | null, signalName: NodeJS.Signals | null) => {
+      // Track subprocess exit and flush telemetry before exiting.
+      // Use .then() to ensure telemetry completes before process.exit().
+      void trackSubprocessExit(NPM, subprocessStartTime, code).then(() => {
+        if (signalName) {
+          process.kill(process.pid, signalName)
+        } else if (typeof code === 'number') {
+          // eslint-disable-next-line n/no-process-exit
+          process.exit(code)
+        }
+      })
     },
   )
 

src/commands/npm/cmd-npm.mts

@@ -6,6 +6,10 @@ import constants, { FLAG_DRY_RUN, FLAG_HELP, NPX } from '../../constants.mts'
 import { commonFlags } from '../../flags.mts'
 import { meowOrExit } from '../../utils/meow-with-subcommands.mts'
 import { getFlagApiRequirementsOutput } from '../../utils/output-formatting.mts'
+import {
+  trackSubprocessExit,
+  trackSubprocessStart,
+} from '../../utils/telemetry/integration.mts'
 
 import type {
   CliCommandConfig,
@@ -74,18 +78,26 @@ async function run(
 
   process.exitCode = 1
 
+  // Track subprocess start.
+  const subprocessStartTime = await trackSubprocessStart(NPX)
+
   const { spawnPromise } = await shadowNpxBin(argv, { stdio: 'inherit' })
 
+  // Handle exit codes and signals using event-based pattern.
   // See https://nodejs.org/api/child_process.html#event-exit.
   spawnPromise.process.on(
     'exit',
-    (code: string | null, signalName: NodeJS.Signals | null) => {
-      if (signalName) {
-        process.kill(process.pid, signalName)
-      } else if (typeof code === 'number') {
-        // eslint-disable-next-line n/no-process-exit
-        process.exit(code)
-      }
+    (code: number | null, signalName: NodeJS.Signals | null) => {
+      // Track subprocess exit and flush telemetry before exiting.
+      // Use .then() to ensure telemetry completes before process.exit().
+      void trackSubprocessExit(NPX, subprocessStartTime, code).then(() => {
+        if (signalName) {
+          process.kill(process.pid, signalName)
+        } else if (typeof code === 'number') {
+          // eslint-disable-next-line n/no-process-exit
+          process.exit(code)
+        }
+      })
     },
   )
 

src/commands/npx/cmd-npx.mts

@@ -7,6 +7,10 @@ import { commonFlags } from '../../flags.mts'
 import { filterFlags } from '../../utils/cmd.mts'
 import { meowOrExit } from '../../utils/meow-with-subcommands.mts'
 import { getFlagApiRequirementsOutput } from '../../utils/output-formatting.mts'
+import {
+  trackSubprocessExit,
+  trackSubprocessStart,
+} from '../../utils/telemetry/integration.mts'
 
 import type {
   CliCommandConfig,
@@ -81,10 +85,30 @@ async function run(
   // Filter Socket flags from argv.
   const filteredArgv = filterFlags(argv, config.flags)
 
+  // Track subprocess start.
+  const subprocessStartTime = await trackSubprocessStart(PNPM)
+
   const { spawnPromise } = await shadowPnpmBin(filteredArgv, {
     stdio: 'inherit',
   })
 
+  // Handle exit codes and signals using event-based pattern.
+  // See https://nodejs.org/api/child_process.html#event-exit.
+  spawnPromise.process.on(
+    'exit',
+    (code: number | null, signalName: NodeJS.Signals | null) => {
+      // Track subprocess exit and flush telemetry before exiting.
+      // Use .then() to ensure telemetry completes before process.exit().
+      void trackSubprocessExit(PNPM, subprocessStartTime, code).then(() => {
+        if (signalName) {
+          process.kill(process.pid, signalName)
+        } else if (typeof code === 'number') {
+          // eslint-disable-next-line n/no-process-exit
+          process.exit(code)
+        }
+      })
+    },
+  )
+
   await spawnPromise
-  process.exitCode = 0
 }

src/commands/pnpm/cmd-pnpm.mts

@@ -7,6 +7,10 @@ import { commonFlags } from '../../flags.mts'
 import { filterFlags } from '../../utils/cmd.mts'
 import { meowOrExit } from '../../utils/meow-with-subcommands.mts'
 import { getFlagApiRequirementsOutput } from '../../utils/output-formatting.mts'
+import {
+  trackSubprocessExit,
+  trackSubprocessStart,
+} from '../../utils/telemetry/integration.mts'
 
 import type {
   CliCommandConfig,
@@ -81,10 +85,32 @@ async function run(
   // Filter Socket flags from argv.
   const filteredArgv = filterFlags(argv, config.flags)
 
+  // Track subprocess start.
+  const subprocessStartTime = await trackSubprocessStart(YARN)
+
   const { spawnPromise } = await shadowYarnBin(filteredArgv, {
     stdio: 'inherit',
   })
 
+  // Handle exit codes and signals using event-based pattern.
+  // See https://nodejs.org/api/child_process.html#event-exit.
+  spawnPromise.process.on(
+    'exit',
+    (code: number | null, signalName: NodeJS.Signals | null) => {
+      // Track subprocess exit and flush telemetry before exiting.
+      // Use .then() to ensure telemetry completes before process.exit().
+      void trackSubprocessExit(YARN, subprocessStartTime, code).then(() => {
+        if (signalName) {
+          process.kill(process.pid, signalName)
+        } else if (typeof code === 'number') {
+          // eslint-disable-next-line n/no-process-exit
+          process.exit(code)
+        }
+      })
+    },
+  )
+
   await spawnPromise
+
   process.exitCode = 0
 }