fix(cli): exit 3 when the API rejects the key with HTTP 401

[Chase J (chajac)]

Note

PR body AI drafted & edited as needed

Overview of Changes

The documented exit-code contract maps code 3 to "QAWOLF_API_KEY is missing or invalid", but only the missing case honored it. A present-but-invalid key sailed past the local requireApiKey check, got a 401 from the API, and surfaced as the default exit 1 — so a CI wrapper branching on exit status misclassified a bad key as a test failure. Root cause: describeRequestError collapsed the structured wire error (which knows status: 401) into a display string, so the layer that picks exit codes had no auth signal left to act on.

• src/shell/platform/requestWithRetry.ts: PlatformFailure gains an optional exitCode, set when a failure kind maps to a documented CLI exit code; failureFields passes it through (omitted entirely when unset, like errorBody).
• src/shell/platform/describeErrors.ts: describeRequestError and describeIdentityError set exitCode: exitCodes.auth on HTTP 401 only, with comments recording why 403 is excluded.
• src/commands/auth/whoami.ts: the missing-key path returns exit 3, and the invalid-key path passes the identity failure's exit code through instead of flattening to the default.
• src/domains/publicApi/handle.ts: no change needed — the code flows through failureFields into withAuthContext's existing result.exitCode ?? 1 wiring, covering every generated public-API command at once.
• Test splits for the 250-line lint cap: whoami's failure-path tests moved to whoami.failures.test.ts; handle.test.ts's spec/ctx helpers extracted to handle.testUtils.ts.

Testing

bun run test
bun run typecheck
bun run lint
bun run format:check
bun run knip

• 7 new tests across describeErrors.test.ts, requestWithRetry.test.ts, handle.test.ts, createPlatformClient.callPublicApi.test.ts, and whoami.failures.test.ts: 401 resolves the auth exit code at each layer; 403/404/500, network, and timeout failures leave it unset; failureFields preserves it; both whoami failure paths return it.
• End-to-end against app.qawolf.com: QAWOLF_API_KEY=definitely_not_a_real_key > tag list and auth whoami both exit 3 (previously 1); a valid key still exits 0; a missing key still exits 3.

Checklist

• Changes follow the code style of this project
• Self-review completed
• Tests added/updated
• No breaking changes

[coderabbitai]

Warning

Review limit reached

Next included review available in 6 minutes.

View limit details

Limit details: You’ve used all 3 included reviews currently available. Your 43 included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: d6d37ca3-699b-4d39-a51b-28ce508a92d7

📥 Commits

Reviewing files that changed from the base of the PR and between b557313 and b5673eb.

📒 Files selected for processing (11)

• .changeset/invalid-key-exit-code.md
• src/commands/auth/whoami.failures.test.ts
• src/commands/auth/whoami.test.ts
• src/commands/auth/whoami.ts
• src/domains/publicApi/handle.test.ts
• src/domains/publicApi/handle.testUtils.ts
• src/shell/platform/createPlatformClient.callPublicApi.test.ts
• src/shell/platform/describeErrors.test.ts
• src/shell/platform/describeErrors.ts
• src/shell/platform/requestWithRetry.test.ts
• src/shell/platform/requestWithRetry.ts

---

_{Comment @coderabbitai help to get the list of available commands.}