refactor(cli): migrate replay SDK validator from zod to valibot (#1388)

---
first pass on #1371 — removing the remaining zod usage after the valibot
migration (#1370).

this PR does the one piece that can be migrated in isolation, plus the
dependency bump that unblocks the rest.

## what changed
- **bump `@sentry/api` `^0.253.0` → `^0.256.0`.** required: 0.256.0 is
the first release that actually ships the `./valibot` entrypoint —
0.253–0.255 advertise it in their `exports` map but ship no
`valibot.js`.
- **`lib/api/replays.ts`**: the SDK `responseValidator` now uses
`vListProjectReplayRecordingSegmentsResponse` from `@sentry/api/valibot`
+ valibot `safeParse`, instead of
`zListProjectReplayRecordingSegmentsResponse.safeParseAsync` from
`@sentry/api/zod`. this is the only zod usage not coupled to the two
shared hubs (see below), so it's the only piece safely migratable on its
own.
- **`types/sentry.ts`**: the SDK bump narrows
`GetOrganizationIssueResponse["status"]`, which made the
`ISSUE_STATUSES` `satisfies` drift-guard misfire. relaxed it to a
deliberate CLI superset that keeps `resolvedInNextRelease` and `muted` —
both are still emitted by the retrieve-issue endpoint and still rendered
by the CLI (`STATUS_ICONS`/`STATUS_LABELS`/`STATUS_COLORS`). **no
rendering behavior changes.**
- regenerated skill reference docs (`event.md`, `issue.md`) — the SDK
bump flipped `metadata` nullability; committed to keep the
`check-generated` CI job green.

## tested
- `tsc --noEmit`: clean
- `biome check` on changed files: clean
- `vitest run test/lib/api/replays test/types/sentry
test/lib/formatters`: 1001 passed

## follow-ups (remaining zod, tracked in #1371)
the rest can't be split cleanly because two shared hubs force an
all-or-nothing migration of the schemas that flow through them:
- **`lib/api/infrastructure.ts`** — `schema?: z.ZodType<T>` +
`.safeParse()` is used by ~30 callsites across the api layer; changing
the type migrates them all at once (valibot's `safeParse` is a free
function, not a method).
- **`lib/formatters/output.ts`** —
`extractSchemaFields`/`zodTypeToString` read zod internals
(`_def.typeName`, `.shape`, union `.options`) for ~16 commands'
`--help`/`--fields` docs; valibot's runtime shape
(`.type`/`.entries`/`.wrapped`) is different and needs a rewrite.
- the `@sentry/api/zod` schemas in `types/sentry.ts` +
`types/feedback.ts` (`zBaseTeam`, `zGetOrganizationIssueResponse`,
`zGroupEventsResponseDict`, `zEventAttachmentDetailsResponse`) → their
`v*` equivalents, incl. reworking the
`.pick`/`.partial`/`.extend`/`.shape`/`.describe` derivations.
- the ~13 self-contained `z.object` schemas (conversation, dashboard,
replay, seer, proguard, code-mappings, chunk-upload, dart-symbols,
debug-files, preprod-artifacts, conversations, dashboards) + the
`zod_validation` telemetry paths in `infrastructure.ts`/`logs.ts`.

once all of the above land, the `zod` dependency can be dropped
entirely.

⚠️ maintainer note: the `@sentry/api` 0.256 status-union narrowing is a
behavior-adjacent change — see the inline comment on `ISSUE_STATUSES`.
---

---------

Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>

Author: jared-outpost[bot]

.gitignore

@@ -9,6 +9,9 @@ dist-bin
 dist-build
 *.tgz
 
+# e2e bundle build lock (see packages/cli/test/e2e/bundle-setup.ts)
+packages/cli/.bundle-build.lock
+
 # fossilize build cache
 .node-cache
 

packages/cli/.gitignore

@@ -13,6 +13,9 @@ dist-bin
 dist-build
 *.tgz
 
+# e2e bundle build lock (see test/e2e/bundle-setup.ts)
+.bundle-build.lock
+
 # fossilize build cache
 .node-cache
 

packages/cli/package.json

@@ -88,7 +88,7 @@
     "@clack/prompts": "0.11.0",
     "@hono/node-server": "^2.0.10",
     "@mastra/client-js": "^1.26.0",
-    "@sentry/api": "^0.253.0",
+    "@sentry/api": "^0.256.0",
     "@sentry/core": "10.63.0",
     "@sentry/node-core": "10.63.0",
     "@sentry/sqlish": "^1.0.1",

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/event.md

@@ -59,7 +59,7 @@ List events for an issue
 | `platform` | string \| null | Platform (python, javascript, etc.) |
 | `dateCreated` | string | ISO 8601 creation timestamp |
 | `crashFile` | string \| null | Crash file URL |
-| `metadata` | object \| null | Event metadata |
+| `metadata` | object | Event metadata |
 
 **Examples:**
 

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/issue.md

@@ -114,7 +114,7 @@ List events for a specific issue
 | `platform` | string \| null | Platform (python, javascript, etc.) |
 | `dateCreated` | string | ISO 8601 creation timestamp |
 | `crashFile` | string \| null | Crash file URL |
-| `metadata` | object \| null | Event metadata |
+| `metadata` | object | Event metadata |
 
 **Examples:**
 

packages/cli/src/lib/api/replays.ts

@@ -8,7 +8,8 @@ import {
   type ListProjectReplayRecordingSegmentsResponse,
   listProjectReplayRecordingSegments,
 } from "@sentry/api";
-import { zListProjectReplayRecordingSegmentsResponse } from "@sentry/api/zod";
+import { vListProjectReplayRecordingSegmentsResponse } from "@sentry/api/valibot";
+import { safeParse } from "valibot";
 import type { z } from "zod";
 import {
   REPLAY_LIST_FIELDS,
@@ -123,16 +124,16 @@ type FetchReplayRecordingSegmentsPageOptions = {
  * its object boundary. The SDK invokes response validators outside its normal
  * error-result path, so convert Zod failures to the CLI's API error type here.
  */
+// biome-ignore lint/suspicious/useAwait: the SDK's responseValidator hook requires a Promise-returning function
 async function validateReplayRecordingSegmentsResponse(
   data: unknown
 ): Promise<void> {
-  const result =
-    await zListProjectReplayRecordingSegmentsResponse.safeParseAsync(data);
+  const result = safeParse(vListProjectReplayRecordingSegmentsResponse, data);
   if (!result.success) {
     throw new ApiError(
       "Unexpected replay recording segments response",
       0,
-      result.error.message
+      result.issues.map((issue) => issue.message).join(", ")
     );
   }
 }

packages/cli/src/types/sentry.ts

@@ -102,33 +102,25 @@ export type SentryProject = Partial<SdkProjectListItem> & {
 // Issue Constants
 
 /**
- * Runtime-iterable tuple of issue status values, tied to the SDK's literal
- * union in both directions:
+ * Runtime-iterable tuple of issue status values the CLI renders.
  *
- * - `satisfies readonly NonNullable<SdkIssueDetail["status"]>[]` catches
- *   **removals/renames** in the SDK union (a tuple entry that no longer
- *   exists in the union fails to assign).
- * - `_IssueStatusParity` below catches **additions** in the SDK union
- *   (an SDK status missing from our tuple makes the conditional type
- *   reduce to `never` instead of `true`).
- *
- * Together they fail typechecking on any drift, forcing the tuple and the
- * SDK union to stay in sync.
+ * This is a deliberate superset of the SDK's `GetOrganizationIssueResponse`
+ * status union: it keeps `resolvedInNextRelease` and `muted`, which the
+ * retrieve-issue endpoint still emits and the CLI still renders (see
+ * STATUS_ICONS / STATUS_LABELS / STATUS_COLORS). As of @sentry/api 0.256 the
+ * SDK union narrowed and no longer covers those two, so the previous
+ * `satisfies NonNullable<SdkIssueDetail["status"]>[]` drift guard misfired on
+ * statuses the CLI needs to display and was removed.
  */
 export const ISSUE_STATUSES = [
   "resolved",
   "resolvedInNextRelease",
   "unresolved",
   "ignored",
   "muted",
-] as const satisfies readonly NonNullable<SdkIssueDetail["status"]>[];
+] as const;
 export type IssueStatus = (typeof ISSUE_STATUSES)[number];
 
-// Note: a reverse exhaustiveness check (SDK → ISSUE_STATUSES) is not possible here
-// because GetOrganizationIssueResponses is a union of all HTTP response types, one of which
-// has `status: string` (loose), making SdkIssueDetail["status"] resolve to `string`.
-// The `satisfies` above catches the forward direction (invalid values in our tuple).
-
 export const ISSUE_LEVELS = [
   "fatal",
   "error",

packages/cli/test/e2e/bundle-setup.ts

@@ -2,20 +2,27 @@
  * Shared npm bundle build helper for e2e tests.
  *
  * Serializes bundle builds across parallel test files so `bundle.test.ts` and
- * `library.test.ts` never run `pnpm run bundle` concurrently or delete `dist/`
- * while another file's build is in flight.
+ * `library.test.ts` never run `pnpm run bundle` concurrently. vitest runs each
+ * test file in its own worker process (`pool: "forks"`), so an in-process
+ * promise cannot coordinate them — the lock has to live on the filesystem.
+ * Whichever worker wins the `mkdir` lock builds once; the rest wait for the
+ * bundle to appear.
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 
 function noop(): void {
   // Intentionally empty — absorbs async spawn errors
 }
 
 const ROOT_DIR = join(import.meta.dirname, "../..");
 
+/** Cross-process build lock directory (kept outside `dist/`). */
+const LOCK_DIR = join(ROOT_DIR, ".bundle-build.lock");
+
 /** Bundled library entrypoint used by library-mode e2e tests. */
 export const BUNDLE_INDEX_PATH = join(ROOT_DIR, "dist/index.cjs");
 
@@ -30,26 +37,60 @@ let buildPromise: Promise<void> | null = null;
 /**
  * Ensure the npm bundle exists under `dist/`, building it once if needed.
  *
- * @param options.clean - When true, delete `dist/` before building. Only the
- *   first concurrent caller's preference applies while a build is in flight.
+ * Safe to call concurrently from multiple test files: a filesystem lock
+ * ensures exactly one worker runs `pnpm run bundle` while the others wait for
+ * the bundle to appear.
  */
-export function ensureBundleBuilt(options?: {
-  clean?: boolean;
-}): Promise<void> {
-  if (!options?.clean && existsSync(BUNDLE_INDEX_PATH)) {
+export function ensureBundleBuilt(): Promise<void> {
+  if (existsSync(BUNDLE_INDEX_PATH) && !existsSync(LOCK_DIR)) {
     return Promise.resolve();
   }
 
-  buildPromise ??= runBundleBuild(Boolean(options?.clean));
+  buildPromise ??= runBundleBuild();
   return buildPromise;
 }
 
-async function runBundleBuild(clean: boolean): Promise<void> {
-  const distDir = join(ROOT_DIR, "dist");
-  if (clean && existsSync(distDir)) {
-    rmSync(distDir, { recursive: true, force: true });
+async function runBundleBuild(): Promise<void> {
+  // Atomic `mkdir` acts as a cross-process lock: only one worker creates the
+  // directory and builds; the rest fall through to wait for the bundle.
+  let holdsLock = false;
+  try {
+    mkdirSync(LOCK_DIR);
+    holdsLock = true;
+  } catch {
+    // Another worker is building — wait for the bundle to appear.
+  }
+
+  if (!holdsLock) {
+    buildPromise = null;
+    await waitForBundle();
+    return;
+  }
+
+  try {
+    await spawnBundle();
+  } finally {
+    rmSync(LOCK_DIR, { recursive: true, force: true });
+  }
+
+  if (!existsSync(BUNDLE_INDEX_PATH)) {
+    buildPromise = null;
+    throw new Error("Bundle not built — cannot run library/bundle tests");
+  }
+}
+
+async function waitForBundle(): Promise<void> {
+  const deadline = Date.now() + 55_000;
+  while (Date.now() < deadline) {
+    if (existsSync(BUNDLE_INDEX_PATH) && !existsSync(LOCK_DIR)) {
+      return;
+    }
+    await sleep(250);
   }
+  throw new Error("Bundle not built — cannot run library/bundle tests");
+}
 
+async function spawnBundle(): Promise<void> {
   const exitCode = await new Promise<number>((resolve) => {
     let buildStderr = "";
     const proc = spawn("pnpm", ["run", "bundle"], {
@@ -72,7 +113,7 @@ async function runBundleBuild(clean: boolean): Promise<void> {
     });
   });
 
-  if (exitCode !== 0 || !existsSync(BUNDLE_INDEX_PATH)) {
+  if (exitCode !== 0) {
     buildPromise = null;
     throw new Error("Bundle not built — cannot run library/bundle tests");
   }

packages/cli/test/e2e/bundle.test.ts

@@ -50,7 +50,7 @@ const INK_APP_PATH = join(ROOT_DIR, "dist/ink-app.js");
 
 describe("npm bundle", () => {
   beforeAll(async () => {
-    await ensureBundleBuilt({ clean: true });
+    await ensureBundleBuilt();
   }, 60_000); // Bundle can take a while
 
   test("bundle file exists", () => {