fix(cli): Generate the idempotent operations list at build time

Go back to having generate:schema write the marked writes to the
gitignored src/generated/idempotent-operations.json instead of shipping
the whole @sentry/api catalog in the bundle.

The apps/local tests import CLI modules that reach sentry-client.ts and
ran before anything generated the file. Its test script now runs
ensure-generated.mjs first, the same bootstrap the CLI's own scripts use.

Chunk uploads keep their explicit opt-in: they post to the URL the
server's chunk-upload options return, which need not match the catalog
path.

Author: sentry-junior[bot]

apps/local/package.json

@@ -8,8 +8,8 @@
     "build": "tsc -b && vite build",
     "lint": "oxlint",
     "preview": "vite preview",
-    "test": "vitest run",
-    "test:integration": "vitest run src/App.integration.test.tsx",
+    "test": "pnpm --filter sentry exec node script/ensure-generated.mjs schema && vitest run",
+    "test:integration": "pnpm run test src/App.integration.test.tsx",
     "typecheck": "tsc -b",
     "sample": "tsx scripts/replay.ts"
   },

packages/cli/script/ensure-generated.mjs

@@ -18,7 +18,11 @@
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 
-const SCHEMA = "src/generated/api-schema.json";
+/** Produced by `generate:schema`; imported at runtime by `src/`. */
+const SCHEMA_OUTPUTS = [
+  "src/generated/api-schema.json",
+  "src/generated/idempotent-operations.json",
+];
 /** Produced by `generate:grammar`; imported by `src/lib/arg-parsing.ts`. */
 const GRAMMAR_OUTPUTS = [
   "src/generated/org-project-target-grammar.js",
@@ -35,7 +39,7 @@ function run(script) {
   execSync(`pnpm run ${script}`, { stdio: "inherit" });
 }
 
-if (!existsSync(SCHEMA)) {
+if (!SCHEMA_OUTPUTS.every(existsSync)) {
   run("generate:schema");
 }
 if (process.argv[2] !== "schema" && !GRAMMAR_OUTPUTS.every(existsSync)) {

packages/cli/script/generate-api-schema.ts

@@ -12,16 +12,22 @@
  * Also reads SDK function names from the installed @sentry/api package to
  * map operationIds to their TypeScript SDK function names.
  *
+ * Also reads the `@sentry/api/operations` catalog to list the non-safe
+ * operations Sentry marks idempotent (`x-sentry-idempotent`), which the
+ * authenticated fetch retries on transient failures.
+ *
  * Usage:
  *   tsx script/generate-api-schema.ts
  *
  * Output:
  *   src/generated/api-schema.json
+ *   src/generated/idempotent-operations.json
  */
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { operations } from "@sentry/api/operations";
 
 /** Resolve the root directory of @sentry/api by finding its main entry point. */
 function sentryApiDir(): string {
@@ -32,6 +38,7 @@ function sentryApiDir(): string {
 }
 
 const OUTPUT_PATH = "src/generated/api-schema.json";
+const IDEMPOTENT_OUTPUT_PATH = "src/generated/idempotent-operations.json";
 
 /**
  * Build the OpenAPI spec URL from the installed @sentry/api version.
@@ -53,6 +60,8 @@ const PATH_PARAM_PATTERN = /\{(\w+)\}/g;
 export type { ApiEndpoint } from "../src/lib/api-schema.js";
 
 import type { ApiEndpoint } from "../src/lib/api-schema.js";
+import type { IdempotentOperation } from "../src/lib/idempotent-operations.js";
+import { isRetryableMethod } from "../src/lib/retry-policy.js";
 
 // ---------------------------------------------------------------------------
 // OpenAPI Types (minimal subset we need)
@@ -231,3 +240,21 @@ await writeFile(OUTPUT_PATH, JSON.stringify(endpoints, null, 2));
 console.log(
   `Generated ${OUTPUT_PATH} (${endpoints.length} endpoints, ${Math.round(JSON.stringify(endpoints).length / 1024)}KB)`,
 );
+
+// Safe methods already retry, so only writes need listing; that keeps the
+// file the CLI loads on every request tiny.
+const idempotentOperations: IdempotentOperation[] = operations
+  .filter((op) => op.idempotent && !isRetryableMethod(op.method))
+  .map((op) => ({ method: op.method, path: op.path }))
+  .sort(
+    (a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method),
+  );
+
+await writeFile(
+  IDEMPOTENT_OUTPUT_PATH,
+  JSON.stringify(idempotentOperations, null, 2),
+);
+
+console.log(
+  `Generated ${IDEMPOTENT_OUTPUT_PATH} (${idempotentOperations.length} operations)`,
+);

packages/cli/src/global.d.ts

@@ -47,3 +47,8 @@ declare module "*/generated/api-schema.json" {
   const endpoints: unknown;
   export default endpoints;
 }
+
+declare module "*/generated/idempotent-operations.json" {
+  const operations: unknown;
+  export default operations;
+}

packages/cli/src/lib/idempotent-operations.ts

@@ -1,20 +1,28 @@
 /**
  * Writes Sentry declares safe to replay.
  *
- * Read from the `@sentry/api` operation catalog, which marks an operation
- * `idempotent` when Sentry sets the `x-sentry-idempotent` OpenAPI extension.
- * Endpoints opt in on the server, so the CLI does not hard-code which
- * assemble calls may retry.
+ * `script/generate-api-schema.ts` copies the non-safe operations that the
+ * `@sentry/api` catalog marks `idempotent` (from Sentry's
+ * `x-sentry-idempotent` OpenAPI extension). Endpoints opt in on the server,
+ * so the CLI does not hard-code which assemble calls may retry.
  */
 
-import { isRetryableMethod } from "./retry-policy.js";
+import generated from "../generated/idempotent-operations.json";
+
+/** A non-safe operation Sentry marks idempotent. */
+export type IdempotentOperation = {
+  /** Uppercase HTTP method */
+  method: string;
+  /** OpenAPI path template, such as `/api/0/organizations/{org}/chunk-upload/` */
+  path: string;
+};
 
 type Matcher = { method: string; pattern: RegExp };
 
 const TEMPLATE_SEGMENT = /^\{[^/]+\}$/;
 const REGEXP_SPECIAL = /[.*+?^${}()|[\]\\]/g;
 
-function toMatcher(method: string, path: string): Matcher {
+function toMatcher({ method, path }: IdempotentOperation): Matcher {
   const source = path
     .split("/")
     .map((segment) =>
@@ -23,34 +31,22 @@ function toMatcher(method: string, path: string): Matcher {
         : segment.replace(REGEXP_SPECIAL, "\\$&"),
     )
     .join("/");
-  return { method, pattern: new RegExp(`^${source}$`) };
+  return { method: method.toUpperCase(), pattern: new RegExp(`^${source}$`) };
 }
 
-/** Loaded on the first write so read-only commands never parse the catalog. */
-let matchers: Promise<Matcher[]> | undefined;
-
-async function loadMatchers(): Promise<Matcher[]> {
-  const { operations } = await import("@sentry/api/operations");
-  return operations
-    .filter((op) => op.idempotent && !isRetryableMethod(op.method))
-    .map((op) => toMatcher(op.method, op.path));
-}
+let matchers: Matcher[] | undefined;
 
 /**
- * Whether Sentry marks this write's operation idempotent.
+ * Whether Sentry marks this request's operation idempotent.
  *
  * Matches from the `/api/` segment on, so a self-hosted install served under
- * a path prefix still matches. Safe methods return false without loading the
- * catalog; they retry regardless.
+ * a path prefix still matches.
  *
  * @param method - HTTP method (any case)
  * @param url - Absolute request URL
  */
-export async function isIdempotentOperation(
-  method: string,
-  url: string,
-): Promise<boolean> {
-  if (isRetryableMethod(method) || !URL.canParse(url)) {
+export function isIdempotentOperation(method: string, url: string): boolean {
+  if (!URL.canParse(url)) {
     return false;
   }
   const pathname = new URL(url).pathname;
@@ -62,8 +58,8 @@ export async function isIdempotentOperation(
   const normalized = apiPath.endsWith("/") ? apiPath : `${apiPath}/`;
   const upper = method.toUpperCase();
 
-  matchers ??= loadMatchers();
-  return (await matchers).some(
+  matchers ??= (generated as IdempotentOperation[]).map(toMatcher);
+  return matchers.some(
     (matcher) => matcher.method === upper && matcher.pattern.test(normalized),
   );
 }

packages/cli/src/lib/sentry-client.ts

@@ -708,9 +708,10 @@ async function fetchWithRetry({
   }
   const attemptFactory = await buildAttemptFactory(input, init);
   const timeoutMs = resolveTimeoutMs(fullUrl);
-  const methodRetryable =
-    isRetryableMethod(method, idempotent) ||
-    (await isIdempotentOperation(method, fullUrl));
+  const methodRetryable = isRetryableMethod(
+    method,
+    idempotent || isIdempotentOperation(method, fullUrl),
+  );
   const urlPath = extractUrlPath(fullUrl);
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {

packages/cli/test/lib/idempotent-operations.test.ts

@@ -8,82 +8,74 @@ describe("isIdempotentOperation", () => {
     "/api/0/organizations/acme/chunk-upload/",
     "/api/0/organizations/acme/artifactbundle/assemble/",
     "/api/0/projects/acme/web/files/difs/assemble/",
-  ])("matches POST %s", async (path) => {
-    expect(await isIdempotentOperation("POST", `${REGION_URL}${path}`)).toBe(
-      true,
-    );
+  ])("matches POST %s", (path) => {
+    expect(isIdempotentOperation("POST", `${REGION_URL}${path}`)).toBe(true);
   });
 
-  test("ignores method case and a missing trailing slash", async () => {
+  test("ignores method case and a missing trailing slash", () => {
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "post",
         `${REGION_URL}/api/0/organizations/acme/chunk-upload`,
       ),
     ).toBe(true);
   });
 
-  test("matches under a self-hosted path prefix", async () => {
+  test("matches under a self-hosted path prefix", () => {
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "POST",
         "https://sentry.example.com/sentry/api/0/organizations/acme/chunk-upload/",
       ),
     ).toBe(true);
   });
 
-  test("ignores the query string", async () => {
+  test("ignores the query string", () => {
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "POST",
         `${REGION_URL}/api/0/organizations/acme/chunk-upload/?foo=bar`,
       ),
     ).toBe(true);
   });
 
-  test("does not match other methods on a marked path", async () => {
+  test("does not match other methods on a marked path", () => {
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "PUT",
         `${REGION_URL}/api/0/organizations/acme/chunk-upload/`,
       ),
     ).toBe(false);
   });
 
-  test("does not match writes Sentry leaves unmarked", async () => {
+  test("does not match writes Sentry leaves unmarked", () => {
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "POST",
         `${REGION_URL}/api/0/projects/acme/web/files/preprodartifacts/assemble/`,
       ),
     ).toBe(false);
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "POST",
         `${REGION_URL}/api/0/organizations/acme/issues/1/autofix/`,
       ),
     ).toBe(false);
   });
 
-  test("does not let a template segment span several path segments", async () => {
+  test("does not let a template segment span several path segments", () => {
     expect(
-      await isIdempotentOperation(
+      isIdempotentOperation(
         "POST",
         `${REGION_URL}/api/0/organizations/acme/extra/chunk-upload/`,
       ),
     ).toBe(false);
   });
 
-  test("returns false for safe methods, unparseable URLs, and non-API paths", async () => {
+  test("returns false for URLs it cannot parse or that are not API paths", () => {
+    expect(isIdempotentOperation("POST", "not a url")).toBe(false);
     expect(
-      await isIdempotentOperation(
-        "GET",
-        `${REGION_URL}/api/0/organizations/acme/chunk-upload/`,
-      ),
-    ).toBe(false);
-    expect(await isIdempotentOperation("POST", "not a url")).toBe(false);
-    expect(
-      await isIdempotentOperation("POST", `${REGION_URL}/organizations/acme/`),
+      isIdempotentOperation("POST", `${REGION_URL}/organizations/acme/`),
     ).toBe(false);
   });
 });