feat: return-based output with OutputConfig on buildCommand

Commands with output config return bare data or [data, {hint}] tuples.
The buildCommand wrapper intercepts returns and renders automatically
using the config's human formatter.

Two forms of output config:
- "json" (string) — flag injection only (--json, --fields)
- { json: true, human: fn } — flag injection + auto-render

Migrated 4 Category A commands to return-based pattern:
- auth/whoami: returns user
- auth/refresh: returns payload, formatRefreshResult in config
- issue/explain: returns causes with [data, {hint}] for footer
- org/view: returns org with optional [data, {hint}] for detection source

Eliminated jsonData — one canonical data object for JSON and human output.

Normalized JSON shapes for consistent jq ergonomics:
- issue/view: always includes event (null when absent)
- log/view: always emits array
- project/view: always emits array

Renames detectedFrom → hint (callers compose full message).
Removes OutputResult/output()/isOutputResult()/renderOutputResult()
and WriteOutputDivergentOptions/jsonData from all output APIs.

Author: BYK

src/commands/auth/refresh.ts

@@ -15,7 +15,6 @@ import {
 import { AuthError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import { formatDuration } from "../../lib/formatters/human.js";
-import { writeOutput } from "../../lib/formatters/index.js";
 
 type RefreshFlags = {
   readonly json: boolean;
@@ -31,6 +30,13 @@ type RefreshOutput = {
   expiresAt?: string;
 };
 
+/** Format refresh result for terminal output */
+function formatRefreshResult(data: RefreshOutput): string {
+  return data.refreshed
+    ? `${success("✓")} Token refreshed successfully. Expires in ${formatDuration(data.expiresIn ?? 0)}.`
+    : `Token still valid (expires in ${formatDuration(data.expiresIn ?? 0)}).\nUse --force to refresh anyway.`;
+}
+
 export const refreshCommand = buildCommand({
   docs: {
     brief: "Refresh your authentication token",
@@ -52,7 +58,7 @@ Examples:
   {"success":true,"refreshed":true,"expiresIn":3600,"expiresAt":"..."}
     `.trim(),
   },
-  output: "json",
+  output: { json: true, human: formatRefreshResult },
   parameters: {
     flags: {
       force: {
@@ -62,9 +68,7 @@ Examples:
       },
     },
   },
-  async func(this: SentryContext, flags: RefreshFlags): Promise<void> {
-    const { stdout } = this;
-
+  async func(this: SentryContext, flags: RefreshFlags) {
     // Env var tokens can't be refreshed
     if (isEnvTokenActive()) {
       const envVar = getActiveEnvVarName();
@@ -88,7 +92,7 @@ Examples:
 
     const result = await refreshToken({ force: flags.force });
 
-    const output: RefreshOutput = {
+    const payload: RefreshOutput = {
       success: true,
       refreshed: result.refreshed,
       message: result.refreshed
@@ -100,13 +104,6 @@ Examples:
         : undefined,
     };
 
-    writeOutput(stdout, output, {
-      json: flags.json,
-      fields: flags.fields,
-      formatHuman: (data) =>
-        data.refreshed
-          ? `${success("✓")} Token refreshed successfully. Expires in ${formatDuration(data.expiresIn ?? 0)}.`
-          : `Token still valid (expires in ${formatDuration(data.expiresIn ?? 0)}).\nUse --force to refresh anyway.`,
-    });
+    return payload;
   },
 });

src/commands/auth/whoami.ts

@@ -12,7 +12,7 @@ import { buildCommand } from "../../lib/command.js";
 import { isAuthenticated } from "../../lib/db/auth.js";
 import { setUserInfo } from "../../lib/db/user.js";
 import { AuthError } from "../../lib/errors.js";
-import { formatUserIdentity, writeOutput } from "../../lib/formatters/index.js";
+import { formatUserIdentity } from "../../lib/formatters/index.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -33,16 +33,18 @@ export const whoamiCommand = buildCommand({
       "This calls the Sentry API live (not cached) so the result always reflects " +
       "the current token. Works with all token types: OAuth, API tokens, and OAuth App tokens.",
   },
-  output: "json",
+  output: {
+    json: true,
+    human: formatUserIdentity,
+  },
   parameters: {
     flags: {
       fresh: FRESH_FLAG,
     },
     aliases: FRESH_ALIASES,
   },
-  async func(this: SentryContext, flags: WhoamiFlags): Promise<void> {
+  async func(this: SentryContext, flags: WhoamiFlags) {
     applyFreshFlag(flags);
-    const { stdout } = this;
 
     if (!(await isAuthenticated())) {
       throw new AuthError("not_authenticated");
@@ -63,16 +65,6 @@ export const whoamiCommand = buildCommand({
       // Cache update failure is non-essential — user identity was already fetched.
     }
 
-    writeOutput(stdout, user, {
-      json: flags.json,
-      fields: flags.fields,
-      jsonData: {
-        id: user.id,
-        name: user.name ?? null,
-        username: user.username ?? null,
-        email: user.email ?? null,
-      },
-      formatHuman: formatUserIdentity,
-    });
+    return user;
   },
 });

src/commands/issue/explain.ts

@@ -7,7 +7,6 @@
 import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { ApiError } from "../../lib/errors.js";
-import { writeOutput } from "../../lib/formatters/index.js";
 import {
   formatRootCauseList,
   handleSeerApiError,
@@ -59,7 +58,7 @@ export const explainCommand = buildCommand({
       "  sentry issue explain 123456789 --json\n" +
       "  sentry issue explain 123456789 --force",
   },
-  output: "json",
+  output: { json: true, human: formatRootCauseList },
   parameters: {
     positional: issueIdPositional,
     flags: {
@@ -72,13 +71,9 @@ export const explainCommand = buildCommand({
     },
     aliases: FRESH_ALIASES,
   },
-  async func(
-    this: SentryContext,
-    flags: ExplainFlags,
-    issueArg: string
-  ): Promise<void> {
+  async func(this: SentryContext, flags: ExplainFlags, issueArg: string) {
     applyFreshFlag(flags);
-    const { stdout, stderr, cwd } = this;
+    const { stderr, cwd } = this;
 
     // Declare org outside try block so it's accessible in catch for error messages
     let resolvedOrg: string | undefined;
@@ -110,13 +105,11 @@ export const explainCommand = buildCommand({
         );
       }
 
-      // Output results
-      writeOutput(stdout, causes, {
-        json: flags.json,
-        fields: flags.fields,
-        formatHuman: formatRootCauseList,
-        footer: `To create a plan, run: sentry issue plan ${issueArg}`,
-      });
+      // Return data with hint for next step
+      return [
+        causes,
+        { hint: `To create a plan, run: sentry issue plan ${issueArg}` },
+      ];
     } catch (error) {
       // Handle API errors with friendly messages
       if (error instanceof ApiError) {

src/commands/issue/view.ts

@@ -154,8 +154,7 @@ export const viewCommand = buildCommand({
       const trace = spanTreeResult?.success
         ? { traceId: spanTreeResult.traceId, spans: spanTreeResult.spans }
         : null;
-      const output = event ? { issue, event, trace } : { issue, trace };
-      writeJson(stdout, output, flags.fields);
+      writeJson(stdout, { issue, event: event ?? null, trace }, flags.fields);
       return;
     }
 

src/commands/log/view.ts

@@ -383,13 +383,7 @@ export const viewCommand = buildCommand({
     warnMissingIds(logIds, logs);
 
     if (flags.json) {
-      // Single ID: output single object for backward compatibility
-      // Multiple IDs: output array
-      if (logIds.length === 1 && logs.length === 1) {
-        writeJson(stdout, logs[0], flags.fields);
-      } else {
-        writeJson(stdout, logs, flags.fields);
-      }
+      writeJson(stdout, logs, flags.fields);
       return;
     }
 

src/commands/org/view.ts

@@ -9,7 +9,7 @@ import { getOrganization } from "../../lib/api-client.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError } from "../../lib/errors.js";
-import { formatOrgDetails, writeOutput } from "../../lib/formatters/index.js";
+import { formatOrgDetails } from "../../lib/formatters/index.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -35,7 +35,7 @@ export const viewCommand = buildCommand({
       "  2. Config defaults\n" +
       "  3. SENTRY_DSN environment variable or source code detection",
   },
-  output: "json",
+  output: { json: true, human: formatOrgDetails },
   parameters: {
     positional: {
       kind: "tuple",
@@ -58,11 +58,7 @@ export const viewCommand = buildCommand({
     },
     aliases: { ...FRESH_ALIASES, w: "web" },
   },
-  async func(
-    this: SentryContext,
-    flags: ViewFlags,
-    orgSlug?: string
-  ): Promise<void> {
+  async func(this: SentryContext, flags: ViewFlags, orgSlug?: string) {
     applyFreshFlag(flags);
     const { stdout, cwd } = this;
 
@@ -79,11 +75,9 @@ export const viewCommand = buildCommand({
 
     const org = await getOrganization(resolved.org);
 
-    writeOutput(stdout, org, {
-      json: flags.json,
-      fields: flags.fields,
-      formatHuman: formatOrgDetails,
-      detectedFrom: resolved.detectedFrom,
-    });
+    const hint = resolved.detectedFrom
+      ? `Detected from ${resolved.detectedFrom}`
+      : undefined;
+    return hint ? [org, { hint }] : org;
   },
 });

src/commands/project/view.ts

@@ -284,18 +284,14 @@ export const viewCommand = buildCommand({
       throw buildContextError();
     }
 
-    // JSON output - array if multiple, single object if one
+    // JSON output - always an array for consistent shape
     if (flags.json) {
       // Add dsn field to JSON output
       const projectsWithDsn = projects.map((p, i) => ({
         ...p,
         dsn: dsns[i] ?? null,
       }));
-      writeJson(
-        stdout,
-        projectsWithDsn.length === 1 ? projectsWithDsn[0] : projectsWithDsn,
-        flags.fields
-      );
+      writeJson(stdout, projectsWithDsn, flags.fields);
       return;
     }
 
@@ -307,7 +303,9 @@ export const viewCommand = buildCommand({
       writeOutput(stdout, firstProject, {
         json: false,
         formatHuman: (p: SentryProject) => formatProjectDetails(p, firstDsn),
-        detectedFrom: firstTarget?.detectedFrom,
+        hint: firstTarget?.detectedFrom
+          ? `Detected from ${firstTarget.detectedFrom}`
+          : undefined,
       });
     } else {
       writeMultipleProjects(stdout, projects, dsns, targets);