From a4a5c8acdea5c2db73ebe8b291aa8f2dc69355ed Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 22 Apr 2026 11:30:54 -0400
Subject: [PATCH 1/5] fix(cli): align env/ + constants/ + build-script error
 messages with 4-ingredient strategy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 packages/cli/scripts/sea-build-utils/downloads.mts | 9 +++------
 packages/cli/src/constants/paths.mts               | 4 +++-
 packages/cli/src/env/checksum-utils.mts            | 7 +++----
 packages/cli/src/env/coana-version.mts             | 2 +-
 packages/cli/src/env/opengrep-version.mts          | 2 +-
 packages/cli/src/env/pycli-version.mts             | 2 +-
 packages/cli/src/env/sfw-version.mts               | 4 ++--
 packages/cli/src/env/socket-basics-version.mts     | 2 +-
 packages/cli/src/env/socket-patch-version.mts      | 2 +-
 packages/cli/src/env/trivy-version.mts             | 2 +-
 packages/cli/src/env/trufflehog-version.mts        | 2 +-
 11 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/packages/cli/scripts/sea-build-utils/downloads.mts b/packages/cli/scripts/sea-build-utils/downloads.mts
index 751b7671b..ffebf5e07 100644
--- a/packages/cli/scripts/sea-build-utils/downloads.mts
+++ b/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`,
           )
         }
 
diff --git a/packages/cli/src/constants/paths.mts b/packages/cli/src/constants/paths.mts
index fa4e12aa8..938b2d2b0 100644
--- a/packages/cli/src/constants/paths.mts
+++ b/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')
 }
diff --git a/packages/cli/src/env/checksum-utils.mts b/packages/cli/src/env/checksum-utils.mts
index 536955032..3f5a79414 100644
--- a/packages/cli/src/env/checksum-utils.mts
+++ b/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
diff --git a/packages/cli/src/env/coana-version.mts b/packages/cli/src/env/coana-version.mts
index 234305abc..cbb105edd 100644
--- a/packages/cli/src/env/coana-version.mts
+++ b/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
diff --git a/packages/cli/src/env/opengrep-version.mts b/packages/cli/src/env/opengrep-version.mts
index 663fc9956..9640e18d0 100644
--- a/packages/cli/src/env/opengrep-version.mts
+++ b/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
diff --git a/packages/cli/src/env/pycli-version.mts b/packages/cli/src/env/pycli-version.mts
index 0a595cc12..e5ffe9ad9 100644
--- a/packages/cli/src/env/pycli-version.mts
+++ b/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
diff --git a/packages/cli/src/env/sfw-version.mts b/packages/cli/src/env/sfw-version.mts
index 604a94457..e85123d82 100644
--- a/packages/cli/src/env/sfw-version.mts
+++ b/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
diff --git a/packages/cli/src/env/socket-basics-version.mts b/packages/cli/src/env/socket-basics-version.mts
index 60a207330..5078fcd3d 100644
--- a/packages/cli/src/env/socket-basics-version.mts
+++ b/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
diff --git a/packages/cli/src/env/socket-patch-version.mts b/packages/cli/src/env/socket-patch-version.mts
index 673bc03bb..f4fa948d0 100644
--- a/packages/cli/src/env/socket-patch-version.mts
+++ b/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
diff --git a/packages/cli/src/env/trivy-version.mts b/packages/cli/src/env/trivy-version.mts
index 4a2d2452d..05ab67c33 100644
--- a/packages/cli/src/env/trivy-version.mts
+++ b/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
diff --git a/packages/cli/src/env/trufflehog-version.mts b/packages/cli/src/env/trufflehog-version.mts
index dec284f7a..145fed032 100644
--- a/packages/cli/src/env/trufflehog-version.mts
+++ b/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

From 7ca388c9505238716fdba7577aa7c622d016d92e Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 22 Apr 2026 11:51:20 -0400
Subject: [PATCH 2/5] 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.
---
 packages/cli/src/env/checksum-utils.mts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/src/env/checksum-utils.mts b/packages/cli/src/env/checksum-utils.mts
index 3f5a79414..223a4b95c 100644
--- a/packages/cli/src/env/checksum-utils.mts
+++ b/packages/cli/src/env/checksum-utils.mts
@@ -30,7 +30,7 @@ export function parseChecksums(
     return JSON.parse(jsonString) as Checksums
   } catch (e) {
     throw new 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`,
+      `INLINED_${toolName.toUpperCase()}_CHECKSUMS is 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 check bundle-tools.json tools.${toolName}.checksums`,
     )
   }
 }

From 56527ec63953f77f57abdb80983513b14429d40e Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 22 Apr 2026 12:03:46 -0400
Subject: [PATCH 3/5] fix(cli): address Cursor bugbot findings on checksum
 error messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 https://github.com/SocketDev/socket-cli/pull/1258 bugbot review.
---
 packages/cli/src/env/checksum-utils.mts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/env/checksum-utils.mts b/packages/cli/src/env/checksum-utils.mts
index 223a4b95c..7ec3ca094 100644
--- a/packages/cli/src/env/checksum-utils.mts
+++ b/packages/cli/src/env/checksum-utils.mts
@@ -30,7 +30,7 @@ export function parseChecksums(
     return JSON.parse(jsonString) as Checksums
   } catch (e) {
     throw new Error(
-      `INLINED_${toolName.toUpperCase()}_CHECKSUMS is 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 check bundle-tools.json tools.${toolName}.checksums`,
+      `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,7 +62,7 @@ export function requireChecksum(
   const sha256 = checksums[assetName]
   if (!sha256) {
     throw new Error(
-      `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`,
+      `${toolName} has no SHA-256 checksum for asset "${assetName}" (known assets: ${Object.keys(checksums).join(', ') || '<empty>'}); add it to the matching entry in bundle-tools.json via \`pnpm run sync-checksums\` — do NOT ship without verification`,
     )
   }
   return sha256

From 7381d9a51d63344feee9216c0163e52c454c8aa3 Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 22 Apr 2026 12:06:36 -0400
Subject: [PATCH 4/5] chore(cli): use joinAnd from @socketsecurity/lib/arrays
 for error lists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 packages/cli/scripts/sea-build-utils/downloads.mts | 7 ++++---
 packages/cli/src/env/checksum-utils.mts            | 4 +++-
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/cli/scripts/sea-build-utils/downloads.mts b/packages/cli/scripts/sea-build-utils/downloads.mts
index ffebf5e07..7efaf87ca 100644
--- a/packages/cli/scripts/sea-build-utils/downloads.mts
+++ b/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,7 +333,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
 
     if (!sha256) {
       throw new Error(
-        `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`,
+        `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`,
       )
     }
 
@@ -472,7 +473,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
 
         if (!wheelSha256) {
           throw new Error(
-            `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`,
+            `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`,
           )
         }
 
@@ -542,7 +543,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
         const archiveSha256 = socketBasicsConfig.checksums?.[archiveKey]
         if (!archiveSha256) {
           throw new Error(
-            `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`,
+            `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`,
           )
         }
 
diff --git a/packages/cli/src/env/checksum-utils.mts b/packages/cli/src/env/checksum-utils.mts
index 7ec3ca094..d970d1ff4 100644
--- a/packages/cli/src/env/checksum-utils.mts
+++ b/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>
 
 /**
@@ -62,7 +64,7 @@ export function requireChecksum(
   const sha256 = checksums[assetName]
   if (!sha256) {
     throw new Error(
-      `${toolName} has no SHA-256 checksum for asset "${assetName}" (known assets: ${Object.keys(checksums).join(', ') || '<empty>'}); add it to the matching entry in bundle-tools.json via \`pnpm run sync-checksums\` — do NOT ship without verification`,
+      `${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

From 2865bb4a21dbd1574b8652e757e2c56be480c79f Mon Sep 17 00:00:00 2001
From: jdalton <john.david.dalton@gmail.com>
Date: Wed, 22 Apr 2026 21:25:36 -0400
Subject: [PATCH 5/5] 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.
---
 packages/cli/scripts/sea-build-utils/downloads.mts | 2 +-
 pnpm-lock.yaml                                     | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/cli/scripts/sea-build-utils/downloads.mts b/packages/cli/scripts/sea-build-utils/downloads.mts
index 7efaf87ca..1c54b9ac8 100644
--- a/packages/cli/scripts/sea-build-utils/downloads.mts
+++ b/packages/cli/scripts/sea-build-utils/downloads.mts
@@ -333,7 +333,7 @@ export async function downloadExternalTools(platform, arch, isMusl = false) {
 
     if (!sha256) {
       throw new Error(
-        `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`,
+        `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`,
       )
     }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index adc83df24..158a84812 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2151,6 +2151,7 @@ packages:
 
   '@socketaddon/iocraft@file:packages/package-builder/build/dev/out/socketaddon-iocraft':
     resolution: {directory: packages/package-builder/build/dev/out/socketaddon-iocraft, type: directory}
+    engines: {node: '>=18'}
 
   '@socketregistry/es-set-tostringtag@1.0.10':
     resolution: {integrity: sha512-btXmvw1JpA8WtSoXx9mTapo9NAyIDKRRzK84i48d8zc0X09M6ORfobVnHbgwhXf7CFhkRzhYrHG9dqbI9vpELQ==}