Address PR review: per-version fallback cache, node prereq, accurate npx wording

- M2: cache the npm-install fallback's resolved script path per version for the
  process lifetime (mirrors the Node CLI's installedCoanaScriptPathsByVersion), so a
  repeated fallback installs once instead of re-installing + leaking a temp dir each call.
- M3: surface a clear error when `node` is missing in the fallback (instead of an opaque
  FileNotFoundError after a costly npm install), and add `node` to the up-front prereq check.
- M1: correct the overstated 'npx --force disables the cache' wording in docstrings, docs,
  and CHANGELOG. The code already matches the Node CLI exactly (npx --yes --force); --force
  does not force a re-download of an already-cached pinned version, so the docs now describe
  what the flags actually do rather than claiming a cache bypass.

Adds tests for per-version caching, node-missing, and real _resolve_coana_bin /
_build_coana_node_cmd parsing.

Author: mtorp

CHANGELOG.md

@@ -12,13 +12,14 @@
   untouched (never auto-updated or downgraded).
 - Opt into always-newest with `--reach-version latest`; pin an explicit version with
   `--reach-version <semver>` (unchanged).
-- npx caching is now disabled (`npx --yes --force`), matching the Socket Node CLI, so a
-  corrupt/partial npx cache entry can't wedge a run.
+- Runs the engine via `npx --yes --force` (the same flags the Socket Node CLI passes for
+  coana); `--yes` skips npx's interactive install prompt so non-interactive/CI runs don't hang.
 - Added an `npm install` + `node` fallback for when the `npx` launcher is missing or fails
-  before the engine starts. Tunable via `SOCKET_CLI_COANA_FORCE_NPM_INSTALL` (use the
-  fallback as the primary path) and `SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK` (never fall back).
-  Also strips `npm_package_*` env vars before spawning the engine to avoid `E2BIG` in large
-  monorepos.
+  before the engine starts. The installed engine is cached per version for the process
+  lifetime (installs once). Tunable via `SOCKET_CLI_COANA_FORCE_NPM_INSTALL` (use the fallback
+  as the primary path) and `SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK` (never fall back). `node` is
+  now part of the up-front prerequisite check. Also strips `npm_package_*` env vars before
+  spawning the engine to avoid `E2BIG` in large monorepos.
 
 ## 2.4.6
 

docs/cli-reference.md

@@ -264,6 +264,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 The Python CLI verifies the following **up front** (before invoking the analysis engine) and exits with code **3** if any are unmet:
 - `npm` - Required (verified up front; ships alongside `npx`)
 - `npx` - Required to fetch (on first use) and run `@coana-tech/cli` (the analysis engine)
+- `node` - Required to run the engine (used directly by the `npm install` fallback)
 - `uv` - Required by the analysis engine
 - An **Enterprise** Socket organization plan (any `enterprise*` plan, including Enterprise trials)
 
@@ -313,7 +314,7 @@ Sample config files:
 
 For CI-specific examples and guidance, see [`ci-cd.md`](ci-cd.md).
 
-The CLI runs a pinned `@coana-tech/cli` version via `npx --yes --force`; it does **not** auto-update the engine or install it globally. `--force` disables the npx cache (matching the Socket Node CLI) so a corrupt or partial cache entry can't wedge a run. If the `npx` launcher is unavailable or fails before the engine starts, the CLI falls back to `npm install`-ing the pinned version into a temp directory and running it via `node`. Pass `--reach-version latest` to opt into the newest published version. Use `--reach` to enable reachability analysis during a full scan, or add `--only-facts-file` (with `--reach`) to submit only the reachability facts file (`.socket.facts.json`) when creating the full scan.
+The CLI runs a pinned `@coana-tech/cli` version via `npx --yes --force` (the same flags the Socket Node CLI passes for coana); it does **not** auto-update the engine or install it globally. `--yes` skips npx's interactive install prompt so non-interactive/CI runs don't hang. If the `npx` launcher is unavailable or fails before the engine starts, the CLI falls back to `npm install`-ing the pinned version into a temp directory and running it via `node`. Pass `--reach-version latest` to opt into the newest published version. Use `--reach` to enable reachability analysis during a full scan, or add `--only-facts-file` (with `--reach`) to submit only the reachability facts file (`.socket.facts.json`) when creating the full scan.
 
 The launcher fallback can be tuned via environment variables:
 - `SOCKET_CLI_COANA_FORCE_NPM_INSTALL` — skip `npx` entirely and always use the `npm install` + `node` path (useful where `npx` is known-broken).

socketsecurity/core/tools/reachability.py

@@ -18,6 +18,11 @@
 # Pass --reach-version latest to opt into the newest published version instead.
 DEFAULT_COANA_CLI_VERSION = "15.3.24"
 
+# Resolved @coana-tech/cli script paths from the npm-install fallback, keyed by version.
+# Lives for the process lifetime so repeated fallback invocations install only once
+# (mirrors the Node CLI's installedCoanaScriptPathsByVersion).
+_INSTALLED_COANA_SCRIPT_PATHS: Dict[str, str] = {}
+
 
 def _build_caller_user_agent() -> str:
     """Build the SOCKET_CALLER_USER_AGENT string forwarded to the coana CLI.
@@ -297,10 +302,12 @@ def _spawn_coana(
     ) -> int:
         """Run coana for the given args, returning the process exit code.
 
-        Primary path: ``npx --yes --force @coana-tech/cli@<version> ...``. ``--force``
-        bypasses the npx cache so a corrupt/partial cache entry can't wedge the run, and
-        ``--yes`` auto-confirms the install prompt (parity with the Node CLI's dlx path,
-        which passes ``--force`` for npm/npx and ``npm_config_dlx_cache_max_age=0`` for pnpm).
+        Primary path: ``npx --yes --force @coana-tech/cli@<version> ...`` — the exact flags
+        the Socket Node CLI passes for coana. ``--yes`` skips npx's interactive install
+        confirmation so non-interactive/CI runs don't hang. ``--force`` matches the Node CLI
+        (it opts out of npm's prompts/protections and refreshes within-range specs); note it
+        does NOT force a re-download of an already-cached pinned version — npx still reuses a
+        cached pinned package, so this is parity with the Node CLI, not a cache bypass.
 
         Fallback path: if npx is missing, or its launcher dies before coana starts, install
         @coana-tech/cli into a temp dir via ``npm install`` and run it directly via ``node``.
@@ -315,7 +322,7 @@ def _spawn_coana(
             return self._spawn_coana_via_npm_install(coana_args, effective_version, coana_env, cwd)
 
         package_spec = f"@coana-tech/cli@{effective_version}"
-        # --yes auto-confirms the install prompt; --force bypasses the npx cache.
+        # --yes skips npx's install confirmation; --force matches the Node CLI's coana flags.
         npx_cmd = ["npx", "--yes", "--force", package_spec, *coana_args]
         log.debug(f"Reachability command: {' '.join(npx_cmd)}")
         try:
@@ -356,8 +363,32 @@ def _spawn_coana_via_npm_install(
 
         Used when npx is unavailable or its launcher fails before coana boots. Mirrors the
         Node CLI's npm-install fallback. Returns coana's exit code; raises if the install
-        itself fails.
+        itself fails or if ``node`` is unavailable.
         """
+        script_path = self._install_coana_to_tmpdir(version, env)
+        node_cmd = self._build_coana_node_cmd(script_path, coana_args)
+        log.debug(f"Reachability fallback command: {' '.join(node_cmd)}")
+        try:
+            result = subprocess.run(node_cmd, env=env, cwd=cwd, stdout=sys.stderr, stderr=sys.stderr)
+        except FileNotFoundError as e:
+            # The fallback exists for broken-launcher environments, but it still needs node.
+            raise Exception(
+                "`node` was not found on PATH; it is required to run the reachability engine "
+                "via the npm-install fallback."
+            ) from e
+        return result.returncode
+
+    def _install_coana_to_tmpdir(self, version: str, env: Dict[str, str]) -> str:
+        """``npm install`` @coana-tech/cli@<version> into a temp dir; return its executable JS path.
+
+        Caches the resolved path per version for the process lifetime so repeated fallback
+        invocations install only once (mirrors the Node CLI's installCoanaToTmpdir). Raises if
+        the install fails.
+        """
+        cached = _INSTALLED_COANA_SCRIPT_PATHS.get(version)
+        if cached and os.path.exists(cached):
+            return cached
+
         install_dir = tempfile.mkdtemp(prefix="socket-coana-")
         npm_cmd = [
             "npm", "install",
@@ -374,10 +405,8 @@ def _spawn_coana_via_npm_install(
             )
 
         script_path = self._resolve_coana_bin(install_dir)
-        node_cmd = self._build_coana_node_cmd(script_path, coana_args)
-        log.debug(f"Reachability fallback command: {' '.join(node_cmd)}")
-        result = subprocess.run(node_cmd, env=env, cwd=cwd, stdout=sys.stderr, stderr=sys.stderr)
-        return result.returncode
+        _INSTALLED_COANA_SCRIPT_PATHS[version] = script_path
+        return script_path
 
     @staticmethod
     def _resolve_coana_bin(install_dir: str) -> str:

socketsecurity/socketcli.py

@@ -189,7 +189,7 @@ def main_code():
     # Check for required dependencies if reachability analysis is enabled
     if config.reach:
         log.info("Reachability analysis enabled, checking for required dependencies...")
-        required_deps = ["npm", "uv", "npx"]
+        required_deps = ["npm", "node", "uv", "npx"]
         missing_deps = []
         found_deps = []
 

tests/unit/test_reachability.py

@@ -24,6 +24,14 @@ def analyzer():
     return ReachabilityAnalyzer(MagicMock(), "test-api-token")
 
 
+@pytest.fixture(autouse=True)
+def _clear_coana_install_cache():
+    """The npm-install fallback caches resolved script paths in a module-level dict; isolate tests."""
+    reachability._INSTALLED_COANA_SCRIPT_PATHS.clear()
+    yield
+    reachability._INSTALLED_COANA_SCRIPT_PATHS.clear()
+
+
 def _spawn_mock(analyzer, mocker, returncode=0, **kwargs):
     """Run run_reachability_analysis with subprocess.run mocked to a fixed exit code.
 
@@ -145,8 +153,8 @@ def _spec_in(cmd):
     return next(a for a in cmd if a.startswith("@coana-tech/cli@"))
 
 
-def test_npx_disables_cache_with_yes_and_force(analyzer, mocker):
-    """npx caching is disabled via --yes --force (parity with the Node CLI dlx path)."""
+def test_npx_uses_yes_and_force_flags(analyzer, mocker):
+    """npx is invoked with --yes --force — the exact flags the Node CLI passes for coana."""
     cmd, _ = _run(analyzer, mocker)
     assert cmd[0] == "npx"
     assert "--yes" in cmd
@@ -292,3 +300,85 @@ def fake_run(argv, **_kw):
     with pytest.raises(Exception):
         analyzer.run_reachability_analysis(org_slug="my-org", target_directory=".")
     assert all(c[:2] != ["npm", "install"] for c in calls)
+
+
+def test_fallback_installs_once_per_version(analyzer, mocker):
+    """A second in-process fallback for the same version reuses the install (no re-install)."""
+    mocker.patch.object(analyzer, "_extract_scan_id", return_value="scan-123")
+    mocker.patch.object(reachability.tempfile, "mkdtemp", return_value="/tmp/socket-coana-cache")
+    mocker.patch.object(
+        analyzer,
+        "_resolve_coana_bin",
+        return_value="/tmp/socket-coana-cache/node_modules/@coana-tech/cli/coana.js",
+    )
+    # The cached script path must "exist" for the 2nd run to reuse it.
+    mocker.patch.object(reachability.os.path, "exists", return_value=True)
+    calls = []
+
+    def fake_run(argv, **_kw):
+        calls.append(argv)
+        m = MagicMock()
+        m.returncode = 137 if argv[0] == "npx" else 0
+        return m
+
+    mocker.patch.object(reachability.subprocess, "run", side_effect=fake_run)
+    analyzer.run_reachability_analysis(org_slug="my-org", target_directory=".")
+    analyzer.run_reachability_analysis(org_slug="my-org", target_directory=".")
+
+    npm_installs = [c for c in calls if c[:2] == ["npm", "install"]]
+    assert len(npm_installs) == 1  # installed once, reused on the second fallback
+
+
+def test_fallback_node_missing_raises_clear_error(analyzer, mocker):
+    """If `node` is missing in the fallback, surface a clear error (not opaque FileNotFoundError)."""
+    mocker.patch.object(analyzer, "_extract_scan_id", return_value=None)
+    mocker.patch.object(reachability.tempfile, "mkdtemp", return_value="/tmp/socket-coana-n")
+    mocker.patch.object(
+        analyzer,
+        "_resolve_coana_bin",
+        return_value="/tmp/socket-coana-n/node_modules/@coana-tech/cli/coana.js",
+    )
+
+    def fake_run(argv, **_kw):
+        if argv[0] == "npx":
+            m = MagicMock()
+            m.returncode = 137
+            return m
+        if argv[0] == "node":
+            raise FileNotFoundError("node")
+        m = MagicMock()  # npm install succeeds
+        m.returncode = 0
+        return m
+
+    mocker.patch.object(reachability.subprocess, "run", side_effect=fake_run)
+    with pytest.raises(Exception, match="node"):
+        analyzer.run_reachability_analysis(org_slug="my-org", target_directory=".")
+
+
+def test_build_coana_node_cmd_js_vs_binary():
+    f = ReachabilityAnalyzer._build_coana_node_cmd
+    assert f("/x/coana.js", ["run", "."]) == ["node", "/x/coana.js", "run", "."]
+    assert f("/x/coana.mjs", ["run"]) == ["node", "/x/coana.mjs", "run"]
+    assert f("/x/coana", ["run", "."]) == ["/x/coana", "run", "."]
+
+
+def test_resolve_coana_bin_parses_package_json(analyzer, tmp_path):
+    pkg_dir = tmp_path / "node_modules" / "@coana-tech" / "cli"
+    pkg_dir.mkdir(parents=True)
+
+    # string bin
+    (pkg_dir / "package.json").write_text('{"bin": "dist/coana.js"}')
+    assert analyzer._resolve_coana_bin(str(tmp_path)) == str(pkg_dir / "dist" / "coana.js")
+
+    # dict bin, prefer the "coana" entry
+    (pkg_dir / "package.json").write_text('{"bin": {"coana": "dist/c.js", "other": "x.js"}}')
+    assert analyzer._resolve_coana_bin(str(tmp_path)) == str(pkg_dir / "dist" / "c.js")
+
+    # dict bin without "coana" -> first value
+    (pkg_dir / "package.json").write_text('{"bin": {"other": "x.js"}}')
+    assert analyzer._resolve_coana_bin(str(tmp_path)) == str(pkg_dir / "x.js")
+
+    # missing bin -> raises
+    (pkg_dir / "package.json").write_text("{}")
+    with pytest.raises(Exception, match="bin"):
+        analyzer._resolve_coana_bin(str(tmp_path))