fix: surface actionable API errors instead of raw JSON dumps (BUG-2046)

[ClayMav]

Summary

Fixes BUG-2046: job-runs create failed during script upload with a generic request failed with HTTP 400: {raw json blob}, burying the only actionable part (InvalidInputException (No storage source found for bucket: ...)) and giving no hint about which step failed or what upload target was attempted.

The CLI builds the upload key correctly (verified against the live OpenAPI spec); the 400 is a server-side storage-source decision. This PR fixes the CLI-side problem: error surfacing.

Before

request failed with HTTP 400: {"errors":[{"code":"BAD_REQUEST_ERROR","message":"Bad Request","details":"InvalidInputException (No storage source found for bucket: qni7xwfc8m)","path":"/files/upload-url","suggestion":"Update your request and try again."}],"requestId":"3629d..."}

After (curated job-runs commands)

requesting upload URL for s3://wbts-wbc-bznimkgwml/qni7xwfc8m/data/shared/scripts/my-job/script.py: request failed with HTTP 400 (BAD_REQUEST_ERROR)
  message:    Bad Request
  details:    InvalidInputException (No storage source found for bucket: qni7xwfc8m)
  suggestion: Update your request and try again.
  request id: 3629d5f8a10139a4867c043509678f05

The upload path s3://wbts-wbc-bznimkgwml/... is not a registered storage source for your organization. To fix this:
  - omit --upload-path to upload to your organization's managed storage, or
  - use a path under a registered storage integration

After (dynamic api ... commands)

Machine-oriented api commands already emit success responses as raw JSON; they now emit the error envelope as raw, parseable JSON too:

{"errors":[{"code":"BAD_REQUEST_ERROR",...}],"requestId":"..."}

Commits

• feat(executor): render API error envelopes as readable errors — parse the standard envelope in HTTPError.Error(), multi-line rendering, exact fallback to prior strings for empty/non-JSON/non-envelope bodies; adds APIErrorDetails and JSONError
• feat(api): emit raw JSON error envelope from dynamic api commands — wrap HTTPError in JSONError in the generated-command path
• fix(jobs): explain upload-url failures with target and guidance — prepareScript wraps upload-url errors with the attempted s3://bucket/key; storage-source guidance only when an explicit --upload-path/WHEROBOTS_UPLOAD_PATH override hit a "No storage source found" error
• fix(executor): require standard shape before treating body as envelope — review follow-up: foreign {"errors":["..."]} payloads fall back to the raw body

Compatibility

• Exit codes unchanged; errors stay on stderr, success output untouched
• *executor.HTTPError struct unchanged; wrapping happens after execWithRetry, so isRetryable's direct type assertion is unaffected (covered by tests)
• Empty/non-JSON/non-envelope bodies keep byte-identical prior error strings (covered by tests)

Testing

• 12 new tests: envelope formatting + all fallbacks, JSONError unwrap semantics, api-command raw-JSON error, and 3 httptest job-runs create scenarios (explicit override w/ guidance, non-envelope w/o guidance, managed default w/o guidance)
• go test ./..., go vet, gofmt, pre-commit run --all-files all clean
• Manual: ran the exact ticket command against production — context line + multi-line envelope render correctly end-to-end

Deferred

Up-front client-side validation of --upload-path against org storage sources was considered and deliberately skipped: the server is the source of truth, pre-validation risks false blocks, and it would add API calls to a path that intentionally skips them. A non-blocking warning could be a follow-up if desired.

[notion-workspace]

🐛 The CLI says “Bad Request” like it’s your fault — but job-runs create can’t clearly explain the upload-path failure

[salty-hambot]

Reviewed by Salty Hambot 🤖🧂

Solid error-handling plumbing with good test coverage. One real callout: the wrapUploadURLError guidance hinges on a fragile English substring match against server prose — worth a comment acknowledging that tradeoff.

_{2 finding(s) posted · 2 filtered as false positives.
💬 To request a re-review, comment @salty-hambot review}