fix(api): throw ValidationError for user-input failures in api command (CLI-1GC) (#855)

## Summary

Fixes [CLI-1GC](https://sentry.sentry.io/issues/7444602558/): user runs
`sentry api ... --input /tmp/missing.json`, sees `Unexpected error:
Error: File not found: ...` with a full stack trace, and the error gets
captured to Sentry as a CLI bug.

## Root cause

`buildBodyFromInput()` in `src/commands/api.ts` throws a plain `new
Error()` when the `--input` file doesn't exist. Because this runs inside
the command's `func()` body (not a Stricli `parse` callback), it
bypasses the `CliError` handling chain in `app.ts`:

1. `classifySilenced()` doesn't recognize plain `Error` →
`Sentry.captureException` fires → reported as a CLI bug.
2. `exc instanceof CliError` is `false` → user sees `Unexpected error:`
+ stack trace instead of a clean message.

This is the same pattern documented in the lore entry _"api.ts: plain
Error throws inside func() bypass CliError handling"_ — same file, same
kind of bug across 7 call sites.

## Fix

Convert all 7 `func()`-path `throw new Error(...)` sites in
`src/commands/api.ts` to `throw new ValidationError(..., field)`:

| Function | `field` |
|----------|---------|
| `buildBodyFromInput` (file not found) | `"input"` |
| `parseHeaders` (bad header format) | `"header"` |
| `parseFieldKey` (bad key format) | `"field"` |
| `validatePathSegments` (dangerous/invalid keys) | `"field"` |
| `validateTypeCompatibility` (type conflicts) | `"field"` |

`parseMethod` (line 74) keeps `new Error()` — it runs in a Stricli
`parse` callback where Stricli catches and formats it.

After the fix:
- User sees a clean `Error: File not found: /tmp/missing.json` (no stack
trace).
- The error is silenced from Sentry telemetry as an expected user error.
- The `field` metadata enables stable Sentry grouping if any of these
surfaces do legitimately need attention.

## Test plan

- Updated existing `buildBodyFromInput` "throws for non-existent file"
test to assert `instanceof ValidationError`.
- `bun test test/commands/api.test.ts` — 203 pass.
- `bun test test/commands/api.property.test.ts` — 50 pass.
- `bun run lint`, `bun run typecheck` — clean.

Author: BYK

src/commands/api.ts

@@ -164,7 +164,7 @@ const BRACKET_CONTENTS_REGEX = /\[([^[\]]*)\]/g;
 export function parseFieldKey(key: string): string[] {
   const match = key.match(FIELD_KEY_REGEX);
   if (!match?.[1]) {
-    throw new Error(`Invalid field key format: ${key}`);
+    throw new ValidationError(`Invalid field key format: ${key}`, "field");
   }
 
   const baseKey = match[1];
@@ -190,14 +190,18 @@ function validatePathSegments(path: string[]): void {
 
     // Check for prototype pollution
     if (DANGEROUS_KEYS.has(segment)) {
-      throw new Error(`Invalid field key: "${segment}" is not allowed`);
+      throw new ValidationError(
+        `Invalid field key: "${segment}" is not allowed`,
+        "field"
+      );
     }
 
     // Empty brackets ("") are only valid at the end of the path (array push syntax)
     // Reject patterns like a[][b] which would silently lose data
     if (segment === "" && i < path.length - 1) {
-      throw new Error(
-        "Invalid field key: empty brackets [] can only appear at the end of a key"
+      throw new ValidationError(
+        "Invalid field key: empty brackets [] can only appear at the end of a key",
+        "field"
       );
     }
   }
@@ -249,14 +253,16 @@ function validateTypeCompatibility(
   const pathStr = formatPathForError(path, index);
 
   if (expectsArray && !Array.isArray(existing)) {
-    throw new Error(
-      `expected array type under "${pathStr}", got ${getTypeName(existing)}`
+    throw new ValidationError(
+      `expected array type under "${pathStr}", got ${getTypeName(existing)}`,
+      "field"
     );
   }
 
   if (!(expectsArray || isTraversableObject(existing))) {
-    throw new Error(
-      `expected map type under "${pathStr}", got ${getTypeName(existing)}`
+    throw new ValidationError(
+      `expected map type under "${pathStr}", got ${getTypeName(existing)}`,
+      "field"
     );
   }
 }
@@ -628,7 +634,10 @@ export function parseHeaders(headers: string[]): Record<string, string> {
   for (const header of headers) {
     const colonIndex = header.indexOf(":");
     if (colonIndex === -1) {
-      throw new Error(`Invalid header format: ${header}. Expected Key: Value`);
+      throw new ValidationError(
+        `Invalid header format: ${header}. Expected Key: Value`,
+        "header"
+      );
     }
 
     const key = header.substring(0, colonIndex).trim();
@@ -821,7 +830,7 @@ export async function buildBodyFromInput(
   } else {
     const file = Bun.file(inputPath);
     if (!(await file.exists())) {
-      throw new Error(`File not found: ${inputPath}`);
+      throw new ValidationError(`File not found: ${inputPath}`, "input");
     }
     content = await file.text();
   }

test/commands/api.test.ts

@@ -1039,12 +1039,12 @@ describe("buildBodyFromInput", () => {
     }
   });
 
-  test("throws for non-existent file", async () => {
+  test("throws ValidationError for non-existent file", async () => {
     const mockStdin = createMockStdin("");
 
     await expect(
       buildBodyFromInput("/nonexistent/path/file.json", mockStdin)
-    ).rejects.toThrow(/File not found/);
+    ).rejects.toBeInstanceOf(ValidationError);
   });
 });