fix(cli): align utils/dlx/ error messages with 4-ingredient strategy

[John-David Dalton (jdalton)]

Summary

PR 3 in the error-message cleanup series started by #1254 (strategy) and #1255 (commands/). This one covers packages/cli/src/utils/dlx/ — the downloaded-tool runner stack.

~35 error messages across 3 files. Tests updated.

What's fixed

spawn.mts (27 messages)

6× "Unexpected resolution type for X" (coana, cdxgen, sfw, trivy, trufflehog, opengrep) — these are internal contract checks between spawnX() and resolveX(). The old message said nothing. The new one names the resolver function and the actual resolution.type seen, so a bug report is actionable:

Before: Unexpected resolution type for coana
After: internal: resolveCoana returned resolution.type="local" (expected "dlx"); this is a resolver contract bug — re-run with --debug and report the output

Archive handling — the "Unsupported archive format", "Binary not found after extraction", and the two security rejections (zip-slip, unsafe symlink) now all name the file, the cache dir, and what to do about it. The security ones specifically tell you to stop trusting the release asset and delete the cache.

Platform detection — Unsupported platform: linux → python-build-standalone does not ship a prebuilt for os.platform()="linux" (supported: darwin, linux, win32); install Python manually and point socket at it via PATH.

PyPI / Python DLX — errors now include the HTTP status, the URL that was fetched, the exact package spec (packageName==version), and the lock file path for retry lock failures.

Package name validation — the two InputErrors at the top of the file now state the actual rule (regex) instead of prose.

resolve-binary.mts (4 messages)

Platform-support errors for socket-patch / trivy / trufflehog / opengrep each list supported platforms and suggest how to install the tool manually as a fallback.

vfs-extract.mts (5 messages)

SEA VFS extraction errors now all suggest "rebuild the SEA binary" and state what specifically went wrong (bundle missing tool, layout changed, etc.).

Error type

Left all these as throw new Error (not InputError) because they're internal-invariant / system-level failures — the user didn't pass bad input, something deeper failed. But the messages now give enough context to file a useful bug.

Tests

Only one existing test pinned on an old substring:

• test/unit/utils/dlx/resolve-binary.test.mts — swapped to regex on the new phrasing.

All 30 tests in test/unit/utils/dlx/ pass.

Test plan

• CI green
• Sanity: socket scan --reach on an unsupported platform prints a clearly-actionable platform error
• Sanity: break the bundle-tools.json checksum, run socket scan --reach — mismatch error names the asset and the tag

---

Note

Low Risk
Low risk: changes are almost entirely error-message rewrites (plus minor refactor of local variables) with no intended behavior change, but they touch tool download/extraction paths so regressions would mainly affect failure-mode diagnostics.

Overview
Improves utils/dlx failure-mode diagnostics by rewriting ~35 errors across binary resolution, GitHub-release downloads/extraction, Python/PyPI installs, and SEA VFS extraction to follow a consistent, actionable format (include platform/asset/tool details, expected vs actual resolver contracts, and concrete remediation steps).

Adds joinAnd for nicer supported/missing lists, enhances internal invariant errors (e.g., resolveX returning unexpected resolution.type), and updates the one unit test assertion to match the new resolveSocketPatch unsupported-platform wording.

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

[cursor]

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

Autofix Details

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

• ✅ Fixed: Error references variables before their declaration
  • Moved the declarations of pythonDir, pythonBin, and lockFile above the retryCount >= MAX_RETRIES guard so they are initialized before the error message interpolates them, avoiding the temporal dead zone ReferenceError.

Or push these changes by commenting:

@cursor push 2a82947a44

Preview (2a82947a44)

diff --git a/packages/cli/src/utils/dlx/spawn.mts b/packages/cli/src/utils/dlx/spawn.mts
--- a/packages/cli/src/utils/dlx/spawn.mts
+++ b/packages/cli/src/utils/dlx/spawn.mts
@@ -1054,6 +1054,9 @@
  */
 export async function ensurePythonDlx(retryCount = 0): Promise<string> {
   const MAX_RETRIES = 3
+  const pythonDir = getPythonCachePath()
+  const pythonBin = getPythonBinPath(pythonDir)
+  const lockFile = path.join(pythonDir, '.downloading')
 
   if (retryCount >= MAX_RETRIES) {
     throw new InputError(
@@ -1061,10 +1064,6 @@
     )
   }
 
-  const pythonDir = getPythonCachePath()
-  const pythonBin = getPythonBinPath(pythonDir)
-  const lockFile = path.join(pythonDir, '.downloading')
-
   if (!existsSync(pythonBin)) {
     await safeMkdir(pythonDir, { recursive: true })

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

[John-David Dalton (jdalton)]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

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

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