feat(init): surface server-provided detail in spinner messages (#588)

## Summary

- Add optional `detail?: string` field to all `LocalOpPayload` types
- Update spinner message logic to prefer `detail` over generic
`"${label} (${operation})..."` format
- Add tests for both detail-present and detail-absent cases

Closes getsentry/cli-init-api#11

## Example

Before: `Installing dependencies (run-commands)...`

After (when server provides detail): `npm install @sentry/nextjs
@sentry/profiling-node`

Author: MathurAditya724

.gitignore

@@ -59,3 +59,4 @@ src/sdk.generated.d.cts
 
 # OpenCode
 .opencode/
+opencode.json*

src/lib/init/types.ts

@@ -30,6 +30,8 @@ export type LocalOpPayload =
 export type ListDirPayload = {
   type: "local-op";
   operation: "list-dir";
+  /** Human-readable spinner hint from the server (≤ 120 chars, sensitive values redacted). */
+  detail?: string;
   cwd: string;
   params: {
     path: string;
@@ -42,6 +44,8 @@ export type ListDirPayload = {
 export type ReadFilesPayload = {
   type: "local-op";
   operation: "read-files";
+  /** Human-readable spinner hint from the server (≤ 120 chars, sensitive values redacted). */
+  detail?: string;
   cwd: string;
   params: {
     paths: string[];
@@ -52,6 +56,8 @@ export type ReadFilesPayload = {
 export type FileExistsBatchPayload = {
   type: "local-op";
   operation: "file-exists-batch";
+  /** Human-readable spinner hint from the server (≤ 120 chars, sensitive values redacted). */
+  detail?: string;
   cwd: string;
   params: {
     paths: string[];
@@ -61,6 +67,8 @@ export type FileExistsBatchPayload = {
 export type RunCommandsPayload = {
   type: "local-op";
   operation: "run-commands";
+  /** Human-readable spinner hint from the server (≤ 120 chars, sensitive values redacted). */
+  detail?: string;
   cwd: string;
   params: {
     commands: string[];
@@ -71,6 +79,8 @@ export type RunCommandsPayload = {
 export type ApplyPatchsetPayload = {
   type: "local-op";
   operation: "apply-patchset";
+  /** Human-readable spinner hint from the server (≤ 120 chars, sensitive values redacted). */
+  detail?: string;
   cwd: string;
   params: {
     patches: Array<{
@@ -84,6 +94,8 @@ export type ApplyPatchsetPayload = {
 export type CreateSentryProjectPayload = {
   type: "local-op";
   operation: "create-sentry-project";
+  /** Human-readable spinner hint from the server (≤ 120 chars, sensitive values redacted). */
+  detail?: string;
   cwd: string;
   params: {
     name: string;

src/lib/init/wizard-runner.ts

@@ -58,6 +58,19 @@ function nextPhase(
   return names[Math.min(phase - 1, names.length - 1)] ?? "done";
 }
 
+/**
+ * Truncate a spinner message to fit within the terminal width.
+ * Leaves room for the spinner character and padding.
+ */
+function truncateForTerminal(message: string): string {
+  // Reserve space for spinner (2 chars) + some padding
+  const maxWidth = (process.stdout.columns || 80) - 4;
+  if (message.length <= maxWidth) {
+    return message;
+  }
+  return `${message.slice(0, maxWidth - 1)}…`;
+}
+
 async function handleSuspendedStep(
   ctx: StepContext,
   stepPhases: Map<string, number>,
@@ -67,8 +80,10 @@ async function handleSuspendedStep(
   const label = STEP_LABELS[stepId] ?? stepId;
 
   if (payload.type === "local-op") {
-    const detail = payload.operation ? ` (${payload.operation})` : "";
-    spin.message(`${label}${detail}...`);
+    const message = payload.detail
+      ? payload.detail
+      : `${label} (${payload.operation})...`;
+    spin.message(truncateForTerminal(message));
 
     const localResult = await handleLocalOp(payload, options);
 

test/lib/init/wizard-runner.test.ts

@@ -485,6 +485,102 @@ describe("runWizard", () => {
       expect(payload.operation).toBe("list-dir");
     });
 
+    test("uses detail field for spinner message when present", async () => {
+      mockStartResult = {
+        status: "suspended",
+        suspended: [["install-deps"]],
+        steps: {
+          "install-deps": {
+            suspendPayload: {
+              type: "local-op",
+              operation: "run-commands",
+              detail: "npm install @sentry/nextjs @sentry/profiling-node",
+              cwd: "/app",
+              params: {
+                commands: ["npm install @sentry/nextjs @sentry/profiling-node"],
+              },
+            },
+          },
+        },
+      };
+      mockResumeResults = [{ status: "success" }];
+
+      await runWizard(makeOptions());
+
+      expect(spinnerMock.message).toHaveBeenCalledWith(
+        "npm install @sentry/nextjs @sentry/profiling-node"
+      );
+    });
+
+    test("falls back to generic message when detail is absent", async () => {
+      mockStartResult = {
+        status: "suspended",
+        suspended: [["install-deps"]],
+        steps: {
+          "install-deps": {
+            suspendPayload: {
+              type: "local-op",
+              operation: "run-commands",
+              cwd: "/app",
+              params: { commands: ["npm install @sentry/nextjs"] },
+            },
+          },
+        },
+      };
+      mockResumeResults = [{ status: "success" }];
+
+      await runWizard(makeOptions());
+
+      expect(spinnerMock.message).toHaveBeenCalledWith(
+        "Installing dependencies (run-commands)..."
+      );
+    });
+
+    test("truncates detail message when terminal is narrow", async () => {
+      const origColumns = process.stdout.columns;
+      Object.defineProperty(process.stdout, "columns", {
+        value: 40,
+        configurable: true,
+      });
+
+      const longDetail =
+        "npm install @sentry/nextjs @sentry/profiling-node @sentry/browser";
+      mockStartResult = {
+        status: "suspended",
+        suspended: [["install-deps"]],
+        steps: {
+          "install-deps": {
+            suspendPayload: {
+              type: "local-op",
+              operation: "run-commands",
+              detail: longDetail,
+              cwd: "/app",
+              params: { commands: [longDetail] },
+            },
+          },
+        },
+      };
+      mockResumeResults = [{ status: "success" }];
+
+      try {
+        await runWizard(makeOptions());
+
+        // 40 columns - 4 reserved = 36 max, truncated with "…"
+        const call = spinnerMock.message.mock.calls.find((c: string[]) =>
+          c[0]?.includes("npm install")
+        ) as string[] | undefined;
+        expect(call).toBeDefined();
+        const msg = call?.[0] ?? "";
+        expect(msg.length).toBeLessThanOrEqual(36);
+        expect(msg.endsWith("…")).toBe(true);
+      } finally {
+        Object.defineProperty(process.stdout, "columns", {
+          value: origColumns,
+          configurable: true,
+        });
+      }
+    });
+
     test("dispatches interactive payload to handleInteractive", async () => {
       mockStartResult = {
         status: "suspended",