feat(coana): add npm-install + node fallback when dlx fails

[Martin Torp (mtorp)]

Summary

• When npx --yes @coana-tech/cli ... (or the equivalent pnpm dlx / yarn dlx) aborts before Coana itself starts, the Socket CLI now retries by installing @coana-tech/cli into a temp directory via npm install and invoking it directly through node. The registry, npm, and node all work normally in the environments that hit this — only the dlx-driven launch is broken.
• All three Coana call sites (socket scan reach, socket fix discovery, socket fix per-GHSA loop) inherit the fallback transparently — the change is isolated to spawnCoanaDlx in src/utils/dlx.mts.
• Installed copies are cached per-version on a module-level Map for the lifetime of the process, so PR mode (which calls Coana once per GHSA) only pays the install cost once.

Env vars

For support/debugging only — not documented in CHANGELOG:

• SOCKET_CLI_COANA_FORCE_NPM_INSTALL=1 — skip dlx, go straight to the install path. Useful for validating the fallback end-to-end without needing dlx to actually fail.
• SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK=1 — disable the fallback and restore the previous behavior of returning the dlx error directly.

Test plan

• pnpm check:tsc — clean
• pnpm check:lint — clean
• pnpm test:unit src/utils/dlx.test.mts — 11/11 pass (added 5 new tests covering: fallback fires on dlx error, install caching across calls, DISABLE env skips fallback, FORCE env skips dlx, both errors surface when install also fails)
• pnpm test:unit for the 4 Coana-caller test files (handle-scan-reach, exclude-paths, handle-create-new-scan, handle-fix-limit) — 47/47 pass
• Manual smoke: SOCKET_CLI_COANA_FORCE_NPM_INSTALL=1 socket scan reach <project> against a small npm project — observed npm install of @coana-tech/cli@15.3.4 into a socket-coana-* tmpdir, followed by Coana running via node and completing the reachability analysis successfully (.socket.facts.json written, expected vuln counts produced).

---

Note

Medium Risk
Adds a new execution path that installs and runs @coana-tech/cli via npm install+node, which changes runtime behavior and introduces new failure/perf modes in environments where dlx is flaky.

Overview
spawnCoanaDlx now retries Coana execution when npx/pnpm dlx/yarn dlx fails by installing @coana-tech/cli into a temp dir via npm install and running it via node, caching the resolved CLI entrypoint per version for the lifetime of the process.

Adds support/debug env toggles to force the npm-install path (SOCKET_CLI_COANA_FORCE_NPM_INSTALL) or disable the fallback (SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK), improves error reporting by surfacing both dlx and fallback failures, and adds unit tests covering fallback behavior and caching.

^{Reviewed by Cursor Bugbot for commit 1549f69. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Uncaught node spawn errors
  • Wrapped the npm-install fallback Coana node spawn in the existing CResult error conversion and added a regression test for fallback node spawn failures.

Or push these changes by commenting:

@cursor push af5c8f716d

Preview (af5c8f716d)

diff --git a/src/utils/dlx.mts b/src/utils/dlx.mts
--- a/src/utils/dlx.mts
+++ b/src/utils/dlx.mts
@@ -316,13 +316,17 @@
       message: `npm install fallback failed: ${stderr || cause}`,
     }
   }
-  return await spawnCoanaScriptViaNode(
-    scriptPath,
-    args,
-    finalEnv,
-    options,
-    spawnExtra,
-  )
+  try {
+    return await spawnCoanaScriptViaNode(
+      scriptPath,
+      args,
+      finalEnv,
+      options,
+      spawnExtra,
+    )
+  } catch (e) {
+    return buildDlxErrorResult(e)
+  }
 }
 
 /**

diff --git a/src/utils/dlx.test.mts b/src/utils/dlx.test.mts
--- a/src/utils/dlx.test.mts
+++ b/src/utils/dlx.test.mts
@@ -388,5 +388,40 @@
       expect(result.message).toContain('npm-install fallback also failed')
       expect(result.message).toContain('registry unreachable')
     })
+
+    it('surfaces both dlx and node errors when fallback node spawn fails', async () => {
+      mockSpawn.mockImplementation(async (cmd: string, args: string[]) => {
+        if (cmd === 'npm' && args[0] === 'install') {
+          const prefixIdx = args.indexOf('--prefix')
+          const installDir = args[prefixIdx + 1]
+          const pkgDir = path.join(
+            installDir,
+            'node_modules',
+            '@coana-tech',
+            'cli',
+          )
+          await fs.mkdir(pkgDir, { recursive: true })
+          await fs.writeFile(
+            path.join(pkgDir, 'package.json'),
+            JSON.stringify({ bin: { coana: 'dist/cli.js' } }),
+          )
+          return { stdout: '', stderr: '' }
+        }
+        throw Object.assign(new Error('node boom'), {
+          code: 127,
+          stderr: 'node failed',
+        })
+      })
+
+      const result = await spawnCoanaDlx(['run', '.'], 'acme', {
+        coanaVersion: nextVersion(),
+      })
+
+      expect(result.ok).toBe(false)
+      expect(result.message).toContain('Coana command failed')
+      expect(result.message).toContain('npx aborted')
+      expect(result.message).toContain('npm-install fallback also failed')
+      expect(result.message).toContain('node failed')
+    })
   })
 })

_{You can send follow-ups to the cloud agent here.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1549f69. Configure here.}