refactor: brand CommandOutput with Symbol and move hints to generator return

Three improvements to the command framework's output system:

1. **Brand CommandOutput with Symbol discriminant**
   - Add COMMAND_OUTPUT_BRAND Symbol to CommandOutput type
   - Add commandOutput() factory function for creating branded values
   - Replace duck-typing ('data' in v) with Symbol check in isCommandOutput()
   - Prevents false positives from raw API responses with 'data' property

2. **Move hints from yield to generator return value**
   - Add CommandReturn type ({ hint?: string }) for generator return values
   - Switch from for-await-of to manual .next() iteration to capture return
   - renderCommandOutput no longer handles hints; wrapper renders post-loop
   - All commands: yield commandOutput(data) + return { hint }

3. **Eliminate noExplicitAny suppressions in command.ts**
   - wrappedFunc params: any → Record<string, unknown> / unknown[]
   - Final Stricli cast: as any → as unknown as StricliBuilderArgs<CONTEXT>
   - OutputConfig<any> kept with improved variance explanation
   - renderCommandOutput config param: kept any with contravariance docs

All 24 command files migrated to use commandOutput() helper.
Tests updated for branded outputs and hint-on-return pattern.

1083 tests pass, 0 fail, 9356 assertions across 38 files.

Author: BYK

src/commands/api.ts

@@ -9,6 +9,7 @@ import type { SentryContext } from "../context.js";
 import { buildSearchParams, rawApiRequest } from "../lib/api-client.js";
 import { buildCommand } from "../lib/command.js";
 import { OutputError, ValidationError } from "../lib/errors.js";
+import { commandOutput } from "../lib/formatters/output.js";
 import { validateEndpoint } from "../lib/input-validation.js";
 import { logger } from "../lib/logger.js";
 import { getDefaultSdkConfig } from "../lib/sentry-client.js";
@@ -1168,14 +1169,12 @@ export const apiCommand = buildCommand({
 
     // Dry-run mode: preview the request that would be sent
     if (flags["dry-run"]) {
-      yield {
-        data: {
-          method: flags.method,
-          url: resolveRequestUrl(normalizedEndpoint, params),
-          headers: resolveEffectiveHeaders(headers, body),
-          body: body ?? null,
-        },
-      };
+      yield commandOutput({
+        method: flags.method,
+        url: resolveRequestUrl(normalizedEndpoint, params),
+        headers: resolveEffectiveHeaders(headers, body),
+        body: body ?? null,
+      });
       return;
     }
 
@@ -1211,7 +1210,7 @@ export const apiCommand = buildCommand({
       throw new OutputError(response.body);
     }
 
-    yield { data: response.body };
+    yield commandOutput(response.body);
     return;
   },
 });

src/commands/auth/logout.ts

@@ -15,6 +15,7 @@ import {
 import { getDbPath } from "../../lib/db/index.js";
 import { AuthError } from "../../lib/errors.js";
 import { formatLogoutResult } from "../../lib/formatters/human.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 
 /** Structured result of the logout operation */
 export type LogoutResult = {
@@ -38,9 +39,10 @@ export const logoutCommand = buildCommand({
   },
   async *func(this: SentryContext) {
     if (!(await isAuthenticated())) {
-      yield {
-        data: { loggedOut: false, message: "Not currently authenticated." },
-      };
+      yield commandOutput({
+        loggedOut: false,
+        message: "Not currently authenticated.",
+      });
       return;
     }
 
@@ -56,12 +58,10 @@ export const logoutCommand = buildCommand({
     const configPath = getDbPath();
     await clearAuth();
 
-    yield {
-      data: {
-        loggedOut: true,
-        configPath,
-      },
-    };
+    yield commandOutput({
+      loggedOut: true,
+      configPath,
+    });
     return;
   },
 });

src/commands/auth/refresh.ts

@@ -15,6 +15,7 @@ import {
 import { AuthError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import { formatDuration } from "../../lib/formatters/human.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 
 type RefreshFlags = {
   readonly json: boolean;
@@ -104,7 +105,7 @@ Examples:
         : undefined,
     };
 
-    yield { data: payload };
+    yield commandOutput(payload);
     return;
   },
 });

src/commands/auth/status.ts

@@ -22,6 +22,7 @@ import { getDbPath } from "../../lib/db/index.js";
 import { getUserInfo } from "../../lib/db/user.js";
 import { AuthError, stringifyUnknown } from "../../lib/errors.js";
 import { formatAuthStatus, maskToken } from "../../lib/formatters/human.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -189,7 +190,7 @@ export const statusCommand = buildCommand({
       verification: await verifyCredentials(),
     };
 
-    yield { data };
+    yield commandOutput(data);
     return;
   },
 });

src/commands/auth/whoami.ts

@@ -13,6 +13,7 @@ import { isAuthenticated } from "../../lib/db/auth.js";
 import { setUserInfo } from "../../lib/db/user.js";
 import { AuthError } from "../../lib/errors.js";
 import { formatUserIdentity } from "../../lib/formatters/index.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -65,7 +66,7 @@ export const whoamiCommand = buildCommand({
       // Cache update failure is non-essential — user identity was already fetched.
     }
 
-    yield { data: user };
+    yield commandOutput(user);
     return;
   },
 });

src/commands/cli/feedback.ts

@@ -14,6 +14,7 @@ import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { ConfigError, ValidationError } from "../../lib/errors.js";
 import { formatFeedbackResult } from "../../lib/formatters/human.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 
 /** Structured result of the feedback submission */
 export type FeedbackResult = {
@@ -66,12 +67,10 @@ export const feedbackCommand = buildCommand({
     // Flush to ensure feedback is sent before process exits
     const sent = await Sentry.flush(3000);
 
-    yield {
-      data: {
-        sent,
-        message,
-      },
-    };
+    yield commandOutput({
+      sent,
+      message,
+    });
     return;
   },
 });

src/commands/cli/fix.ts

@@ -17,6 +17,7 @@ import {
 } from "../../lib/db/schema.js";
 import { OutputError } from "../../lib/errors.js";
 import { formatFixResult } from "../../lib/formatters/human.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 import { getRealUsername } from "../../lib/utils.js";
 
 type FixFlags = {
@@ -734,7 +735,7 @@ export const fixCommand = buildCommand({
       throw new OutputError(result);
     }
 
-    yield { data: result };
+    yield commandOutput(result);
     return;
   },
 });

src/commands/cli/upgrade.ts

@@ -31,6 +31,7 @@ import {
 } from "../../lib/db/release-channel.js";
 import { UpgradeError } from "../../lib/errors.js";
 import { formatUpgradeResult } from "../../lib/formatters/human.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 import { logger } from "../../lib/logger.js";
 import {
   detectInstallationMethod,
@@ -493,7 +494,7 @@ export const upgradeCommand = buildCommand({
       flags,
     });
     if (resolved.kind === "done") {
-      yield { data: resolved.result };
+      yield commandOutput(resolved.result);
       return;
     }
 
@@ -510,17 +511,15 @@ export const upgradeCommand = buildCommand({
         target,
         versionArg
       );
-      yield {
-        data: {
-          action: downgrade ? "downgraded" : "upgraded",
-          currentVersion: CLI_VERSION,
-          targetVersion: target,
-          channel,
-          method,
-          forced: flags.force,
-          warnings,
-        } satisfies UpgradeResult,
-      };
+      yield commandOutput({
+        action: downgrade ? "downgraded" : "upgraded",
+        currentVersion: CLI_VERSION,
+        targetVersion: target,
+        channel,
+        method,
+        forced: flags.force,
+        warnings,
+      } satisfies UpgradeResult);
       return;
     }
 
@@ -532,16 +531,14 @@ export const upgradeCommand = buildCommand({
       execPath: this.process.execPath,
     });
 
-    yield {
-      data: {
-        action: downgrade ? "downgraded" : "upgraded",
-        currentVersion: CLI_VERSION,
-        targetVersion: target,
-        channel,
-        method,
-        forced: flags.force,
-      } satisfies UpgradeResult,
-    };
+    yield commandOutput({
+      action: downgrade ? "downgraded" : "upgraded",
+      currentVersion: CLI_VERSION,
+      targetVersion: target,
+      channel,
+      method,
+      forced: flags.force,
+    } satisfies UpgradeResult);
     return;
   },
 });

src/commands/event/view.ts

@@ -23,6 +23,7 @@ import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
 import { formatEventDetails } from "../../lib/formatters/index.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -380,12 +381,11 @@ export const viewCommand = buildCommand({
       ? { traceId: spanTreeResult.traceId, spans: spanTreeResult.spans }
       : null;
 
-    yield {
-      data: { event, trace, spanTreeLines: spanTreeResult?.lines },
+    yield commandOutput({ event, trace, spanTreeLines: spanTreeResult?.lines });
+    return {
       hint: target.detectedFrom
         ? `Detected from ${target.detectedFrom}`
         : undefined,
     };
-    return;
   },
 });

src/commands/issue/explain.ts

@@ -7,6 +7,7 @@
 import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { ApiError } from "../../lib/errors.js";
+import { commandOutput } from "../../lib/formatters/output.js";
 import {
   formatRootCauseList,
   handleSeerApiError,
@@ -104,11 +105,8 @@ export const explainCommand = buildCommand({
         );
       }
 
-      yield {
-        data: causes,
-        hint: `To create a plan, run: sentry issue plan ${issueArg}`,
-      };
-      return;
+      yield commandOutput(causes);
+      return { hint: `To create a plan, run: sentry issue plan ${issueArg}` };
     } catch (error) {
       // Handle API errors with friendly messages
       if (error instanceof ApiError) {