Consolidate Coana launcher env vars into SOCKET_CLI_COANA_LAUNCHER

[Martin Torp (mtorp)]

Why

Follow-up from this review discussion on the Python CLI: the two env vars tuning how the pinned @coana-tech/cli engine is launched — SOCKET_CLI_COANA_FORCE_NPM_INSTALL (skip npx, always npm install + node) and SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK (npx only, never fall back) — really express three modes of one setting, so they're better off as a single variable. A matching PR updates the Python CLI.

What changed

• New SOCKET_CLI_COANA_LAUNCHER variable:
  • auto (default / unset) — try npx/dlx first, fall back to npm install + node on launcher-level failures.
  • npx — never fall back; surface the dlx failure directly.
  • npm-install — skip dlx entirely; always npm install + node.
• When set to a recognized value, the new variable wins outright and the legacy variables are ignored. Unrecognized values warn and behave as auto.
• The legacy variables are still honored when the new variable is unset (no breaking change), but are intentionally undocumented; only SOCKET_CLI_COANA_LAUNCHER is documented (README).
• SOCKET_CLI_COANA_LOCAL_PATH is unrelated (takes a path) and is unchanged.

Testing

• New unit tests in src/utils/dlx.test.mts cover npm-install mode, npx mode, precedence over the legacy variables, and unrecognized-value handling; existing legacy-var tests are kept as back-compat coverage.
• pnpm test:unit src/utils/dlx.test.mts — 26/26 passing; pnpm run check clean.

---

Note

Low Risk
Behavioral change is limited to Coana spawn strategy and preserves legacy env vars when the new one is unset; mis-set values only warn and default to auto.

Overview
Replaces two undocumented Coana launch toggles with a single SOCKET_CLI_COANA_LAUNCHER env var that selects how @coana-tech/cli is started: auto (try npx/dlx, then npm install + node on launcher failure), npx (dlx only, no fallback), or npm-install (skip dlx entirely).

When the new variable is set, it overrides SOCKET_CLI_COANA_FORCE_NPM_INSTALL and SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK; those legacy flags still work if the new var is unset. Invalid launcher values log a warning and behave like auto. SOCKET_CLI_COANA_LOCAL_PATH is unchanged.

spawnCoanaDlx in src/utils/dlx.mts routes through getCoanaLauncherMode(); README documents only the new variable. Unit tests in src/utils/dlx.test.mts cover each mode, precedence, and bad values.

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

Also fixed

Cursor Bugbot flagged (correctly) that the local-path, forced npm-install, and auto-mode fallback branches only honored stdio passed via the spawnExtra argument, dropping stdio set on the options argument (e.g. socket fix --silence requests stdio: 'pipe' via options) and defaulting to inherit. This predates this PR (#1353 only fixed the dlx branch), but since it's the same plumbing, the requested stdio is now resolved once and threaded through every launch path, with regression tests for the npm-install and fallback paths.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue.}

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

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

[Oskar Haarklou Veileborg (BarrensZeppelin)]

LGTM 🎉