@posthog/wizard 2.66.0 → 2.68.0

package/dist/bin.js

@@ -1,28 +1,29 @@
 #!/usr/bin/env node
-import { Ct as isHeadless, L as Integration, St as headlessOption, U as POSTHOG_DOCS_URL, a as getLogFilePath, f as getUI, gt as VERSION, m as LoggingUI, mt as getSkillsBaseUrl, p as setUI, pt as WIZARD_USER_AGENT, r as debug, s as logToFile, wt as regionOption } from "./debug-BKqv-yfT.js";
-import { a as getLocalDev, i as checkLocalServices, o as initLocalDev, r as POSTHOG_LOCAL_URL, s as localMcpSkillsNotice } from "./local-dev-BN6NKQ0B.js";
-import { n as analytics } from "./analytics-D8JNuPAT.js";
-import { r as setEntryCommand } from "./telemetry-BllPiBKw.js";
-import { a as safeReadFile, o as walkProjectFiles } from "./bounded-fs-C6OjqZst.js";
-import { n as isUsingTypeScript } from "./setup-utils-aWZEdfwh.js";
-import { o as handleApiError } from "./api-CemGgyBv.js";
-import "./wizard-session-DTyLMPsX.js";
-import { i as wizardAbort, r as runCleanups } from "./wizard-abort-D9jiMkZA.js";
-import { n as isNonInteractiveEnvironment } from "./environment-Cl-fIQku.js";
-import { n as runAgent, s as authenticate } from "./agent-runner-DEeMqJxy.js";
-import { m as writeJsonAtomic } from "./queue-tools-DABh1Ssc.js";
-import { D as WIZARD_TOOL_NAMES, j as fetchSkillMenu, l as recoverOrphanedSettingsBackups, p as AgentSignals } from "./agent-interface-D3MNaDp3.js";
-import { S as SETUP_REPORT_FILE, _ as AUDIT_CHECKS_KEY, g as AUDIT_CHECKS_FILE, v as AUDIT_REPORT_FILE } from "./yara-hooks-BXDBIOBq.js";
-import { i as SPINNER_MESSAGE, t as FRAMEWORK_REGISTRY } from "./registry-CxNpCNAj.js";
-import { C as scopeInstallDirToProject, D as detectFramework, E as gatherFrameworkContext, S as detectIntegrationProjects, T as resolveProjectDir, _ as HEALTH_CHECK_STEP, a as LINE_CHART_BLOCK, b as getDetectedWarehouseSources, d as isClearBlock, g as detectPostHogIntegration, h as Icons, i as FUNNEL_BLOCK, m as Colors, n as integrationRunStep, o as PRODUCT_SUITE_BLOCK, r as posthogIntegrationConfig, s as StatusPeekTrigger, u as wordWrap, v as WAREHOUSE_ABORT_CASES, x as detectWarehouseSources, y as detectWarehousePrerequisites } from "./posthog-integration-LxEBGkoe.js";
-import { n as readApiKeyFromEnv } from "./env-api-key-CzHDwfV2.js";
+import { a as AgentSignals, c as emitWizardError, l as ErrorCodes, r as detectErrorCode } from "./errors-BHervYGs.js";
+import { Ct as isHeadless, L as Integration, St as headlessOption, U as POSTHOG_DOCS_URL, a as getLogFilePath, f as getUI, gt as VERSION, m as LoggingUI, mt as getSkillsBaseUrl, p as setUI, pt as WIZARD_USER_AGENT, r as debug, s as logToFile, wt as regionOption } from "./debug-aA5dm2MR.js";
+import { a as getLocalDev, i as checkLocalServices, o as initLocalDev, r as POSTHOG_LOCAL_URL, s as localMcpSkillsNotice } from "./local-dev-DPZiIPCK.js";
+import { n as analytics } from "./analytics-tF06lcmE.js";
+import { r as setEntryCommand } from "./telemetry-wp-z9LXH.js";
+import { a as safeReadFile, o as walkProjectFiles } from "./bounded-fs-BwuqKpBH.js";
+import { n as isUsingTypeScript } from "./setup-utils-BLKhAx6g.js";
+import { o as handleApiError } from "./api-D7-8R4xx.js";
+import "./wizard-session-C_7r3-rO.js";
+import { i as wizardAbort, r as runCleanups } from "./wizard-abort-Bv87YVSp.js";
+import { n as isNonInteractiveEnvironment } from "./environment-BGUJxuvj.js";
+import { n as runAgent, s as authenticate } from "./agent-runner-Do5kyhPo.js";
+import { T as WIZARD_TOOL_NAMES, k as fetchSkillMenu, l as recoverOrphanedSettingsBackups } from "./agent-interface-CaEptZuu.js";
+import { m as writeJsonAtomic } from "./queue-tools-i_TmeI02.js";
+import { S as SETUP_REPORT_FILE, _ as AUDIT_CHECKS_KEY, g as AUDIT_CHECKS_FILE, v as AUDIT_REPORT_FILE } from "./yara-hooks-DeonKbE_.js";
+import { i as SPINNER_MESSAGE, t as FRAMEWORK_REGISTRY } from "./registry-CbXqxcX0.js";
+import { C as scopeInstallDirToProject, D as detectFramework, E as gatherFrameworkContext, S as detectIntegrationProjects, T as resolveProjectDir, _ as HEALTH_CHECK_STEP, a as LINE_CHART_BLOCK, b as getDetectedWarehouseSources, d as isClearBlock, g as detectPostHogIntegration, h as Icons, i as FUNNEL_BLOCK, m as Colors, n as integrationRunStep, o as PRODUCT_SUITE_BLOCK, r as posthogIntegrationConfig, s as StatusPeekTrigger, u as wordWrap, v as WAREHOUSE_ABORT_CASES, x as detectWarehouseSources, y as detectWarehousePrerequisites } from "./posthog-integration-DJX4qTDQ.js";
+import { n as readApiKeyFromEnv } from "./env-api-key-CwkRyrgi.js";
 import { satisfies } from "semver";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { existsSync, readFileSync, readdirSync, statSync } from "fs";
 import path, { join, relative } from "path";
 import * as os from "node:os";
-import * as path$1 from "node:path";
+import * as path$2 from "node:path";
 import { join as join$1 } from "node:path";
 import { spawnSync } from "node:child_process";
 import * as fs$1 from "node:fs";
@@ -132,6 +133,10 @@ var Wizard = class Wizard {
 		}).strictOptions().strictCommands().fail((msg, err) => {
 			const text = msg || err && err.message || "Invalid arguments";
 			process.stderr.write(`\n\x1b[1;91m✖ ${text}\x1b[0m\n  Run \`wizard --help\` to see available commands and options.\n\n`);
+			emitWizardError({
+				code: ErrorCodes.CliBadArgs,
+				message: text
+			});
 			process.exit(1);
 		}).help().alias("help", "h").version().alias("version", "v");
 	}
@@ -152,18 +157,30 @@ var Wizard = class Wizard {
 			const envHasCI = process.env.POSTHOG_WIZARD_CI != null && process.env.POSTHOG_WIZARD_CI !== "";
 			if (argvHasCI || envHasCI) {
 				process.stderr.write(`\n\x1b[1;91m✖ CI mode is not currently supported in published builds.\x1b[0m\n\n`);
+				emitWizardError({
+					code: ErrorCodes.CliFlagUnavailable,
+					message: "CI mode is not supported in published builds."
+				});
 				process.exit(1);
 			}
 			const argvHasOverride = args.some((a) => a === "--harness" || a.startsWith("--harness=") || a === "--sequence" || a.startsWith("--sequence=") || a === "--model" || a.startsWith("--model=") || a === "--capture-aio" || a === "--no-capture-aio" || a.startsWith("--capture-aio="));
 			const envHasOverride = process.env.POSTHOG_WIZARD_HARNESS != null && process.env.POSTHOG_WIZARD_HARNESS !== "" || process.env.POSTHOG_WIZARD_SEQUENCE != null && process.env.POSTHOG_WIZARD_SEQUENCE !== "" || process.env.POSTHOG_WIZARD_MODEL != null && process.env.POSTHOG_WIZARD_MODEL !== "" || process.env.POSTHOG_WIZARD_CAPTURE_AIO != null && process.env.POSTHOG_WIZARD_CAPTURE_AIO !== "";
 			if (argvHasOverride || envHasOverride) {
 				process.stderr.write(`\n\x1b[1;91m✖ The --harness, --sequence, --model, and --capture-aio overrides are not available in published builds.\x1b[0m\n\n`);
+				emitWizardError({
+					code: ErrorCodes.CliFlagUnavailable,
+					message: "The --harness, --sequence, --model, and --capture-aio overrides are not available in published builds."
+				});
 				process.exit(1);
 			}
 			const argvHasLocalTarget = args.some((a) => LOCAL_TARGET_FLAGS.some((f) => a === `--${f}` || a === `--no-${f}` || a.startsWith(`--${f}=`)));
 			const envHasLocalTarget = LOCAL_TARGET_ENV_VARS.some((k) => process.env[k] != null && process.env[k] !== "");
 			if (argvHasLocalTarget || envHasLocalTarget) {
 				process.stderr.write("\n\x1B[1;91m✖ The --local-dev, --local-context-mill, --local-mcp, and --local-posthog targets are not available in published builds.\x1B[0m\n  They point the wizard at development servers on localhost.\n\n");
+				emitWizardError({
+					code: ErrorCodes.CliFlagUnavailable,
+					message: "The --local-dev, --local-context-mill, --local-mcp, and --local-posthog targets are not available in published builds."
+				});
 				process.exit(1);
 			}
 		}
@@ -225,7 +242,7 @@ function runProvision(argv) {
 }
 async function provision({ email, region, name, baseUrl, jsonMode }) {
 	try {
-		const { provisionNewAccount } = await import("./provisioning-BHTl91OZ.js").then((n) => n.r);
+		const { provisionNewAccount } = await import("./provisioning-DEEt9xl4.js").then((n) => n.r);
 		if (!jsonMode) getUI().log.info(`Provisioning account for ${email} in ${region}...`);
 		emitResult(await provisionNewAccount(email, name, region, { baseUrl }), jsonMode);
 		process.exit(0);
@@ -292,22 +309,22 @@ const basicIntegrationCommand = {
 		setEntryCommand("integrate");
 		(async () => {
 			if (isHeadless(argv)) {
-				const { runHeadlessInstall } = await import("./ci-install-DIB2n4Ju.js");
+				const { runHeadlessInstall } = await import("./ci-install-CrqqhXAw.js");
 				return runHeadlessInstall(argv);
 			}
 			if (argv.ci) {
-				const { runCIInstall } = await import("./ci-install-DIB2n4Ju.js");
+				const { runCIInstall } = await import("./ci-install-CrqqhXAw.js");
 				return runCIInstall(argv);
 			}
 			if (isNonInteractiveEnvironment()) {
-				const { failNonInteractive } = await import("./non-interactive-CNoYoEZp.js");
+				const { failNonInteractive } = await import("./non-interactive-ezilF3PY.js");
 				return failNonInteractive();
 			}
 			if (argv.playground) {
-				const { runPlayground } = await import("./playground-uHHgZChe.js");
+				const { runPlayground } = await import("./playground-Dnyb4jLu.js");
 				return runPlayground();
 			}
-			const { runInteractive } = await import("./interactive-D3LdFxZG.js");
+			const { runInteractive } = await import("./interactive-BRB6w6KG.js");
 			runInteractive(argv);
 		})();
 	}
@@ -686,6 +703,7 @@ function createSkillProgram(opts) {
 *  defined in the skill's `Abort statuses` section. */
 const AUDIT_ABORT_CASES = [{
 	match: /^no posthog sdk found$/i,
+	errorCode: ErrorCodes.DetectNoPosthogSdk,
 	message: "No PostHog SDK found",
 	body: "The audit needs an existing PostHog integration to review. No PostHog SDK appears in this project’s dependency manifests. Run the basic integration program to install PostHog first, then re-run the audit.",
 	docsUrl: "https://posthog.com/docs/getting-started/install"
@@ -1189,12 +1207,14 @@ const WEB_ANALYTICS_ABORT_CASES = [
 	},
 	{
 		match: /^insufficient permissions$/i,
+		errorCode: ErrorCodes.AuthMissingScope,
 		message: "Insufficient permissions",
 		body: "The doctor could not query your project — the authenticated token is missing query access. Re-run the wizard to sign in again, or use a key with read access to your events.",
 		docsUrl: "https://posthog.com/docs/web-analytics"
 	},
 	{
 		match: /^posthog sdk not installed$/i,
+		errorCode: ErrorCodes.DetectNoPosthogSdk,
 		message: "PostHog SDK not installed",
 		body: "The doctor could not find a PostHog SDK in this project. Install and configure PostHog first (run `npx @posthog/wizard`), then run the doctor to check your web analytics setup.",
 		docsUrl: "https://posthog.com/docs/libraries/js"
@@ -1891,6 +1911,7 @@ const GO_SDK_MODULE = "github.com/posthog/posthog-go";
 const SOURCE_MAPS_ABORT_CASES = [
 	{
 		match: /^no posthog sdk detected$/i,
+		errorCode: ErrorCodes.DetectNoPosthogSdk,
 		message: "No PostHog SDK detected",
 		body: "The agent could not find a PostHog SDK in your project. Source map upload requires the SDK to already be installed so it can report errors. Run `npx @posthog/wizard` first to install the SDK (for Go and Rust, add posthog-go / posthog-rs by hand first — the wizard cannot install the SDK for those stacks yet).",
 		docsUrl: "https://posthog.com/docs/error-tracking"
@@ -1903,6 +1924,7 @@ const SOURCE_MAPS_ABORT_CASES = [
 	},
 	{
 		match: /^bare react native not supported$/i,
+		errorCode: ErrorCodes.DetectUnsupportedPlatform,
 		message: "Bare React Native is not supported",
 		body: "Source-map upload for React Native requires Expo, and this project has no `expo` package. Bare React Native builds cannot inject the chunk IDs PostHog needs to resolve stack traces.",
 		docsUrl: "https://posthog.com/docs/error-tracking/upload-source-maps/react-native"
@@ -2485,7 +2507,7 @@ const getContentBlocks$1 = (store) => pace([
 //#region src/steps/install-cli-steering/index.ts
 const dirExists = (...segments) => {
 	try {
-		return fs$1.existsSync(path$1.join(os.homedir(), ...segments));
+		return fs$1.existsSync(path$2.join(os.homedir(), ...segments));
 	} catch {
 		return false;
 	}
@@ -2494,19 +2516,19 @@ const CLI_STEERING_TARGETS = [
 	{
 		id: "claude-code",
 		name: "Claude Code",
-		instructionsPath: () => path$1.join(os.homedir(), ".claude", "CLAUDE.md"),
+		instructionsPath: () => path$2.join(os.homedir(), ".claude", "CLAUDE.md"),
 		isDetected: () => dirExists(".claude")
 	},
 	{
 		id: "codex",
 		name: "Codex",
-		instructionsPath: () => path$1.join(os.homedir(), ".codex", "AGENTS.md"),
+		instructionsPath: () => path$2.join(os.homedir(), ".codex", "AGENTS.md"),
 		isDetected: () => dirExists(".codex")
 	},
 	{
 		id: "gemini",
 		name: "Gemini CLI",
-		instructionsPath: () => path$1.join(os.homedir(), ".gemini", "GEMINI.md"),
+		instructionsPath: () => path$2.join(os.homedir(), ".gemini", "GEMINI.md"),
 		isDetected: () => dirExists(".gemini")
 	}
 ];
@@ -2851,6 +2873,7 @@ const SELF_DRIVING_ABORT_CASES = [
 	},
 	{
 		match: /^requires-interactive-mode$/i,
+		errorCode: ErrorCodes.CliInteractiveRequired,
 		message: "Interactive terminal required",
 		body: "Self-driving setup asks questions along the way (GitHub and issue trackers), so it needs an interactive terminal. Run the wizard outside CI / non-interactive mode."
 	},
@@ -3864,6 +3887,29 @@ const mcpTutorialConfig = {
 //#region src/lib/programs/mcp-analytics/index.ts
 const MCP_ANALYTICS_REPORT_FILE = "posthog-mcp-analytics-report.md";
 /**
+* `[ABORT]` reasons the mcp-analytics skill emits when the project can't be
+* instrumented. Kept in sync with the stop conditions in the skill's
+* `description.md` (context-mill `context/skills/mcp-analytics`).
+*/
+const MCP_ANALYTICS_ABORT_CASES = [
+	{
+		match: /^unsupported language for mcp analytics$/i,
+		errorCode: ErrorCodes.DetectUnsupportedPlatform,
+		message: "Unsupported language for MCP analytics",
+		body: "MCP analytics supports TypeScript/JavaScript (`@posthog/mcp`) and Python (`posthog.mcp`, shipped inside the `posthog` package). This project doesn't look like either, so there's nothing to instrument. See https://posthog.com/docs/mcp-analytics for the supported setups."
+	},
+	{
+		match: /^no mcp server found$/i,
+		message: "No MCP server found",
+		body: "This command instruments an existing MCP server with PostHog analytics, but no MCP server was found in this project. If you just want PostHog product analytics, run `npx @posthog/wizard` instead."
+	},
+	{
+		match: /^could not locate the server entry point$/i,
+		message: "Could not locate the MCP server entry point",
+		body: "This project has MCP signals, but the agent couldn't find where the server is constructed or requests are dispatched, so there's nowhere safe to add instrumentation. See https://posthog.com/docs/mcp-analytics for the supported server styles, or point the wizard at the package that defines the server if it's in a monorepo subdirectory."
+	}
+];
+/**
 * `wizard mcp-analytics` — flat skill command.
 *
 * Instruments the user's own MCP server with the `@posthog/mcp` SDK so it
@@ -3889,23 +3935,7 @@ const mcpAnalyticsConfig = createSkillProgram({
 	docsUrl: "https://posthog.com/docs/mcp-analytics",
 	spinnerMessage: "Setting up MCP analytics...",
 	estimatedDurationMinutes: 5,
-	abortCases: [
-		{
-			match: /^unsupported language for mcp analytics$/i,
-			message: "Unsupported language for MCP analytics",
-			body: "MCP analytics supports TypeScript/JavaScript (`@posthog/mcp`) and Python (`posthog.mcp`, shipped inside the `posthog` package). This project doesn't look like either, so there's nothing to instrument. See https://posthog.com/docs/mcp-analytics for the supported setups."
-		},
-		{
-			match: /^no mcp server found$/i,
-			message: "No MCP server found",
-			body: "This command instruments an existing MCP server with PostHog analytics, but no MCP server was found in this project. If you just want PostHog product analytics, run `npx @posthog/wizard` instead."
-		},
-		{
-			match: /^could not locate the server entry point$/i,
-			message: "Could not locate the MCP server entry point",
-			body: "This project has MCP signals, but the agent couldn't find where the server is constructed or requests are dispatched, so there's nowhere safe to add instrumentation. See https://posthog.com/docs/mcp-analytics for the supported server styles, or point the wizard at the package that defines the server if it's in a monorepo subdirectory."
-		}
-	]
+	abortCases: MCP_ANALYTICS_ABORT_CASES
 });
 //#endregion
 //#region src/lib/programs/replay-vision/index.ts
@@ -3943,8 +3973,10 @@ const REPLAY_VISION_SUPPORTED = new Set([
 	"flutter"
 ]);
 async function abortUnsupportedPlatform(integration) {
+	const name = FRAMEWORK_REGISTRY[integration]?.metadata.name ?? integration;
 	await wizardAbort({
-		message: `Session replay isn't available for ${FRAMEWORK_REGISTRY[integration]?.metadata.name ?? integration} projects, and Replay vision needs session recordings to watch — so there is nothing to set up here.
+		code: ErrorCodes.DetectUnsupportedPlatform,
+		message: `Session replay isn't available for ${name} projects, and Replay vision needs session recordings to watch — so there is nothing to set up here.
 
 If this repo also contains a web or mobile app, run the command from that project directory instead. See what replay supports at:
   https://posthog.com/docs/session-replay`,
@@ -4023,7 +4055,10 @@ const replayVisionConfig = {
 		await scopeInstallDirToProject(session);
 		const integration = await detectFramework(session.installDir);
 		if (!integration) {
-			await wizardAbort({ message: "Could not auto-detect your framework for this project." });
+			await wizardAbort({
+				code: ErrorCodes.DetectNoFramework,
+				message: "Could not auto-detect your framework for this project."
+			});
 			return;
 		}
 		if (!REPLAY_VISION_SUPPORTED.has(integration)) {
@@ -4290,7 +4325,7 @@ const mcpAddCommand = {
 function runMcpAdd(argv) {
 	const features = parseFeatures(argv.features);
 	(async () => {
-		const { readApiKeyFromEnv } = await import("./env-api-key-CzHDwfV2.js").then((n) => n.t);
+		const { readApiKeyFromEnv } = await import("./env-api-key-CwkRyrgi.js").then((n) => n.t);
 		const apiKey = argv.apiKey || readApiKeyFromEnv();
 		const debug = argv.debug;
 		const localMcp = argv.local;
@@ -4304,8 +4339,8 @@ function runMcpAdd(argv) {
 			return;
 		}
 		try {
-			const { startTUI } = await import("./start-tui-BQH4mQIZ.js");
-			const { buildSession } = await import("./wizard-session-Cw7-_OcZ.js");
+			const { startTUI } = await import("./start-tui-D1MqJVT1.js");
+			const { buildSession } = await import("./wizard-session-D1KQqUml.js");
 			const tui = startTUI(VERSION, Program.McpAdd);
 			tui.store.session = buildSession({
 				debug,
@@ -4322,7 +4357,7 @@ function runMcpAdd(argv) {
 }
 async function runHeadlessAdd(args) {
 	setUI(new LoggingUI());
-	const { addMCPServerToClientsStep } = await import("./add-mcp-server-to-clients-DWDEuDUR.js").then((n) => n.r);
+	const { addMCPServerToClientsStep } = await import("./add-mcp-server-to-clients-y0swAr9I.js").then((n) => n.r);
 	const { installed, failed } = await addMCPServerToClientsStep(args);
 	if (failed.length > 0 || installed.length === 0) process.exitCode = 1;
 }
@@ -4354,8 +4389,8 @@ function runMcpRemove(argv) {
 			return;
 		}
 		try {
-			const { startTUI } = await import("./start-tui-BQH4mQIZ.js");
-			const { buildSession } = await import("./wizard-session-Cw7-_OcZ.js");
+			const { startTUI } = await import("./start-tui-D1MqJVT1.js");
+			const { buildSession } = await import("./wizard-session-D1KQqUml.js");
 			const tui = startTUI(VERSION, Program.McpRemove);
 			tui.store.session = buildSession({
 				debug,
@@ -4371,7 +4406,7 @@ function runMcpRemove(argv) {
 /** No exit code on an empty result: nothing to remove is the requested end state. */
 async function runHeadlessRemove(local) {
 	setUI(new LoggingUI());
-	const { removeMCPServerFromClientsStep } = await import("./add-mcp-server-to-clients-DWDEuDUR.js").then((n) => n.r);
+	const { removeMCPServerFromClientsStep } = await import("./add-mcp-server-to-clients-y0swAr9I.js").then((n) => n.r);
 	await removeMCPServerFromClientsStep({ local });
 }
 //#endregion
@@ -4391,8 +4426,8 @@ function runMcpTutorial(argv) {
 		const debug = argv.debug;
 		const localMcp = argv.local;
 		try {
-			const { startTUI } = await import("./start-tui-BQH4mQIZ.js");
-			const { buildSession } = await import("./wizard-session-Cw7-_OcZ.js");
+			const { startTUI } = await import("./start-tui-D1MqJVT1.js");
+			const { buildSession } = await import("./wizard-session-D1KQqUml.js");
 			const tui = startTUI(VERSION, Program.McpTutorial);
 			tui.store.session = buildSession({
 				debug,
@@ -4402,6 +4437,10 @@ function runMcpTutorial(argv) {
 		} catch (err) {
 			setUI(new LoggingUI());
 			getUI().log.error(`The MCP tutorial requires an interactive terminal. ${err instanceof Error ? err.message : String(err)}`);
+			emitWizardError({
+				code: ErrorCodes.CliInteractiveRequired,
+				message: "The MCP tutorial requires an interactive terminal."
+			});
 			process.exit(1);
 		}
 	})();
@@ -4473,17 +4512,17 @@ function runWizard(config, options) {
 	(async () => {
 		try {
 			const installDir = options.installDir || process.cwd();
-			const { startTUI } = await import("./start-tui-BQH4mQIZ.js");
-			const { buildSession, RunPhase } = await import("./wizard-session-Cw7-_OcZ.js");
-			const { TaskStreamPush } = await import("./task-stream-jUARpyB5.js");
-			const { PostHogDestination } = await import("./posthog-ChzdlmCs.js");
+			const { startTUI } = await import("./start-tui-D1MqJVT1.js");
+			const { buildSession, RunPhase } = await import("./wizard-session-D1KQqUml.js");
+			const { TaskStreamPush } = await import("./task-stream-CLXzeuPO.js");
+			const { PostHogDestination } = await import("./posthog-BHyJiU05.js");
 			const local = getLocalDev();
 			const localServicesError = await checkLocalServices({
 				...local,
 				localPosthog: local.localPosthog && !options.baseUrl
 			});
 			if (localServicesError) {
-				const { wizardAbort } = await import("./wizard-abort-pFFH7dcx.js");
+				const { wizardAbort } = await import("./wizard-abort-oazJA1Jb.js");
 				await wizardAbort({ message: localServicesError });
 				return;
 			}
@@ -4554,7 +4593,7 @@ function runWizard(config, options) {
 				if (shown(step)) await advanceStep(step, activeTui.store, config);
 			}
 			else if (skipAgent) {
-				const { getOrAskForProjectData } = await import("./setup-utils-aWZEdfwh.js").then((n) => n.r);
+				const { getOrAskForProjectData } = await import("./setup-utils-BLKhAx6g.js").then((n) => n.r);
 				const { projectApiKey, host, accessToken, projectId } = await getOrAskForProjectData({
 					signup: session.signup,
 					ci: session.ci,
@@ -4605,6 +4644,10 @@ function runWizard(config, options) {
 			} catch {}
 			console.error("Wizard run failed:", err);
 			console.error(`Full logs: ${getLogFilePath()}`);
+			emitWizardError({
+				code: ErrorCodes.InternalUnhandled,
+				message: err instanceof Error ? err.message : String(err)
+			});
 			process.exit(1);
 		}
 	})();
@@ -4627,11 +4670,19 @@ function validateNonInteractiveOptions(options, mode) {
 	if (!options.apiKey) {
 		getUI().intro("PostHog Wizard");
 		getUI().log.error(`${label} mode requires --api-key (${keyHint})`);
+		emitWizardError({
+			code: ErrorCodes.ArgsMissingApiKey,
+			message: `${label} mode requires --api-key (${keyHint})`
+		});
 		process.exit(1);
 	}
 	if (!options.installDir) {
 		getUI().intro("PostHog Wizard");
 		getUI().log.error(`${label} mode requires --install-dir (directory to install in)`);
+		emitWizardError({
+			code: ErrorCodes.ArgsMissingInstallDir,
+			message: `${label} mode requires --install-dir`
+		});
 		process.exit(1);
 	}
 }
@@ -4655,11 +4706,11 @@ function runNonInteractive(config, options, mode) {
 	analytics.setTag("build", mode);
 	(async () => {
 		const path = await import("path");
-		const { buildSession, RunPhase, OutroKind } = await import("./wizard-session-Cw7-_OcZ.js");
-		const { readEnvironment } = await import("./environment-Cl-fIQku.js").then((n) => n.t);
-		const { readApiKeyFromEnv } = await import("./env-api-key-CzHDwfV2.js").then((n) => n.t);
-		const { configureLogFileFromEnvironment, logToFile } = await import("./debug-H-GTKvvU.js");
-		const { wizardAbort, WizardError } = await import("./wizard-abort-pFFH7dcx.js");
+		const { buildSession, RunPhase, OutroKind } = await import("./wizard-session-D1KQqUml.js");
+		const { readEnvironment } = await import("./environment-BGUJxuvj.js").then((n) => n.t);
+		const { readApiKeyFromEnv } = await import("./env-api-key-CwkRyrgi.js").then((n) => n.t);
+		const { configureLogFileFromEnvironment, logToFile } = await import("./debug-CWn7PsPd.js");
+		const { wizardAbort, WizardError } = await import("./wizard-abort-oazJA1Jb.js");
 		configureLogFileFromEnvironment();
 		const env = readEnvironment();
 		const apiKey = options.apiKey ?? readApiKeyFromEnv() ?? void 0;
@@ -4697,15 +4748,18 @@ function runNonInteractive(config, options, mode) {
 			localPosthog: session.baseUrl === POSTHOG_LOCAL_URL
 		});
 		if (localServicesError) {
-			await wizardAbort({ message: localServicesError });
+			await wizardAbort({
+				code: ErrorCodes.EnvLocalServicesDown,
+				message: localServicesError
+			});
 			return;
 		}
 		let store = null;
 		let taskStream = null;
 		if (mode === "headless") {
-			const { WizardStore } = await import("./store-P_7zUfbj.js").then((n) => n.n);
-			const { HeadlessUI } = await import("./headless-ui-DT3Db1bk.js");
-			const { TaskStreamPush, PostHogDestination } = await import("./task-stream-jUARpyB5.js");
+			const { WizardStore } = await import("./store-OGBMWp3H.js").then((n) => n.n);
+			const { HeadlessUI } = await import("./headless-ui-DtIYZNVv.js");
+			const { TaskStreamPush, PostHogDestination } = await import("./task-stream-CLXzeuPO.js");
 			store = new WizardStore(config.id);
 			store.session = session;
 			setUI(new HeadlessUI(store));
@@ -4741,27 +4795,54 @@ function runNonInteractive(config, options, mode) {
 					setSkillId: (skillId) => {
 						session.skillId = skillId;
 					},
-					setUnsupportedVersion: () => void 0,
+					setUnsupportedVersion: (info) => {
+						session.unsupportedVersion = info;
+					},
 					addDiscoveredFeature: () => void 0,
 					setDetectionComplete: () => void 0
 				};
 				for (const step of config.steps) if (step.onReady) await step.onReady(readyCtx);
 				const detectError = session.frameworkContext.detectError;
+				if (session.unsupportedVersion) {
+					const { current, minimum, docsUrl } = session.unsupportedVersion;
+					const message = `Detected framework version ${current} is not supported. Minimum supported version is ${minimum}.`;
+					await settleStream(RunPhase.Error, {
+						kind: OutroKind.Error,
+						message,
+						errorCode: ErrorCodes.DetectUnsupportedVersion
+					});
+					await wizardAbort({
+						code: ErrorCodes.DetectUnsupportedVersion,
+						message: `${message}\n\nSee ${docsUrl}`,
+						error: new WizardError(`${config.id} unsupported framework version`, {
+							integration: config.id,
+							current,
+							minimum
+						}, ErrorCodes.DetectUnsupportedVersion)
+					});
+				}
 				if (detectError) {
+					const code = detectErrorCode(detectError.kind);
+					const detectKind = detectError.kind;
+					const detail = { ...detectError };
 					await settleStream(RunPhase.Error, {
 						kind: OutroKind.Error,
-						message: `Prerequisites not met: ${detectError.kind}`
+						message: `Prerequisites not met: ${detectKind}`,
+						errorCode: code,
+						errorDetail: detail
 					});
 					await wizardAbort({
-						message: `Prerequisites not met: ${detectError.kind}\n\nSee ${runDef?.docsUrl ?? "https://posthog.com/docs"}`,
+						code,
+						detail,
+						message: `Prerequisites not met: ${detectKind}\n\nSee ${runDef?.docsUrl ?? "https://posthog.com/docs"}`,
 						error: new WizardError(`${config.id} prerequisites failed`, {
 							integration: config.id,
-							detect_error_kind: detectError.kind
-						})
+							detect_error_kind: detectKind
+						}, code)
 					});
 				}
 			}
-			const { runAgent } = await import("./agent-runner-DEeMqJxy.js").then((n) => n.t);
+			const { runAgent } = await import("./agent-runner-Do5kyhPo.js").then((n) => n.t);
 			await runAgent(config, session);
 			await settleStream(RunPhase.Completed);
 		} catch (error) {
@@ -4773,14 +4854,20 @@ function runNonInteractive(config, options, mode) {
 			const docsUrl = session.frameworkConfig?.metadata.docsUrl ?? runDef?.docsUrl ?? "https://posthog.com/docs";
 			await settleStream(RunPhase.Error, {
 				kind: OutroKind.Error,
-				message: errorMessage
+				message: errorMessage,
+				errorCode: ErrorCodes.InternalUnhandled
 			});
 			await wizardAbort({
+				code: ErrorCodes.InternalUnhandled,
 				message: `Something went wrong: ${errorMessage}\n\nYou can read the documentation at ${docsUrl} to set up manually.${debugInfo}`,
 				error
 			});
 		}
-	})().catch(() => {
+	})().catch((error) => {
+		emitWizardError({
+			code: ErrorCodes.InternalUnhandled,
+			message: error instanceof Error ? error.message : String(error)
+		});
 		process.exit(1);
 	});
 }
@@ -4846,12 +4933,16 @@ function runCommandHandler(work) {
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			process.stderr.write(`\n\x1b[1;91m✖ ${msg}\x1b[0m\n\n`);
+			emitWizardError({
+				code: ErrorCodes.InternalUnhandled,
+				message: msg
+			});
 			process.exit(1);
 		}
 	})();
 }
 function dispatchProgram(config, argv) {
-	const argvRecord = argv;
+	const argvRecord = { ...argv };
 	const extras = config.mapCliOptions?.(argvRecord) ?? {};
 	const options = {
 		...argvRecord,
@@ -4957,6 +5048,10 @@ async function exitDispatchError(reason, properties, message, code = 1) {
 		await analytics.flush();
 	} catch {}
 	process.stderr.write(message);
+	emitWizardError({
+		code: ErrorCodes.CliBadArgs,
+		message: reason
+	});
 	return process.exit(code);
 }
 /**
@@ -5985,12 +6080,16 @@ async function runDoctorCI(options) {
 	if (!apiKey) {
 		getUI().intro("PostHog Wizard");
 		getUI().log.error("CI mode requires --api-key (personal API key phx_xxx)");
+		emitWizardError({
+			code: ErrorCodes.ArgsMissingApiKey,
+			message: "CI mode requires --api-key (personal API key phx_xxx)"
+		});
 		process.exit(1);
 	}
 	getUI().intro("Welcome to the PostHog setup wizard");
 	getUI().log.info("Running posthog-doctor in CI mode");
 	try {
-		const { getOrAskForProjectData } = await import("./setup-utils-aWZEdfwh.js").then((n) => n.r);
+		const { getOrAskForProjectData } = await import("./setup-utils-BLKhAx6g.js").then((n) => n.r);
 		const { host, accessToken, projectId } = await getOrAskForProjectData({
 			signup: false,
 			ci: true,
@@ -6008,9 +6107,13 @@ async function runDoctorCI(options) {
 		for (const issue of sorted) getUI().log.info(`  • [${issue.severity}] ${getKindMeta(issue.kind).title}`);
 		process.exit(1);
 	} catch (error) {
-		const { ApiError } = await import("./api-CemGgyBv.js").then((n) => n.n);
+		const { ApiError } = await import("./api-D7-8R4xx.js").then((n) => n.n);
 		const message = error instanceof ApiError && error.statusCode === 401 ? "Your PostHog API key is invalid or expired." : error instanceof Error ? error.message : String(error);
 		getUI().log.error(`Doctor failed: ${message}`);
+		emitWizardError({
+			code: error instanceof ApiError && error.statusCode === 401 ? ErrorCodes.AuthInvalidOrExpired : ErrorCodes.InternalUnhandled,
+			message
+		});
 		process.exit(1);
 	}
 }
@@ -6090,8 +6193,8 @@ function runSlackConnect(argv) {
 	(async () => {
 		const debug = argv.debug;
 		try {
-			const { startTUI } = await import("./start-tui-BQH4mQIZ.js");
-			const { buildSession } = await import("./wizard-session-Cw7-_OcZ.js");
+			const { startTUI } = await import("./start-tui-D1MqJVT1.js");
+			const { buildSession } = await import("./wizard-session-D1KQqUml.js");
 			const tui = startTUI(VERSION, Program.SlackConnect);
 			tui.store.session = buildSession({
 				debug,
@@ -6100,6 +6203,10 @@ function runSlackConnect(argv) {
 		} catch (err) {
 			setUI(new LoggingUI());
 			getUI().log.error(`Connecting Slack requires an interactive terminal. ${err instanceof Error ? err.message : String(err)}`);
+			emitWizardError({
+				code: ErrorCodes.CliInteractiveRequired,
+				message: "Connecting Slack requires an interactive terminal."
+			});
 			process.exit(1);
 		}
 	})();
@@ -6217,6 +6324,10 @@ const skillCommand = {
 						await analytics.flush();
 					} catch {}
 					process.stderr.write("\n\x1B[1;91m✖ Couldn't reach the skill registry.\x1B[0m\n  Check your network connection and try again.\n\n");
+					emitWizardError({
+						code: ErrorCodes.SkillMenuFetchFailed,
+						message: "Couldn't reach the skill registry."
+					});
 					process.exit(1);
 				}
 				const entries = (menu.cliEntries ?? []).filter((e) => BROWSABLE_ROLES.has(e.role));
@@ -6333,7 +6444,7 @@ async function runCliAdd(argv) {
 /** Resolve which instruction files to write, from flags, detection, or a prompt. */
 async function resolveTargetFiles(argv) {
 	const ui = getUI();
-	if (typeof argv.path === "string" && argv.path.trim()) return [path$1.resolve(argv.path.trim())];
+	if (typeof argv.path === "string" && argv.path.trim()) return [path$2.resolve(argv.path.trim())];
 	if (typeof argv.agent === "string") {
 		const target = findTarget(argv.agent);
 		if (!target) {
@@ -6410,6 +6521,10 @@ if (!satisfies(process.version, NODE_VERSION_RANGE)) {
 		``,
 		`Then run the wizard again. Stuck? Email wizard@posthog.com and we'll help.`
 	].join("\n"));
+	emitWizardError({
+		code: ErrorCodes.CliNodeVersion,
+		message: `Node ${process.version} is below the required range ${NODE_VERSION_RANGE}`
+	});
 	process.exit(1);
 }
 recoverOrphanedSettingsBackups(resolveInstallDir());