fix(build): enable sourcemap resolution for compiled binaries

Fix four issues preventing sourcemaps from working in Bun-compiled binaries:

1. Events had no debug_meta because the IIFE snippet was placed before
   ESM imports (invalid ESM). Register debug IDs at module scope via
   build-time constant instead.

2. Artifact bundle ZIPs lacked the SYSB magic header required by
   the symbolic crate's SourceBundle parser. Add the 8-byte header
   in ZipWriter.

3. Bun.build reformats code (3.7k → 40k lines), breaking sourcemap
   positions. Use sourcemap: "linked" to embed a map in the binary
   that Bun's runtime uses to auto-resolve Error.stack positions
   back to esbuild output coordinates.

4. Bun's embedded map produces relative paths in Error.stack (e.g.,
   "dist-bin/bin.js"). The symbolicator's URL candidate generator
   skips relative paths silently. Normalize to absolute in beforeSend.

Author: BYK

script/build.ts

@@ -38,7 +38,7 @@ import { $ } from "bun";
 import { build as esbuild } from "esbuild";
 import pkg from "../package.json";
 import { uploadSourcemaps } from "../src/lib/api/sourcemaps.js";
-import { injectDebugId } from "./debug-id.js";
+import { injectDebugId, PLACEHOLDER_DEBUG_ID } from "./debug-id.js";
 
 const gzipAsync = promisify(gzip);
 
@@ -104,13 +104,15 @@ async function bundleJs(): Promise<boolean> {
       target: "esnext",
       format: "esm",
       external: ["bun:*"],
-      sourcemap: "external",
+      sourcemap: "linked",
+      // Minify syntax and whitespace but NOT identifiers. Bun.build
       minify: true,
       metafile: true,
       define: {
         SENTRY_CLI_VERSION: JSON.stringify(VERSION),
         SENTRY_CLIENT_ID_BUILD: JSON.stringify(SENTRY_CLIENT_ID),
         "process.env.NODE_ENV": JSON.stringify("production"),
+        __SENTRY_DEBUG_ID__: JSON.stringify(PLACEHOLDER_DEBUG_ID),
       },
     });
 
@@ -147,20 +149,57 @@ async function bundleJs(): Promise<boolean> {
  * injection always runs (even without auth token) so local builds get
  * debug IDs for development/testing.
  */
-async function injectAndUploadSourcemap(): Promise<void> {
-  // Always inject debug IDs (even without auth token) so local builds
-  // get debug IDs for development/testing purposes.
+/** Module-level debug ID set by {@link injectDebugIds} for use in {@link uploadSourcemapToSentry}. */
+let currentDebugId: string | undefined;
+
+/**
+ * Inject debug IDs into the JS and sourcemap. Runs before compilation.
+ * The upload happens separately after compilation (see {@link uploadSourcemapToSentry}).
+ */
+async function injectDebugIds(): Promise<void> {
+  // skipSnippet: true — the IIFE snippet breaks ESM (placed before import
+  // declarations). The debug ID is instead registered in constants.ts via
+  // a build-time __SENTRY_DEBUG_ID__ constant.
   console.log("  Injecting debug IDs...");
-  let debugId: string;
   try {
-    ({ debugId } = await injectDebugId(BUNDLE_JS, SOURCEMAP_FILE));
+    const { debugId } = await injectDebugId(BUNDLE_JS, SOURCEMAP_FILE, {
+      skipSnippet: true,
+    });
+    currentDebugId = debugId;
     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;
   }
 
+  // Replace the placeholder UUID with the real debug ID in the JS bundle.
+  // Both are 36-char UUIDs so sourcemap character positions stay valid.
+  try {
+    const jsContent = await Bun.file(BUNDLE_JS).text();
+    await Bun.write(
+      BUNDLE_JS,
+      jsContent.split(PLACEHOLDER_DEBUG_ID).join(currentDebugId)
+    );
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `    Warning: Debug ID placeholder replacement failed: ${msg}`
+    );
+  }
+}
+
+/**
+ * Upload the (composed) sourcemap to Sentry. Runs after compilation
+ * because {@link compileTarget} composes the Bun sourcemap with the
+ * esbuild sourcemap first.
+ */
+async function uploadSourcemapToSentry(): Promise<void> {
+  const debugId = currentDebugId;
+  if (!debugId) {
+    return;
+  }
+
   if (!process.env.SENTRY_AUTH_TOKEN) {
     console.log("  No SENTRY_AUTH_TOKEN, skipping sourcemap upload");
     return;
@@ -169,7 +208,13 @@ async function injectAndUploadSourcemap(): Promise<void> {
   console.log(`  Uploading sourcemap to Sentry (release: ${VERSION})...`);
 
   try {
-    const urlPrefix = "~/$bunfs/root/";
+    // With sourcemap: "linked", Bun's runtime auto-resolves Error.stack
+    // paths via the embedded map, producing relative paths like
+    // "dist-bin/bin.js". The beforeSend hook normalizes these to absolute
+    // ("/dist-bin/bin.js") so the symbolicator's candidate URL generator
+    // produces "~/dist-bin/bin.js" — matching our upload URL.
+    const dir = BUNDLE_JS.slice(0, BUNDLE_JS.lastIndexOf("/") + 1);
+    const urlPrefix = `~/${dir}`;
     const jsBasename = BUNDLE_JS.split("/").pop() ?? "bin.js";
     const mapBasename = SOURCEMAP_FILE.split("/").pop() ?? "bin.js.map";
 
@@ -204,8 +249,11 @@ async function injectAndUploadSourcemap(): Promise<void> {
 /**
  * Step 2: Compile the pre-bundled JS into a native binary for a target.
  *
- * Uses the JS file produced by {@link bundleJs} — no sourcemap is embedded
- * in the binary (it's uploaded to Sentry separately).
+ * Uses the JS file produced by {@link bundleJs}. The esbuild sourcemap
+ * (JS → original TS) is uploaded to Sentry as-is — no composition needed
+ * because `sourcemap: "linked"` causes Bun to embed a sourcemap in the
+ * binary that its runtime uses to auto-resolve `Error.stack` positions
+ * back to the esbuild output's coordinate space.
  */
 async function compileTarget(target: BuildTarget): Promise<boolean> {
   const packageName = getPackageName(target);
@@ -215,6 +263,10 @@ async function compileTarget(target: BuildTarget): Promise<boolean> {
 
   console.log(`  Step 2: Compiling ${packageName}...`);
 
+  // Save the esbuild map before Bun.build overwrites it (sourcemap: "linked"
+  // writes Bun's own map to bin.js.map). We restore it after for upload.
+  const savedEsbuildMap = await Bun.file(SOURCEMAP_FILE).arrayBuffer();
+
   const result = await Bun.build({
     entrypoints: [BUNDLE_JS],
     compile: {
@@ -226,9 +278,14 @@ async function compileTarget(target: BuildTarget): Promise<boolean> {
         | "bun-windows-x64",
       outfile,
     },
-    // Already minified in Step 1 — skip re-minification to avoid
-    // double-minifying identifiers and producing different output.
-    minify: false,
+    // "linked" embeds a sourcemap in the binary. At runtime, Bun's engine
+    // auto-resolves Error.stack positions through this embedded map back to
+    // the esbuild output positions. The esbuild sourcemap (uploaded to
+    // Sentry) then maps those to original TypeScript sources.
+    sourcemap: "linked",
+    // Minify whitespace and syntax but NOT identifiers to avoid Bun's
+    // identifier renaming collision bug (oven-sh/bun#14585).
+    minify: { whitespace: true, syntax: true, identifiers: false },
   });
 
   if (!result.success) {
@@ -241,6 +298,9 @@ async function compileTarget(target: BuildTarget): Promise<boolean> {
 
   console.log(`    -> ${outfile}`);
 
+  // Restore the esbuild sourcemap (Bun.build overwrote it with its own map).
+  await Bun.write(SOURCEMAP_FILE, savedEsbuildMap);
+
   // Hole-punch: zero unused ICU data entries so they compress to nearly nothing.
   // Always runs so the smoke test exercises the same binary as the release.
   const hpStats = processBinary(outfile);
@@ -344,8 +404,10 @@ async function build(): Promise<void> {
     process.exit(1);
   }
 
-  // Inject debug IDs and upload sourcemap to Sentry before compiling (non-fatal on failure)
-  await injectAndUploadSourcemap();
+  // Inject debug IDs into the JS and sourcemap (non-fatal on failure).
+  // Upload happens AFTER compilation because Bun.build (with sourcemap: "linked")
+  // overwrites bin.js.map. We restore it from the saved copy before uploading.
+  await injectDebugIds();
 
   console.log("");
 
@@ -362,6 +424,9 @@ async function build(): Promise<void> {
     }
   }
 
+  // Step 3: Upload the composed sourcemap to Sentry (after compilation)
+  await uploadSourcemapToSentry();
+
   // Clean up intermediate bundle (only the binaries are artifacts)
   await $`rm -f ${BUNDLE_JS} ${SOURCEMAP_FILE}`;
 

script/bundle.ts

@@ -3,7 +3,7 @@ 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";
+import { injectDebugId, PLACEHOLDER_DEBUG_ID } from "./debug-id.js";
 
 const VERSION = pkg.version;
 const SENTRY_CLIENT_ID = process.env.SENTRY_CLIENT_ID ?? "";
@@ -67,7 +67,9 @@ async function injectDebugIdsForOutputs(
   for (const jsPath of jsFiles) {
     const mapPath = `${jsPath}.map`;
     try {
-      const { debugId } = await injectDebugId(jsPath, mapPath);
+      const { debugId } = await injectDebugId(jsPath, mapPath, {
+        skipSnippet: true,
+      });
       injected.push({ jsPath, mapPath, debugId });
       console.log(`  Debug ID injected: ${debugId}`);
     } catch (err) {
@@ -151,6 +153,16 @@ const sentrySourcemapPlugin: Plugin = {
         return;
       }
 
+      // Replace the placeholder UUID with the real debug ID in each JS output.
+      // Both are 36-char UUIDs so sourcemap character positions stay valid.
+      for (const { jsPath, debugId } of injected) {
+        const content = await Bun.file(jsPath).text();
+        await Bun.write(
+          jsPath,
+          content.split(PLACEHOLDER_DEBUG_ID).join(debugId)
+        );
+      }
+
       if (!process.env.SENTRY_AUTH_TOKEN) {
         return;
       }
@@ -194,6 +206,7 @@ const result = await build({
     SENTRY_CLI_VERSION: JSON.stringify(VERSION),
     SENTRY_CLIENT_ID_BUILD: JSON.stringify(SENTRY_CLIENT_ID),
     "process.env.NODE_ENV": JSON.stringify("production"),
+    __SENTRY_DEBUG_ID__: JSON.stringify(PLACEHOLDER_DEBUG_ID),
     // Replace import.meta.url with the injected shim variable for CJS
     "import.meta.url": "import_meta_url",
   },

script/debug-id.ts

@@ -10,3 +10,13 @@ export {
   getDebugIdSnippet,
   injectDebugId,
 } from "../src/lib/sourcemap/debug-id.js";
+
+/**
+ * Placeholder UUID used by esbuild's `define` for `__SENTRY_DEBUG_ID__`.
+ *
+ * After esbuild finishes and the real debug ID is computed from the
+ * sourcemap content hash, this placeholder is replaced in the JS output
+ * via `String.replaceAll`. The placeholder is exactly 36 characters
+ * (standard UUID length) so character positions in the sourcemap stay valid.
+ */
+export const PLACEHOLDER_DEBUG_ID = "00000000-0000-4000-a000-000000000000";

src/lib/constants.ts

@@ -7,6 +7,17 @@ import { getEnv } from "./env.js";
 /** Build-time constant injected by esbuild/bun */
 declare const SENTRY_CLI_VERSION: string | undefined;
 
+/**
+ * Build-time debug ID for sourcemap resolution, injected by esbuild.
+ *
+ * During the build, esbuild's `define` replaces this identifier with a
+ * placeholder UUID string literal. After esbuild finishes, the build
+ * script replaces the placeholder with the real debug ID (derived from
+ * the sourcemap content hash). The same-length swap keeps sourcemap
+ * character positions valid.
+ */
+declare const __SENTRY_DEBUG_ID__: string | undefined;
+
 /** Default Sentry SaaS hostname */
 export const DEFAULT_SENTRY_HOST = "sentry.io";
 
@@ -106,3 +117,31 @@ export function getUserAgent(): string {
  */
 export const SENTRY_CLI_DSN =
   "https://1188a86f3f8168f089450587b00bca66@o1.ingest.us.sentry.io/4510776311808000";
+
+/**
+ * Register the build-time debug ID with the Sentry SDK's native discovery.
+ *
+ * The SDK reads `globalThis._sentryDebugIds` (a map of Error.stack → debugId)
+ * during event processing to populate `debug_meta.images`, which the server
+ * uses to match uploaded sourcemaps.
+ *
+ * Previously this was done by a runtime IIFE snippet prepended to the bundle
+ * output by `injectDebugId()`. That broke ESM because the snippet appeared
+ * before `import` declarations. Placing the same logic here — inside the
+ * module, after all imports — is valid ESM and feeds the SDK's existing
+ * mechanism directly.
+ */
+if (typeof __SENTRY_DEBUG_ID__ !== "undefined") {
+  try {
+    // biome-ignore lint/suspicious/useErrorMessage: stack trace capture only
+    const stack = new Error().stack;
+    if (stack) {
+      // biome-ignore lint/suspicious/noExplicitAny: SDK reads this untyped global
+      const g = globalThis as any;
+      g._sentryDebugIds = g._sentryDebugIds || {};
+      g._sentryDebugIds[stack] = __SENTRY_DEBUG_ID__;
+    }
+  } catch (_) {
+    // Non-critical — sourcemap resolution degrades gracefully
+  }
+}

src/lib/sourcemap/debug-id.ts

@@ -64,22 +64,30 @@ export function getDebugIdSnippet(debugId: string): string {
  * Inject a Sentry debug ID into a JavaScript file and its companion
  * sourcemap.
  *
- * Performs four mutations:
+ * By default performs four mutations:
  * 1. Prepends the runtime snippet to the JS file (after any hashbang)
  * 2. Appends a `//# debugId=<uuid>` comment to the JS file
  * 3. Prepends a `;` to the sourcemap `mappings` (offsets by one line)
  * 4. Adds `debug_id` and `debugId` fields to the sourcemap JSON
  *
+ * When `options.skipSnippet` is `true`, step 1 is skipped and step 3
+ * is adjusted (no extra `;` prefix since no snippet line is added).
+ * This is used by the CLI's own build pipeline where the debug ID is
+ * registered in source code (`constants.ts`) instead of via the IIFE.
+ *
  * The operation is **idempotent** — files that already contain a
  * `//# debugId=` comment are returned unchanged.
  *
  * @param jsPath - Path to the JavaScript file
  * @param mapPath - Path to the companion `.map` file
+ * @param options - Optional settings
+ * @param options.skipSnippet - Skip the IIFE runtime snippet (steps 1 & 3)
  * @returns The debug ID and whether it was newly injected
  */
 export async function injectDebugId(
   jsPath: string,
-  mapPath: string
+  mapPath: string,
+  options?: { skipSnippet?: boolean }
 ): Promise<{ debugId: string; wasInjected: boolean }> {
   const [jsContent, mapContent] = await Promise.all([
     readFile(jsPath, "utf-8"),
@@ -94,21 +102,29 @@ export async function injectDebugId(
 
   // Generate debug ID from the sourcemap content (deterministic)
   const debugId = contentToDebugId(mapContent);
-  const snippet = getDebugIdSnippet(debugId);
+  const skipSnippet = options?.skipSnippet ?? false;
 
   // --- Mutate JS file ---
-  // Preserve hashbang if present, insert snippet after it
   let newJs: string;
-  if (jsContent.startsWith("#!")) {
-    const newlineIdx = jsContent.indexOf("\n");
-    // Handle hashbang without trailing newline (entire file is the #! line)
-    const splitAt = newlineIdx === -1 ? jsContent.length : newlineIdx + 1;
-    const hashbang = jsContent.slice(0, splitAt);
-    const rest = jsContent.slice(splitAt);
-    const sep = newlineIdx === -1 ? "\n" : "";
-    newJs = `${hashbang}${sep}${snippet}\n${rest}`;
+  if (skipSnippet) {
+    // Metadata-only mode: just append the debugId comment, no IIFE snippet.
+    // Used by the CLI's own build where the debug ID is registered in source.
+    newJs = jsContent;
   } else {
-    newJs = `${snippet}\n${jsContent}`;
+    // Full mode: prepend the runtime IIFE snippet (for user-facing injection).
+    const snippet = getDebugIdSnippet(debugId);
+    // Preserve hashbang if present, insert snippet after it
+    if (jsContent.startsWith("#!")) {
+      const newlineIdx = jsContent.indexOf("\n");
+      // Handle hashbang without trailing newline (entire file is the #! line)
+      const splitAt = newlineIdx === -1 ? jsContent.length : newlineIdx + 1;
+      const hashbang = jsContent.slice(0, splitAt);
+      const rest = jsContent.slice(splitAt);
+      const sep = newlineIdx === -1 ? "\n" : "";
+      newJs = `${hashbang}${sep}${snippet}\n${rest}`;
+    } else {
+      newJs = `${snippet}\n${jsContent}`;
+    }
   }
   // Append debug ID comment at the end
   newJs += `\n${DEBUGID_COMMENT_PREFIX}${debugId}\n`;
@@ -120,10 +136,12 @@ export async function injectDebugId(
     debug_id?: string;
     debugId?: string;
   };
-  // Prepend one `;` to mappings — tells decoders "no mappings for the
-  // first line" (the injected snippet line). Each `;` in VLQ mappings
-  // represents a line boundary.
-  map.mappings = `;${map.mappings}`;
+  if (!skipSnippet) {
+    // Prepend one `;` to mappings — tells decoders "no mappings for the
+    // first line" (the injected snippet line). Each `;` in VLQ mappings
+    // represents a line boundary.
+    map.mappings = `;${map.mappings}`;
+  }
   map.debug_id = debugId;
   map.debugId = debugId;