fix(cli): align utils/ miscellaneous error messages with 4-ingredient strategy by jdalton · Pull Request #1260 · SocketDev/socket-cli

John-David Dalton (jdalton) · 2026-04-22T15:42:25Z

Summary

Final PR in the error-message series. Covers everything not already touched by #1255–#1259: flags.mts, utils/basics, utils/config, utils/fs, utils/git, utils/npm, utils/promise, utils/terminal.

~14 messages across 9 source files + 3 test files. Full unit suite (5225 tests) passes.

What's fixed

Flag validation (`flags.mts`)

Before: Invalid value for --max-old-space-size: abc
After: --max-old-space-size must be a non-negative integer in megabytes (saw: "abc"); pass a whole number like --max-old-space-size=4096 for 4GB

Same for --max-semi-space-size.

Env-var decode (`utils/config.mts`)

SOCKET_CLI_CONFIG is base64-encoded JSON. When it decodes to garbage, you now get told how to re-encode (echo '{...}' | base64) and what the symptom means (replacement characters).

SEA VFS extraction (`utils/basics/vfs-extract.mts`, 4 throws)

Same treatment as the other SEA paths in #1256/#1258 — name the missing path, the exit code, point at "rebuild the SEA binary" as the fix.

Library-level guards (4 throws in `promise/queue`, `npm/spec`, `git/operations`, `fs/path-resolve`)

Each now names the offending value/path and suggests a concrete repair. Example for the npm path walk cycle:

Before: path traversal exceeded maximum iterations of 100
After: npm path resolution walked 100 directories without finding lib/node_modules/npm starting from "<input>" (current: "<where-we-are>"); check for a circular symlink or corrupt node install

GitLab provider (`utils/git/gitlab-provider.mts`, 2 throws)

Missing-token error now points at https://gitlab.com/-/user_settings/personal_access_tokens and specifies the api scope.
Retry-exhaustion error names the owner/repo/head refs and the retry count.

Native-module load (`utils/terminal/iocraft.mts`)

Before: Failed to load iocraft native module: <err>\nMake sure @socketaddon/iocraft is installed...
After: could not load @socketaddon/iocraft native module (<msg>); reinstall socket-cli to pull the prebuilt for your platform, or check that your platform (<plat>-<arch>) has a published prebuilt

Skipped (already informative)

github-provider.mts pass-through errors (forward inner CResult cause/message)
gitlab-provider.mts try/catch wrappers using formatErrorWithDetail (inner error already contextual)
process.exit called sentinels in npm/pnpm/yarn/with-subcommands paths (test harness re-raise markers, not user-facing)

Tests

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: 5225/5225 passes.

Series complete

This closes out the 4-ingredient error-message cleanup on packages/cli/src/:

docs(claude): add Error Messages four-ingredient strategy #1254 — strategy in CLAUDE.md (merged)
fix(cli): align commands/ error messages with 4-ingredient strategy #1255 — commands/
fix(cli): align utils/dlx/ error messages with 4-ingredient strategy #1256 — utils/dlx/
fix(cli): align utils/update/ + utils/command/ error messages with 4-ingredient strategy #1257 — utils/update/ + utils/command/
fix(cli): align env/ + constants/ + build-script error messages with 4-ingredient strategy #1258 — env/ + constants/ + build scripts
fix(cli): align test/ error messages with 4-ingredient strategy #1259 — test/
this PR — utils/ miscellaneous + flags

Test plan

CI green
Sanity: socket --max-old-space-size=abc scan ... prints the new message
Sanity: unset GITLAB_TOKEN && socket fix with a GitLab repo triggers the new token-missing error

Note

Low Risk
Low risk: changes are limited to improving thrown error messages (plus minor helper imports) and updating unit tests to match, with no behavioral logic changes beyond message text.

Overview
Improves user-facing error messages across the CLI for several failure paths (flag validation, config base64 decode, basics SEA/VFS extraction and tool validation, npm path resolution, GitLab MR creation/token lookup, git executable discovery, npm spec→PURL conversion, PromiseQueue parameter validation, and iocraft native module loading) by adding concrete context (offending values/paths, exit codes) and suggested remediation steps.

Updates related unit tests to assert the new, more descriptive error outputs.

^{Reviewed by Cursor Bugbot for commit 579638d. Configure here.}

… 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.

Four issues flagged by Cursor bugbot on #1260: 1. (Medium) gitlab-provider.mts: error said 'check GL_TOKEN permissions' but the actual env var is GITLAB_TOKEN (as the same file's getGitLabToken confirms). Fixed to GITLAB_TOKEN. 2. (Medium) git/operations.mts: error suggested 'set SOCKET_CLI_GIT_PATH to point at a specific binary' — that env var is not read anywhere. Removed the false suggestion; kept the real fix (install git and put it on PATH) with package-manager examples. 3. (Low) terminal/iocraft.mts: '(e as Error).message' evaluates to undefined when a non-Error is thrown. Switched to 'e instanceof Error ? e.message : String(e)' for safe stringification. 4. (Low) gitlab-provider.mts: error said 'after ${retries} retries' but the loop runs attempt 1..retries inclusive — retries is the total attempt count, not retries beyond the first. Reworded to 'attempts'. Matching test assertions updated. Caught by #1260 bugbot review.

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.

- basics/vfs-extract.mts: missingTools list now renders as prose via joinAnd('a, b, and c'). - terminal/iocraft.mts: inline `e instanceof Error ? e.message : String(e)` swapped for getErrorCause(e). require() of a native binding can throw non-Error values, so the safe-stringify with UNKNOWN_ERROR fallback is correct here. No behavior change for Error throws.

socket-security-staging · 2026-04-23T00:07:24Z

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

John-David Dalton (jdalton) · 2026-04-23T01:14:05Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 579638d. Configure here.}

cursor Bot reviewed Apr 22, 2026

View reviewed changes

Comment thread packages/cli/src/utils/git/gitlab-provider.mts Outdated

Comment thread packages/cli/src/utils/git/operations.mts Outdated

Comment thread packages/cli/src/utils/terminal/iocraft.mts Outdated

Comment thread packages/cli/src/utils/git/gitlab-provider.mts Outdated

John-David Dalton (jdalton) force-pushed the jdd/error-msg-utils-misc branch from 2d9bec8 to 579638d Compare April 23, 2026 00:10

cursor Bot reviewed Apr 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

fix(cli): align utils/ miscellaneous error messages with 4-ingredient strategy#1260
John-David Dalton (jdalton) wants to merge 3 commits intomainfrom
jdd/error-msg-utils-misc

John-David Dalton (jdalton) commented Apr 22, 2026 •

edited by cursor Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

socket-security-staging Bot commented Apr 23, 2026 •

edited

Loading

Uh oh!

John-David Dalton (jdalton) commented Apr 23, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

John-David Dalton (jdalton) commented Apr 22, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's fixed

Flag validation (flags.mts)

Env-var decode (utils/config.mts)

SEA VFS extraction (utils/basics/vfs-extract.mts, 4 throws)

Library-level guards (4 throws in promise/queue, npm/spec, git/operations, fs/path-resolve)

GitLab provider (utils/git/gitlab-provider.mts, 2 throws)

Native-module load (utils/terminal/iocraft.mts)

Skipped (already informative)

Tests

Series complete

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

socket-security-staging Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

John-David Dalton (jdalton) commented Apr 23, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

John-David Dalton (jdalton) commented Apr 22, 2026 •

edited by cursor Bot

Loading

Flag validation (`flags.mts`)

Env-var decode (`utils/config.mts`)

SEA VFS extraction (`utils/basics/vfs-extract.mts`, 4 throws)

Library-level guards (4 throws in `promise/queue`, `npm/spec`, `git/operations`, `fs/path-resolve`)

GitLab provider (`utils/git/gitlab-provider.mts`, 2 throws)

Native-module load (`utils/terminal/iocraft.mts`)

socket-security-staging Bot commented Apr 23, 2026 •

edited

Loading