fix(sfw): use separate versions for SEA and npm CLI distributions

- SEA builds use GitHub binary from SocketDev/sfw-free (v1.6.1)
- npm CLI uses npm package sfw (2.0.4) which downloads binary on demand
- Rename 'version' to 'githubRelease' for github-release type tools
- Add 'npmVersion' field for sfw npm package version
- Update environment-variables, vfs-extract, and resolve-binary accordingly

Author: jdalton

packages/cli/external-tools.json

@@ -1,6 +1,6 @@
 {
   "$schema": "External tools configuration for Socket CLI VFS bundling",
-  "$comment": "Build process uses @npmcli/arborist (scripts/sea-build-utils/npm-packages.mjs) to download npm packages with full dependency trees. npm packages are bundled with node_modules/ into VFS alongside security tool binaries.",
+  "$comment": "Build process uses @npmcli/arborist (scripts/sea-build-utils/npm-packages.mjs) to download npm packages with full dependency trees. npm packages are bundled with node_modules/ into VFS alongside security tool binaries. For github-release types, 'githubRelease' is the release tag (any format: v1.6.1, 3.11.14, etc.).",
   "@coana-tech/cli": {
     "description": "Coana CLI for static analysis and reachability detection",
     "type": "npm",
@@ -17,13 +17,13 @@
     "description": "OpenGrep SAST/code analysis engine (fork of Semgrep)",
     "type": "github-release",
     "repository": "opengrep/opengrep",
-    "version": "v1.16.0"
+    "githubRelease": "v1.16.0"
   },
   "python": {
     "description": "Python runtime from python-build-standalone",
     "type": "github-release",
     "repository": "astral-sh/python-build-standalone",
-    "version": "3.11.14",
+    "githubRelease": "3.11.14",
     "buildTag": "20260203"
   },
   "socket-basics": {
@@ -42,13 +42,15 @@
     "description": "Socket Patch CLI for applying security patches (Rust binary)",
     "type": "github-release",
     "repository": "SocketDev/socket-patch",
-    "version": "v2.0.0"
+    "githubRelease": "v2.0.0"
   },
   "sfw": {
-    "description": "Socket Firewall (sfw)",
+    "description": "Socket Firewall (sfw) - GitHub binary for SEA, npm package for CLI",
     "type": "github-release",
     "repository": "SocketDev/sfw-free",
-    "version": "v1.6.0"
+    "githubRelease": "v1.6.1",
+    "npmPackage": "sfw",
+    "npmVersion": "2.0.4"
   },
   "synp": {
     "description": "Tool for converting between yarn.lock and package-lock.json",
@@ -60,12 +62,12 @@
     "description": "Trivy container and filesystem vulnerability scanner",
     "type": "github-release",
     "repository": "aquasecurity/trivy",
-    "version": "v0.69.2"
+    "githubRelease": "v0.69.2"
   },
   "trufflehog": {
     "description": "TruffleHog secret and credential detection",
     "type": "github-release",
     "repository": "trufflesecurity/trufflehog",
-    "version": "v3.93.1"
+    "githubRelease": "v3.93.1"
   }
 }

packages/cli/scripts/environment-variables.mjs

@@ -80,17 +80,22 @@ export class EnvironmentVariables {
       return value
     }
 
+    // npm packages use 'version' field.
     const cdxgenVersion = getExternalToolVersion('@cyclonedx/cdxgen')
     const coanaVersion = getExternalToolVersion('@coana-tech/cli')
-    const opengrepVersion = getExternalToolVersion('opengrep')
+    const synpVersion = getExternalToolVersion('synp')
+    // pypi packages use 'version' field.
     const pyCliVersion = getExternalToolVersion('socketsecurity')
+    // github-release tools use 'githubRelease' field (release tag, any format).
+    const opengrepVersion = getExternalToolVersion('opengrep', 'githubRelease')
     const pythonBuildTag = getExternalToolVersion('python', 'buildTag')
-    const pythonVersion = getExternalToolVersion('python')
-    const sfwVersion = getExternalToolVersion('sfw')
-    const socketPatchVersion = getExternalToolVersion('socket-patch')
-    const synpVersion = getExternalToolVersion('synp')
-    const trivyVersion = getExternalToolVersion('trivy')
-    const trufflehogVersion = getExternalToolVersion('trufflehog')
+    const pythonVersion = getExternalToolVersion('python', 'githubRelease')
+    const socketPatchVersion = getExternalToolVersion('socket-patch', 'githubRelease')
+    const trivyVersion = getExternalToolVersion('trivy', 'githubRelease')
+    const trufflehogVersion = getExternalToolVersion('trufflehog', 'githubRelease')
+    // sfw uses both: GitHub binary for SEA, npm package for CLI.
+    const sfwVersion = getExternalToolVersion('sfw', 'githubRelease')
+    const sfwNpmVersion = getExternalToolVersion('sfw', 'npmVersion')
 
     // Build-time constants that can be overridden by environment variables.
     const publishedBuild =
@@ -116,6 +121,7 @@ export class EnvironmentVariables {
       INLINED_SOCKET_CLI_PYTHON_BUILD_TAG: pythonBuildTag,
       INLINED_SOCKET_CLI_PYTHON_VERSION: pythonVersion,
       INLINED_SOCKET_CLI_SENTRY_BUILD: sentryBuild ? '1' : '',
+      INLINED_SOCKET_CLI_SFW_NPM_VERSION: sfwNpmVersion,
       INLINED_SOCKET_CLI_SFW_VERSION: sfwVersion,
       INLINED_SOCKET_CLI_SOCKET_PATCH_VERSION: socketPatchVersion,
       INLINED_SOCKET_CLI_SYNP_VERSION: synpVersion,
@@ -142,9 +148,10 @@ export class EnvironmentVariables {
           externalTools['@coana-tech/cli']?.version || '',
         INLINED_SOCKET_CLI_PYCLI_VERSION:
           externalTools.socketsecurity?.version || '',
-        INLINED_SOCKET_CLI_SFW_VERSION: externalTools.sfw?.version || '',
+        INLINED_SOCKET_CLI_SFW_NPM_VERSION: externalTools.sfw?.npmVersion || '',
+        INLINED_SOCKET_CLI_SFW_VERSION: externalTools.sfw?.githubRelease || '',
         INLINED_SOCKET_CLI_SOCKET_PATCH_VERSION:
-          externalTools['socket-patch']?.version || '',
+          externalTools['socket-patch']?.githubRelease || '',
       }
     } catch {
       return {}

packages/cli/scripts/sea-build-utils/downloads.mjs

@@ -271,9 +271,11 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
       TOOL_REPOS[toolName] = {
         owner,
         repo,
-        // Python uses buildTag for version, others use version field.
+        // Python uses buildTag for release tag, others use githubRelease field.
         version:
-          toolName === 'python' ? toolConfig.buildTag : toolConfig.version,
+          toolName === 'python'
+            ? toolConfig.buildTag
+            : toolConfig.githubRelease,
       }
     }
   }
@@ -321,8 +323,8 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
     const archivePath = normalizePath(path.join(toolsDir, assetName))
 
     // Download archive directly from GitHub releases.
-    // Python uses date-based tags without 'v' prefix.
-    const tag = toolName === 'python' ? config.version : config.version
+    // Release tags can be any format (v1.6.1, 3.11.14, 20260203, etc.).
+    const tag = config.version
     const url = `https://github.com/${config.owner}/${config.repo}/releases/download/${tag}/${assetName}`
     await httpDownload(url, archivePath, {
       logger,
@@ -337,11 +339,11 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
     const isStandalone = !isZip && !isTarGz
 
     if (isStandalone) {
-      // Standalone binary (e.g., sfw) - create node_modules structure for VFS compatibility.
+      // Standalone binary - create node_modules structure for VFS compatibility.
       // node-smol VFS requires all files to be under node_modules/ for security.
       logger.log(`  Preparing ${toolName}...`)
 
-      // Create node_modules/@socketsecurity/sfw-bin/ structure.
+      // Create node_modules/@socketsecurity/{toolName}-bin/ structure.
       const packageDir = normalizePath(
         path.join(
           toolsDir,

packages/cli/src/env/sfw-version.mts

@@ -1,13 +1,20 @@
 /**
- * Socket Firewall (sfw) version getter function.
+ * Socket Firewall (sfw) version getter functions.
  * Uses direct process.env access so esbuild define can inline values.
  * IMPORTANT: esbuild's define plugin can only replace direct process.env['KEY'] references.
  * If we imported from env modules, esbuild couldn't inline the values at build time.
  * This is critical for embedding version info into the binary.
+ *
+ * sfw uses two different distributions:
+ * - GitHub binary (SocketDev/sfw-free): Used for SEA builds, version like "v1.6.1"
+ * - npm package (sfw): Used for CLI dlx, version like "2.0.4"
  */
 
 import process from 'node:process'
 
+/**
+ * Get the GitHub release version for sfw (used in SEA builds).
+ */
 export function getSwfVersion(): string {
   const version = process.env['INLINED_SOCKET_CLI_SFW_VERSION']
   if (!version) {
@@ -17,3 +24,16 @@ export function getSwfVersion(): string {
   }
   return version
 }
+
+/**
+ * Get the npm package version for sfw (used in CLI dlx).
+ */
+export function getSfwNpmVersion(): string {
+  const version = process.env['INLINED_SOCKET_CLI_SFW_NPM_VERSION']
+  if (!version) {
+    throw new Error(
+      'INLINED_SOCKET_CLI_SFW_NPM_VERSION not found. Please ensure sfw npmVersion is configured in external-tools.json.',
+    )
+  }
+  return version
+}

packages/cli/src/utils/dlx/resolve-binary.mts

@@ -12,7 +12,7 @@ import { SOCKET_CLI_COANA_LOCAL_PATH } from '../../env/socket-cli-coana-local-pa
 import { SOCKET_CLI_PYCLI_LOCAL_PATH } from '../../env/socket-cli-pycli-local-path.mts'
 import { SOCKET_CLI_SFW_LOCAL_PATH } from '../../env/socket-cli-sfw-local-path.mts'
 import { SOCKET_CLI_SOCKET_PATCH_LOCAL_PATH } from '../../env/socket-cli-socket-patch-local-path.mts'
-import { getSwfVersion } from '../../env/sfw-version.mts'
+import { getSfwNpmVersion } from '../../env/sfw-version.mts'
 import { getSocketPatchVersion } from '../../env/socket-patch-version.mts'
 import { getSynpVersion } from '../../env/synp-version.mts'
 
@@ -94,6 +94,9 @@ export function resolvePyCli(): BinaryResolution | { type: 'python' } {
 /**
  * Resolve path for Socket Firewall (sfw) binary.
  * Checks SOCKET_CLI_SFW_LOCAL_PATH environment variable first.
+ *
+ * Note: This returns the npm package version for dlx usage.
+ * SEA builds use the GitHub binary directly via VFS extraction.
  */
 export function resolveSfw(): BinaryResolution {
   if (SOCKET_CLI_SFW_LOCAL_PATH) {
@@ -104,7 +107,7 @@ export function resolveSfw(): BinaryResolution {
     type: 'dlx',
     details: {
       name: 'sfw',
-      version: getSwfVersion(),
+      version: getSfwNpmVersion(),
       binaryName: 'sfw',
     },
   }

packages/cli/src/utils/dlx/vfs-extract.mts

@@ -29,7 +29,6 @@
  * ```
  *
  * VFS structure in SEA binaries:
- *   sfw                               # Standalone binary from GitHub release
  *   socket-patch                      # Standalone Rust binary from GitHub release
  *   node_modules/
  *     ├── @cyclonedx/cdxgen/        # Full package with dependencies
@@ -40,6 +39,8 @@
  *     │   ├── bin/coana
  *     │   ├── package.json
  *     │   └── node_modules/
+ *     ├── @socketsecurity/sfw-bin/  # Standalone binary from GitHub release
+ *     │   └── sfw
  *     └── synp/
  *         ├── bin/synp
  *         ├── package.json
@@ -89,7 +90,7 @@ export type ExternalTool = (typeof EXTERNAL_TOOLS)[number]
 
 // Map of npm package tools to their node_modules/ paths.
 // These are full npm packages with dependencies and node_modules/ subdirectories.
-// Standalone binaries (like sfw) are NOT in this map - they use direct file paths.
+// Note: sfw uses GitHub binary for SEA (standalone), npm package for CLI (dlx).
 const TOOL_NPM_PATHS: Partial<
   Record<ExternalTool, { packageName: string; binPath: string }>
 > = {
@@ -109,8 +110,10 @@ const TOOL_NPM_PATHS: Partial<
 
 // Map of standalone binary tools to their VFS paths.
 // These tools are single binaries from GitHub releases without npm dependencies.
-// sfw is stored under node_modules/ for VFS structure, socket-patch is at root level.
+// sfw is stored under node_modules/@socketsecurity/sfw-bin/ for VFS structure.
 const TOOL_STANDALONE_PATHS: Partial<Record<ExternalTool, string>> = {
+  // sfw is a standalone binary from GitHub releases (SocketDev/sfw-free).
+  // Note: npm CLI uses the sfw npm package via dlx instead.
   sfw: 'node_modules/@socketsecurity/sfw-bin/sfw',
   // socket-patch is a Rust binary downloaded from GitHub releases.
   // As of v2.0.0, it's bundled directly (not as an npm package).
@@ -145,7 +148,6 @@ function getToolFilePath(tool: ExternalTool, nodeSmolBase: string): string {
  * Structure:
  * ~/.socket/_dlx/<node-smol-hash>/
  *   ├── node/node                    # Node binary
- *   ├── sfw                          # Standalone binary (GitHub release)
  *   ├── socket-patch                 # Standalone Rust binary (GitHub release)
  *   └── node_modules/                # npm packages with dependencies
  *       ├── @cyclonedx/cdxgen/
@@ -154,6 +156,8 @@ function getToolFilePath(tool: ExternalTool, nodeSmolBase: string): string {
  *       ├── @coana-tech/cli/
  *       │   ├── bin/coana
  *       │   └── node_modules/
+ *       ├── @socketsecurity/sfw-bin/ # Standalone sfw binary (GitHub release)
+ *       │   └── sfw
  *       └── synp/
  *           ├── bin/synp
  *           └── node_modules/
@@ -659,7 +663,7 @@ export async function extractExternalTools(
  *
  * @example
  * const paths = getToolPaths()
- * logger.log('sfw:', paths.sfw)  // ~/.socket/_dlx/<hash>/sfw
+ * logger.log('sfw:', paths.sfw)  // ~/.socket/_dlx/<hash>/node_modules/@socketsecurity/sfw-bin/sfw
  * logger.log('cdxgen:', paths.cdxgen)  // ~/.socket/_dlx/<hash>/node_modules/@cyclonedx/cdxgen/bin/cdxgen
  */
 export function getToolPaths(): Record<ExternalTool, string> {

packages/cli/test/setup.mts

@@ -18,6 +18,7 @@ if (existsSync(externalToolsPath)) {
     const externalTools = JSON.parse(readFileSync(externalToolsPath, 'utf8'))
 
     // Set inlined environment variables if not already set.
+    // npm packages use 'version', github-release uses 'githubRelease', pypi uses 'version'.
     const toolVersions: Record<string, string | undefined> = {
       INLINED_SOCKET_CLI_CDXGEN_VERSION:
         externalTools['@cyclonedx/cdxgen']?.version,
@@ -27,20 +28,23 @@ if (existsSync(externalToolsPath)) {
         externalTools['@cyclonedx/cdxgen']?.version,
       INLINED_SOCKET_CLI_HOMEPAGE: 'https://github.com/SocketDev/socket-cli',
       INLINED_SOCKET_CLI_NAME: '@socketsecurity/cli',
-      INLINED_SOCKET_CLI_OPENGREP_VERSION: externalTools['opengrep']?.version,
+      INLINED_SOCKET_CLI_OPENGREP_VERSION:
+        externalTools['opengrep']?.githubRelease,
       INLINED_SOCKET_CLI_PUBLISHED_BUILD: '',
       INLINED_SOCKET_CLI_PYCLI_VERSION:
         externalTools['socketsecurity']?.version,
       INLINED_SOCKET_CLI_PYTHON_BUILD_TAG: externalTools['python']?.buildTag,
-      INLINED_SOCKET_CLI_PYTHON_VERSION: externalTools['python']?.version,
+      INLINED_SOCKET_CLI_PYTHON_VERSION:
+        externalTools['python']?.githubRelease,
       INLINED_SOCKET_CLI_SENTRY_BUILD: '',
-      INLINED_SOCKET_CLI_SFW_VERSION: externalTools['sfw']?.version,
+      INLINED_SOCKET_CLI_SFW_NPM_VERSION: externalTools['sfw']?.npmVersion,
+      INLINED_SOCKET_CLI_SFW_VERSION: externalTools['sfw']?.githubRelease,
       INLINED_SOCKET_CLI_SOCKET_PATCH_VERSION:
-        externalTools['socket-patch']?.version,
+        externalTools['socket-patch']?.githubRelease,
       INLINED_SOCKET_CLI_SYNP_VERSION: externalTools['synp']?.version,
-      INLINED_SOCKET_CLI_TRIVY_VERSION: externalTools['trivy']?.version,
+      INLINED_SOCKET_CLI_TRIVY_VERSION: externalTools['trivy']?.githubRelease,
       INLINED_SOCKET_CLI_TRUFFLEHOG_VERSION:
-        externalTools['trufflehog']?.version,
+        externalTools['trufflehog']?.githubRelease,
       INLINED_SOCKET_CLI_VERSION: '0.0.0-test',
       INLINED_SOCKET_CLI_VERSION_HASH: '0.0.0-test:abc1234:test',
     }

packages/cli/test/unit/utils/dlx/resolve-binary.test.mts

@@ -174,7 +174,7 @@ describe('resolve-binary', () => {
         SOCKET_CLI_SFW_LOCAL_PATH: undefined,
       }))
       vi.doMock('../../../../src/env/sfw-version.mts', () => ({
-        getSwfVersion: () => '2.0.0',
+        getSfwNpmVersion: () => '2.0.0',
       }))
 
       const { resolveSfw } =