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.

Author: jdalton

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

@@ -332,8 +332,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: ${Object.keys(toolConfig?.checksums ?? {}).join(', ') || '<empty>'}); run \`pnpm run sync-checksums\` to populate — builds must verify every external download`,
       )
     }
 
@@ -473,8 +472,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: ${Object.keys(pyCliConfig.checksums ?? {}).join(', ') || '<empty>'}); run \`pnpm run sync-checksums\` to populate from PyPI — builds must verify the wheel hash`,
           )
         }
 
@@ -544,8 +542,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: ${Object.keys(socketBasicsConfig.checksums ?? {}).join(', ') || '<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

@@ -28,9 +28,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_${toolName.toUpperCase()}_CHECKSUMS is not valid JSON at runtime (JSON.parse threw: ${(e as Error).message}); the build-time inline step produced corrupt data — rebuild socket-cli (\`pnpm run build:cli\`) and check bundle-tools.json tools.${toolName}.checksums`,
     )
   }
 }
@@ -62,8 +62,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.',
+      `bundle-tools.json tools.${toolName}.checksums has no entry for asset "${assetName}" (available: ${Object.keys(checksums).join(', ') || '<empty>'}); add the SHA-256 for this asset 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