refactor: converge Tier 1 commands to writeOutput helper (#376)

BYK · web-flow · commit 23b4f98e0a8e · 2026-03-10T12:02:59.000Z
## Phase 2: `writeOutput` convergence Builds on #373 (`output: "json"` centralization). Enhance `writeOutput` with two new options and migrate 3 Tier 1 commands to use it. ### New options on `writeOutput` - **`footer?: string`** — muted hint after human output, suppressed in JSON mode. Replaces separate `writeFooter()` calls. - **`jsonData?: J`** — separate data object for JSON when the serialized shape differs from the human formatter's input. ### Commands migrated | Command | What changed | |---------|-------------| | `auth/whoami` | `jsonData` narrows user to `{id, name, username, email}` for JSON | | `auth/refresh` | Inline `formatHuman` replaces 3-branch if/else | | `issue/explain` | `footer` replaces separate `writeFooter()` call | Commands with multi-part output or divergent data assembly (`issue/view`, `event/view`, `trace/view`, `project/create`, `log/view`) are intentionally left as-is — they don't fit the single-formatter pattern. ### Tests 16 new tests in `test/lib/formatters/output.test.ts` cover JSON mode, human mode, footer, detectedFrom, and jsonData divergence.
diff --git a/src/commands/auth/refresh.ts b/src/commands/auth/refresh.ts
@@ -15,7 +15,7 @@ import {
 import { AuthError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import { formatDuration } from "../../lib/formatters/human.js";
-import { writeJson } from "../../lib/formatters/index.js";
+import { writeOutput } from "../../lib/formatters/index.js";
 
 type RefreshFlags = {
   readonly json: boolean;
@@ -100,17 +100,13 @@ Examples:
         : undefined,
     };
 
-    if (flags.json) {
-      writeJson(stdout, output, flags.fields);
-    } else if (result.refreshed) {
-      stdout.write(
-        `${success("✓")} Token refreshed successfully. Expires in ${formatDuration(result.expiresIn ?? 0)}.\n`
-      );
-    } else {
-      stdout.write(
-        `Token still valid (expires in ${formatDuration(result.expiresIn ?? 0)}).\n` +
-          "Use --force to refresh anyway.\n"
-      );
-    }
+    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.`,
+    });
   },
 });
diff --git a/src/commands/auth/whoami.ts b/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, writeJson } from "../../lib/formatters/index.js";
+import { formatUserIdentity, writeOutput } from "../../lib/formatters/index.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
@@ -63,20 +63,16 @@ export const whoamiCommand = buildCommand({
       // Cache update failure is non-essential — user identity was already fetched.
     }
 
-    if (flags.json) {
-      writeJson(
-        stdout,
-        {
-          id: user.id,
-          name: user.name ?? null,
-          username: user.username ?? null,
-          email: user.email ?? null,
-        },
-        flags.fields
-      );
-      return;
-    }
-
-    stdout.write(`${formatUserIdentity(user)}\n`);
+    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,
+    });
   },
 });
diff --git a/src/commands/issue/explain.ts b/src/commands/issue/explain.ts
@@ -7,7 +7,7 @@
 import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { ApiError } from "../../lib/errors.js";
-import { writeFooter, writeJson } from "../../lib/formatters/index.js";
+import { writeOutput } from "../../lib/formatters/index.js";
 import {
   formatRootCauseList,
   handleSeerApiError,
@@ -111,17 +111,12 @@ export const explainCommand = buildCommand({
       }
 
       // Output results
-      if (flags.json) {
-        writeJson(stdout, causes, flags.fields);
-        return;
-      }
-
-      // Human-readable output
-      stdout.write(`${formatRootCauseList(causes)}\n`);
-      writeFooter(
-        stdout,
-        `To create a plan, run: sentry issue plan ${issueArg}`
-      );
+      writeOutput(stdout, causes, {
+        json: flags.json,
+        fields: flags.fields,
+        formatHuman: formatRootCauseList,
+        footer: `To create a plan, run: sentry issue plan ${issueArg}`,
+      });
     } catch (error) {
       // Handle API errors with friendly messages
       if (error instanceof ApiError) {
diff --git a/src/lib/formatters/output.ts b/src/lib/formatters/output.ts
@@ -9,6 +9,12 @@ import type { Writer } from "../../types/index.js";
 import { muted } from "./colors.js";
 import { writeJson } from "./json.js";
 
+/**
+ * Options for {@link writeOutput} when JSON and human data share the same type.
+ *
+ * Most commands fetch data and then either serialize it to JSON or format it
+ * for the terminal — use this form when the same object works for both paths.
+ */
 type WriteOutputOptions<T> = {
   /** Output JSON format instead of human-readable */
   json: boolean;
@@ -18,23 +24,52 @@ type WriteOutputOptions<T> = {
   formatHuman: (data: T) => string;
   /** Optional source description if data was auto-detected */
   detectedFrom?: string;
+  /** Footer hint shown after human output (suppressed in JSON mode) */
+  footer?: string;
+};
+
+/**
+ * Options for {@link writeOutput} when JSON needs a different data shape.
+ *
+ * Some commands build a richer or narrower object for JSON than the one
+ * the human formatter receives. Supply `jsonData` to decouple the two.
+ *
+ * @typeParam T - Type of data used by the human formatter
+ * @typeParam J - Type of data serialized to JSON (defaults to T)
+ */
+type WriteOutputDivergentOptions<T, J> = WriteOutputOptions<T> & {
+  /**
+   * Separate data object to serialize when `json: true`.
+   * When provided, `data` is only used by `formatHuman` and
+   * `jsonData` is passed to `writeJson`.
+   */
+  jsonData: J;
 };
 
 /**
  * Write formatted output to stdout based on output format.
- * Handles the common JSON vs human-readable pattern used across commands.
  *
- * @param stdout - Writer to output to
- * @param data - Data to output
- * @param options - Output options including format and formatters
+ * Handles the common JSON-vs-human pattern used across commands:
+ * - JSON mode: serialize data (or `jsonData` if provided) with optional field filtering
+ * - Human mode: call `formatHuman`, then optionally print `detectedFrom` and `footer`
+ *
+ * When JSON and human paths need different data shapes, pass `jsonData`:
+ * ```ts
+ * writeOutput(stdout, fullUser, {
+ *   json: true,
+ *   jsonData: { id: fullUser.id, email: fullUser.email },
+ *   formatHuman: formatUserIdentity,
+ * });
+ * ```
  */
-export function writeOutput<T>(
+export function writeOutput<T, J = T>(
   stdout: Writer,
   data: T,
-  options: WriteOutputOptions<T>
+  options: WriteOutputOptions<T> | WriteOutputDivergentOptions<T, J>
 ): void {
   if (options.json) {
-    writeJson(stdout, data, options.fields);
+    const jsonPayload = "jsonData" in options ? options.jsonData : data;
+    writeJson(stdout, jsonPayload, options.fields);
     return;
   }
 
@@ -44,6 +79,10 @@ export function writeOutput<T>(
   if (options.detectedFrom) {
     stdout.write(`\nDetected from ${options.detectedFrom}\n`);
   }
+
+  if (options.footer) {
+    writeFooter(stdout, options.footer);
+  }
 }
 
 /**
diff --git a/test/lib/formatters/output.test.ts b/test/lib/formatters/output.test.ts
