refactor: use system Node.js with --require for shadow npm

When spawning npm/npx, we now require system Node.js to exist.
Since npm must be installed, Node.js must also exist on the system.
This simplifies the implementation by always using --require flag
with the inject script instead of having a fallback SEA binary path.

Changes:
- Export findSystemNodejs() from spawn-node.mts
- Check for system Node.js in npm-base.mts, error if not found
- Always use --require with getShadowNpmInjectPath()
- Always send IPC handshake with extra field for custom data
- Remove legacy RegistryInternals type and getInternals() function
- Remove IpcObject type from types.mts (now in shadow.mts)

Author: jdalton

packages/cli/src/constants.mts

@@ -248,7 +248,6 @@ import {
   REPORT_LEVEL_WARN,
 } from './constants/reporting.mts'
 import {
-  getInternals,
   getShadowNpmBinPath as SHADOW_getShadowNpmBinPath,
   getShadowNpxBinPath as SHADOW_getShadowNpxBinPath,
   getShadowPnpmBinPath as SHADOW_getShadowPnpmBinPath,
@@ -286,12 +285,9 @@ import { WIN32 } from './constants/types.mts'
 // Export types.
 export type {
   Agent,
-  IpcObject,
   ProcessEnv,
   RegistryEnv,
-  RegistryInternals,
   Remap,
-  Sentry,
   SpawnOptions,
 } from './constants/types.mts'
 
@@ -369,7 +365,6 @@ export {
   getExecPath,
   getGithubCachePath,
   getInstrumentWithSentryPath,
-  getInternals,
   getMinimumVersionByAgent,
   getNmBunPath,
   getNmNodeGypPath,
@@ -621,7 +616,6 @@ export default {
   getExecPath,
   getGithubCachePath,
   getInstrumentWithSentryPath,
-  getInternals,
   getMinimumVersionByAgent,
   getNmBunPath,
   getNmNodeGypPath,

packages/cli/src/constants/shadow.mts

@@ -6,8 +6,6 @@ import path from 'node:path'
 
 import { distPath } from './paths.mts'
 
-import type { RegistryInternals } from './types.mts'
-
 // Re-export SOCKET_IPC_HANDSHAKE from registry
 export { SOCKET_IPC_HANDSHAKE } from '@socketsecurity/lib/constants/socket'
 
@@ -30,14 +28,6 @@ export const SOCKET_CLI_SHADOW_SILENT = 'SOCKET_CLI_SHADOW_SILENT'
 export const SOCKET_CLI_ACCEPT_RISKS = 'SOCKET_CLI_ACCEPT_RISKS'
 export const SOCKET_CLI_VIEW_ALL_RISKS = 'SOCKET_CLI_VIEW_ALL_RISKS'
 
-/**
- * Get registry internals for accessing IPC and Sentry instances.
- */
-export function getInternals(): RegistryInternals {
-  const registry = require('@socketsecurity/registry')
-  return registry.internals ?? {}
-}
-
 /**
  * Get the path to the shadow npm binary.
  */

packages/cli/src/constants/types.mts

@@ -12,24 +12,6 @@ export type { Agent } from '../utils/ecosystem/environment.mjs'
 
 export type RegistryEnv = typeof ENV
 
-export type RegistryInternals = {
-  getIpc?: () => IpcObject | undefined
-  getSentry?: () => Sentry | undefined
-  setSentry?: (sentry: Sentry) => void
-}
-
-export type Sentry = any
-
-export type IpcObject = Readonly<{
-  SOCKET_CLI_FIX?: string | undefined
-  SOCKET_CLI_OPTIMIZE?: boolean | undefined
-  SOCKET_CLI_SHADOW_ACCEPT_RISKS?: boolean | undefined
-  SOCKET_CLI_SHADOW_API_TOKEN?: string | undefined
-  SOCKET_CLI_SHADOW_BIN?: string | undefined
-  SOCKET_CLI_SHADOW_PROGRESS?: boolean | undefined
-  SOCKET_CLI_SHADOW_SILENT?: boolean | undefined
-}>
-
 export type ProcessEnv = {
   [K in keyof typeof ENV]?: string | undefined
 }

packages/cli/src/shadow/npm-base.mts

@@ -21,7 +21,7 @@ import { getOwn } from '@socketsecurity/lib/objects'
 import { normalizePath } from '@socketsecurity/lib/path'
 import { spawnSync } from '@socketsecurity/lib/spawn'
 
-import { spawnNode } from '../utils/spawn/spawn-node.mjs'
+import { findSystemNodejs, spawnNode } from '../utils/spawn/spawn-node.mjs'
 import { NPM, type NPX } from '../constants/agents.mts'
 import { FLAG_LOGLEVEL } from '../constants/cli.mts'
 import ENV from '../constants/env.mts'
@@ -53,7 +53,7 @@ export type ShadowBinOptions = SpawnOptions & {
 }
 
 export type ShadowBinResult = {
-  spawnPromise: SpawnResult
+  spawnPromise: Promise<SpawnResult>
 }
 
 export default async function shadowNpmBase(
@@ -149,11 +149,17 @@ export default async function shadowNpmBase(
     ? await installNpmLinks(shadowBinPath)
     : await installNpxLinks(shadowBinPath)
 
-  // Use spawnNode() to handle SEA bootstrap automatically.
-  // This will:
-  // - Use system Node.js if available (preferred)
-  // - Fall back to self-spawning with IPC handshake (for SEA binaries)
-  // - Handle IPC channel setup and handshake message automatically
+  // If we're forwarding to npm, then npm exists on the system,
+  // which means Node.js must also exist. Use system Node.js with --require.
+  const systemNode = await findSystemNodejs()
+  if (!systemNode) {
+    throw new Error(
+      'System Node.js not found. npm/npx require Node.js to be installed.',
+    )
+  }
+
+  // Use spawnNode() to handle spawning with IPC handshake.
+  // Since we know system Node.js exists, we can always use --require.
   const spawnPromise = spawnNode(
     [
       ...getNodeNoWarningsFlags(),

packages/cli/src/utils/spawn/spawn-node.mts

@@ -36,14 +36,22 @@ export interface SpawnNodeOptions extends SpawnOptions {
   /**
    * Additional IPC handshake data to send to subprocess.
    *
-   * This is merged with bootstrap indicators (subprocess: true, parent_pid)
-   * to create the full IPC handshake message.
+   * This is placed in the `extra` field of the handshake message to avoid
+   * collision with standard fields (subprocess, parent_pid).
+   *
+   * Final handshake structure:
+   * {
+   *   subprocess: true,
+   *   parent_pid: <pid>,
+   *   extra: { ...ipc }  // Custom data goes here
+   * }
    *
    * Use this to pass custom configuration to the subprocess:
    * - Shadow npm/pnpm/yarn settings (API token, bin name, etc.)
    * - Custom application data
    *
-   * Only used when spawning SEA binary as subprocess.
+   * System Node.js will ignore the handshake message.
+   * SEA subprocess will use it to skip bootstrap.
    */
   ipc?: Record<string, unknown>
 }
@@ -71,32 +79,25 @@ export async function spawnNode(
   // Get the Node.js executable path to use.
   const nodePath = await getNodeExecutablePath()
 
-  // Determine if we need to set up IPC handshake.
-  const needsIpcHandshake = isSeaBinary() && nodePath === process.execPath
-
-  // If we need IPC handshake, ensure stdio includes 'ipc'.
-  const finalOptions = needsIpcHandshake
-    ? {
-        ...spawnOpts,
-        stdio: ensureIpcInStdio(spawnOpts.stdio),
-      }
-    : spawnOpts
+  // Always ensure stdio includes 'ipc' for handshake.
+  // System Node.js will ignore the handshake message.
+  // SEA subprocess will use it to skip bootstrap.
+  const finalOptions = {
+    ...spawnOpts,
+    stdio: ensureIpcInStdio(spawnOpts.stdio),
+  }
 
   // Spawn the Node.js process.
   const spawnResult = spawn(nodePath, args, finalOptions, extra)
 
-  // If we're spawning ourselves as a SEA subprocess, send IPC handshake.
-  if (needsIpcHandshake) {
-    // Build IPC handshake with bootstrap indicators + custom data.
-    const handshakeData = {
-      // Bootstrap indicators - always included for subprocess detection.
-      subprocess: true,
-      parent_pid: process.pid,
-      // Custom IPC data (shadow config, application data, etc.).
-      ...(ipc ?? {}),
-    }
-    sendBootstrapHandshake(spawnResult.process, handshakeData)
+  // Always send IPC handshake with bootstrap indicators + custom data.
+  const handshakeData = {
+    subprocess: true,
+    parent_pid: process.pid,
+    // Custom IPC data in extra field to avoid collision with standard fields.
+    ...(ipc ? { extra: { ...ipc } } : {}),
   }
+  sendBootstrapHandshake(spawnResult.process, handshakeData)
 
   return spawnResult
 }
@@ -133,7 +134,7 @@ async function getNodeExecutablePath(): Promise<string> {
  *
  * @returns Path to system Node.js, or undefined
  */
-async function findSystemNodejs(): Promise<string | undefined> {
+export async function findSystemNodejs(): Promise<string | undefined> {
   // Use which to find 'node' in PATH (returns all matches).
   const nodePath = await which('node', { all: true, nothrow: true })