refactor: unify commands as generators with HumanRenderer factory, remove stdout plumbing (#416)

## Summary

Unifies all command functions as async generators, introduces a
`HumanRenderer` factory for stateful rendering, and removes direct
stdout/stderr plumbing from commands. This is Phase 6b of the output
convergence plan.

### 1. Unify all command functions as async generators

Every command `func` is now an `async *func` generator. Commands yield
`CommandOutput<T>` values instead of writing to stdout directly.

- Commands that produce output yield via `commandOutput(data)`
- Void generators (e.g. `auth/token`) are valid no-op generators
- The `buildCommand` wrapper iterates the generator and routes output
through the `OutputConfig` pipeline

### 2. Brand `CommandOutput` with Symbol discriminant

Replace duck-typing (`"data" in value`) with a `COMMAND_OUTPUT_BRAND`
Symbol. Prevents false positives from raw API responses that have a
`data` property.

- `commandOutput<T>(data)` factory creates branded values
- `isCommandOutput()` checks the Symbol instead of structural shape
- All command files migrated to use `commandOutput()`

### 3. Move hints from yield to generator return value

Hints (footer text like "Detected from .env.local") are no longer part
of the yielded `CommandOutput`. Generators `return { hint }` after their
final yield.

- New `CommandReturn` type: `{ hint?: string }`
- Wrapper uses manual `.next()` iteration to capture the return value
- Hints are suppressed in JSON mode

### 4. `HumanRenderer` factory pattern for `OutputConfig.human`

`OutputConfig.human` is now a factory function `() => HumanRenderer<T>`
instead of a plain `(data: T) => string`. This enables stateful
rendering (e.g., streaming tables) without module-level singletons.

- `HumanRenderer<T>` has `render(data: T): string` and optional
`finalize(hint?: string): string`
- `stateless(fn)` helper wraps plain formatters for commands that don't
need state
- `createLogRenderer()` replaces the old module-level
`streamingTable`/`streamingHeaderEmitted` singletons in `log/list.ts`
- The `buildCommand` wrapper resolves the factory once per invocation,
passes the renderer through iteration, and calls `finalize()` after the
generator completes

### 5. Remove stdout/stderr plumbing from commands

Commands no longer receive or pass `stdout`/`stderr` Writer references.
All diagnostic/interactive output routes through consola logger (→
stderr), keeping stdout reserved for structured command output.

- `HandlerContext` and `DispatchOptions` no longer carry `stdout`
- `runInteractiveLogin` uses logger instead of Writer params
- Follow-mode banners, diagnostics, and QR code display all use logger
- `displayTraceLogs` → `formatTraceLogs` (returns string)
- `formatFooter()` helper extracted from `writeFooter()`

### 6. `log/list.ts` streaming refactor

The most complex command — 685 lines with follow-mode streaming, trace
filtering, and JSONL output — is fully converted:

- `createLogRenderer()` factory manages streaming table state
per-invocation
- `render()` emits table header on first non-empty batch, rows per batch
- `finalize(hint?)` closes the table footer and appends hint text
- Empty-state hints render as primary text (not muted footer)
- `jsonl` flag on `LogListResult` controls JSONL vs array serialization
- `executeSingleFetch`/`executeTraceSingleFetch` return `FetchResult`
with separate `result` and `hint` fields

### 7. `auth/login` yield pattern

Interactive OAuth login now yields `LoginResult` values through the
generator instead of writing to stdout/stderr directly:

- Token-based login: yields success result, returns hint
- OAuth flow: yields QR code + URL, progress dots, and final result
- `runInteractiveLogin` returns `LoginResult` values consumed by the
generator

**Remaining stdout usage (intentional):**
- `auth/token`: raw stdout for pipe compatibility (`sentry auth token |
pbcopy`)
- `help.ts`: help text to stdout (like `git --help`)
- `trace/logs.ts`: `process.stdout.write` (pending OutputConfig
migration)

## Test plan

- 1656 tests pass, 0 fail, 15753 assertions across 55 files
- Typecheck clean, lint clean (375 files)
- E2E tests pass (103 pass, 3 skip)
- All CI checks green including Seer Code Review and Cursor BugBot

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

AGENTS.md

@@ -45,6 +45,8 @@ Authenticate with Sentry
 - `--token <value> - Authenticate using an API token instead of OAuth`
 - `--timeout <value> - Timeout for OAuth flow in seconds (default: 900) - (default: "900")`
 - `--force - Re-authenticate without prompting`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 **Examples:**
 
@@ -109,6 +111,10 @@ sentry auth status
 
 Print the stored authentication token
 
+**Flags:**
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
+
 #### `sentry auth whoami`
 
 Show the currently authenticated user
@@ -485,6 +491,8 @@ Configure shell integration
 - `--no-completions - Skip shell completion installation`
 - `--no-agent-skills - Skip agent skill installation for AI coding assistants`
 - `--quiet - Suppress output (for scripted usage)`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
 #### `sentry cli upgrade <version>`
 

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -103,11 +103,7 @@ const autoAuthMiddleware: ErrorMiddleware = async (next, args) => {
           : "Authentication required. Starting login flow...\n\n"
       );
 
-      const loginSuccess = await runInteractiveLogin(
-        process.stdout,
-        process.stderr,
-        process.stdin
-      );
+      const loginSuccess = await runInteractiveLogin();
 
       if (loginSuccess) {
         process.stderr.write("\nRetrying command...\n\n");

src/bin.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";
@@ -1052,7 +1053,7 @@ function logResponse(response: { status: number; headers: Headers }): void {
 }
 
 export const apiCommand = buildCommand({
-  output: { json: true, human: formatApiResponse },
+  output: { human: formatApiResponse },
   docs: {
     brief: "Make an authenticated API request",
     fullDescription:
@@ -1155,7 +1156,7 @@ export const apiCommand = buildCommand({
       n: "dry-run",
     },
   },
-  async func(this: SentryContext, flags: ApiFlags, endpoint: string) {
+  async *func(this: SentryContext, flags: ApiFlags, endpoint: string) {
     const { stdin } = this;
 
     const normalizedEndpoint = normalizeEndpoint(endpoint);
@@ -1168,14 +1169,13 @@ export const apiCommand = buildCommand({
 
     // Dry-run mode: preview the request that would be sent
     if (flags["dry-run"]) {
-      return {
-        data: {
-          method: flags.method,
-          url: resolveRequestUrl(normalizedEndpoint, params),
-          headers: resolveEffectiveHeaders(headers, body),
-          body: body ?? null,
-        },
-      };
+      yield new CommandOutput({
+        method: flags.method,
+        url: resolveRequestUrl(normalizedEndpoint, params),
+        headers: resolveEffectiveHeaders(headers, body),
+        body: body ?? null,
+      });
+      return;
     }
 
     const verbose = flags.verbose && !flags.silent;
@@ -1210,6 +1210,6 @@ export const apiCommand = buildCommand({
       throw new OutputError(response.body);
     }
 
-    return { data: response.body };
+    return yield new CommandOutput(response.body);
   },
 });

src/commands/api.ts

@@ -12,13 +12,38 @@ import {
 import { getDbPath } from "../../lib/db/index.js";
 import { getUserInfo, setUserInfo } from "../../lib/db/user.js";
 import { AuthError } from "../../lib/errors.js";
-import { formatUserIdentity } from "../../lib/formatters/human.js";
+import { success } from "../../lib/formatters/colors.js";
+import {
+  formatDuration,
+  formatUserIdentity,
+} from "../../lib/formatters/human.js";
+import { CommandOutput } from "../../lib/formatters/output.js";
+import type { LoginResult } from "../../lib/interactive-login.js";
 import { runInteractiveLogin } from "../../lib/interactive-login.js";
 import { logger } from "../../lib/logger.js";
 import { clearResponseCache } from "../../lib/response-cache.js";
 
 const log = logger.withTag("auth.login");
 
+/** Format a {@link LoginResult} for human-readable terminal output. */
+function formatLoginResult(result: LoginResult): string {
+  const lines: string[] = [];
+  lines.push(
+    success(
+      `✔ ${result.method === "token" ? "Authenticated with API token" : "Authentication successful!"}`
+    )
+  );
+  if (result.user) {
+    lines.push(`  Logged in as: ${formatUserIdentity(result.user)}`);
+  }
+  lines.push(`  Config saved to: ${result.configPath}`);
+  if (result.expiresIn) {
+    lines.push(`  Token expires in: ${formatDuration(result.expiresIn)}`);
+  }
+  lines.push(""); // trailing newline
+  return lines.join("\n");
+}
+
 type LoginFlags = {
   readonly token?: string;
   readonly timeout: number;
@@ -104,7 +129,8 @@ export const loginCommand = buildCommand({
       },
     },
   },
-  async func(this: SentryContext, flags: LoginFlags): Promise<void> {
+  output: { human: formatLoginResult },
+  async *func(this: SentryContext, flags: LoginFlags) {
     // Check if already authenticated and handle re-authentication
     if (await isAuthenticated()) {
       const shouldProceed = await handleExistingAuth(flags.force);
@@ -113,15 +139,15 @@ export const loginCommand = buildCommand({
       }
     }
 
+    // Clear stale cached responses from a previous session
+    try {
+      await clearResponseCache();
+    } catch {
+      // Non-fatal: cache directory may not exist
+    }
+
     // Token-based authentication
     if (flags.token) {
-      // Clear stale cached responses from a previous session
-      try {
-        await clearResponseCache();
-      } catch {
-        // Non-fatal: cache directory may not exist
-      }
-
       // Save token first, then validate by fetching user regions
       await setAuthToken(flags.token);
 
@@ -139,46 +165,35 @@ export const loginCommand = buildCommand({
 
       // Fetch and cache user info via /auth/ (works with all token types).
       // A transient failure here must not block login — the token is already valid.
-      let user: Awaited<ReturnType<typeof getCurrentUser>> | undefined;
+      const result: LoginResult = {
+        method: "token",
+        configPath: getDbPath(),
+      };
       try {
-        user = await getCurrentUser();
+        const user = await getCurrentUser();
         setUserInfo({
           userId: user.id,
           email: user.email,
           username: user.username,
           name: user.name,
         });
+        result.user = user;
       } catch {
         // Non-fatal: user info is supplementary. Token remains stored and valid.
       }
 
-      log.success("Authenticated with API token");
-      if (user) {
-        log.info(`Logged in as: ${formatUserIdentity(user)}`);
-      }
-      log.info(`Config saved to: ${getDbPath()}`);
-      return;
+      return yield new CommandOutput(result);
     }
 
-    // Clear stale cached responses from a previous session
-    try {
-      await clearResponseCache();
-    } catch {
-      // Non-fatal: cache directory may not exist
-    }
-
-    const { stdout, stderr } = this;
-    const loginSuccess = await runInteractiveLogin(
-      stdout,
-      stderr,
-      process.stdin,
-      {
-        timeout: flags.timeout * 1000,
-      }
-    );
+    // OAuth device flow
+    const result = await runInteractiveLogin({
+      timeout: flags.timeout * 1000,
+    });
 
-    if (!loginSuccess) {
-      // Error already displayed by runInteractiveLogin - just set exit code
+    if (result) {
+      yield new CommandOutput(result);
+    } else {
+      // Error already displayed by runInteractiveLogin
       process.exitCode = 1;
     }
   },

src/commands/auth/login.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 = {
@@ -32,15 +33,16 @@ export const logoutCommand = buildCommand({
     fullDescription:
       "Remove stored authentication credentials from the local database.",
   },
-  output: { json: true, human: formatLogoutResult },
+  output: { human: formatLogoutResult },
   parameters: {
     flags: {},
   },
-  async func(this: SentryContext): Promise<{ data: LogoutResult }> {
+  async *func(this: SentryContext) {
     if (!(await isAuthenticated())) {
-      return {
-        data: { loggedOut: false, message: "Not currently authenticated." },
-      };
+      return yield new CommandOutput({
+        loggedOut: false,
+        message: "Not currently authenticated.",
+      });
     }
 
     if (isEnvTokenActive()) {
@@ -55,11 +57,9 @@ export const logoutCommand = buildCommand({
     const configPath = getDbPath();
     await clearAuth();
 
-    return {
-      data: {
-        loggedOut: true,
-        configPath,
-      },
-    };
+    return yield new CommandOutput({
+      loggedOut: true,
+      configPath,
+    });
   },
 });

src/commands/auth/logout.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;
@@ -58,7 +59,7 @@ Examples:
   {"success":true,"refreshed":true,"expiresIn":3600,"expiresAt":"..."}
     `.trim(),
   },
-  output: { json: true, human: formatRefreshResult },
+  output: { human: formatRefreshResult },
   parameters: {
     flags: {
       force: {
@@ -68,7 +69,7 @@ Examples:
       },
     },
   },
-  async func(this: SentryContext, flags: RefreshFlags) {
+  async *func(this: SentryContext, flags: RefreshFlags) {
     // Env var tokens can't be refreshed
     if (isEnvTokenActive()) {
       const envVar = getActiveEnvVarName();
@@ -104,6 +105,6 @@ Examples:
         : undefined,
     };
 
-    return { data: payload };
+    return yield new CommandOutput(payload);
   },
 });

src/commands/auth/refresh.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,
@@ -143,7 +144,7 @@ export const statusCommand = buildCommand({
       "Display information about your current authentication status, " +
       "including whether you're logged in and your default organization/project settings.",
   },
-  output: { json: true, human: formatAuthStatus },
+  output: { human: formatAuthStatus },
   parameters: {
     flags: {
       "show-token": {
@@ -155,7 +156,7 @@ export const statusCommand = buildCommand({
     },
     aliases: FRESH_ALIASES,
   },
-  async func(this: SentryContext, flags: StatusFlags) {
+  async *func(this: SentryContext, flags: StatusFlags) {
     applyFreshFlag(flags);
 
     const auth = getAuthConfig();
@@ -189,6 +190,6 @@ export const statusCommand = buildCommand({
       verification: await verifyCredentials(),
     };
 
-    return { data };
+    return yield new CommandOutput(data);
   },
 });

src/commands/auth/status.ts

@@ -9,28 +9,25 @@ import type { SentryContext } from "../../context.js";
 import { buildCommand } from "../../lib/command.js";
 import { getAuthToken } from "../../lib/db/auth.js";
 import { AuthError } from "../../lib/errors.js";
+import { CommandOutput } from "../../lib/formatters/output.js";
 
 export const tokenCommand = buildCommand({
   docs: {
     brief: "Print the stored authentication token",
     fullDescription:
       "Print the stored authentication token to stdout.\n\n" +
       "This outputs the raw token without any formatting, making it suitable for " +
-      "piping to other commands or scripts. The token is printed without a trailing newline " +
-      "when stdout is not a TTY (e.g., when piped).",
+      "piping to other commands or scripts.",
   },
   parameters: {},
-  func(this: SentryContext): void {
-    const { stdout } = this;
-
+  output: { human: (token: string) => token },
+  // biome-ignore lint/suspicious/useAwait: sync body but async generator required by buildCommand
+  async *func(this: SentryContext) {
     const token = getAuthToken();
     if (!token) {
       throw new AuthError("not_authenticated");
     }
 
-    // Add newline only if stdout is a TTY (interactive terminal)
-    // When piped, omit newline for cleaner output
-    const suffix = process.stdout.isTTY ? "\n" : "";
-    stdout.write(`${token}${suffix}`);
+    return yield new CommandOutput(token);
   },
 });