refactor: convert Tier 1 commands to return-based output

Convert 5 remaining Tier 1 commands to the return-based CommandOutput<T>
pattern introduced in #380. Commands return { data, hint? } and declare
an OutputConfig with json: true and a human formatter — the framework
handles JSON serialization and human-readable rendering.

Commands converted:
- event/view: formatEventView + buildEventData
- issue/view: formatIssueView + buildIssueData
- issue/plan: formatPlanOutput + buildPlanData (removed outputSolution)
- project/create: formatProjectCreatedView
- trace/view: formatTraceView + buildTraceData

Additional cleanup from review feedback:
- Unify hint and footer into single hint field on CommandOutput<T>
- Replace normalizePlatform stderr.write with consola logger
- Remove stdout parameter from openInBrowser/openOrShowUrl (now uses
  process.stdout directly) — all 7 command callers updated
- Remove unused Writer imports and stdout destructuring from commands

Author: BYK

src/commands/event/view.ts

@@ -22,7 +22,7 @@ import {
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
-import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
+import { formatEventDetails } from "../../lib/formatters/index.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -40,7 +40,7 @@ import {
 } from "../../lib/sentry-url-parser.js";
 import { buildEventSearchUrl } from "../../lib/sentry-urls.js";
 import { getSpanTreeLines } from "../../lib/span-tree.js";
-import type { SentryEvent, Writer } from "../../types/index.js";
+import type { SentryEvent } from "../../types/index.js";
 
 type ViewFlags = {
   readonly json: boolean;
@@ -50,30 +50,29 @@ type ViewFlags = {
   readonly fields?: string[];
 };
 
-type HumanOutputOptions = {
+/** Return type for event view — includes all data both renderers need */
+type EventViewData = {
   event: SentryEvent;
-  detectedFrom?: string;
+  trace: { traceId: string; spans: unknown[] } | null;
+  /** Pre-formatted span tree lines for human output (not serialized) */
   spanTreeLines?: string[];
 };
 
 /**
- * Write human-readable event output to stdout.
+ * Format event view data for human-readable terminal output.
  *
- * @param stdout - Output stream
- * @param options - Output options including event, detectedFrom, and spanTreeLines
+ * Renders event details and optional span tree.
  */
-function writeHumanOutput(stdout: Writer, options: HumanOutputOptions): void {
-  const { event, detectedFrom, spanTreeLines } = options;
+function formatEventView(data: EventViewData): string {
+  const parts: string[] = [];
 
-  stdout.write(`${formatEventDetails(event, `Event ${event.eventID}`)}\n`);
+  parts.push(formatEventDetails(data.event, `Event ${data.event.eventID}`));
 
-  if (spanTreeLines && spanTreeLines.length > 0) {
-    stdout.write(`${spanTreeLines.join("\n")}\n`);
+  if (data.spanTreeLines && data.spanTreeLines.length > 0) {
+    parts.push(data.spanTreeLines.join("\n"));
   }
 
-  if (detectedFrom) {
-    stdout.write(`\nDetected from ${detectedFrom}\n`);
-  }
+  return parts.join("\n");
 }
 
 /** Usage hint for ContextError messages */
@@ -303,7 +302,11 @@ export const viewCommand = buildCommand({
       "  sentry event view <org>/<proj> <event-id> # explicit org and project\n" +
       "  sentry event view <project> <event-id>    # find project across all orgs",
   },
-  output: "json",
+  output: {
+    json: true,
+    human: formatEventView,
+    jsonExclude: ["spanTreeLines"],
+  },
   parameters: {
     positional: {
       kind: "array",
@@ -325,13 +328,9 @@ export const viewCommand = buildCommand({
     },
     aliases: { ...FRESH_ALIASES, w: "web" },
   },
-  async func(
-    this: SentryContext,
-    flags: ViewFlags,
-    ...args: string[]
-  ): Promise<void> {
+  async func(this: SentryContext, flags: ViewFlags, ...args: string[]) {
     applyFreshFlag(flags);
-    const { stdout, cwd } = this;
+    const { cwd } = this;
 
     const log = logger.withTag("event.view");
 
@@ -360,11 +359,7 @@ export const viewCommand = buildCommand({
     }
 
     if (flags.web) {
-      await openInBrowser(
-        stdout,
-        buildEventSearchUrl(target.org, eventId),
-        "event"
-      );
+      await openInBrowser(buildEventSearchUrl(target.org, eventId), "event");
       return;
     }
 
@@ -381,18 +376,15 @@ export const viewCommand = buildCommand({
         ? await getSpanTreeLines(target.org, event, flags.spans)
         : undefined;
 
-    if (flags.json) {
-      const trace = spanTreeResult?.success
-        ? { traceId: spanTreeResult.traceId, spans: spanTreeResult.spans }
-        : null;
-      writeJson(stdout, { event, trace }, flags.fields);
-      return;
-    }
+    const trace = spanTreeResult?.success
+      ? { traceId: spanTreeResult.traceId, spans: spanTreeResult.spans }
+      : null;
 
-    writeHumanOutput(stdout, {
-      event,
-      detectedFrom: target.detectedFrom,
-      spanTreeLines: spanTreeResult?.lines,
-    });
+    return {
+      data: { event, trace, spanTreeLines: spanTreeResult?.lines },
+      hint: target.detectedFrom
+        ? `Detected from ${target.detectedFrom}`
+        : undefined,
+    };
   },
 });

src/commands/issue/explain.ts

@@ -73,7 +73,7 @@ export const explainCommand = buildCommand({
   },
   async func(this: SentryContext, flags: ExplainFlags, issueArg: string) {
     applyFreshFlag(flags);
-    const { stderr, cwd } = this;
+    const { cwd } = this;
 
     // Declare org outside try block so it's accessible in catch for error messages
     let resolvedOrg: string | undefined;
@@ -91,7 +91,6 @@ export const explainCommand = buildCommand({
       const state = await ensureRootCauseAnalysis({
         org,
         issueId: numericId,
-        stderr,
         json: flags.json,
         force: flags.force,
       });

src/commands/issue/list.ts

@@ -756,7 +756,6 @@ async function fetchOrgAllIssues(
 /** Options for {@link handleOrgAllIssues}. */
 type OrgAllIssuesOptions = {
   stdout: Writer;
-  stderr: Writer;
   org: string;
   flags: ListFlags;
   setContext: (orgs: string[], projects: string[]) => void;
@@ -769,7 +768,7 @@ type OrgAllIssuesOptions = {
  * never accidentally reused.
  */
 async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
-  const { stdout, stderr, org, flags, setContext } = options;
+  const { stdout, org, flags, setContext } = options;
   // Encode sort + query in context key so cursors from different searches don't collide.
   const contextKey = buildPaginationContextKey("org", org, {
     sort: flags.sort,
@@ -781,7 +780,7 @@ async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
   setContext([org], []);
 
   const { issues, nextCursor } = await withProgress(
-    { stderr, message: `Fetching issues (up to ${flags.limit})...` },
+    { message: `Fetching issues (up to ${flags.limit})...` },
     (setMessage) =>
       fetchOrgAllIssues(org, flags, cursor, (fetched, limit) =>
         setMessage(
@@ -927,7 +926,7 @@ async function handleResolvedTargets(
       : "Fetching issues";
 
   const { results, hasMore } = await withProgress(
-    { stderr, message: `${baseMessage} (up to ${flags.limit})...` },
+    { message: `${baseMessage} (up to ${flags.limit})...` },
     (setMessage) =>
       fetchWithBudget(
         activeTargets,
@@ -1266,7 +1265,6 @@ export const listCommand = buildListCommand("issue", {
         "org-all": (ctx) =>
           handleOrgAllIssues({
             stdout: ctx.stdout,
-            stderr,
             org: ctx.parsed.org,
             flags,
             setContext,

src/commands/issue/plan.ts

@@ -9,8 +9,6 @@ import type { SentryContext } from "../../context.js";
 import { triggerSolutionPlanning } from "../../lib/api-client.js";
 import { buildCommand, numberParser } from "../../lib/command.js";
 import { ApiError, ValidationError } from "../../lib/errors.js";
-import { muted } from "../../lib/formatters/colors.js";
-import { writeJson } from "../../lib/formatters/index.js";
 import {
   formatSolution,
   handleSeerApiError,
@@ -20,7 +18,7 @@ import {
   FRESH_ALIASES,
   FRESH_FLAG,
 } from "../../lib/list-command.js";
-import type { Writer } from "../../types/index.js";
+import { logger } from "../../lib/logger.js";
 import {
   type AutofixState,
   extractRootCauses,
@@ -108,39 +106,36 @@ function validateCauseSelection(
   return causeId;
 }
 
-type OutputSolutionOptions = {
-  stdout: Writer;
-  stderr: Writer;
-  solution: SolutionArtifact | null;
-  state: AutofixState;
-  json: boolean;
-  fields?: string[];
+/** Return type for issue plan — includes state metadata and solution */
+type PlanData = {
+  run_id: number;
+  status: string;
+  solution: SolutionArtifact["data"] | null;
 };
 
 /**
- * Output a solution artifact to stdout.
+ * Format solution plan data for human-readable terminal output.
+ *
+ * Returns the formatted solution or a "no solution" message.
  */
-function outputSolution(options: OutputSolutionOptions): void {
-  const { stdout, stderr, solution, state, json, fields } = options;
-
-  if (json) {
-    writeJson(
-      stdout,
-      {
-        run_id: state.run_id,
-        status: state.status,
-        solution: solution?.data ?? null,
-      },
-      fields
-    );
-    return;
+function formatPlanOutput(data: PlanData): string {
+  if (data.solution) {
+    // Wrap in the SolutionArtifact shape expected by formatSolution
+    return formatSolution({ data: data.solution } as SolutionArtifact);
   }
+  return "No solution found. Check the Sentry web UI for details.";
+}
 
-  if (solution) {
-    stdout.write(`${formatSolution(solution)}\n`);
-  } else {
-    stderr.write("No solution found. Check the Sentry web UI for details.\n");
-  }
+/**
+ * Build the plan data object from autofix state.
+ */
+function buildPlanData(state: AutofixState): PlanData {
+  const solution = extractSolution(state);
+  return {
+    run_id: state.run_id,
+    status: state.status,
+    solution: solution?.data ?? null,
+  };
 }
 
 export const planCommand = buildCommand({
@@ -171,7 +166,10 @@ export const planCommand = buildCommand({
       "  sentry issue plan cli-G --cause 0\n" +
       "  sentry issue plan 123456789 --force",
   },
-  output: "json",
+  output: {
+    json: true,
+    human: formatPlanOutput,
+  },
   parameters: {
     positional: issueIdPositional,
     flags: {
@@ -190,13 +188,9 @@ export const planCommand = buildCommand({
     },
     aliases: FRESH_ALIASES,
   },
-  async func(
-    this: SentryContext,
-    flags: PlanFlags,
-    issueArg: string
-  ): Promise<void> {
+  async func(this: SentryContext, flags: PlanFlags, issueArg: string) {
     applyFreshFlag(flags);
-    const { stdout, stderr, cwd } = this;
+    const { cwd } = this;
 
     // Declare org outside try block so it's accessible in catch for error messages
     let resolvedOrg: string | undefined;
@@ -214,7 +208,6 @@ export const planCommand = buildCommand({
       const state = await ensureRootCauseAnalysis({
         org,
         issueId: numericId,
-        stderr,
         json: flags.json,
       });
 
@@ -229,23 +222,16 @@ export const planCommand = buildCommand({
       if (!flags.force) {
         const existingSolution = extractSolution(state);
         if (existingSolution) {
-          outputSolution({
-            stdout,
-            stderr,
-            solution: existingSolution,
-            state,
-            json: flags.json,
-            fields: flags.fields,
-          });
-          return;
+          return { data: buildPlanData(state) };
         }
       }
 
       // No solution exists, trigger planning
       if (!flags.json) {
-        stderr.write(`Creating plan for cause #${causeId}...\n`);
+        const log = logger.withTag("issue.plan");
+        log.info(`Creating plan for cause #${causeId}...`);
         if (selectedCause) {
-          stderr.write(`${muted(`"${selectedCause.description}"`)}\n\n`);
+          log.info(`"${selectedCause.description}"`);
         }
       }
 
@@ -255,7 +241,6 @@ export const planCommand = buildCommand({
       const finalState = await pollAutofixState({
         orgSlug: org,
         issueId: numericId,
-        stderr,
         json: flags.json,
         timeoutMessage:
           "Plan creation timed out after 6 minutes. Try again or check the issue in Sentry web UI.",
@@ -272,16 +257,7 @@ export const planCommand = buildCommand({
         throw new Error("Plan creation was cancelled.");
       }
 
-      // Extract and output solution
-      const solution = extractSolution(finalState);
-      outputSolution({
-        stdout,
-        stderr,
-        solution,
-        state: finalState,
-        json: flags.json,
-        fields: flags.fields,
-      });
+      return { data: buildPlanData(finalState) };
     } catch (error) {
       // Handle API errors with friendly messages
       if (error instanceof ApiError) {