fix(polyfill): add missing Bun API polyfills for npm distribution (#637)

## Summary

- Add `Bun.file().size` and `.lastModified` polyfills — fixes DSN
auto-detection silently failing on npm (size guard bypassed, cache
invalidation broken)
- Add `Bun.spawnSync()` polyfill — fixes `sentry init` crashing on npm
when running git status checks
- Add `{ PATH }` option support to `Bun.which()` polyfill — fixes custom
PATH lookups being silently ignored in shell completion detection
- Fix incorrect JSDoc in `oauth.ts` referencing wrong esbuild define key
name

## Context

Audit of build-time replacement issues (similar to #627) found no
remaining `define` replacement bugs, but uncovered these silent failures
in the Node.js polyfill layer where code works on Bun but silently
breaks on the npm distribution.

Author: BYK

script/node-polyfills.ts

@@ -1,7 +1,12 @@
 /**
  * Node.js polyfills for Bun APIs. Injected at bundle time via esbuild.
  */
-import { execSync, spawn as nodeSpawn } from "node:child_process";
+import {
+  execSync,
+  spawn as nodeSpawn,
+  spawnSync as nodeSpawnSync,
+} from "node:child_process";
+import { statSync } from "node:fs";
 import { access, readFile, writeFile } from "node:fs/promises";
 // node:sqlite is imported lazily inside NodeDatabasePolyfill to avoid
 // crashing on Node.js versions without node:sqlite support when the
@@ -98,6 +103,22 @@ const bunSqlitePolyfill = { Database: NodeDatabasePolyfill };
 const BunPolyfill = {
   file(path: string) {
     return {
+      /** File size in bytes (synchronous, like Bun.file().size). Returns 0 for non-existent files. */
+      get size(): number {
+        try {
+          return statSync(path).size;
+        } catch {
+          return 0;
+        }
+      },
+      /** Last-modified time in ms since epoch (like Bun.file().lastModified). Returns 0 for non-existent files. */
+      get lastModified(): number {
+        try {
+          return statSync(path).mtimeMs;
+        } catch {
+          return 0;
+        }
+      },
       async exists(): Promise<boolean> {
         try {
           await access(path);
@@ -132,12 +153,22 @@ const BunPolyfill = {
     }
   },
 
-  which(command: string): string | null {
+  which(command: string, opts?: { PATH?: string }): string | null {
     try {
       const isWindows = process.platform === "win32";
       const cmd = isWindows ? `where ${command}` : `which ${command}`;
+      // If a custom PATH is provided, override it in the subprocess env.
+      // Use !== undefined (not truthy) so empty-string PATH is respected.
+      const env =
+        opts?.PATH !== undefined
+          ? { ...process.env, PATH: opts.PATH }
+          : undefined;
       return (
-        execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] })
+        execSync(cmd, {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "ignore"],
+          env,
+        })
           .trim()
           .split("\n")[0] || null
       );
@@ -146,6 +177,31 @@ const BunPolyfill = {
     }
   },
 
+  /**
+   * Synchronously spawn a subprocess. Matches Bun.spawnSync() used by
+   * git.ts for pre-flight checks in `sentry init`.
+   */
+  spawnSync(
+    cmd: string[],
+    opts?: {
+      stdout?: "pipe" | "ignore" | "inherit";
+      stderr?: "pipe" | "ignore" | "inherit";
+      cwd?: string;
+    }
+  ) {
+    const [command, ...args] = cmd;
+    const result = nodeSpawnSync(command, args, {
+      stdio: ["ignore", opts?.stdout ?? "ignore", opts?.stderr ?? "ignore"],
+      cwd: opts?.cwd,
+    });
+    return {
+      success: result.status === 0,
+      exitCode: result.status ?? 1,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  },
+
   spawn(
     cmd: string[],
     opts?: {

src/lib/oauth.ts

@@ -31,7 +31,7 @@ function getSentryUrl(): string {
 /**
  * OAuth client ID
  *
- * Build-time: Injected via Bun.build({ define: { SENTRY_CLIENT_ID: "..." } })
+ * Build-time: Injected via esbuild define: { SENTRY_CLIENT_ID_BUILD: "..." }
  * Runtime: Can be overridden via SENTRY_CLIENT_ID env var (for self-hosted)
  *
  * Read at call time (not module load time) so tests can override SENTRY_CLIENT_ID

test/script/node-polyfills.test.ts

@@ -1,8 +1,7 @@
 /**
- * Node.js Polyfill Tests — Bun.spawn and Bun.Glob
+ * Node.js Polyfill Tests — Bun.spawn, Bun.spawnSync, Bun.which, Bun.file, and Bun.Glob
  *
- * Tests the spawn and glob logic used by the Node.js polyfill in
- * script/node-polyfills.ts.
+ * Tests the logic used by the Node.js polyfill in script/node-polyfills.ts.
  *
  * We can't import the polyfill directly (it overwrites globalThis.Bun and has
  * side effects), so we reproduce the exact implementation and verify its
@@ -15,7 +14,14 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { spawn as nodeSpawn } from "node:child_process";
+import {
+  execSync,
+  spawn as nodeSpawn,
+  spawnSync as nodeSpawnSync,
+} from "node:child_process";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 /**
  * Reproduces the exact spawn logic from script/node-polyfills.ts.
@@ -226,3 +232,258 @@ describe("Glob polyfill match()", () => {
     }
   });
 });
+
+/**
+ * Reproduces the exact spawnSync logic from script/node-polyfills.ts.
+ * Kept in sync manually — if the polyfill changes, update this too.
+ */
+function polyfillSpawnSync(
+  cmd: string[],
+  opts?: {
+    stdout?: "pipe" | "ignore" | "inherit";
+    stderr?: "pipe" | "ignore" | "inherit";
+    cwd?: string;
+  }
+) {
+  const [command, ...args] = cmd;
+  const result = nodeSpawnSync(command, args, {
+    stdio: ["ignore", opts?.stdout ?? "ignore", opts?.stderr ?? "ignore"],
+    cwd: opts?.cwd,
+  });
+  return {
+    success: result.status === 0,
+    exitCode: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+describe("spawnSync polyfill", () => {
+  test("returns success: true for exit code 0", () => {
+    const result = polyfillSpawnSync(["node", "-e", "process.exit(0)"]);
+    expect(result.success).toBe(true);
+    expect(result.exitCode).toBe(0);
+  });
+
+  test("returns success: false for non-zero exit code", () => {
+    const result = polyfillSpawnSync(["node", "-e", "process.exit(42)"]);
+    expect(result.success).toBe(false);
+    expect(result.exitCode).toBe(42);
+  });
+
+  test("captures stdout when stdout: pipe", () => {
+    const result = polyfillSpawnSync(
+      ["node", "-e", 'process.stdout.write("hello")'],
+      { stdout: "pipe" }
+    );
+    expect(result.success).toBe(true);
+    expect(result.stdout.toString()).toBe("hello");
+  });
+
+  test("respects cwd option", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "polyfill-cwd-"));
+    try {
+      const result = polyfillSpawnSync(
+        ["node", "-e", "process.stdout.write(process.cwd())"],
+        {
+          stdout: "pipe",
+          cwd: tmpDir,
+        }
+      );
+      expect(result.success).toBe(true);
+      // Resolve symlinks (macOS /tmp → /private/tmp)
+      const expected = Bun.which("realpath")
+        ? execSync(`realpath "${tmpDir}"`, { encoding: "utf-8" }).trim()
+        : tmpDir;
+      const actual = Bun.which("realpath")
+        ? execSync(`realpath "${result.stdout.toString()}"`, {
+            encoding: "utf-8",
+          }).trim()
+        : result.stdout.toString();
+      expect(actual).toBe(expected);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("is consistent with Bun.spawnSync for git --version", () => {
+    const polyfill = polyfillSpawnSync(["git", "--version"], {
+      stdout: "pipe",
+    });
+    const bun = Bun.spawnSync(["git", "--version"], { stdout: "pipe" });
+    expect(polyfill.success).toBe(bun.success);
+    expect(polyfill.exitCode).toBe(bun.exitCode);
+    // Both should output something starting with "git version"
+    expect(polyfill.stdout.toString()).toStartWith("git version");
+    expect(bun.stdout.toString()).toStartWith("git version");
+  });
+});
+
+/**
+ * Reproduces the exact file() polyfill logic from script/node-polyfills.ts.
+ * Kept in sync manually — if the polyfill changes, update this too.
+ */
+function polyfillFile(path: string) {
+  return {
+    get size(): number {
+      try {
+        return statSync(path).size;
+      } catch {
+        return 0;
+      }
+    },
+    get lastModified(): number {
+      try {
+        return statSync(path).mtimeMs;
+      } catch {
+        return 0;
+      }
+    },
+  };
+}
+
+describe("file polyfill size and lastModified", () => {
+  test("size returns correct byte length", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "polyfill-file-"));
+    const filePath = join(tmpDir, "test.txt");
+    try {
+      writeFileSync(filePath, "hello world"); // 11 bytes
+      const pf = polyfillFile(filePath);
+      expect(pf.size).toBe(11);
+
+      // Verify consistency with Bun.file().size
+      expect(pf.size).toBe(Bun.file(filePath).size);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("size returns 0 for empty file", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "polyfill-file-"));
+    const filePath = join(tmpDir, "empty.txt");
+    try {
+      writeFileSync(filePath, "");
+      const pf = polyfillFile(filePath);
+      expect(pf.size).toBe(0);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("lastModified returns a recent timestamp in milliseconds", () => {
+    const before = Date.now();
+    const tmpDir = mkdtempSync(join(tmpdir(), "polyfill-file-"));
+    const filePath = join(tmpDir, "test.txt");
+    try {
+      writeFileSync(filePath, "data");
+      const after = Date.now();
+      const pf = polyfillFile(filePath);
+
+      // Should be between before and after (with 1s tolerance for slow CI)
+      expect(pf.lastModified).toBeGreaterThanOrEqual(before - 1000);
+      expect(pf.lastModified).toBeLessThanOrEqual(after + 1000);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("lastModified is consistent with Bun.file().lastModified", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "polyfill-file-"));
+    const filePath = join(tmpDir, "test.txt");
+    try {
+      writeFileSync(filePath, "data");
+      const pf = polyfillFile(filePath);
+      const bunMtime = Bun.file(filePath).lastModified;
+      // Both should be within 1ms of each other
+      expect(Math.abs(pf.lastModified - bunMtime)).toBeLessThanOrEqual(1);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("size returns 0 for non-existent file (matches Bun behavior)", () => {
+    const pf = polyfillFile("/tmp/__nonexistent_file_polyfill_test__");
+    expect(pf.size).toBe(0);
+    expect(pf.size).toBe(
+      Bun.file("/tmp/__nonexistent_file_polyfill_test__").size
+    );
+  });
+
+  test("lastModified returns 0 for non-existent file", () => {
+    const pf = polyfillFile("/tmp/__nonexistent_file_polyfill_test__");
+    expect(pf.lastModified).toBe(0);
+  });
+});
+
+/**
+ * Reproduces the exact which() polyfill logic from script/node-polyfills.ts
+ * with PATH option support.
+ * Kept in sync manually — if the polyfill changes, update this too.
+ */
+function polyfillWhich(
+  command: string,
+  opts?: { PATH?: string }
+): string | null {
+  try {
+    const isWindows = process.platform === "win32";
+    const cmd = isWindows ? `where ${command}` : `which ${command}`;
+    const env =
+      opts?.PATH !== undefined
+        ? { ...process.env, PATH: opts.PATH }
+        : undefined;
+    return (
+      execSync(cmd, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"],
+        env,
+      })
+        .trim()
+        .split("\n")[0] || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+describe("which polyfill with PATH option", () => {
+  test("finds command on default PATH", () => {
+    const result = polyfillWhich("node");
+    expect(result).not.toBeNull();
+    // Should match Bun.which
+    expect(result).toBe(Bun.which("node"));
+  });
+
+  test("returns null for nonexistent command", () => {
+    const result = polyfillWhich("__nonexistent_command_polyfill_test__");
+    expect(result).toBeNull();
+  });
+
+  test("returns null when PATH is empty string (matches Bun behavior)", () => {
+    // Empty-string PATH should be respected, not ignored as falsy
+    const result = polyfillWhich("node", { PATH: "" });
+    expect(result).toBeNull();
+    expect(result).toBe(Bun.which("node", { PATH: "" }));
+  });
+
+  test("returns null when PATH excludes command directory", () => {
+    // Use a valid but irrelevant directory so which finds nothing
+    const result = polyfillWhich("__nonexistent_command__", { PATH: "/tmp" });
+    expect(result).toBeNull();
+  });
+
+  test("passes env with custom PATH to execSync", () => {
+    // Verify the polyfill constructs the env correctly when PATH is provided
+    const withPath = polyfillWhich("node", { PATH: process.env.PATH });
+    const withoutPath = polyfillWhich("node");
+    // Both should find node when given the same PATH
+    expect(withPath).toBe(withoutPath);
+  });
+
+  test("PATH option changes search scope", () => {
+    // A nonexistent command should not be found regardless of PATH
+    const result = polyfillWhich("__does_not_exist_anywhere__", {
+      PATH: "/usr/bin:/usr/local/bin",
+    });
+    expect(result).toBeNull();
+  });
+});