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

Final PR in the error-message series. Covers everything not already
touched by #1255-#1259: utils/basics, utils/config, utils/fs,
utils/git, utils/npm, utils/promise, utils/terminal, and the flags
module at the root of the CLI tree.

Sources:
- flags.mts: 2 throws (--max-old-space-size, --max-semi-space-size)
  — name the flag, show the offending value, suggest a concrete
  megabyte value.
- utils/config.mts: 1 throw (SOCKET_CLI_CONFIG base64 decode) —
  explains the replacement-character symptom and how to re-encode.
- utils/basics/vfs-extract.mts: 4 throws (SEA VFS extraction for
  Python + security tools) — name the missing paths, the exit
  codes, and point at the "rebuild the SEA binary" fix.
- utils/promise/queue.mts: 1 throw (PromiseQueue concurrency guard)
  — show the offending value and suggest 4/8.
- utils/npm/spec.mts: 1 throw (PURL conversion) — show the input,
  state what a valid npm spec looks like.
- utils/git/operations.mts: 1 throw (git-not-on-PATH) — point at
  install and the local-path env-var override.
- utils/git/gitlab-provider.mts: 2 throws (no token, PR creation
  after retries) — name the token scope, the retry count, the
  repo/head refs.
- utils/fs/path-resolve.mts: 1 throw (npm path-walk iteration cap)
  — name the start path, current directory, and what usually
  causes the cycle (symlinks).
- utils/terminal/iocraft.mts: 1 throw (native-module load failure)
  — show the underlying error and the offending platform/arch
  triple.

Skipped (already informative):
- github-provider.mts pass-through errors (forward inner CResult
  cause/message)
- gitlab-provider.mts try/catch wrappers that call
  formatErrorWithDetail (inner error has context)
- 'process.exit called' sentinel throws in npm/pnpm/yarn/with-
  subcommands paths (test harness re-raise markers, not user-facing)

Tests updated:
- test/unit/utils/promise/queue.test.mts (2 assertions)
- test/unit/utils/npm/spec.test.mts (2 assertions)
- test/unit/utils/git/gitlab-provider.test.mts (3 assertions)

Full suite (343 files / 5225 tests) passes.

Completes the series: #1255 (commands/) → #1256 (utils/dlx/) →
#1257 (utils/update + utils/command/) → #1258 (env/ + constants/) →
#1259 (test/) → this.

Author: jdalton

packages/cli/src/flags.mts

@@ -64,12 +64,12 @@ function getRawSpaceSizeFlags(): RawSpaceSizeFlags {
     // Validate numeric flags (should be guaranteed by meow type='number', but defensive).
     if (Number.isNaN(maxOldSpaceSize) || maxOldSpaceSize < 0) {
       throw new Error(
-        `Invalid value for --max-old-space-size: ${cli.flags['maxOldSpaceSize']}`,
+        `--max-old-space-size must be a non-negative integer in megabytes (saw: "${cli.flags['maxOldSpaceSize']}"); pass a whole number like --max-old-space-size=4096 for 4GB`,
       )
     }
     if (Number.isNaN(maxSemiSpaceSize) || maxSemiSpaceSize < 0) {
       throw new Error(
-        `Invalid value for --max-semi-space-size: ${cli.flags['maxSemiSpaceSize']}`,
+        `--max-semi-space-size must be a non-negative integer in megabytes (saw: "${cli.flags['maxSemiSpaceSize']}"); pass a whole number like --max-semi-space-size=128`,
       )
     }
 

packages/cli/src/utils/basics/vfs-extract.mts

@@ -176,7 +176,7 @@ export async function extractBasicsTools(
     const missingTools = tools.filter(t => !extractedPaths[t])
     if (missingTools.length) {
       throw new Error(
-        `Failed to extract all basics tools. Missing: ${missingTools.join(', ')}`,
+        `socket-basics VFS extraction returned ${Object.keys(extractedPaths).length}/${tools.length} tools (missing: ${missingTools.join(', ')}); the SEA bundle is incomplete — rebuild with all basics tools included`,
       )
     }
 
@@ -186,7 +186,9 @@ export async function extractBasicsTools(
     const pythonExe = isPlatWin ? 'python3.exe' : 'python3'
     const pythonDir = extractedPaths['python']
     if (!pythonDir) {
-      throw new Error('Python extraction path not found')
+      throw new Error(
+        `extractedPaths.python is undefined after VFS extraction (expected a directory path); the basics SEA bundle is missing Python — rebuild the SEA binary`,
+      )
     }
     const pythonPath = normalizePath(path.join(pythonDir, 'bin', pythonExe))
 
@@ -197,7 +199,7 @@ export async function extractBasicsTools(
 
     if (!validateResult || validateResult.code !== 0) {
       throw new Error(
-        `Python validation failed: ${validateResult?.stderr || 'Unable to execute Python'}`,
+        `extracted Python at ${pythonPath} failed to run with exit code ${validateResult?.code ?? 'null'} (stderr: ${validateResult?.stderr || '<none>'}); the extracted binary may be corrupt or missing a shared lib — rebuild the SEA binary`,
       )
     }
 
@@ -218,7 +220,7 @@ export async function extractBasicsTools(
 
       if (!toolValidateResult || toolValidateResult.code !== 0) {
         throw new Error(
-          `${tool} validation failed: ${toolValidateResult?.stderr || `Unable to execute ${tool}`}`,
+          `extracted ${tool} at ${toolPath} failed to run with exit code ${toolValidateResult?.code ?? 'null'} (stderr: ${toolValidateResult?.stderr || '<none>'}); the extracted binary may be corrupt or missing a shared lib — rebuild the SEA binary`,
         )
       }
 

packages/cli/src/utils/config.mts

@@ -140,7 +140,9 @@ function getConfigValues(retryCount = 0): LocalConfig {
             const decoded = Buffer.from(rawString, 'base64').toString('utf8')
             // Check for invalid UTF-8 sequences (replacement character).
             if (decoded.includes('\ufffd')) {
-              throw new Error('Invalid UTF-8 in base64-encoded config')
+              throw new Error(
+                `SOCKET_CLI_CONFIG contains invalid UTF-8 after base64-decode (replacement-character in output); the env var may have been truncated or double-encoded — re-export it with \`echo '{...}' | base64\``,
+              )
             }
             const parsed = JSON.parse(decoded)
             // Only copy supported config keys to prevent prototype pollution.

packages/cli/src/utils/fs/path-resolve.mts

@@ -55,7 +55,7 @@ export function findNpmDirPathSync(npmBinPath: string): string | undefined {
   while (true) {
     if (iterations >= MAX_ITERATIONS) {
       throw new Error(
-        `path traversal exceeded maximum iterations of ${MAX_ITERATIONS}`,
+        `npm path resolution walked ${MAX_ITERATIONS} directories without finding lib/node_modules/npm starting from "${npmBinPath}" (current: "${thePath}"); check for a circular symlink or corrupt node install`,
       )
     }
     iterations += 1

packages/cli/src/utils/git/gitlab-provider.mts

@@ -97,7 +97,7 @@ export class GitLabProvider implements PrProvider {
     }
 
     throw new Error(
-      `Failed to create merge request after ${retries} attempts: ${owner}/${repo}#${head}`,
+      `GitLab API rejected createMergeRequest for ${owner}/${repo} (head="${head}") after ${retries} retries with exponential backoff; check GL_TOKEN permissions (needs api scope), the target branch exists, and GitLab is reachable`,
     )
   }
 
@@ -326,6 +326,6 @@ function getGitLabToken(): string {
   }
 
   throw new Error(
-    'GitLab token not found. Set GITLAB_TOKEN environment variable.',
+    `GitLab access requires a token but process.env.GITLAB_TOKEN is not set; create a personal access token with the \`api\` scope at https://gitlab.com/-/user_settings/personal_access_tokens and export GITLAB_TOKEN=<token>`,
   )
 }

packages/cli/src/utils/git/operations.mts

@@ -55,7 +55,9 @@ async function getGitPath(): Promise<string> {
   if (!_gitPath) {
     const result = await whichReal('git', { nothrow: true })
     if (!result || Array.isArray(result)) {
-      throw new Error('git not found in PATH')
+      throw new Error(
+        `git executable not found on PATH (whichReal returned ${Array.isArray(result) ? 'multiple matches' : 'null'}); install git and ensure it is on PATH, or set SOCKET_CLI_GIT_PATH to point at a specific binary`,
+      )
     }
     _gitPath = result
   }

packages/cli/src/utils/npm/spec.mts

@@ -184,7 +184,9 @@ export function safeNpmSpecToPurl(pkgSpec: string): string | undefined {
 export function npmSpecToPurl(pkgSpec: string): string {
   const purl = safeNpmSpecToPurl(pkgSpec)
   if (!purl) {
-    throw new Error(`Failed to convert ${NPM} spec to PURL: ${pkgSpec}`)
+    throw new Error(
+      `cannot convert npm spec "${pkgSpec}" to PURL (safeNpmSpecToPurl returned null); valid npm specs look like "lodash@4.17.21" or "@scope/pkg@^1.0.0" — check the spec for typos or unsupported forms`,
+    )
   }
   return purl
 }

packages/cli/src/utils/promise/queue.mts

@@ -27,7 +27,9 @@ export class PromiseQueue {
       this.maxQueueLength = maxQueueLength
     }
     if (maxConcurrency < 1) {
-      throw new Error('maxConcurrency must be at least 1')
+      throw new Error(
+        `PromiseQueue maxConcurrency must be >= 1 (saw: ${maxConcurrency}); pass a positive integer like 4 or 8`,
+      )
     }
   }
 

packages/cli/src/utils/terminal/iocraft.mts

@@ -27,8 +27,7 @@ function getIocraft(): typeof iocraft {
       iocraftInstance = loaded.default || loaded
     } catch (e) {
       throw new Error(
-        `Failed to load iocraft native module: ${e}\n` +
-          `Make sure @socketaddon/iocraft is installed and your platform is supported.`,
+        `could not load @socketaddon/iocraft native module (${(e as Error).message}); reinstall socket-cli to pull the prebuilt for your platform, or check that your platform (${process.platform}-${process.arch}) has a published prebuilt`,
       )
     }
   }

packages/cli/test/unit/utils/git/gitlab-provider.test.mts

@@ -72,7 +72,7 @@ describe('git/gitlab-provider', () => {
     it('throws error when no token available', () => {
       delete process.env['GITLAB_TOKEN']
       expect(() => new GitLabProvider()).toThrow(
-        'GitLab token not found. Set GITLAB_TOKEN environment variable.',
+        /GitLab access requires a token but process\.env\.GITLAB_TOKEN is not set/,
       )
     })
   })
@@ -193,7 +193,9 @@ describe('git/gitlab-provider', () => {
           retries: 2,
           title: 'Test',
         }),
-      ).rejects.toThrow('Failed to create merge request after 2 attempts')
+      ).rejects.toThrow(
+        /GitLab API rejected createMergeRequest for owner\/repo .*after 2 retries/,
+      )
     })
 
     it('does not retry on 400 errors', async () => {
@@ -212,7 +214,9 @@ describe('git/gitlab-provider', () => {
           retries: 3,
           title: 'Test',
         }),
-      ).rejects.toThrow('Failed to create merge request after 3 attempts')
+      ).rejects.toThrow(
+        /GitLab API rejected createMergeRequest for owner\/repo .*after 3 retries/,
+      )
 
       expect(mockCreate).toHaveBeenCalledTimes(1)
     })