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

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

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

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