fix(init): surface wizard exit code and command stderr in Sentry events (CLI-1JA) (#980)

## Summary

Every event in CLI-1JA was identical in Sentry: \`WizardError: Workflow
returned an error\` with no way to distinguish exit 11 (no files found),
20 (unknown platform), 30 (install failed), or 41 (codemod failed). The
server already tags \`wizard.exit_code\` via \`bailWithTracking\`, but
the CLI-side event never reflected it.

## Changes

**\`wizard-runner.ts\`** — \`handleFinalResult\` now tags
\`wizard.exit_code\` with the numeric workflow code when present, and
uses \`result.result?.message ?? result.error\` as the \`WizardError\`
message instead of the generic fallback. Priority order matches
\`formatError\` (which already showed the right message in the terminal,
just not in Sentry).

**\`run-commands.ts\`** — adds an explicit \`addBreadcrumb\` with up to
500 chars of stderr when a spawned command exits non-zero. The automatic
Sentry child-process breadcrumb only captured the exit code;
pnpm/npm/xcodebuild failure reasons were invisible.

## Test Plan

- New events in CLI-1JA should carry \`wizard.exit_code: 11/20/30/41\`
so failures are immediately distinguishable
- The exception message will be the actual bail reason (e.g. "Dependency
installation failed after 5 attempts…") instead of "Workflow returned an
error"
- Command failure breadcrumbs will show the first 500 chars of stderr
from pnpm/npm/xcodebuild

8 new unit tests cover both changes
(\`wizard-runner-handle-final-result.mocked.test.ts\`,
\`run-commands.mocked.test.ts\`).

Fixes CLI-1JA

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: betegon

src/lib/init/tools/run-commands.ts

@@ -1,3 +1,4 @@
+import { addBreadcrumb } from "@sentry/node-core/light";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "../constants.js";
 import type { RunCommandsPayload, ToolResult } from "../types.js";
 import {
@@ -46,6 +47,15 @@ export async function runCommands(
     const result = await runSingleCommand(command, payload.cwd, timeoutMs);
     results.push(result);
     if (result.exitCode !== 0) {
+      addBreadcrumb({
+        level: "error",
+        message: `Command failed: ${command.original}`,
+        data: {
+          exitCode: result.exitCode,
+          stderr: result.stderr.slice(0, 500),
+          cwd: payload.cwd,
+        },
+      });
       return {
         ok: false,
         error: `Command "${command.original}" failed with exit code ${result.exitCode}: ${result.stderr}`,

src/lib/init/wizard-runner.ts

@@ -846,7 +846,7 @@ export async function runWizard(initialOptions: WizardOptions): Promise<void> {
   }
 }
 
-function handleFinalResult(
+export function handleFinalResult(
   result: WorkflowRunResult,
   spin: SpinnerHandle,
   spinState: SpinState,
@@ -865,7 +865,13 @@ function handleFinalResult(
     const workflowCode = result.result?.exitCode;
     const exitCode = mapWorkflowExitCode(workflowCode);
     setTag("wizard.outcome", "errored");
-    throw new WizardError("Workflow returned an error", { exitCode });
+    if (workflowCode !== undefined) {
+      setTag("wizard.exit_code", workflowCode);
+    }
+    throw new WizardError(
+      result.result?.message ?? result.error ?? "Workflow returned an error",
+      { exitCode }
+    );
   }
 
   if (spinState.running) {

test/lib/run-commands.mocked.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Unit tests for the run-commands tool.
+ *
+ * Kept as a mocked sibling file because mock.module() on @sentry/node-core/light
+ * must precede all module imports to take effect.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import type { RunCommandsPayload } from "../../src/lib/init/types.js";
+
+// ============================================================================
+// Mock Setup — must precede all imports of the module under test
+// ============================================================================
+
+type Breadcrumb = {
+  level: string;
+  message: string;
+  data: { exitCode: number; stderr: string; cwd: string };
+};
+
+const breadcrumbs: Breadcrumb[] = [];
+
+mock.module("@sentry/node-core/light", () => ({
+  addBreadcrumb: (crumb: Breadcrumb) => breadcrumbs.push(crumb),
+}));
+
+// Import AFTER mock setup
+import { runCommands } from "../../src/lib/init/tools/run-commands.js";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makePayload(commands: string[], cwd = "/tmp"): RunCommandsPayload {
+  return { type: "tool", operation: "run-commands", cwd, params: { commands } };
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+beforeEach(() => breadcrumbs.splice(0));
+
+describe("runCommands breadcrumb on failure", () => {
+  test("emits an error breadcrumb with stderr when a command exits non-zero", async () => {
+    // `ls /nonexistent-sentry-test-path` exits 1 on macOS/Linux with a
+    // "No such file" message on stderr — a reliable non-zero exit without
+    // requiring shell built-ins.
+    const result = await runCommands(
+      makePayload(["ls /nonexistent-sentry-test-path-xyz"]),
+      { dryRun: false }
+    );
+
+    expect(result.ok).toBe(false);
+    expect(breadcrumbs).toHaveLength(1);
+
+    const crumb = breadcrumbs[0];
+    expect(crumb.level).toBe("error");
+    expect(crumb.message).toContain("ls");
+    expect(crumb.data.exitCode).not.toBe(0);
+    expect(typeof crumb.data.stderr).toBe("string");
+    expect(crumb.data.cwd).toBe("/tmp");
+  });
+
+  test("does not emit a breadcrumb when the command succeeds", async () => {
+    const result = await runCommands(makePayload(["echo hello"]), {
+      dryRun: false,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(breadcrumbs).toHaveLength(0);
+  });
+
+  test("does not emit a breadcrumb in dry-run mode", async () => {
+    const result = await runCommands(
+      makePayload(["ls /nonexistent-sentry-test-path-xyz"]),
+      { dryRun: true }
+    );
+
+    expect(result.ok).toBe(true);
+    expect(breadcrumbs).toHaveLength(0);
+  });
+});

test/lib/wizard-runner-handle-final-result.mocked.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Unit tests for handleFinalResult in wizard-runner.ts.
+ *
+ * Kept as a mocked sibling file because mock.module() on @sentry/node-core/light
+ * would pollute the module graph for other wizard-runner tests that may not
+ * want Sentry calls mocked.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import type {
+  WizardOutput,
+  WorkflowRunResult,
+} from "../../src/lib/init/types.js";
+
+// ============================================================================
+// Mock Setup — must precede all imports of the module under test
+// ============================================================================
+
+const tags: Record<string, unknown> = {};
+
+mock.module("@sentry/node-core/light", () => ({
+  addBreadcrumb: () => null,
+  captureException: () => null,
+  getTraceData: () => ({}),
+  setTag: (key: string, value: unknown) => {
+    tags[key] = value;
+  },
+}));
+
+import { WizardError } from "../../src/lib/errors.js";
+// Import AFTER mock setup so the mocked module is used
+import { handleFinalResult } from "../../src/lib/init/wizard-runner.js";
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+function makeSpinnerHandle() {
+  return { start: () => null, stop: () => null };
+}
+
+function makeSpinState(running = false) {
+  return { running };
+}
+
+/** Minimal WizardUI stub — only the methods formatError touches. */
+function makeUI() {
+  const noop = () => null;
+  return {
+    log: { error: noop, warn: noop, info: noop, message: noop },
+    cancel: noop,
+    feedback: noop,
+    summary: noop,
+    outro: noop,
+    intro: noop,
+    setStep: noop,
+    markFilesAnalyzed: noop,
+  } as any;
+}
+
+function makeBailResult(
+  partial: Partial<WizardOutput> = {}
+): WorkflowRunResult {
+  return {
+    status: "success",
+    result: { exitCode: 30, ...partial },
+  };
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+beforeEach(() => {
+  for (const key of Object.keys(tags)) {
+    delete tags[key];
+  }
+});
+
+describe("handleFinalResult", () => {
+  describe("WizardError message", () => {
+    test("uses bail message from result.result.message when present", () => {
+      const result = makeBailResult({
+        message:
+          "Dependency installation failed after 5 attempts: pnpm exited with code 1",
+      });
+
+      expect(() =>
+        handleFinalResult(
+          result,
+          makeSpinnerHandle(),
+          makeSpinState(),
+          makeUI()
+        )
+      ).toThrow(
+        "Dependency installation failed after 5 attempts: pnpm exited with code 1"
+      );
+    });
+
+    test("falls back to generic message when result.result.message is absent", () => {
+      const result = makeBailResult({ message: undefined });
+
+      expect(() =>
+        handleFinalResult(
+          result,
+          makeSpinnerHandle(),
+          makeSpinState(),
+          makeUI()
+        )
+      ).toThrow("Workflow returned an error");
+    });
+  });
+
+  describe("wizard.exit_code tag", () => {
+    test("tags wizard.exit_code with the workflow exit code", () => {
+      const result = makeBailResult({ exitCode: 11 });
+
+      expect(() =>
+        handleFinalResult(
+          result,
+          makeSpinnerHandle(),
+          makeSpinState(),
+          makeUI()
+        )
+      ).toThrow(WizardError);
+
+      expect(tags["wizard.exit_code"]).toBe(11);
+    });
+
+    test("does not set wizard.exit_code when exitCode is absent", () => {
+      const result: WorkflowRunResult = {
+        status: "failed",
+        error: "network error",
+      };
+
+      expect(() =>
+        handleFinalResult(
+          result,
+          makeSpinnerHandle(),
+          makeSpinState(),
+          makeUI()
+        )
+      ).toThrow(WizardError);
+
+      expect(tags["wizard.exit_code"]).toBeUndefined();
+    });
+  });
+
+  describe("WizardError message — result.error fallback", () => {
+    test("uses result.error when result.result is absent (plain workflow failure)", () => {
+      const result: WorkflowRunResult = {
+        status: "failed",
+        error: "upstream network timeout",
+      };
+
+      expect(() =>
+        handleFinalResult(
+          result,
+          makeSpinnerHandle(),
+          makeSpinState(),
+          makeUI()
+        )
+      ).toThrow("upstream network timeout");
+    });
+  });
+});