fix(cli): error messages in env/ + constants/ + sea-build scripts (#1258)

* fix(cli): align env/ + constants/ + build-script error messages with 4-ingredient strategy

Rewrites runtime and build-time error messages for the build-inlined
version/checksum pipeline to follow the What / Where / Saw vs. wanted /
Fix strategy from CLAUDE.md.

Sources (runtime):
- env/coana-version.mts, env/sfw-version.mts (2 getters),
  env/socket-basics-version.mts, env/socket-patch-version.mts,
  env/trufflehog-version.mts, env/trivy-version.mts,
  env/opengrep-version.mts, env/pycli-version.mts — 9 "INLINED_X
  not found" errors. Each now names the exact env var, the
  bundle-tools.json path it comes from, and how to rebuild
  (`pnpm run build:cli`).
- env/checksum-utils.mts — parseChecksums() and requireChecksum()
  now show the exact JSON.parse error or the list of known assets
  so you can see what was in vs. out of the map.
- constants/paths.mts — getSocketRegistryPath() now enumerates
  every env var the app-data lookup checks (HOME, USERPROFILE,
  LOCALAPPDATA, XDG_DATA_HOME) so a cold environment tells you
  which to set.

Sources (build-time scripts, same message style for consistency):
- scripts/sea-build-utils/downloads.mts — 3 checksum-missing
  errors in the SEA build path, each now names the bundle-tools.json
  key and tells you to run `pnpm run sync-checksums`.

No tests pinned these messages (only dist/cli.js — unchecked-in
build output).

Follows strategy from #1254. Continues #1255, #1256, #1257.

* chore(cli): harden (e as Error) casts to safe stringify

Switch `(e as Error).message` to `e instanceof Error ? e.message : String(e)` so that when a non-Error value is thrown (strings, objects, null) the error message stays informative instead of becoming 'undefined'.

Same fix as applied to #1260 (iocraft.mts) after Cursor bugbot flagged the pattern on that PR.

* fix(cli): address Cursor bugbot findings on checksum error messages

Two issues flagged by Cursor bugbot on #1258:

1. (Low) parseChecksums() built the env var name as
   `INLINED_${toolName.toUpperCase()}_CHECKSUMS`. When toolName has
   spaces (e.g. 'Socket Patch'), toUpperCase() produces 'SOCKET PATCH'
   → 'INLINED_SOCKET PATCH_CHECKSUMS' — not a valid env var name. The
   real env var is INLINED_SOCKET_PATCH_CHECKSUMS.

2. (Low) Both parseChecksums() and requireChecksum() embedded
   `tools.${toolName}.checksums` to reference bundle-tools.json paths,
   but toolName is the display name (PyCLI, OpenGrep, Socket Patch)
   not the case-sensitive JSON key (socketsecurity, opengrep,
   socket-patch).

Both came from the same root cause: I treated the display-name
parameter as if it were a canonical identifier. Fix: reword the
messages to just name the tool in prose ('inlined checksums for X',
'X has no SHA-256 for Y') and point at the 'matching entry in
bundle-tools.json' instead of inventing a wrong path. Keeps the
4-ingredient structure (what/where/saw/fix) without claiming
identifiers that don't exist.

Caught by #1258 bugbot review.

* chore(cli): use joinAnd from @socketsecurity/lib/arrays for error lists

Switch the 4 `Object.keys(x).join(', ')` calls in error messages on
this branch to `joinAnd(Object.keys(x))` so they render as human
prose (e.g. 'a, b, and c') instead of machine-y comma-joins.

Sites:
- src/env/checksum-utils.mts: requireChecksum known-assets list
- scripts/sea-build-utils/downloads.mts: 3 missing-checksum errors
  (external tools, socketsecurity wheel, socket-basics archive)

No behavior change — just uses the fleet helper consistently.

* fix(cli): use bracket notation for hyphenated tool keys in error message

Cursor flagged the checksum-missing error in downloads.mts: it used
\`tools.\${toolName}.checksums\` (dot notation) which produces an
invalid JSONPath like \`tools.socket-patch.checksums\` when toolName
is hyphenated. The socket-basics site a few hundred lines down already
uses bracket notation for the same reason; make this one match.

Reported on PR #1258.

Author: jdalton

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

@@ -16,6 +16,7 @@ import AdmZip from 'adm-zip'
 import { logTransientErrorHelp } from 'build-infra/lib/github-error-utils'
 import { downloadReleaseAsset } from 'build-infra/lib/github-releases'
 
+import { joinAnd } from '@socketsecurity/lib/arrays'
 import { safeDelete, safeMkdir } from '@socketsecurity/lib/fs'
 import { httpDownload, httpRequest } from '@socketsecurity/lib/http-request'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
@@ -332,8 +333,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
 
     if (!sha256) {
       throw new Error(
-        `Missing SHA-256 checksum for ${toolName} asset: ${assetName}. ` +
-          'This is a security requirement. Please update bundle-tools.json with the correct checksum.',
+        `bundle-tools.json tools["${toolName}"].checksums has no entry for "${assetName}" (seen: ${joinAnd(Object.keys(toolConfig?.checksums ?? {})) || '<empty>'}); run \`pnpm run sync-checksums\` to populate — builds must verify every external download`,
       )
     }
 
@@ -473,8 +473,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
 
         if (!wheelSha256) {
           throw new Error(
-            `Missing SHA-256 checksum for socketsecurity wheel: ${wheelFilename}. ` +
-              'Please update bundle-tools.json with the correct checksum.',
+            `bundle-tools.json tools.socketsecurity.checksums has no entry for "${wheelFilename}" (seen: ${joinAnd(Object.keys(pyCliConfig.checksums ?? {})) || '<empty>'}); run \`pnpm run sync-checksums\` to populate from PyPI — builds must verify the wheel hash`,
           )
         }
 
@@ -544,8 +543,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
         const archiveSha256 = socketBasicsConfig.checksums?.[archiveKey]
         if (!archiveSha256) {
           throw new Error(
-            `Missing SHA-256 checksum for socket-basics archive: ${archiveKey}. ` +
-              'Please update bundle-tools.json with the correct checksum.',
+            `bundle-tools.json tools["socket-basics"].checksums has no entry for "${archiveKey}" (seen: ${joinAnd(Object.keys(socketBasicsConfig.checksums ?? {})) || '<empty>'}); run \`pnpm run sync-checksums\` to populate from the GitHub release — builds must verify the source tarball hash`,
           )
         }
 

packages/cli/src/constants/paths.mts

@@ -190,7 +190,9 @@ export function getSocketCachePath(): string {
 export function getSocketRegistryPath(): string {
   const appDataPath = getSocketAppDataPath()
   if (!appDataPath) {
-    throw new Error('Unable to determine Socket app data path')
+    throw new Error(
+      `could not determine the Socket app-data directory: getSocketAppDataPath() returned undefined because none of HOME, USERPROFILE, LOCALAPPDATA, or XDG_DATA_HOME are set; export one of those env vars (typically HOME on macOS/Linux or LOCALAPPDATA on Windows) and retry`,
+    )
   }
   return path.join(appDataPath, 'registry')
 }

packages/cli/src/env/checksum-utils.mts

@@ -6,6 +6,8 @@
  * This module provides shared parsing and validation logic.
  */
 
+import { joinAnd } from '@socketsecurity/lib/arrays'
+
 export type Checksums = Record<string, string>
 
 /**
@@ -28,9 +30,9 @@ export function parseChecksums(
   }
   try {
     return JSON.parse(jsonString) as Checksums
-  } catch {
+  } catch (e) {
     throw new Error(
-      `Failed to parse ${toolName} checksums. This indicates a build configuration error.`,
+      `inlined checksums for ${toolName} are not valid JSON at runtime (JSON.parse threw: ${e instanceof Error ? e.message : String(e)}); the build-time inline step produced corrupt data — rebuild socket-cli (\`pnpm run build:cli\`) and verify the matching checksums entry in bundle-tools.json`,
     )
   }
 }
@@ -62,8 +64,7 @@ export function requireChecksum(
   const sha256 = checksums[assetName]
   if (!sha256) {
     throw new Error(
-      `Missing SHA-256 checksum for ${toolName} asset: ${assetName}. ` +
-        'This is a security requirement. Please update bundle-tools.json with the correct checksum.',
+      `${toolName} has no SHA-256 checksum for asset "${assetName}" (known assets: ${joinAnd(Object.keys(checksums)) || '<empty>'}); add it to the matching entry in bundle-tools.json via \`pnpm run sync-checksums\` — do NOT ship without verification`,
     )
   }
   return sha256

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

@@ -12,7 +12,7 @@ export function getCoanaVersion(): string {
   const version = process.env['INLINED_COANA_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_COANA_VERSION not found. Please ensure @coana-tech/cli is properly configured in bundle-tools.json.',
+      `process.env.INLINED_COANA_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools["@coana-tech/cli"].version — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version

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

@@ -12,7 +12,7 @@ export function getOpengrepVersion(): string {
   const version = process.env['INLINED_OPENGREP_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_OPENGREP_VERSION not found. Please ensure opengrep is properly configured in bundle-tools.json.',
+      `process.env.INLINED_OPENGREP_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools.opengrep.version — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version

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

@@ -19,7 +19,7 @@ export function getPyCliVersion(): string {
   const version = process.env['INLINED_PYCLI_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_PYCLI_VERSION not set - build configuration error. Please rebuild the CLI.',
+      `process.env.INLINED_PYCLI_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools.socketsecurity.version (PyPI package) — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version

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

@@ -19,7 +19,7 @@ export function getSwfVersion(): string {
   const version = process.env['INLINED_SFW_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_SFW_VERSION not found. Please ensure sfw is properly configured in bundle-tools.json.',
+      `process.env.INLINED_SFW_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools.sfw.version (GitHub release tag) — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version
@@ -32,7 +32,7 @@ export function getSfwNpmVersion(): string {
   const version = process.env['INLINED_SFW_NPM_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_SFW_NPM_VERSION not found. Please ensure sfw npm.version is configured in bundle-tools.json.',
+      `process.env.INLINED_SFW_NPM_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools.sfw.npm.version (npm package semver) — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version

packages/cli/src/env/socket-basics-version.mts

@@ -12,7 +12,7 @@ export function getSocketBasicsVersion(): string {
   const version = process.env['INLINED_SOCKET_BASICS_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_SOCKET_BASICS_VERSION not found. Please ensure socket-basics is properly configured in bundle-tools.json.',
+      `process.env.INLINED_SOCKET_BASICS_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools["socket-basics"].version — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version

packages/cli/src/env/socket-patch-version.mts

@@ -12,7 +12,7 @@ export function getSocketPatchVersion(): string {
   const version = process.env['INLINED_SOCKET_PATCH_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_SOCKET_PATCH_VERSION not found. Please ensure socket-patch is properly configured in bundle-tools.json.',
+      `process.env.INLINED_SOCKET_PATCH_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools["socket-patch"].version — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version

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

@@ -12,7 +12,7 @@ export function getTrivyVersion(): string {
   const version = process.env['INLINED_TRIVY_VERSION']
   if (!version) {
     throw new Error(
-      'INLINED_TRIVY_VERSION not found. Please ensure trivy is properly configured in bundle-tools.json.',
+      `process.env.INLINED_TRIVY_VERSION is empty at runtime; this value should be inlined at build time from bundle-tools.json tools.trivy.version — rebuild socket-cli (\`pnpm run build:cli\`) or check that esbuild's define step ran`,
     )
   }
   return version