feat: native debug ID injection and sourcemap upload (#543)

## Summary

Replace `npx @sentry/cli sourcemaps inject` and `@sentry/esbuild-plugin`
with native TypeScript implementations. **Zero new dependencies** — only
uses `node:crypto`, `node:fs/promises`, `node:zlib`, and existing
`p-limit`.

## What changed

### Debug ID Injection (`script/debug-id.ts`)
- `contentToDebugId()`: SHA-256 → UUID v4 (byte-for-byte compatible with
`@sentry/bundler-plugin-core`'s `stringToUUID`, verified against the
actual package)
- `getDebugIdSnippet()`: Runtime IIFE that registers debug IDs in
`globalThis._sentryDebugIds`
- `injectDebugId()`: Injects snippet + comment into JS, adjusts
sourcemap mappings, adds `debugId`/`debug_id` fields
- Idempotent, hashbang-safe, always runs (even without
`SENTRY_AUTH_TOKEN`)

### Streaming ZIP Builder (`src/lib/sourcemap/zip.ts`)
- Writes entries to disk via `node:fs/promises` `FileHandle` — only one
compressed entry in memory at a time
- Uses raw DEFLATE (`node:zlib`) for compression, STORE for empty files
- Produces valid ZIP archives extractable by standard tools

### Sourcemap Upload API (`src/lib/api/sourcemaps.ts`)
- Implements Sentry's chunk-upload + assemble protocol natively
- Parallel chunk uploads via `p-limit` with server-configured
concurrency
- Gzip compression for chunks (server only supports gzip — verified on
US and DE regions)
- Streaming: reads ZIP back in 8MB chunks for upload, never holds full
bundle in memory

### Build Pipeline
- `script/build.ts`: Uses native injection + upload (removed
`execSync('npx @sentry/cli ...')`)
- `script/bundle.ts`: Custom `sentrySourcemapPlugin` esbuild plugin
replaces `@sentry/esbuild-plugin`

### Dependency Removal
- `@sentry/esbuild-plugin` removed from devDependencies
- Its transitive `@sentry/cli` (Rust binary) dependency is eliminated

## Tests
- 13 tests for debug-id (5 property-based, 8 unit)
- 10 tests for ZipWriter (2 property-based, 5 unit, 3 binary format)

## Follow-up (PR 3)
User-facing CLI commands (`sentry sourcemap inject/upload`) with
worker-based parallel processing — tracked separately.

Author: BYK

AGENTS.md

@@ -11,7 +11,6 @@
     "@clack/prompts": "^0.11.0",
     "@mastra/client-js": "^1.4.0",
     "@sentry/api": "^0.54.0",
-    "@sentry/esbuild-plugin": "^2.23.0",
     "@sentry/node-core": "10.44.0",
     "@stricli/auto-complete": "^1.2.4",
     "@stricli/core": "^1.2.4",

bun.lock

@@ -30,12 +30,13 @@
  *     bin.js.map          (sourcemap, uploaded to Sentry then deleted)
  */
 
-import { execSync } from "node:child_process";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
 import { processBinary } from "binpunch";
 import { $ } from "bun";
 import pkg from "../package.json";
+import { uploadSourcemaps } from "../src/lib/api/sourcemaps.js";
+import { injectDebugId } from "./debug-id.js";
 
 const gzipAsync = promisify(gzip);
 
@@ -117,33 +118,61 @@ async function bundleJs(): Promise<boolean> {
 }
 
 /**
- * Upload the sourcemap to Sentry for server-side stack trace resolution.
+ * Inject debug IDs and upload sourcemap to Sentry.
  *
- * Uses @sentry/cli's `sourcemaps upload` command. The sourcemap is associated
- * with the release version so Sentry matches it against incoming error events.
+ * Both injection and upload are done natively — no external binary needed.
+ * Uses the chunk-upload + assemble protocol for reliable artifact delivery.
  *
- * Requires SENTRY_AUTH_TOKEN environment variable. Skips gracefully when
- * not available (local builds, PR checks).
+ * Requires SENTRY_AUTH_TOKEN environment variable for upload. Debug ID
+ * injection always runs (even without auth token) so local builds get
+ * debug IDs for development/testing.
  */
-function uploadSourcemap(): void {
+async function injectAndUploadSourcemap(): Promise<void> {
+  // Always inject debug IDs (even without auth token) so local builds
+  // get debug IDs for development/testing purposes.
+  console.log("  Injecting debug IDs...");
+  let debugId: string;
+  try {
+    ({ debugId } = await injectDebugId(BUNDLE_JS, SOURCEMAP_FILE));
+    console.log(`    -> Debug ID: ${debugId}`);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.warn(`    Warning: Debug ID injection failed: ${msg}`);
+    return;
+  }
+
   if (!process.env.SENTRY_AUTH_TOKEN) {
     console.log("  No SENTRY_AUTH_TOKEN, skipping sourcemap upload");
     return;
   }
 
   console.log(`  Uploading sourcemap to Sentry (release: ${VERSION})...`);
 
-  // Single quotes prevent $bunfs shell expansion on POSIX (CI is always Linux).
   try {
-    // Inject debug IDs into JS + map, then upload with /$bunfs/root/ prefix
-    // to match Bun's compiled binary stack trace paths.
-    execSync("npx @sentry/cli sourcemaps inject dist-bin/", {
-      stdio: ["pipe", "pipe", "pipe"],
+    const urlPrefix = "~/$bunfs/root/";
+    const jsBasename = BUNDLE_JS.split("/").pop() ?? "bin.js";
+    const mapBasename = SOURCEMAP_FILE.split("/").pop() ?? "bin.js.map";
+
+    await uploadSourcemaps({
+      org: "sentry",
+      project: "cli",
+      release: VERSION,
+      files: [
+        {
+          path: BUNDLE_JS,
+          debugId,
+          type: "minified_source",
+          url: `${urlPrefix}${jsBasename}`,
+          sourcemapFilename: mapBasename,
+        },
+        {
+          path: SOURCEMAP_FILE,
+          debugId,
+          type: "source_map",
+          url: `${urlPrefix}${mapBasename}`,
+        },
+      ],
     });
-    execSync(
-      `npx @sentry/cli sourcemaps upload --org sentry --project cli --release ${VERSION} --url-prefix '/$bunfs/root/' ${BUNDLE_JS} ${SOURCEMAP_FILE}`,
-      { stdio: ["pipe", "pipe", "pipe"] }
-    );
     console.log("    -> Sourcemap uploaded to Sentry");
   } catch (error) {
     // Non-fatal: don't fail the build if upload fails
@@ -294,8 +323,8 @@ async function build(): Promise<void> {
     process.exit(1);
   }
 
-  // Upload sourcemap to Sentry before compiling (non-fatal on failure)
-  await uploadSourcemap();
+  // Inject debug IDs and upload sourcemap to Sentry before compiling (non-fatal on failure)
+  await injectAndUploadSourcemap();
 
   console.log("");
 

package.json

@@ -1,20 +1,9 @@
 #!/usr/bin/env bun
-/**
- * Bundle script for npm package
- *
- * Creates a single-file Node.js bundle using esbuild.
- * Injects Bun polyfills for Node.js compatibility.
- * Uploads source maps to Sentry when SENTRY_AUTH_TOKEN is available.
- *
- * Usage:
- *   bun run script/bundle.ts
- *
- * Output:
- *   dist/bin.cjs - Minified, single-file bundle for npm
- */
-import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";
+import { unlink } from "node:fs/promises";
 import { build, type Plugin } from "esbuild";
 import pkg from "../package.json";
+import { uploadSourcemaps } from "../src/lib/api/sourcemaps.js";
+import { injectDebugId } from "./debug-id.js";
 
 const VERSION = pkg.version;
 const SENTRY_CLIENT_ID = process.env.SENTRY_CLIENT_ID ?? "";
@@ -33,17 +22,15 @@ if (!SENTRY_CLIENT_ID) {
 const BUN_SQLITE_FILTER = /^bun:sqlite$/;
 const ANY_FILTER = /.*/;
 
-// Plugin to replace bun:sqlite with our node:sqlite polyfill
+/** Plugin to replace bun:sqlite with our node:sqlite polyfill. */
 const bunSqlitePlugin: Plugin = {
   name: "bun-sqlite-polyfill",
   setup(pluginBuild) {
-    // Intercept imports of "bun:sqlite" and redirect to our polyfill
     pluginBuild.onResolve({ filter: BUN_SQLITE_FILTER }, () => ({
       path: "bun:sqlite",
       namespace: "bun-sqlite-polyfill",
     }));
 
-    // Provide the polyfill content
     pluginBuild.onLoad(
       { filter: ANY_FILTER, namespace: "bun-sqlite-polyfill" },
       () => ({
@@ -59,30 +46,135 @@ const bunSqlitePlugin: Plugin = {
   },
 };
 
-// Configure Sentry plugin for source map uploads (production builds only)
-const plugins: Plugin[] = [bunSqlitePlugin];
+type InjectedFile = { jsPath: string; mapPath: string; debugId: string };
 
-if (process.env.SENTRY_AUTH_TOKEN) {
-  console.log("  Sentry auth token found, source maps will be uploaded");
-  plugins.push(
-    sentryEsbuildPlugin({
+/** Delete .map files after a successful upload — they shouldn't ship to users. */
+async function deleteMapFiles(injected: InjectedFile[]): Promise<void> {
+  for (const { mapPath } of injected) {
+    try {
+      await unlink(mapPath);
+    } catch {
+      // Ignore — file might already be gone
+    }
+  }
+}
+
+/** Inject debug IDs into JS outputs and their companion sourcemaps. */
+async function injectDebugIdsForOutputs(
+  jsFiles: string[]
+): Promise<InjectedFile[]> {
+  const injected: InjectedFile[] = [];
+  for (const jsPath of jsFiles) {
+    const mapPath = `${jsPath}.map`;
+    try {
+      const { debugId } = await injectDebugId(jsPath, mapPath);
+      injected.push({ jsPath, mapPath, debugId });
+      console.log(`  Debug ID injected: ${debugId}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(
+        `  Warning: Debug ID injection failed for ${jsPath}: ${msg}`
+      );
+    }
+  }
+  return injected;
+}
+
+/**
+ * Upload injected sourcemaps to Sentry via the chunk-upload protocol.
+ *
+ * @returns `true` if upload succeeded, `false` if it failed (non-fatal).
+ */
+async function uploadInjectedSourcemaps(
+  injected: InjectedFile[]
+): Promise<boolean> {
+  try {
+    console.log("  Uploading sourcemaps to Sentry...");
+    await uploadSourcemaps({
       org: "sentry",
       project: "cli",
-      authToken: process.env.SENTRY_AUTH_TOKEN,
-      release: {
-        name: VERSION,
-      },
-      sourcemaps: {
-        filesToDeleteAfterUpload: ["dist/**/*.map"],
-      },
-      // Don't fail the build if source map upload fails
-      errorHandler: (err) => {
-        console.warn("  Warning: Source map upload failed:", err.message);
-      },
-    })
-  );
+      release: VERSION,
+      files: injected.flatMap(({ jsPath, mapPath, debugId }) => {
+        const jsName = jsPath.split("/").pop() ?? "bin.cjs";
+        const mapName = mapPath.split("/").pop() ?? "bin.cjs.map";
+        return [
+          {
+            path: jsPath,
+            debugId,
+            type: "minified_source" as const,
+            url: `~/${jsName}`,
+            sourcemapFilename: mapName,
+          },
+          {
+            path: mapPath,
+            debugId,
+            type: "source_map" as const,
+            url: `~/${mapName}`,
+          },
+        ];
+      }),
+    });
+    console.log("  Sourcemaps uploaded to Sentry");
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`  Warning: Sourcemap upload failed: ${msg}`);
+    return false;
+  }
+}
+
+/**
+ * esbuild plugin that injects debug IDs and uploads sourcemaps to Sentry.
+ *
+ * Runs after esbuild finishes bundling (onEnd hook):
+ * 1. Injects debug IDs into each JS output + its companion .map
+ * 2. Uploads all artifacts to Sentry via the chunk-upload protocol
+ * 3. Deletes .map files after upload (they shouldn't ship to users)
+ *
+ * Replaces `@sentry/esbuild-plugin` with zero external dependencies.
+ */
+const sentrySourcemapPlugin: Plugin = {
+  name: "sentry-sourcemap",
+  setup(pluginBuild) {
+    pluginBuild.onEnd(async (buildResult) => {
+      const outputs = Object.keys(buildResult.metafile?.outputs ?? {});
+      const jsFiles = outputs.filter(
+        (p) => p.endsWith(".cjs") || (p.endsWith(".js") && !p.endsWith(".map"))
+      );
+
+      if (jsFiles.length === 0) {
+        return;
+      }
+
+      const injected = await injectDebugIdsForOutputs(jsFiles);
+      if (injected.length === 0) {
+        return;
+      }
+
+      if (!process.env.SENTRY_AUTH_TOKEN) {
+        return;
+      }
+
+      const uploaded = await uploadInjectedSourcemaps(injected);
+
+      // Only delete .map files after a successful upload — preserving
+      // them on failure allows retrying without a full rebuild.
+      if (uploaded) {
+        await deleteMapFiles(injected);
+      }
+    });
+  },
+};
+
+// Always inject debug IDs (even without auth token); upload is gated inside the plugin
+const plugins: Plugin[] = [bunSqlitePlugin, sentrySourcemapPlugin];
+
+if (process.env.SENTRY_AUTH_TOKEN) {
+  console.log("  Sentry auth token found, source maps will be uploaded");
 } else {
-  console.log("  No SENTRY_AUTH_TOKEN, skipping source map upload");
+  console.log(
+    "  No SENTRY_AUTH_TOKEN, debug IDs will be injected but source maps will not be uploaded"
+  );
 }
 
 const result = await build({