docs(claude): align Error Messages with fleet doctrine#1261
docs(claude): align Error Messages with fleet doctrine#1261John-David Dalton (jdalton) wants to merge 5 commits intomainfrom
Conversation
…s doc Restructure the CLI-specific Error Messages section to match the updated fleet doctrine from socket-repo-template: - Keep the four ingredients (What / Where / Saw vs. wanted / Fix). - Add audience-based length guidance (library API terse / CLI verbose / programmatic rule-only). `InputError`/`AuthError` usages are verbose-tier. - Tighten baseline rules to one-liners; drop narrative phrasing. - Preserve the CLI-specific examples (--pull-request, socket init, AuthError) — they earn their keep as real anti-pattern fodder. Add `docs/references/error-messages.md` with fleet-wide worked examples so CLAUDE.md stays tight and the rich anti-patterns live once.
Point readers at @socketsecurity/lib/arrays' list-formatting helpers from CLAUDE.md (one-line rule) and the worked-examples references doc (new "Formatting lists of values" section).
Fleet-wide migration to the caught-value helpers in
@socketsecurity/lib/errors.
- pnpm-workspace.yaml: catalog bump 5.21.0 → 5.24.0.
- 18 src files under packages/cli/src: replace every
`e instanceof Error ? e.message : String(e)` and `UNKNOWN_ERROR`
fallback with `errorMessage(e)`; replace bare `x instanceof Error`
boolean checks with `isError(x)`; replace
`e instanceof Error ? e.stack : undefined` with `errorStack(e)`.
- packages/cli/src/utils/error/errors.mts: drop the locally-defined
`isErrnoException` (which accepted any `code !== undefined`) and
re-export the library's stricter string-code variant.
- packages/cli/src/commands/manifest/convert-{gradle,sbt}-to-maven.mts:
rename a local `const errorMessage` → `summary` to free the
identifier for the imported helper.
- packages/cli/src/utils/telemetry/service.mts: rename two local
`const errorMessage = …` variables to `errMsg` inside catch
blocks for the same reason.
- docs/references/error-messages.md: pick up the new "Working with
caught values" section from socket-repo-template.
Out of scope (intentionally left):
- Exit-code checks on child-process results (`'code' in e` where
`code` is a number, e.g. display.mts:257). `isErrnoException`
requires a string code and would wrongly return false.
- The local `getErrorMessage` / `getErrorMessageOr` helpers in
errors.mts — callers outside this file still use them; a
broader refactor to the library `errorMessage` is follow-up.
Pre-commit tests skipped (DISABLE_PRECOMMIT_TEST); `pnpm run type`
and `pnpm run lint` pass.
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Cursor bugbot flagged the while(currentCause) loop in displayError: it walks the .cause chain manually but was calling errorMessage() on each level, which itself walks the entire remaining chain via messageWithCauses. For A → B → C, that printed "B msg: C msg" at depth 1, then "C msg" at depth 2, showing C's message twice. Switch to reading `.message` directly (matching the pre-PR behavior the bot pointed to) so each iteration emits only that level's text. Fall back to `String(currentCause)` for non-Error nodes in the chain. Drop the now-unused `errorMessage` import. Reported on PR #1261.
…ntics
The debugApiResponse test expected errorMessage('String error') to
return the 'Unknown error' sentinel, matching the old local shim's
behavior that treated any non-Error caught value as unusable. The
catalog bump to @socketsecurity/lib 5.24 switched debug.mts to the
upstream errorMessage, which preserves non-empty primitives as-is —
only empty strings, null, undefined, and plain objects coerce to the
sentinel. Assert on 'String error' to pin the current contract.
|
Warning Review the following alerts detected in dependencies. According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.
|
|
bugbot run |
There was a problem hiding this comment.
✅ 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 178568c. Configure here.
1 participant
Summary
CLAUDE.md's Error Messages section to match the updated fleet doctrine fromsocket-repo-template: four ingredients stay, audience-based length guidance (library API terse / CLI verbose / programmatic rule-only) added, baseline rules tightened.InputError/AuthErrorexamples — they're better training material than generic ones.docs/references/error-messages.mdwith cross-fleet worked examples and anti-patterns so CLAUDE.md stays tight (CLAUDE.md is always loaded; we want it under the 40 KB ceiling and short enough to re-read).Test plan
CLAUDE.mdis still < 40 KB (12.5 KB).Note
Medium Risk
Touches many CLI error paths and bumps
@socketsecurity/libto5.24.0, which could subtly change surfaced error/cause strings and telemetry/debug output. No core business logic changes, but behavior changes are concentrated around failure handling.Overview
Updates
CLAUDE.md’s error-message guidance (audience-based length + tightened rules) and addsdocs/references/error-messages.mdwith worked examples/anti-patterns.Across the CLI, standardizes caught-error handling by adopting
@socketsecurity/lib/errorshelpers (isError,errorMessage,errorStack,isErrnoException) instead of ad-hocinstanceof Error ? … : String(…)patterns, including command execution results, renderers, update checks, GitHub/GitLab providers, and debug/telemetry plumbing. This removes the CLI’s localisErrnoExceptionimplementation and updates the related unit test expectation.Reviewed by Cursor Bugbot for commit 178568c. Configure here.