@posthog/plugin-utils 1.1.3 → 2.0.0

package/dist/chunk-ids.d.ts

@@ -1,13 +1,18 @@
 /**
  * Returns the minified chunk-id IIFE the SDK reads at runtime to map an
- * error's stack back to a chunk id.
+ * error's stack back to a chunk id. With `releaseId`, the snippet also pins
+ * `_posthogReleaseId` on the global so the SDK emits the release on every
+ * exception (first write wins, so the first loaded chunk decides).
  *
- * Byte-for-byte contract with posthog-cli (`CODE_SNIPPET_TEMPLATE` in
- * cli/src/sourcemaps/constant.rs): the CLI recognizes and removes previously
- * injected snippets by exact substring match, so any change here must ship in
- * the CLI constants too. Covered by a parity test in chunk-ids.spec.ts.
+ * Byte-for-byte contract with posthog-cli (`CODE_SNIPPET_TEMPLATE` and
+ * `CODE_SNIPPET_WITH_RELEASE_TEMPLATE` in cli/src/sourcemaps/constant.rs): the
+ * CLI recognizes and removes previously injected snippets by exact substring
+ * match, so any change here must ship in the CLI constants too. Ids are
+ * JSON-encoded for the same reason the CLI encodes them: an id carrying a quote
+ * would otherwise break out of the string literal. Covered by a parity test in
+ * chunk-ids.spec.ts.
  */
-export declare function createChunkIdSnippet(chunkId: string): string;
+export declare function createChunkIdSnippet(chunkId: string, releaseId?: string): string;
 /**
  * Returns the comment posthog-cli discovers chunk ids from at upload time
  * (`CHUNKID_COMMENT_PREFIX` in cli/src/sourcemaps/constant.rs), including the
@@ -18,6 +23,17 @@ export declare function createChunkIdComment(chunkId: string): string;
  * Mints a fresh random chunk id: a new id per chunk, per build.
  */
 export declare function createChunkId(): string;
+/**
+ * Derives a chunk id from the chunk's own bytes (UUIDv5), so identical code keeps its id across
+ * rebuilds and re-uploads dedupe against the symbol set already stored. Used in event release
+ * mode, where the release travels inside the chunk instead of being bound to the symbol set, so
+ * a per-build random id would create a fresh symbol set on every build.
+ *
+ * The id is content-addressed over what `renderChunk` sees. posthog-cli derives its own ids from
+ * the file on disk, which by then also carries the trailing `sourceMappingURL` comment, so the
+ * same chunk gets a different (but equally stable) id depending on which tool injected it.
+ */
+export declare function createStableChunkId(code: string): string;
 /**
  * Extracts the chunk id from source that already carries one, using the same
  * detection the CLI uses: a `//# chunkId=` comment at the start of a line.

package/dist/chunk-ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk-ids.d.ts","sourceRoot":"","sources":["../src/chunk-ids.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AASD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa3E"}
+{"version":3,"file":"chunk-ids.d.ts","sourceRoot":"","sources":["../src/chunk-ids.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAMhF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAOD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUxD;AASD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa3E"}

package/dist/chunk-ids.js

@@ -24,14 +24,17 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    createStableChunkId: ()=>createStableChunkId,
     createChunkIdSnippet: ()=>createChunkIdSnippet,
     createChunkId: ()=>createChunkId,
     createChunkIdComment: ()=>createChunkIdComment,
     determineChunkIdFromSource: ()=>determineChunkIdFromSource
 });
 const external_crypto_namespaceObject = require("crypto");
-function createChunkIdSnippet(chunkId) {
-    return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]="${chunkId}")}catch(e){}}();`;
+function createChunkIdSnippet(chunkId, releaseId) {
+    const chunk = JSON.stringify(chunkId);
+    if (void 0 === releaseId) return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]=${chunk})}catch(e){}}();`;
+    return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{};e._posthogReleaseId=e._posthogReleaseId||${JSON.stringify(releaseId)};var n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]=${chunk})}catch(e){}}();`;
 }
 function createChunkIdComment(chunkId) {
     return `\n//# chunkId=${chunkId}`;
@@ -39,6 +42,15 @@ function createChunkIdComment(chunkId) {
 function createChunkId() {
     return external_crypto_namespaceObject.randomUUID();
 }
+const CHUNK_ID_NAMESPACE = '0e9b3c7a-5d1f-42a8-b6c4-e2d0f8a17593';
+function createStableChunkId(code) {
+    const namespace = Buffer.from(CHUNK_ID_NAMESPACE.replace(/-/g, ''), 'hex');
+    const hash = external_crypto_namespaceObject.createHash('sha1').update(namespace).update(code, 'utf8').digest();
+    hash[6] = 0x0f & hash[6] | 0x50;
+    hash[8] = 0x3f & hash[8] | 0x80;
+    const hex = hash.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
 const COMMENT_REGEX = /^\/\/# chunkId=(\S{1,128})/;
 const COMMENT_MARKER = '//# chunkId=';
 const WINDOW = 256;
@@ -52,11 +64,13 @@ function determineChunkIdFromSource(code) {
 exports.createChunkId = __webpack_exports__.createChunkId;
 exports.createChunkIdComment = __webpack_exports__.createChunkIdComment;
 exports.createChunkIdSnippet = __webpack_exports__.createChunkIdSnippet;
+exports.createStableChunkId = __webpack_exports__.createStableChunkId;
 exports.determineChunkIdFromSource = __webpack_exports__.determineChunkIdFromSource;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "createChunkId",
     "createChunkIdComment",
     "createChunkIdSnippet",
+    "createStableChunkId",
     "determineChunkIdFromSource"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {

package/dist/chunk-ids.mjs

@@ -1,6 +1,8 @@
-import { randomUUID } from "crypto";
-function createChunkIdSnippet(chunkId) {
-    return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]="${chunkId}")}catch(e){}}();`;
+import { createHash, randomUUID } from "crypto";
+function createChunkIdSnippet(chunkId, releaseId) {
+    const chunk = JSON.stringify(chunkId);
+    if (void 0 === releaseId) return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]=${chunk})}catch(e){}}();`;
+    return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{};e._posthogReleaseId=e._posthogReleaseId||${JSON.stringify(releaseId)};var n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]=${chunk})}catch(e){}}();`;
 }
 function createChunkIdComment(chunkId) {
     return `\n//# chunkId=${chunkId}`;
@@ -8,6 +10,15 @@ function createChunkIdComment(chunkId) {
 function createChunkId() {
     return randomUUID();
 }
+const CHUNK_ID_NAMESPACE = '0e9b3c7a-5d1f-42a8-b6c4-e2d0f8a17593';
+function createStableChunkId(code) {
+    const namespace = Buffer.from(CHUNK_ID_NAMESPACE.replace(/-/g, ''), 'hex');
+    const hash = createHash('sha1').update(namespace).update(code, 'utf8').digest();
+    hash[6] = 0x0f & hash[6] | 0x50;
+    hash[8] = 0x3f & hash[8] | 0x80;
+    const hex = hash.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
 const COMMENT_REGEX = /^\/\/# chunkId=(\S{1,128})/;
 const COMMENT_MARKER = '//# chunkId=';
 const WINDOW = 256;
@@ -18,4 +29,4 @@ function determineChunkIdFromSource(code) {
         if (match) return match[1];
     }
 }
-export { createChunkId, createChunkIdComment, createChunkIdSnippet, determineChunkIdFromSource };
+export { createChunkId, createChunkIdComment, createChunkIdSnippet, createStableChunkId, determineChunkIdFromSource };

package/dist/cli.d.ts

@@ -28,4 +28,12 @@ export declare function runSourcemapCli(config: ResolvedPluginConfig, options: (
 }) & {
     command?: SourcemapCliCommand;
 }): Promise<void>;
+/**
+ * Resolves the release this build belongs to, creating it if it doesn't exist yet, and returns its
+ * id for injection into the chunks. Returns undefined when nothing identifies a release: the CLI
+ * prints nothing and exits zero for a build with no release name/version and no git or CI
+ * metadata to derive them from, which is a build that ships without a release rather than a
+ * failure.
+ */
+export declare function resolveReleaseId(config: ResolvedPluginConfig): Promise<string | undefined>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAG/C;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEtD;;GAEG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,EAAE;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC7C,OAAO,GAAE,mBAA+B,GACzC,MAAM,EAAE,CAkCV;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAAC,UAAU,CAQ3E;AAED;;GAEG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,GAC/F,OAAO,CAAC,IAAI,CAAC,CAgBf"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAG/C;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,QAAQ,CAAA;AAwBtD;;GAEG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,EAAE;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC7C,OAAO,GAAE,mBAA+B,GACzC,MAAM,EAAE,CA8BV;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAAC,UAAU,CAW3E;AAED;;GAEG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,GAC/F,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuBhG"}

package/dist/cli.js

@@ -24,11 +24,19 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    runSourcemapCli: ()=>runSourcemapCli,
+    resolveReleaseId: ()=>resolveReleaseId,
     buildCliEnv: ()=>buildCliEnv,
+    runSourcemapCli: ()=>runSourcemapCli,
     buildSourcemapCliArgs: ()=>buildSourcemapCliArgs
 });
 const external_spawn_local_js_namespaceObject = require("./spawn-local.js");
+function buildReleaseArgs(config) {
+    const args = [];
+    if (config.sourcemaps.releaseName) args.push('--release-name', config.sourcemaps.releaseName);
+    if (config.sourcemaps.releaseVersion) args.push('--release-version', config.sourcemaps.releaseVersion);
+    if (void 0 !== config.sourcemaps.build && '' !== config.sourcemaps.build) args.push('--build', config.sourcemaps.build);
+    return args;
+}
 function buildSourcemapCliArgs(config, mode, command = 'process') {
     const args = [
         'sourcemap',
@@ -36,9 +44,8 @@ function buildSourcemapCliArgs(config, mode, command = 'process') {
     ];
     if ('stdin' in mode) args.push('--stdin');
     else args.push('--directory', mode.directory);
-    if (config.sourcemaps.releaseName) args.push('--release-name', config.sourcemaps.releaseName);
-    if (config.sourcemaps.releaseVersion) args.push('--release-version', config.sourcemaps.releaseVersion);
-    if (void 0 !== config.sourcemaps.build && '' !== config.sourcemaps.build) args.push('--build', config.sourcemaps.build);
+    args.push(...buildReleaseArgs(config));
+    if ('event' === config.sourcemaps.releaseMode) args.push('--release-mode', 'event');
     if (config.sourcemaps.deleteAfterUpload && 'process' === command) args.push('--delete-after');
     if (config.sourcemaps.batchSize) args.push('--batch-size', config.sourcemaps.batchSize.toString());
     return args;
@@ -49,7 +56,8 @@ function buildCliEnv(config) {
         RUST_LOG: `posthog_cli=${config.logLevel}`,
         POSTHOG_CLI_HOST: config.host,
         POSTHOG_CLI_API_KEY: config.personalApiKey,
-        POSTHOG_CLI_PROJECT_ID: config.projectId
+        POSTHOG_CLI_PROJECT_ID: config.projectId,
+        POSTHOG_RELEASE_MODE: config.sourcemaps.releaseMode
     };
 }
 async function runSourcemapCli(config, options) {
@@ -68,12 +76,31 @@ async function runSourcemapCli(config, options) {
     if ('filePaths' in options) spawnOptions.stdin = options.filePaths.join('\n') + '\n';
     await (0, external_spawn_local_js_namespaceObject.spawnLocal)(config.cliBinaryPath, args, spawnOptions);
 }
+async function resolveReleaseId(config) {
+    const args = [
+        'release',
+        'resolve',
+        ...buildReleaseArgs(config)
+    ];
+    const { code, stdout, stderr } = await (0, external_spawn_local_js_namespaceObject.spawnLocalCapture)(config.cliBinaryPath, args, {
+        cwd: process.cwd(),
+        env: buildCliEnv(config)
+    });
+    if (0 !== code) {
+        const hint = /unrecognized subcommand|unexpected argument/.test(stderr) ? ` Event release mode needs a posthog-cli with 'release resolve' (${config.cliBinaryPath}).` : '';
+        throw new Error(`posthog-cli release resolve failed with code ${code}.${hint}\n${stderr.trim()}`);
+    }
+    if (stderr.trim()) process.stderr.write(stderr);
+    return stdout.trim() || void 0;
+}
 exports.buildCliEnv = __webpack_exports__.buildCliEnv;
 exports.buildSourcemapCliArgs = __webpack_exports__.buildSourcemapCliArgs;
+exports.resolveReleaseId = __webpack_exports__.resolveReleaseId;
 exports.runSourcemapCli = __webpack_exports__.runSourcemapCli;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "buildCliEnv",
     "buildSourcemapCliArgs",
+    "resolveReleaseId",
     "runSourcemapCli"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {

package/dist/cli.mjs

@@ -1,4 +1,11 @@
-import { spawnLocal } from "./spawn-local.mjs";
+import { spawnLocal, spawnLocalCapture } from "./spawn-local.mjs";
+function buildReleaseArgs(config) {
+    const args = [];
+    if (config.sourcemaps.releaseName) args.push('--release-name', config.sourcemaps.releaseName);
+    if (config.sourcemaps.releaseVersion) args.push('--release-version', config.sourcemaps.releaseVersion);
+    if (void 0 !== config.sourcemaps.build && '' !== config.sourcemaps.build) args.push('--build', config.sourcemaps.build);
+    return args;
+}
 function buildSourcemapCliArgs(config, mode, command = 'process') {
     const args = [
         'sourcemap',
@@ -6,9 +13,8 @@ function buildSourcemapCliArgs(config, mode, command = 'process') {
     ];
     if ('stdin' in mode) args.push('--stdin');
     else args.push('--directory', mode.directory);
-    if (config.sourcemaps.releaseName) args.push('--release-name', config.sourcemaps.releaseName);
-    if (config.sourcemaps.releaseVersion) args.push('--release-version', config.sourcemaps.releaseVersion);
-    if (void 0 !== config.sourcemaps.build && '' !== config.sourcemaps.build) args.push('--build', config.sourcemaps.build);
+    args.push(...buildReleaseArgs(config));
+    if ('event' === config.sourcemaps.releaseMode) args.push('--release-mode', 'event');
     if (config.sourcemaps.deleteAfterUpload && 'process' === command) args.push('--delete-after');
     if (config.sourcemaps.batchSize) args.push('--batch-size', config.sourcemaps.batchSize.toString());
     return args;
@@ -19,7 +25,8 @@ function buildCliEnv(config) {
         RUST_LOG: `posthog_cli=${config.logLevel}`,
         POSTHOG_CLI_HOST: config.host,
         POSTHOG_CLI_API_KEY: config.personalApiKey,
-        POSTHOG_CLI_PROJECT_ID: config.projectId
+        POSTHOG_CLI_PROJECT_ID: config.projectId,
+        POSTHOG_RELEASE_MODE: config.sourcemaps.releaseMode
     };
 }
 async function runSourcemapCli(config, options) {
@@ -38,4 +45,21 @@ async function runSourcemapCli(config, options) {
     if ('filePaths' in options) spawnOptions.stdin = options.filePaths.join('\n') + '\n';
     await spawnLocal(config.cliBinaryPath, args, spawnOptions);
 }
-export { buildCliEnv, buildSourcemapCliArgs, runSourcemapCli };
+async function resolveReleaseId(config) {
+    const args = [
+        'release',
+        'resolve',
+        ...buildReleaseArgs(config)
+    ];
+    const { code, stdout, stderr } = await spawnLocalCapture(config.cliBinaryPath, args, {
+        cwd: process.cwd(),
+        env: buildCliEnv(config)
+    });
+    if (0 !== code) {
+        const hint = /unrecognized subcommand|unexpected argument/.test(stderr) ? ` Event release mode needs a posthog-cli with 'release resolve' (${config.cliBinaryPath}).` : '';
+        throw new Error(`posthog-cli release resolve failed with code ${code}.${hint}\n${stderr.trim()}`);
+    }
+    if (stderr.trim()) process.stderr.write(stderr);
+    return stdout.trim() || void 0;
+}
+export { buildCliEnv, buildSourcemapCliArgs, resolveReleaseId, runSourcemapCli };

package/dist/config.d.ts

@@ -1,4 +1,12 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * How an exception gets associated with a release, mirroring posthog-cli's `--release-mode`.
+ *
+ * `event`, the default, leaves the uploaded symbol sets unbound and injects the release id into
+ * each chunk, so the release is resolved per exception. `symbol-set` binds the uploaded symbol
+ * sets to a release instead.
+ */
+export type ReleaseMode = 'symbol-set' | 'event';
 export interface PluginConfig {
     personalApiKey: string;
     /** @deprecated Use projectId instead */
@@ -18,6 +26,13 @@ export interface PluginConfig {
         build?: string | number;
         deleteAfterUpload?: boolean;
         batchSize?: number;
+        /**
+         * Defaults to the `POSTHOG_RELEASE_MODE` env var, the same one posthog-cli reads, then to
+         * `event`. Event mode needs a posthog-cli that supports `release resolve` and
+         * `--release-mode`. Set `symbol-set` to bind the uploaded symbol sets to a release
+         * instead.
+         */
+        releaseMode?: ReleaseMode;
     };
 }
 export interface ResolvedPluginConfig extends Omit<PluginConfig, 'envId' | 'projectId'> {
@@ -32,6 +47,7 @@ export interface ResolvedPluginConfig extends Omit<PluginConfig, 'envId' | 'proj
         build?: string;
         deleteAfterUpload: boolean;
         batchSize?: number;
+        releaseMode: ReleaseMode;
     };
 }
 export interface ResolveConfigOptions {

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAErE,MAAM,WAAW,YAAY;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,UAAU,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,0CAA0C;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,6CAA6C;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QACvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;CACJ;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,WAAW,CAAC;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,QAAQ,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE;QACR,OAAO,EAAE,OAAO,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,iBAAiB,EAAE,OAAO,CAAA;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;CACJ;AAED,MAAM,WAAW,oBAAoB;IACjC,sFAAsF;IACtF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAyChH"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,CAAA;AAchD,MAAM,WAAW,YAAY;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,UAAU,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,0CAA0C;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,6CAA6C;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QACvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB;;;;;WAKG;QACH,WAAW,CAAC,EAAE,WAAW,CAAA;KAC5B,CAAA;CACJ;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,WAAW,CAAC;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,QAAQ,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE;QACR,OAAO,EAAE,OAAO,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,iBAAiB,EAAE,OAAO,CAAA;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,WAAW,CAAA;KAC3B,CAAA;CACJ;AAED,MAAM,WAAW,oBAAoB;IACjC,sFAAsF;IACtF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CA0ChH"}

package/dist/config.js

@@ -35,6 +35,15 @@ function normalizeHost(value) {
     const normalizedHost = 'string' == typeof value ? value.trim() : '';
     return normalizedHost || DEFAULT_PLUGIN_HOST;
 }
+const RELEASE_MODES = [
+    'symbol-set',
+    'event'
+];
+function normalizeReleaseMode(value) {
+    if (void 0 === value || '' === value) return 'event';
+    if (!RELEASE_MODES.includes(value)) throw new Error(`sourcemaps.releaseMode must be one of ${RELEASE_MODES.join(', ')}, got '${value}'`);
+    return value;
+}
 function resolveConfig(options, resolveOptions) {
     const projectId = options.projectId ?? options.envId;
     const personalApiKey = normalizeApiKey(options.personalApiKey);
@@ -64,7 +73,8 @@ function resolveConfig(options, resolveOptions) {
             releaseVersion: userSourcemaps.releaseVersion ?? userSourcemaps.version,
             build: void 0 !== userSourcemaps.build ? String(userSourcemaps.build) : void 0,
             deleteAfterUpload: userSourcemaps.deleteAfterUpload ?? true,
-            batchSize: userSourcemaps.batchSize
+            batchSize: userSourcemaps.batchSize,
+            releaseMode: normalizeReleaseMode(userSourcemaps.releaseMode ?? process.env.POSTHOG_RELEASE_MODE)
         }
     };
 }

package/dist/config.mjs

@@ -7,6 +7,15 @@ function normalizeHost(value) {
     const normalizedHost = 'string' == typeof value ? value.trim() : '';
     return normalizedHost || DEFAULT_PLUGIN_HOST;
 }
+const RELEASE_MODES = [
+    'symbol-set',
+    'event'
+];
+function normalizeReleaseMode(value) {
+    if (void 0 === value || '' === value) return 'event';
+    if (!RELEASE_MODES.includes(value)) throw new Error(`sourcemaps.releaseMode must be one of ${RELEASE_MODES.join(', ')}, got '${value}'`);
+    return value;
+}
 function resolveConfig(options, resolveOptions) {
     const projectId = options.projectId ?? options.envId;
     const personalApiKey = normalizeApiKey(options.personalApiKey);
@@ -36,7 +45,8 @@ function resolveConfig(options, resolveOptions) {
             releaseVersion: userSourcemaps.releaseVersion ?? userSourcemaps.version,
             build: void 0 !== userSourcemaps.build ? String(userSourcemaps.build) : void 0,
             deleteAfterUpload: userSourcemaps.deleteAfterUpload ?? true,
-            batchSize: userSourcemaps.batchSize
+            batchSize: userSourcemaps.batchSize,
+            releaseMode: normalizeReleaseMode(userSourcemaps.releaseMode ?? process.env.POSTHOG_RELEASE_MODE)
         }
     };
 }

package/dist/spawn-local.d.ts

@@ -1,3 +1,17 @@
+export interface CapturedRun {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Runs a command and captures both streams instead of inheriting them, for commands whose stdout
+ * is a value the caller needs rather than build output. Resolves with a non-zero `code` rather
+ * than rejecting, so the caller can shape the error from what the command wrote to stderr.
+ */
+export declare function spawnLocalCapture(executable: string, args: string[], options: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}): Promise<CapturedRun>;
 export declare function spawnLocal(executable: string, args: string[], options: {
     env: NodeJS.ProcessEnv;
     stdio: 'inherit' | 'ignore';

package/dist/spawn-local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-local.d.ts","sourceRoot":"","sources":["../src/spawn-local.ts"],"names":[],"mappings":"AAEA,wBAAsB,UAAU,CAC5B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACL,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IACtB,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,GACF,OAAO,CAAC,IAAI,CAAC,CAiCf"}
+{"version":3,"file":"spawn-local.d.ts","sourceRoot":"","sources":["../src/spawn-local.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACL,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IACtB,GAAG,EAAE,MAAM,CAAA;CACd,GACF,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAED,wBAAsB,UAAU,CAC5B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IACL,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IACtB,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,GACF,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/spawn-local.js

@@ -24,9 +24,39 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    spawnLocalCapture: ()=>spawnLocalCapture,
     spawnLocal: ()=>spawnLocal
 });
 const external_cross_spawn_namespaceObject = require("cross-spawn");
+async function spawnLocalCapture(executable, args, options) {
+    const child = (0, external_cross_spawn_namespaceObject.spawn)(executable, [
+        ...args
+    ], {
+        stdio: [
+            'ignore',
+            'pipe',
+            'pipe'
+        ],
+        env: options.env,
+        cwd: options.cwd
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk)=>{
+        stdout += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk)=>{
+        stderr += chunk.toString();
+    });
+    return await new Promise((resolve, reject)=>{
+        child.on('close', (code)=>resolve({
+                code,
+                stdout,
+                stderr
+            }));
+        child.on('error', (error)=>reject(error));
+    });
+}
 async function spawnLocal(executable, args, options) {
     const stdioOption = void 0 !== options.stdin ? [
         'pipe',
@@ -58,8 +88,10 @@ async function spawnLocal(executable, args, options) {
     });
 }
 exports.spawnLocal = __webpack_exports__.spawnLocal;
+exports.spawnLocalCapture = __webpack_exports__.spawnLocalCapture;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
-    "spawnLocal"
+    "spawnLocal",
+    "spawnLocalCapture"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/spawn-local.mjs

@@ -1,4 +1,33 @@
 import { spawn } from "cross-spawn";
+async function spawnLocalCapture(executable, args, options) {
+    const child = spawn(executable, [
+        ...args
+    ], {
+        stdio: [
+            'ignore',
+            'pipe',
+            'pipe'
+        ],
+        env: options.env,
+        cwd: options.cwd
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk)=>{
+        stdout += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk)=>{
+        stderr += chunk.toString();
+    });
+    return await new Promise((resolve, reject)=>{
+        child.on('close', (code)=>resolve({
+                code,
+                stdout,
+                stderr
+            }));
+        child.on('error', (error)=>reject(error));
+    });
+}
 async function spawnLocal(executable, args, options) {
     const stdioOption = void 0 !== options.stdin ? [
         'pipe',
@@ -29,4 +58,4 @@ async function spawnLocal(executable, args, options) {
         });
     });
 }
-export { spawnLocal };
+export { spawnLocal, spawnLocalCapture };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/plugin-utils",
-  "version": "1.1.3",
+  "version": "2.0.0",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },
@@ -39,8 +39,8 @@
   },
   "scripts": {
     "clean": "rimraf dist",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "oxlint --report-unused-disable-directives-severity error src",
+    "lint:fix": "oxlint --report-unused-disable-directives-severity error src --fix",
     "build": "rslib build",
     "dev": "rslib build -w",
     "test:unit": "jest",

package/src/chunk-ids.ts

@@ -2,15 +2,24 @@ import * as crypto from 'crypto'
 
 /**
  * Returns the minified chunk-id IIFE the SDK reads at runtime to map an
- * error's stack back to a chunk id.
+ * error's stack back to a chunk id. With `releaseId`, the snippet also pins
+ * `_posthogReleaseId` on the global so the SDK emits the release on every
+ * exception (first write wins, so the first loaded chunk decides).
  *
- * Byte-for-byte contract with posthog-cli (`CODE_SNIPPET_TEMPLATE` in
- * cli/src/sourcemaps/constant.rs): the CLI recognizes and removes previously
- * injected snippets by exact substring match, so any change here must ship in
- * the CLI constants too. Covered by a parity test in chunk-ids.spec.ts.
+ * Byte-for-byte contract with posthog-cli (`CODE_SNIPPET_TEMPLATE` and
+ * `CODE_SNIPPET_WITH_RELEASE_TEMPLATE` in cli/src/sourcemaps/constant.rs): the
+ * CLI recognizes and removes previously injected snippets by exact substring
+ * match, so any change here must ship in the CLI constants too. Ids are
+ * JSON-encoded for the same reason the CLI encodes them: an id carrying a quote
+ * would otherwise break out of the string literal. Covered by a parity test in
+ * chunk-ids.spec.ts.
  */
-export function createChunkIdSnippet(chunkId: string): string {
-    return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]="${chunkId}")}catch(e){}}();`
+export function createChunkIdSnippet(chunkId: string, releaseId?: string): string {
+    const chunk = JSON.stringify(chunkId)
+    if (releaseId === undefined) {
+        return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]=${chunk})}catch(e){}}();`
+    }
+    return `!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{};e._posthogReleaseId=e._posthogReleaseId||${JSON.stringify(releaseId)};var n=(new e.Error).stack;n&&(e._posthogChunkIds=e._posthogChunkIds||{},e._posthogChunkIds[n]=${chunk})}catch(e){}}();`
 }
 
 /**
@@ -29,6 +38,33 @@ export function createChunkId(): string {
     return crypto.randomUUID()
 }
 
+// Fixed namespace for content-addressed chunk ids, matching `CHUNK_ID_NAMESPACE` in
+// cli/src/sourcemaps/constant.rs. Both sides must derive ids from the same namespace, or a
+// dist processed by one tool and re-processed by the other would upload the same code twice.
+const CHUNK_ID_NAMESPACE = '0e9b3c7a-5d1f-42a8-b6c4-e2d0f8a17593'
+
+/**
+ * Derives a chunk id from the chunk's own bytes (UUIDv5), so identical code keeps its id across
+ * rebuilds and re-uploads dedupe against the symbol set already stored. Used in event release
+ * mode, where the release travels inside the chunk instead of being bound to the symbol set, so
+ * a per-build random id would create a fresh symbol set on every build.
+ *
+ * The id is content-addressed over what `renderChunk` sees. posthog-cli derives its own ids from
+ * the file on disk, which by then also carries the trailing `sourceMappingURL` comment, so the
+ * same chunk gets a different (but equally stable) id depending on which tool injected it.
+ */
+export function createStableChunkId(code: string): string {
+    const namespace = Buffer.from(CHUNK_ID_NAMESPACE.replace(/-/g, ''), 'hex')
+    const hash = crypto.createHash('sha1').update(namespace).update(code, 'utf8').digest()
+
+    // RFC 4122: version in the high nibble of byte 6, variant in the top two bits of byte 8.
+    hash[6] = (hash[6] & 0x0f) | 0x50
+    hash[8] = (hash[8] & 0x3f) | 0x80
+
+    const hex = hash.subarray(0, 16).toString('hex')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
 // Anchored with a bounded quantifier and only ever run against a fixed-size
 // window: an unbounded regex over the whole bundle is quadratic on adversarial
 // input (a match attempt per marker occurrence, each scanning ahead).

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { ResolvedPluginConfig } from './config'
-import { spawnLocal } from './spawn-local'
+import { spawnLocal, spawnLocalCapture } from './spawn-local'
 
 /**
  * `process` injects chunk ids into the built files on disk and uploads them.
@@ -8,6 +8,28 @@ import { spawnLocal } from './spawn-local'
  */
 export type SourcemapCliCommand = 'process' | 'upload'
 
+/**
+ * The flags identifying which release this build belongs to. Shared by every command that
+ * resolves one, so `release resolve` lands on the same release row the upload would have.
+ */
+function buildReleaseArgs(config: ResolvedPluginConfig): string[] {
+    const args: string[] = []
+
+    if (config.sourcemaps.releaseName) {
+        args.push('--release-name', config.sourcemaps.releaseName)
+    }
+
+    if (config.sourcemaps.releaseVersion) {
+        args.push('--release-version', config.sourcemaps.releaseVersion)
+    }
+
+    if (config.sourcemaps.build !== undefined && config.sourcemaps.build !== '') {
+        args.push('--build', config.sourcemaps.build)
+    }
+
+    return args
+}
+
 /**
  * Build CLI arguments for `posthog-cli sourcemap <command>`.
  */
@@ -24,16 +46,12 @@ export function buildSourcemapCliArgs(
         args.push('--directory', mode.directory)
     }
 
-    if (config.sourcemaps.releaseName) {
-        args.push('--release-name', config.sourcemaps.releaseName)
-    }
+    args.push(...buildReleaseArgs(config))
 
-    if (config.sourcemaps.releaseVersion) {
-        args.push('--release-version', config.sourcemaps.releaseVersion)
-    }
-
-    if (config.sourcemaps.build !== undefined && config.sourcemaps.build !== '') {
-        args.push('--build', config.sourcemaps.build)
+    // Only passed in event mode, so a symbol-set build keeps working against a posthog-cli
+    // predating the flag.
+    if (config.sourcemaps.releaseMode === 'event') {
+        args.push('--release-mode', 'event')
     }
 
     // On `upload` the caller owns map deletion: `--delete-after` also rewrites
@@ -62,6 +80,9 @@ export function buildCliEnv(config: ResolvedPluginConfig): NodeJS.ProcessEnv {
         POSTHOG_CLI_HOST: config.host,
         POSTHOG_CLI_API_KEY: config.personalApiKey,
         POSTHOG_CLI_PROJECT_ID: config.projectId,
+        // The CLI reads this variable itself, so an inherited value would decide the release mode
+        // of the spawned command while the plugin injected chunks for the mode it resolved.
+        POSTHOG_RELEASE_MODE: config.sourcemaps.releaseMode,
     }
 }
 
@@ -88,3 +109,35 @@ export async function runSourcemapCli(
 
     await spawnLocal(config.cliBinaryPath, args, spawnOptions)
 }
+
+/**
+ * Resolves the release this build belongs to, creating it if it doesn't exist yet, and returns its
+ * id for injection into the chunks. Returns undefined when nothing identifies a release: the CLI
+ * prints nothing and exits zero for a build with no release name/version and no git or CI
+ * metadata to derive them from, which is a build that ships without a release rather than a
+ * failure.
+ */
+export async function resolveReleaseId(config: ResolvedPluginConfig): Promise<string | undefined> {
+    const args = ['release', 'resolve', ...buildReleaseArgs(config)]
+    const { code, stdout, stderr } = await spawnLocalCapture(config.cliBinaryPath, args, {
+        cwd: process.cwd(),
+        env: buildCliEnv(config),
+    })
+
+    if (code !== 0) {
+        // `release resolve` shipped after `sourcemap upload`, so an older binary on the PATH
+        // fails here rather than at upload time, where the message would make more sense.
+        const hint = /unrecognized subcommand|unexpected argument/.test(stderr)
+            ? ` Event release mode needs a posthog-cli with 'release resolve' (${config.cliBinaryPath}).`
+            : ''
+        throw new Error(`posthog-cli release resolve failed with code ${code}.${hint}\n${stderr.trim()}`)
+    }
+
+    // The CLI logs to stderr and prints only the id to stdout, so forward its warnings rather
+    // than swallowing them with the captured stream.
+    if (stderr.trim()) {
+        process.stderr.write(stderr)
+    }
+
+    return stdout.trim() || undefined
+}

package/src/config.ts

@@ -13,6 +13,27 @@ function normalizeHost(value?: unknown): string {
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
 
+/**
+ * How an exception gets associated with a release, mirroring posthog-cli's `--release-mode`.
+ *
+ * `event`, the default, leaves the uploaded symbol sets unbound and injects the release id into
+ * each chunk, so the release is resolved per exception. `symbol-set` binds the uploaded symbol
+ * sets to a release instead.
+ */
+export type ReleaseMode = 'symbol-set' | 'event'
+
+const RELEASE_MODES: ReleaseMode[] = ['symbol-set', 'event']
+
+function normalizeReleaseMode(value: string | undefined): ReleaseMode {
+    if (value === undefined || value === '') {
+        return 'event'
+    }
+    if (!(RELEASE_MODES as string[]).includes(value)) {
+        throw new Error(`sourcemaps.releaseMode must be one of ${RELEASE_MODES.join(', ')}, got '${value}'`)
+    }
+    return value as ReleaseMode
+}
+
 export interface PluginConfig {
     personalApiKey: string
     /** @deprecated Use projectId instead */
@@ -32,6 +53,13 @@ export interface PluginConfig {
         build?: string | number
         deleteAfterUpload?: boolean
         batchSize?: number
+        /**
+         * Defaults to the `POSTHOG_RELEASE_MODE` env var, the same one posthog-cli reads, then to
+         * `event`. Event mode needs a posthog-cli that supports `release resolve` and
+         * `--release-mode`. Set `symbol-set` to bind the uploaded symbol sets to a release
+         * instead.
+         */
+        releaseMode?: ReleaseMode
     }
 }
 
@@ -47,6 +75,7 @@ export interface ResolvedPluginConfig extends Omit<PluginConfig, 'envId' | 'proj
         build?: string
         deleteAfterUpload: boolean
         batchSize?: number
+        releaseMode: ReleaseMode
     }
 }
 
@@ -96,6 +125,7 @@ export function resolveConfig(options: PluginConfig, resolveOptions?: ResolveCon
             build: userSourcemaps.build !== undefined ? String(userSourcemaps.build) : undefined,
             deleteAfterUpload: userSourcemaps.deleteAfterUpload ?? true,
             batchSize: userSourcemaps.batchSize,
+            releaseMode: normalizeReleaseMode(userSourcemaps.releaseMode ?? process.env.POSTHOG_RELEASE_MODE),
         },
     }
 }

package/src/spawn-local.ts

@@ -1,5 +1,45 @@
 import { spawn } from 'cross-spawn'
 
+export interface CapturedRun {
+    code: number | null
+    stdout: string
+    stderr: string
+}
+
+/**
+ * Runs a command and captures both streams instead of inheriting them, for commands whose stdout
+ * is a value the caller needs rather than build output. Resolves with a non-zero `code` rather
+ * than rejecting, so the caller can shape the error from what the command wrote to stderr.
+ */
+export async function spawnLocalCapture(
+    executable: string,
+    args: string[],
+    options: {
+        env: NodeJS.ProcessEnv
+        cwd: string
+    }
+): Promise<CapturedRun> {
+    const child = spawn(executable, [...args], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: options.env,
+        cwd: options.cwd,
+    })
+
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk: Buffer) => {
+        stdout += chunk.toString()
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString()
+    })
+
+    return await new Promise<CapturedRun>((resolve, reject) => {
+        child.on('close', (code) => resolve({ code, stdout, stderr }))
+        child.on('error', (error) => reject(error))
+    })
+}
+
 export async function spawnLocal(
     executable: string,
     args: string[],