@posthog/plugin-utils 1.1.2 → 1.2.0

package/LICENSE

@@ -327,12 +327,12 @@ SOFTWARE.
 
 ---
 
-Some files in this codebase contain code from MCPCat/mcpcat-typescript-sdk.
+Some files in this codebase contain code from agentcathq/agentcat-typescript-sdk (formerly MCPCat/mcpcat-typescript-sdk).
 In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases.
 
 MIT License
 
-Copyright (c) 2025 MCPcat
+Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/chunk-ids.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Returns the minified chunk-id IIFE the SDK reads at runtime to map an
+ * 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` 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, 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
+ * leading newline the CLI's exact-match removal expects.
+ */
+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.
+ * The injected IIFE is deliberately not matched — its marker text can appear
+ * inside string literals of bundled code (docs strings, bundled PostHog
+ * tooling), and the CLI only ever reads the line-anchored comment. Keeping the
+ * two in sync guarantees this returning an id ⟺ the CLI finding one.
+ */
+export declare function determineChunkIdFromSource(code: string): string | undefined;
+//# sourceMappingURL=chunk-ids.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,78 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+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, 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}`;
+}
+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;
+function determineChunkIdFromSource(code) {
+    for(let at = code.indexOf(COMMENT_MARKER); -1 !== at; at = code.indexOf(COMMENT_MARKER, at + COMMENT_MARKER.length)){
+        if (0 !== at && '\n' !== code[at - 1]) continue;
+        const match = COMMENT_REGEX.exec(code.slice(at, at + WINDOW));
+        if (match) return match[1];
+    }
+}
+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', {
+    value: true
+});

package/dist/chunk-ids.mjs

@@ -0,0 +1,32 @@
+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}`;
+}
+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;
+function determineChunkIdFromSource(code) {
+    for(let at = code.indexOf(COMMENT_MARKER); -1 !== at; at = code.indexOf(COMMENT_MARKER, at + COMMENT_MARKER.length)){
+        if (0 !== at && '\n' !== code[at - 1]) continue;
+        const match = COMMENT_REGEX.exec(code.slice(at, at + WINDOW));
+        if (match) return match[1];
+    }
+}
+export { createChunkId, createChunkIdComment, createChunkIdSnippet, createStableChunkId, determineChunkIdFromSource };

package/dist/cli.d.ts

@@ -1,12 +1,18 @@
 import { ResolvedPluginConfig } from './config';
 /**
- * Build CLI arguments for `posthog-cli sourcemap process`.
+ * `process` injects chunk ids into the built files on disk and uploads them.
+ * `upload` only reads the files, expecting chunk ids to already be present
+ * (e.g. injected in-memory by a bundler plugin before the files were written).
+ */
+export type SourcemapCliCommand = 'process' | 'upload';
+/**
+ * Build CLI arguments for `posthog-cli sourcemap <command>`.
  */
 export declare function buildSourcemapCliArgs(config: ResolvedPluginConfig, mode: {
     stdin: true;
 } | {
     directory: string;
-}): string[];
+}, command?: SourcemapCliCommand): string[];
 /**
  * Build environment variables for CLI invocation.
  * Plugin config values override any existing process.env values.
@@ -15,9 +21,19 @@ export declare function buildCliEnv(config: ResolvedPluginConfig): NodeJS.Proces
 /**
  * Spawn the PostHog CLI for sourcemap processing via stdin (file list).
  */
-export declare function runSourcemapCli(config: ResolvedPluginConfig, options: {
+export declare function runSourcemapCli(config: ResolvedPluginConfig, options: ({
     filePaths: string[];
 } | {
     directory: string;
+}) & {
+    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;;GAEG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,EAAE;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC9C,MAAM,EAAE,CA8BV;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;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACzD,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,22 +24,29 @@ 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 buildSourcemapCliArgs(config, mode) {
+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',
-        'process'
+        command
     ];
     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);
-    if (config.sourcemaps.deleteAfterUpload) args.push('--delete-after');
+    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) {
@@ -58,7 +66,7 @@ async function runSourcemapCli(config, options) {
     } : {
         directory: options.directory
     };
-    const args = buildSourcemapCliArgs(config, mode);
+    const args = buildSourcemapCliArgs(config, mode, options.command ?? 'process');
     const env = buildCliEnv(config);
     const spawnOptions = {
         cwd: process.cwd(),
@@ -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,15 +1,21 @@
-import { spawnLocal } from "./spawn-local.mjs";
-function buildSourcemapCliArgs(config, mode) {
+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',
-        'process'
+        command
     ];
     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);
-    if (config.sourcemaps.deleteAfterUpload) args.push('--delete-after');
+    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) {
@@ -28,7 +35,7 @@ async function runSourcemapCli(config, options) {
     } : {
         directory: options.directory
     };
-    const args = buildSourcemapCliArgs(config, mode);
+    const args = buildSourcemapCliArgs(config, mode, options.command ?? 'process');
     const env = buildCliEnv(config);
     const spawnOptions = {
         cwd: process.cwd(),
@@ -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,11 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * How an exception gets associated with a release, mirroring posthog-cli's `--release-mode`.
+ *
+ * `symbol-set` binds the uploaded symbol sets to a release. `event` leaves them unbound and
+ * injects the release id into each chunk instead, so the release is resolved per exception.
+ */
+export type ReleaseMode = 'symbol-set' | 'event';
 export interface PluginConfig {
     personalApiKey: string;
     /** @deprecated Use projectId instead */
@@ -18,6 +25,12 @@ export interface PluginConfig {
         build?: string | number;
         deleteAfterUpload?: boolean;
         batchSize?: number;
+        /**
+         * EXPERIMENTAL. Defaults to the `POSTHOG_RELEASE_MODE` env var, the same one posthog-cli
+         * reads, then to `symbol-set`. Event mode needs a posthog-cli that supports
+         * `release resolve` and `--release-mode`.
+         */
+        releaseMode?: ReleaseMode;
     };
 }
 export interface ResolvedPluginConfig extends Omit<PluginConfig, 'envId' | 'projectId'> {
@@ -32,6 +45,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;;;;;GAKG;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;;;;WAIG;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 'symbol-set';
+    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 'symbol-set';
+    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/index.d.ts

@@ -2,4 +2,5 @@ export * from './spawn-local';
 export { resolveBinaryPath, buildLocalBinaryPaths } from './utils';
 export * from './config';
 export * from './cli';
+export * from './chunk-ids';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAClE,cAAc,UAAU,CAAA;AACxB,cAAc,OAAO,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAClE,cAAc,UAAU,CAAA;AACxB,cAAc,OAAO,CAAA;AACrB,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -1,5 +1,8 @@
 "use strict";
 var __webpack_modules__ = {
+    "./chunk-ids": function(module) {
+        module.exports = require("./chunk-ids.js");
+    },
     "./cli": function(module) {
         module.exports = require("./cli.js");
     },
@@ -91,6 +94,16 @@ var __webpack_exports__ = {};
         return _cli__WEBPACK_IMPORTED_MODULE_3__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
+    var _chunk_ids__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__("./chunk-ids");
+    var __WEBPACK_REEXPORT_OBJECT__ = {};
+    for(var __WEBPACK_IMPORT_KEY__ in _chunk_ids__WEBPACK_IMPORTED_MODULE_4__)if ([
+        "buildLocalBinaryPaths",
+        "resolveBinaryPath",
+        "default"
+    ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
+        return _chunk_ids__WEBPACK_IMPORTED_MODULE_4__[key];
+    }).bind(0, __WEBPACK_IMPORT_KEY__);
+    __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
 })();
 exports.buildLocalBinaryPaths = __webpack_exports__.buildLocalBinaryPaths;
 exports.resolveBinaryPath = __webpack_exports__.resolveBinaryPath;

package/dist/index.mjs

@@ -2,4 +2,5 @@ import { buildLocalBinaryPaths, resolveBinaryPath } from "./utils.mjs";
 export * from "./spawn-local.mjs";
 export * from "./config.mjs";
 export * from "./cli.mjs";
+export * from "./chunk-ids.mjs";
 export { buildLocalBinaryPaths, resolveBinaryPath };

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.2",
+  "version": "1.2.0",
   "bugs": {
     "url": "https://github.com/PostHog/posthog-js/issues"
   },

package/src/chunk-ids.ts

@@ -0,0 +1,96 @@
+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. 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` 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, 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){}}();`
+}
+
+/**
+ * Returns the comment posthog-cli discovers chunk ids from at upload time
+ * (`CHUNKID_COMMENT_PREFIX` in cli/src/sourcemaps/constant.rs), including the
+ * leading newline the CLI's exact-match removal expects.
+ */
+export function createChunkIdComment(chunkId: string): string {
+    return `\n//# chunkId=${chunkId}`
+}
+
+/**
+ * Mints a fresh random chunk id: a new id per chunk, per build.
+ */
+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).
+const COMMENT_REGEX = /^\/\/# chunkId=(\S{1,128})/
+const COMMENT_MARKER = '//# chunkId='
+const WINDOW = 256
+
+/**
+ * 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.
+ * The injected IIFE is deliberately not matched — its marker text can appear
+ * inside string literals of bundled code (docs strings, bundled PostHog
+ * tooling), and the CLI only ever reads the line-anchored comment. Keeping the
+ * two in sync guarantees this returning an id ⟺ the CLI finding one.
+ */
+export function determineChunkIdFromSource(code: string): string | undefined {
+    for (
+        let at = code.indexOf(COMMENT_MARKER);
+        at !== -1;
+        at = code.indexOf(COMMENT_MARKER, at + COMMENT_MARKER.length)
+    ) {
+        if (at !== 0 && code[at - 1] !== '\n') continue
+        const match = COMMENT_REGEX.exec(code.slice(at, at + WINDOW))
+        if (match) {
+            return match[1]
+        }
+    }
+    return undefined
+}

package/src/cli.ts

@@ -1,20 +1,19 @@
 import { ResolvedPluginConfig } from './config'
-import { spawnLocal } from './spawn-local'
+import { spawnLocal, spawnLocalCapture } from './spawn-local'
 
 /**
- * Build CLI arguments for `posthog-cli sourcemap process`.
+ * `process` injects chunk ids into the built files on disk and uploads them.
+ * `upload` only reads the files, expecting chunk ids to already be present
+ * (e.g. injected in-memory by a bundler plugin before the files were written).
  */
-export function buildSourcemapCliArgs(
-    config: ResolvedPluginConfig,
-    mode: { stdin: true } | { directory: string }
-): string[] {
-    const args = ['sourcemap', 'process']
+export type SourcemapCliCommand = 'process' | 'upload'
 
-    if ('stdin' in mode) {
-        args.push('--stdin')
-    } else {
-        args.push('--directory', mode.directory)
-    }
+/**
+ * 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)
@@ -28,7 +27,38 @@ export function buildSourcemapCliArgs(
         args.push('--build', config.sourcemaps.build)
     }
 
-    if (config.sourcemaps.deleteAfterUpload) {
+    return args
+}
+
+/**
+ * Build CLI arguments for `posthog-cli sourcemap <command>`.
+ */
+export function buildSourcemapCliArgs(
+    config: ResolvedPluginConfig,
+    mode: { stdin: true } | { directory: string },
+    command: SourcemapCliCommand = 'process'
+): string[] {
+    const args = ['sourcemap', command]
+
+    if ('stdin' in mode) {
+        args.push('--stdin')
+    } else {
+        args.push('--directory', mode.directory)
+    }
+
+    args.push(...buildReleaseArgs(config))
+
+    // 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
+    // the .js files (stripping sourcemap references), and callers pick `upload`
+    // precisely because the written files must not change — e.g. Subresource
+    // Integrity hashes were already computed from them.
+    if (config.sourcemaps.deleteAfterUpload && command === 'process') {
         args.push('--delete-after')
     }
 
@@ -50,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,
     }
 }
 
@@ -58,10 +91,10 @@ export function buildCliEnv(config: ResolvedPluginConfig): NodeJS.ProcessEnv {
  */
 export async function runSourcemapCli(
     config: ResolvedPluginConfig,
-    options: { filePaths: string[] } | { directory: string }
+    options: ({ filePaths: string[] } | { directory: string }) & { command?: SourcemapCliCommand }
 ): Promise<void> {
     const mode = 'filePaths' in options ? { stdin: true as const } : { directory: options.directory }
-    const args = buildSourcemapCliArgs(config, mode)
+    const args = buildSourcemapCliArgs(config, mode, options.command ?? 'process')
     const env = buildCliEnv(config)
 
     const spawnOptions: Parameters<typeof spawnLocal>[2] = {
@@ -76,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,26 @@ 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`.
+ *
+ * `symbol-set` binds the uploaded symbol sets to a release. `event` leaves them unbound and
+ * injects the release id into each chunk instead, so the release is resolved per exception.
+ */
+export type ReleaseMode = 'symbol-set' | 'event'
+
+const RELEASE_MODES: ReleaseMode[] = ['symbol-set', 'event']
+
+function normalizeReleaseMode(value: string | undefined): ReleaseMode {
+    if (value === undefined || value === '') {
+        return 'symbol-set'
+    }
+    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 +52,12 @@ export interface PluginConfig {
         build?: string | number
         deleteAfterUpload?: boolean
         batchSize?: number
+        /**
+         * EXPERIMENTAL. Defaults to the `POSTHOG_RELEASE_MODE` env var, the same one posthog-cli
+         * reads, then to `symbol-set`. Event mode needs a posthog-cli that supports
+         * `release resolve` and `--release-mode`.
+         */
+        releaseMode?: ReleaseMode
     }
 }
 
@@ -47,6 +73,7 @@ export interface ResolvedPluginConfig extends Omit<PluginConfig, 'envId' | 'proj
         build?: string
         deleteAfterUpload: boolean
         batchSize?: number
+        releaseMode: ReleaseMode
     }
 }
 
@@ -96,6 +123,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/index.ts

@@ -2,3 +2,4 @@ export * from './spawn-local'
 export { resolveBinaryPath, buildLocalBinaryPaths } from './utils'
 export * from './config'
 export * from './cli'
+export * from './chunk-ids'

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[],